Autenticazione e accesso alle API di Experience Platform

Questo documento fornisce un tutorial dettagliato per accedere a un account sviluppatore Adobe Experience Platform per effettuare chiamate alle API Experience Platform. Al termine di questa esercitazione, avrai generato o raccolto le seguenti credenziali, necessarie come intestazioni in tutte le chiamate API di Platform:

Per mantenere la sicurezza delle applicazioni e degli utenti, tutte le richieste alle API Experience 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 Experience Platform, è necessario disporre dei seguenti elementi:

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

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 amministratore Admin Console della tua organizzazione per aggiungerti come sviluppatore a un profilo di prodotto Experience Platform utilizzando Admin Console. Consulta la documentazione di Admin Console per istruzioni specifiche su come gestire l'accesso degli sviluppatori per i profili di prodotto.

Una volta assegnati come sviluppatori, puoi iniziare a creare integrazioni in Adobe Developer Console. Queste integrazioni sono una pipeline da app e servizi esterni alle API Adobe.

Ottenere l’accesso utente gain-user-access

L'amministratore di Admin Console deve aggiungere l'utente allo stesso profilo di prodotto. Con l’accesso utente, puoi visualizzare nell’interfaccia utente il risultato delle operazioni API eseguite.

Per ulteriori informazioni, consulta la guida sulla gestione dei gruppi di utenti in Admin Console🔗.

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

Dopo aver ottenuto l'accesso utente e sviluppatore a Platform tramite Admin Console, il passaggio successivo consiste nel generare le credenziali di {ORG_ID} e {API_KEY} in Adobe Developer Console. 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 di Adobe Developer Console.

Dopo aver creato un nuovo progetto, seleziona Aggiungi API nella schermata Panoramica progetto.

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

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

Quindi, seleziona il tipo di autenticazione OAuth Server-to-Server per generare i token di accesso e accedere all'API Experience Platform.

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

Nella schermata Configura API, selezionare AEP-Default-All-Users.

Seleziona Salva API configurata quando sei pronto.

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

Raccogli le credenziali gather-credentials

Una volta aggiunta l'API al progetto, nella pagina Experience Platform API per il progetto vengono visualizzate le credenziali seguenti, necessarie in tutte le chiamate alle API Experience Platform:

Generare un token di accesso generate-access-token

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

Crea e recupera le credenziali di autenticazione direttamente nella documentazione di riferimento dell’API get-credentials-functionality

A partire dalla versione di novembre 2024 di Experience Platform, è possibile ottenere le credenziali per utilizzare le API Experience Platform direttamente dalle pagine di riferimento API, senza dover passare a Developer Console. Visualizza l'esempio seguente dalla pagina Destinazioni dell'API del servizio di flusso.

Per ottenere le credenziali per chiamare le API di Platform, passa a una pagina di riferimento API Experience Platform e seleziona Accedi nella parte superiore della pagina. Accedi con il tuo account personale o account aziendale o scolastico.

Dopo aver effettuato l'accesso, selezionare Crea nuova credenziale per creare un nuovo set di credenziali per accedere alle API di Platform.

Quindi, utilizza il selettore a discesa per aprire la finestra delle credenziali, generare un token di accesso e ottenere la chiave API e l’ID organizzazione. Copia le credenziali nei blocchi Prova nelle pagine di riferimento API per iniziare a lavorare con le API di Platform.

[Deprecato]{class="badge informative"} genera un token web JSON (JWT) jwt

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}'

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}

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 tutte le classi standard Experience Data Model (XDM) disponibili per la tua organizzazione. Importa ed esegui la chiamata in Postman.

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"
    }
  ]
}

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

Per accedere a o modificare diverse risorse all’interno di Experience Platform, è necessario disporre delle autorizzazioni di controllo di accesso appropriate. Gli amministratori di sistema possono concederti le autorizzazioni necessarie. Ulteriori informazioni nella sezione sulla 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 Experience Platform per velocizzare il lavoro con le API Experience Platform. Ulteriori informazioni su utilizzo di Postman in Experience Platform e guida introduttiva a raccolte e ambienti.

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

Scarica e importa un ambiente Postman da utilizzare con le API Experience Platform

Utilizzare una raccolta Postman per generare token di accesso

Scarica la raccolta Postman di Identity Management Service e guarda il video seguente per scoprire come generare i token di accesso.

Scarica raccolte Postman API Experience Platform e interagisce con le API

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

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.

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

Seleziona la scheda Sviluppatori, quindi seleziona Aggiungi sviluppatore.

Immetti Email o nome utente dello sviluppatore. Indirizzo e-mail o nome utente valido mostrerà i dettagli dello sviluppatore. Seleziona Salva.

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

Assegnare API a un ruolo

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

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

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

Si è tornati alla scheda Credenziali API, in cui è elencata la nuova API aggiunta.

Risorse aggiuntive additional-resources

Per ulteriori informazioni introduttive sulle API di Experience 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 alle chiamate API di esempio 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 delle sandbox.