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 di questa esercitazione, avrai generato o raccolto le seguenti credenziali, necessarie come intestazioni in tutte le chiamate API di Platform:

  • {ACCESS_TOKEN}
  • {API_KEY}
  • {ORG_ID}
TIP
Oltre alle tre credenziali di cui sopra, molte API di Platform richiedono anche una {SANDBOX_NAME} da fornire come intestazione. Consulta la panoramica sulle sandbox per ulteriori informazioni sulle sandbox e endpoint di gestione sandbox per informazioni sull’elenco delle sandbox disponibili per la tua organizzazione.

Per mantenere la sicurezza delle applicazioni e degli utenti, tutte le richieste alle API Experienci Platform devono essere autenticate e autorizzate utilizzando standard come OAuth.

Questo tutorial illustra come raccogliere le credenziali necessarie per autenticare le chiamate API di Platform, come descritto nel diagramma di flusso seguente. È possibile raccogliere la maggior parte delle credenziali richieste nella configurazione iniziale una tantum. Il token di accesso, tuttavia, deve essere aggiornato ogni 24 ore.

Prerequisiti prerequisites

Per effettuare correttamente le chiamate alle API Experienci Platform, è necessario disporre dei seguenti elementi:

  • Organizzazione con accesso a Adobe Experience Platform.
  • Un amministratore di Admin Console che può aggiungerti come sviluppatore e utente per un profilo di prodotto.
  • Un amministratore di Experience Platform che può concederti i controlli di accesso basati su attributi necessari per eseguire operazioni di lettura o scrittura su parti diverse di Experienci Platform tramite API.

Per completare questa esercitazione è necessario disporre anche di un Adobe ID. Se non disponi di un’Adobe ID, puoi crearne una seguendo questi passaggi:

  1. Vai a Console Adobe Developer.
  2. Seleziona Crea un nuovo account.
  3. Completa il processo di registrazione.

Ottieni l’accesso di sviluppatori e utenti, ad Experience Platform gain-developer-user-access

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

Accesso per sviluppatori gain-developer-access

Contatta un Admin Console per aggiungerti come sviluppatore a un profilo di prodotto di Experience Platform utilizzando Admin Console. Consulta la Admin Console documentazione per istruzioni specifiche su come gestire l’accesso degli sviluppatori per i profili di prodotto.

Una volta che ti è stato assegnato come sviluppatore, puoi iniziare a creare integrazioni in Console Adobe Developer. Queste integrazioni sono una pipeline da app e servizi esterni alle API Adobe.

Ottenere l’accesso utente gain-user-access

Il tuo Admin Console l’amministratore deve anche aggiungerti come utente allo stesso profilo di prodotto. Con l’accesso utente, puoi visualizzare nell’interfaccia utente il risultato delle operazioni API eseguite.

Consulta la guida su gestione dei gruppi di utenti in Admin Console per ulteriori informazioni.

Generare una chiave API (ID client) e un ID organizzazione generate-credentials

NOTE
Se stai seguendo questo documento da Guida all’API di Privacy Service, è ora possibile tornare a tale guida per generare le credenziali di accesso univoche per Privacy Service.

Dopo aver ottenuto l’accesso a Platform da parte di sviluppatori e utenti tramite Admin Console, il passaggio successivo consiste nel generare {ORG_ID} e {API_KEY} credenziali nella console Adobe Developer. Queste credenziali devono essere generate solo una volta e possono essere riutilizzate nelle chiamate API future di Platform.

Aggiungere un Experience Platform a un progetto add-platform-to-project

Vai a Adobe Developer Console e accedi con il tuo Adobe ID. Quindi, segui i passaggi descritti nel tutorial su creazione di un progetto vuoto nella documentazione della console Adobe Developer.

Dopo aver creato un nuovo progetto, seleziona Aggiungi API il Panoramica del progetto schermo.

TIP
Se disponi del provisioning per più organizzazioni, utilizza il selettore organizzazione nell’angolo superiore destro dell’interfaccia per assicurarti di essere nell’organizzazione necessaria.

Nella schermata Console sviluppatori è evidenziata l’opzione Aggiungi API.

Viene visualizzata la schermata Add an API (Aggiungi un’API). Seleziona l’icona del prodotto per Adobe Experience Platform, quindi scegli API EXPERIENCI PLATFORM prima di selezionare Successivo.

Seleziona Experienci Platform API.

TIP
Seleziona la Visualizza documenti per passare in una finestra del browser separata al Documentazione di riferimento dell’API Experienci Platform.

Seleziona il tipo di autenticazione server-to-server OAuth select-oauth-server-to-server

Quindi, seleziona il tipo di autenticazione per generare token di accesso e accedere all’API Experienci Platform.

IMPORTANT
Seleziona la OAuth Server-to-Server poiché questo sarà l’unico metodo supportato per andare avanti. Il Account di servizio (JWT) è obsoleto. Anche se le integrazioni che utilizzano il metodo di autenticazione JWT continueranno a funzionare fino al 1° gennaio 2025, Adobe consiglia vivamente di migrare le integrazioni esistenti al nuovo metodo server-to-server OAuth prima di tale data. Ulteriori informazioni nella sezione+----------------+ | badge negative | +================+ | Obsoleto | +----------------+Generare un token web JSON (JWT).

Seleziona Experienci Platform API.

Selezionare i profili di prodotto per l’integrazione select-product-profiles

In Configurare API schermata, seleziona AEP-Default-All-Users.

IMPORTANT
Per accedere a determinate funzioni di Platform, è necessario disporre anche di un amministratore di sistema per concedere le autorizzazioni di controllo dell’accesso basate su attributi necessarie. Ulteriori informazioni nella sezione Ottenere le autorizzazioni di controllo dell'accesso basate su attributi necessarie.

Seleziona i profili di prodotto per la tua integrazione.

Seleziona Salva API configurata quando sei pronto.

Nell’esercitazione video seguente è disponibile anche una procedura dettagliata per configurare un’integrazione con l’API Experienci Platform:

Raccogli le credenziali gather-credentials

Una volta aggiunta l’API al progetto, la API EXPERIENCI PLATFORM Nella pagina del progetto vengono visualizzate le seguenti credenziali necessarie in tutte le chiamate alle API Experienci Platform:

Informazioni sull’integrazione dopo l’aggiunta di un’API in Developer Console.

  • {API_KEY} (ID client)
  • {ORG_ID} (ID organizzazione)

Generare un token di accesso generate-access-token

Il passaggio successivo consiste nel generare un {ACCESS_TOKEN} credenziali da utilizzare nelle chiamate API di Platform. A differenza dei valori per {API_KEY} e {ORG_ID}, per continuare a utilizzare le API di Platform, è necessario generare un nuovo token ogni 24 ore. Seleziona Genera token di accesso, come illustrato di seguito.

Mostra come generare il token di accesso

TIP
Puoi inoltre utilizzare un ambiente e una raccolta Postman per generare i token di accesso. Per ulteriori informazioni, consulta la sezione su utilizzo di Postman per autenticare e testare le chiamate API.

Obsoletogenera un token web JSON (JWT) jwt

WARNING
Il metodo JWT per generare i token di accesso è stato dichiarato obsoleto. Tutte le nuove integrazioni devono essere create utilizzando Metodo di autenticazione server-to-server OAuth. Adobe consiglia inoltre di migrare le integrazioni esistenti al metodo OAuth. Leggi la seguente documentazione importante:
Visualizza informazioni obsolete

Il passaggio successivo consiste nel generare un token web JSON (JWT) in base alle credenziali del tuo account. Questo valore viene utilizzato per generare il {ACCESS_TOKEN} credenziali da utilizzare nelle chiamate API di Platform, che devono essere rigenerate ogni 24 ore.

note important
IMPORTANT
Ai fini di questa esercitazione, i passaggi seguenti descrivono come generare un JWT in Developer Console. Tuttavia, questo metodo di generazione dovrebbe essere utilizzato solo a fini di prova e valutazione.
Per un uso regolare, il JWT deve essere generato automaticamente. Per ulteriori informazioni su come generare JWT a livello di programmazione, consulta guida all’autenticazione dell’account di servizio su Adobe Developer.

Seleziona Account di servizio (JWT) nel menu di navigazione a sinistra, seleziona quindi Genera JWT.

Nella casella di testo fornita in Generare un JWT personalizzato, incolla il contenuto della chiave privata generata in precedenza durante l’aggiunta dell’API Platform all’account del servizio. Quindi, seleziona Genera 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 del presente tutorial, seleziona Copia accanto a JWT generato 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 {ORG_ID}, per continuare a utilizzare le API di Platform, è necessario generare un nuovo token ogni 24 ore.

Richiesta

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

code language-shell
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}'
table 0-row-2 1-row-2 2-row-2 3-row-2
Proprietà Descrizione
{API_KEY} Il {API_KEY} (ID client) recuperate in un passaggio precedente.
{SECRET} Il segreto client recuperato in un passaggio precedente.
{JWT} Il JWT generato in un passaggio precedente.
note note
NOTE
Puoi utilizzare la stessa chiave API, lo stesso segreto client e lo stesso JWT per generare un nuovo token di accesso per ogni sessione. Questo consente di automatizzare la generazione dei token di accesso nelle applicazioni.

Risposta

code language-json
{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}
table 0-row-2 1-row-2 2-row-2 3-row-2
Proprietà Descrizione
token_type Il tipo of token restituito. Per i token di accesso questo valore è sempre bearer.
access_token Il valore generato {ACCESS_TOKEN}. Questo valore è preceduto dalla parola Bearer, è richiesto in quanto Authentication intestazione per tutte le chiamate API di Platform.
expires_in Il numero di millisecondi rimanenti fino alla scadenza del token di accesso. Quando questo valore raggiunge 0, è necessario generare un nuovo token di accesso per continuare a utilizzare le API di Platform.

Verifica credenziali di accesso test-credentials

Dopo aver raccolto tutte e tre le credenziali richieste (token di accesso, chiave API e ID organizzazione), puoi provare ad effettuare la seguente chiamata API. Questa chiamata elenca tutti gli standard Experience Data Model (XDM) classi disponibili per la tua organizzazione. Importare ed eseguire la chiamata in Postman.

recommendation-more-help

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: {{ORG_ID}}'

Risposta

Se la risposta è simile a quella mostrata di seguito, le credenziali sono valide e funzionanti. (La risposta è stata troncata per motivi di 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"
    }
  ]
}
IMPORTANT
Anche se la chiamata precedente è sufficiente per testare le credenziali di accesso, non sarà possibile accedere a o modificare diverse risorse senza disporre delle autorizzazioni di controllo dell’accesso basate su attributi corretti. Per ulteriori informazioni, consulta Ottenere le autorizzazioni di controllo dell'accesso basate su attributi necessarie sezione successiva.

Ottenere le autorizzazioni di controllo dell'accesso basate su attributi necessarie get-abac-permissions

Per accedere a o modificare diverse risorse all’interno di Experienci Platform, è necessario disporre delle autorizzazioni di controllo di accesso appropriate. Gli amministratori di sistema possono concedere autorizzazioni necessarie. Per ulteriori informazioni, consulta la sezione su gestione delle credenziali API per un ruolo.

Informazioni dettagliate su come un amministratore di sistema può concedere le autorizzazioni necessarie per accedere alle risorse Platform tramite l’API sono disponibili anche nel tutorial video seguente:

Utilizzare Postman per autenticare e testare le chiamate API use-postman

Postman è uno strumento popolare che consente agli sviluppatori di esplorare e testare le API RESTful. Puoi utilizzare le raccolte e gli ambienti Postman di Experienci Platform per velocizzare il lavoro con le API Experienci Platform. Ulteriori informazioni su utilizzo di Postman in Experienci Platform e la guida introduttiva alle raccolte e agli ambienti.

Informazioni dettagliate sull’utilizzo di Postman con raccolte e ambienti di Experienci Platform sono disponibili anche nei tutorial video seguenti:

Scaricare e importare un ambiente Postman da utilizzare con le API Experienci Platform

Utilizzare una raccolta Postman per generare i token di accesso

Scarica il file Raccolta Postman del servizio Identity Management guarda il video seguente per scoprire come generare i token di accesso.

Scarica raccolte Postman di API Experienci Platform e interagisce con le API

Amministratori di sistema: concedere agli sviluppatori e al controllo dell’accesso API autorizzazioni Experienci Platform grant-developer-and-api-access-control

NOTE
Solo gli amministratori di sistema possono visualizzare e gestire le credenziali API in Autorizzazioni.

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

Aggiungere sviluppatori al profilo di prodotto add-developers-to-product-profile

Vai a Admin Console e accedi con il tuo Adobe ID.

Seleziona Prodotti, quindi seleziona Adobe Experience Platform dall’elenco dei prodotti.

Elenco prodotti su Admin Console

Dalla sezione Profili di prodotto , seleziona AEP-Default-All-Users. In alternativa, utilizza la barra di ricerca per cercare il profilo di prodotto inserendo il nome.

Cercare il profilo prodotto

Seleziona la Sviluppatori , quindi seleziona Aggiungi sviluppatore.

Aggiungere uno sviluppatore dalla scheda Sviluppatori

Immetti il E-mail o nome utente. Un valore valido E-mail o nome utente visualizzerà i dettagli dello sviluppatore. Seleziona Salva.

Aggiungi sviluppatore utilizzando il suo nome utente o e-mail

Lo sviluppatore è stato aggiunto correttamente e viene visualizzato nel Sviluppatori scheda.

Sviluppatori elencati nella scheda Sviluppatori

Assegnare API a un ruolo

Un amministratore di sistema può assegnare le API ai ruoli nell’interfaccia utente di Experienci Platform.

Seleziona Autorizzazioni e il ruolo a cui desideri aggiungere l’API. Seleziona la Credenziali API , quindi seleziona Aggiungi credenziali API.

Scheda Credenziali API nel ruolo selezionato

Seleziona l’API da aggiungere al ruolo, quindi seleziona Salva.

Elenco delle API disponibili per la selezione

Viene visualizzata di nuovo la Credenziali API , in cui è elencata la nuova API aggiunta.

Scheda Credenziali API con API appena aggiunta

Risorse aggiuntive additional-resources

Per ulteriori informazioni introduttive sulle API di Experienci Platform, consulta le risorse aggiuntive elencate di seguito

Passaggi successivi next-steps

Una volta letto questo documento, hai raccolto e verificato correttamente le credenziali di accesso per le API di Platform. Ora puoi seguire insieme agli esempi di chiamate API fornite in documentazione.

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

5741548a-2e07-44b3-9157-9c181502d0c5