Guida introduttiva alle API di Adobe Experience Platform

Adobe Experience Platform è sviluppato secondo la filosofia "API first". Utilizzando le API di Experience Platform, puoi eseguire in modo programmatico operazioni CRUD (Create, Read, Update, Delete) di base sui dati, ad esempio la configurazione di attributi calcolati, l’accesso a dati/entità, l’esportazione di dati, l’eliminazione di dati o batch non necessari e altro ancora.

Le API di ciascun servizio Experience Platform condividono tutte lo stesso set di intestazioni di autenticazione e utilizzano sintassi simili per le operazioni CRUD. La guida seguente illustra i passaggi necessari per iniziare a utilizzare le API di Experience Platform.

Autenticazione e intestazioni

Per effettuare correttamente le chiamate agli endpoint di Experience Platform, è necessario completare l'esercitazione sull'autenticazione. Il completamento del tutorial di autenticazione fornisce i valori per ciascuna delle intestazioni richieste nelle chiamate API di Experience Platform, come mostrato di seguito:

Intestazione sandbox

Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Le richieste alle API di Experience Platform richiedono un’intestazione che specifichi il nome della sandbox in cui verrà eseguita l’operazione:

Per ulteriori informazioni sulle sandbox in Experience Platform, consulta la documentazione di panoramica sulle sandbox.

Intestazione content-type

Tutte le richieste con un payload nel corpo della richiesta (come chiamate POST, PUT e PATCH) devono includere un'intestazione Content-Type. I valori accettati sono specifici per ogni endpoint API. Se è necessario un valore Content-Type specifico per un endpoint, il relativo valore verrà visualizzato nelle richieste API di esempio fornite dalle guide API per i singoli servizi Experience Platform.

Nozioni di base sulle API di Experience Platform

Le API di Adobe Experience Platform utilizzano diverse tecnologie e sintassi di base importanti da comprendere per gestire in modo efficace le risorse di Experience Platform.

Per ulteriori informazioni sulle tecnologie API di base utilizzate da Experience Platform, inclusi gli oggetti schema JSON di esempio, visita la guida sulle API di base di Experience Platform.

Raccolte di Postman per le API di Experience Platform

Postman è una piattaforma di collaborazione per lo sviluppo di API che consente di configurare ambienti con variabili preimpostate, condividere raccolte API, semplificare le richieste CRUD e altro ancora. La maggior parte dei servizi API di Experience Platform dispone di raccolte Postman che possono essere utilizzate per facilitare l’esecuzione di chiamate API.

Per ulteriori informazioni su Postman, tra cui la configurazione di un ambiente, un elenco delle raccolte disponibili e le modalità di importazione delle raccolte, visita la documentazione di Experience Platform Postman.

Lettura delle chiamate API di esempio sample-api

I formati delle richieste variano a seconda dell’API Experience Platform utilizzata. Il modo migliore per imparare a strutturare le chiamate API è seguire gli esempi forniti nella documentazione del particolare servizio Experience Platform che stai utilizzando.

La documentazione di Experience Platform mostra le chiamate API di esempio in due modi diversi. Innanzitutto, la chiamata viene presentata nel suo formato API, una rappresentazione di modello che mostra solo l'operazione (GET, POST, PUT, PATCH, DELETE) e l'endpoint utilizzato (ad esempio, /global/classes). Alcuni modelli mostrano anche la posizione delle variabili per illustrare come deve essere formulata una chiamata, ad esempio GET /{VARIABLE}/classes/{ANOTHER_VARIABLE}.

Le chiamate vengono quindi visualizzate come comandi cURL in una Richiesta, che include le intestazioni necessarie e il "percorso base" completo necessario per interagire correttamente con l'API. Il percorso di base deve essere preaperto a tutti gli endpoint. Ad esempio, l'endpoint /global/classes sopra indicato diventa https://platform.adobe.io/data/foundation/schemaregistry/global/classes. Vedrai il formato/modello di richiesta API in tutta la documentazione e utilizzerai il percorso completo mostrato nella richiesta di esempio quando effettui chiamate personalizzate alle API di Experience Platform.

Esempio di richiesta API

Di seguito è riportato un esempio di richiesta API che dimostra il formato che incontrerai nella documentazione.

Formato API

Il formato API mostra l’operazione (GET) e l’endpoint utilizzati. Le variabili sono indicate da parentesi graffe (in questo caso, {CONTAINER_ID}).

GET /{CONTAINER_ID}/classes

Richiesta

In questo esempio di richiesta, alle variabili del formato API vengono assegnati valori effettivi nel percorso della richiesta. Inoltre, tutte le intestazioni richieste vengono visualizzate come valori di intestazione di esempio o come variabili in cui devono essere incluse informazioni sensibili (come token di sicurezza e ID di accesso).

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}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

La risposta illustra cosa ci si aspetta di ricevere in seguito a una chiamata all’API con esito positivo, in base alla richiesta inviata. A volte la risposta viene troncata per motivi di spazio, il che significa che è possibile visualizzare ulteriori informazioni o informazioni aggiuntive rispetto a quelle visualizzate nell’esempio.

{
    "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"
        }
    ],
    "_links": {}
}

Messaggi di errore

La guida alla risoluzione dei problemi di Experience Platform fornisce un elenco di errori che possono verificarsi quando si utilizza un servizio Experience Platform.

Per le guide alla risoluzione dei problemi sui singoli servizi Experience Platform, vedere la directory per la risoluzione dei problemi dei servizi.

Per ulteriori informazioni su endpoint specifici nelle API di Experience Platform, incluse le intestazioni richieste e i corpi delle richieste, consulta le guide API di Experience Platform.

Guide API di Experience Platform api-guides

Per ulteriori informazioni su endpoint e operazioni specifici disponibili per ciascun servizio, consulta la documentazione di riferimento API su Adobe I/O.

Passaggi successivi

Questo documento presenta le intestazioni richieste, le guide disponibili e fornisce un esempio di chiamata API. Ora che disponi dei valori di intestazione richiesti per effettuare chiamate API su Adobe Experience Platform, seleziona un endpoint API da esplorare dalla tabella delle guide API di Experience Platform.

Per le risposte alle domande frequenti, fare riferimento alla Guida alla risoluzione dei problemi di Experience Platform.

Per configurare un ambiente Postman ed esplorare le raccolte Postman disponibili, consulta la guida di Experience Platform Postman.