Autenticazione e accesso alle API di Experience Platform

Questo documento spiega passo-passo come accedere a un account sviluppatore di Adobe Experience Platform per effettuare chiamate alle API di Experience Platform. Al termine dell’esercitazione, avrai generato le seguenti credenziali richieste per tutte le chiamate API di Platform:

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {IMS_ORG}

Per mantenere la sicurezza delle applicazioni e degli utenti, tutte le richieste alle API di Adobe I/O devono essere autenticate e autorizzate utilizzando standard come OAuth e JSON Web Token (JWT). Per generare il token di accesso personale, viene utilizzato un JWT con informazioni specifiche per il cliente.

Questa esercitazione illustra come raccogliere le credenziali richieste per autenticare le chiamate API di Platform, come descritto nel seguente diagramma di flusso:

Prerequisiti

Per effettuare correttamente le chiamate alle API di Experience Platform, devi disporre dei seguenti elementi:

  • Organizzazione IMS con accesso a Adobe Experience Platform.
  • Un amministratore di Admin Console in grado di aggiungerti come sviluppatore e come utente per un profilo di prodotto.

Devi anche disporre di un Adobe ID per completare questa esercitazione. Se non disponi di un Adobe ID, puoi crearne uno seguendo questi passaggi:

  1. Vai a Adobe Developer Console.
  2. Seleziona Create a new account.
  3. Completa il processo di registrazione.

Acquisisci ad Experience Platform l’accesso degli sviluppatori e degli utenti

Prima di creare integrazioni su Adobe Developer Console, il tuo account deve disporre delle autorizzazioni per sviluppatori e utenti per un profilo di prodotto di Experience Platform in Adobe Admin Console.

Accesso per sviluppatori

Contatta un amministratore Admin Console della tua organizzazione per aggiungerti come sviluppatore a un profilo di prodotto di Experience Platform utilizzando Admin Console. Per istruzioni specifiche su come gestire l'accesso degli sviluppatori per i profili di prodotto, consulta la documentazione Admin Console .

Una volta assegnato come sviluppatore, puoi iniziare a creare integrazioni in Adobe Developer Console. Queste integrazioni sono una pipeline da applicazioni e servizi esterni alle API di Adobe.

Accesso utente

L’amministratore di Admin Console deve anche aggiungerti come utente allo stesso profilo di prodotto. Per ulteriori informazioni, consulta la guida sulla gestione dei gruppi di utenti in Admin Console .

Generare una chiave API, un ID organizzazione IMS e un segreto client

NOTA

Se segui questo documento dalla guida per sviluppatori di Privacy Service, ora puoi tornare a tale guida per generare le credenziali di accesso univoche per Privacy Service.

Dopo aver ricevuto dallo sviluppatore e dall’utente l’accesso a Platform tramite Admin Console, il passaggio successivo consiste nel generare le credenziali {IMS_ORG} e {API_KEY} in Adobe Developer Console. Queste credenziali devono essere generate una sola volta e possono essere riutilizzate nelle chiamate API future di Platform.

Aggiungere un Experience Platform a un progetto

Vai a Adobe Developer Console e accedi con il tuo Adobe ID. Quindi, segui i passaggi descritti nell’esercitazione su creazione di un progetto vuoto nella documentazione di Adobe Developer Console.

Dopo aver creato un nuovo progetto, seleziona Add API nella schermata Project Overview .

Viene visualizzata la schermata Add an API. Seleziona l’icona del prodotto per Adobe Experience Platform, quindi scegli Experience Platform API prima di selezionare Next.

Da qui, segui i passaggi descritti nell’esercitazione sull’ aggiunta di un’API a un progetto utilizzando un account di servizio (JWT) (a partire dal passaggio "Configura API") per completare il processo.

IMPORTANTE

A un certo punto del processo collegato qui sopra, il browser scarica automaticamente una chiave privata e un certificato pubblico associato. Nota dove questa chiave privata è memorizzata nel computer, in quanto è necessaria in un passaggio successivo in questa esercitazione.

Raccogli credenziali

Una volta aggiunta l’API al progetto, la pagina Experience Platform API del progetto visualizza le seguenti credenziali richieste in tutte le chiamate alle API di Experience Platform:

  • {API_KEY} (Client ID)
  • {IMS_ORG} (Organization ID)

Oltre alle credenziali di cui sopra, è necessario anche il Client Secret generato per un passaggio futuro. Selezionare Retrieve client secret per visualizzare il valore, quindi copiarlo per un uso successivo.

Generare un token web JSON (JWT)

Il passaggio successivo consiste nel generare un JSON Web Token (JWT) basato sulle credenziali del tuo account. Questo valore viene utilizzato per generare le credenziali {ACCESS_TOKEN} da utilizzare nelle chiamate API di Platform, che devono essere rigenerate ogni 24 ore.

Seleziona Service Account (JWT) nel menu di navigazione a sinistra, quindi seleziona Generate JWT.

Nella casella di testo fornita in Generate custom JWT, incolla il contenuto della chiave privata che hai generato in precedenza quando aggiungi l’API Platform al tuo account di servizio. Quindi, seleziona Generate Token.

La pagina viene aggiornata per mostrare il JWT generato, insieme a un comando cURL di esempio che consente di generare un token di accesso. Ai fini di questa esercitazione, seleziona Copy accanto a Generated JWT per copiare il token negli Appunti.

Generare un token di accesso

Dopo aver generato un JWT, puoi utilizzarlo in una chiamata API per generare il tuo {ACCESS_TOKEN}. A differenza dei valori per {API_KEY} e {IMS_ORG}, per continuare a utilizzare le API di Platform è necessario generare un nuovo token ogni 24 ore.

Richiesta

La seguente richiesta genera un nuovo {ACCESS_TOKEN} in base alle credenziali fornite nel payload. Questo endpoint accetta solo i dati del modulo come payload, pertanto deve essere fornito un'intestazione Content-Type di multipart/form-data.

curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'
Proprietà Descrizione
{API_KEY} Il {API_KEY} (Client ID) recuperato in un passaggio precedente.
{SECRET} Il segreto client recuperato in un passaggio precedente.
{JWT} JWT generato in un passaggio precedente.
NOTA

Puoi utilizzare la stessa chiave API, lo stesso segreto client e JWT per generare un nuovo token di accesso per ogni sessione. Questo consente di automatizzare la generazione di token di accesso nelle applicazioni.

Risposta

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
Proprietà Descrizione
token_type Tipo di token restituito. Per i token di accesso, questo valore è sempre bearer.
access_token Il {ACCESS_TOKEN} generato. Questo valore, con il prefisso Bearer, è obbligatorio come intestazione Authentication per tutte le chiamate API di Platform.
expires_in Il numero di millisecondi che rimangono fino alla scadenza del token di accesso. Una volta che questo valore raggiunge 0, è necessario generare un nuovo token di accesso per continuare a utilizzare le API di Platform.

Verificare le credenziali di accesso

Dopo aver raccolto tutte e tre le credenziali richieste, puoi provare a effettuare la seguente chiamata API. Questa chiamata elenca tutte le classi Experience Data Model standard (XDM) disponibili per la tua organizzazione.

Richiesta

curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'

Risposta

Se la risposta è simile a quella mostrata di seguito, le credenziali sono valide e funzionanti. Questa risposta è stata troncata per lo spazio.

{
  "results": [
    {
        "title": "XDM ExperienceEvent",
        "$id": "https://ns.adobe.com/xdm/context/experienceevent",
        "meta:altId": "_xdm.context.experienceevent",
        "version": "1"
    },
    {
        "title": "XDM Individual Profile",
        "$id": "https://ns.adobe.com/xdm/context/profile",
        "meta:altId": "_xdm.context.profile",
        "version": "1"
    }
  ]
}

Utilizzare Postman per autenticare e testare le chiamate API

🔗 Postmanis uno strumento popolare che consente agli sviluppatori di esplorare e testare le API RESTful. Questo post medio descrive come impostare Postman per eseguire automaticamente l'autenticazione JWT e utilizzarlo per utilizzare le API di Platform.

Passaggi successivi

Leggendo questo documento, hai raccolto e verificato con successo le credenziali di accesso per le API di Platform. Ora puoi seguire l'esempio di chiamate API fornite nella documentazione.

Oltre ai valori di autenticazione raccolti in questa esercitazione, molte API di Platform richiedono anche un {SANDBOX_NAME} valido da fornire come intestazione. Per ulteriori informazioni, consulta la panoramica sulle sandbox .

In questa pagina