Guida introduttiva alle API di Adobe Experience Platform

Adobe Experience Platform si sviluppa sotto una filosofia "API first". Utilizzando le API di Platform, puoi eseguire in modo programmatico operazioni CRUD di base (Crea, Leggi, Aggiorna, Elimina) in base ai dati, come 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 per ogni servizio Experience Platform condividono tutti lo stesso set di intestazioni di autenticazione e utilizzano sintassi simili per le loro operazioni CRUD. La guida seguente illustra i passaggi necessari per iniziare a utilizzare le API di Platform.

Autenticazione e intestazioni

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

  • Authorization: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Intestazione Sandbox

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

  • x-sandbox-name: {SANDBOX_NAME}

Per ulteriori informazioni sulle sandbox in Platform, consulta la sezione documentazione panoramica su sandbox.

Intestazione del tipo di contenuto

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

Experience Platform di base API

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

Per ulteriori informazioni sulle tecnologie API sottostanti che Platform utilizza, inclusi gli oggetti schema JSON, visita il Experience Platform di base API guida.

Raccolte Postman per API di Experience Platform

Postman è una piattaforma di collaborazione per lo sviluppo 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 Platform dispone di raccolte Postman che possono essere utilizzate per facilitare l’esecuzione di chiamate API.

Per ulteriori informazioni su Postman, tra cui come impostare un ambiente, un elenco delle raccolte disponibili e come importare le raccolte, visita il Documentazione di Platform Postman.

Lettura di chiamate API di esempio

I formati di richiesta variano a seconda dell’API Platform utilizzata. Il modo migliore per strutturare le chiamate API è seguire gli esempi forniti nella documentazione del particolare servizio Platform che utilizzi.

La documentazione di Experience Platform mostra esempi di chiamate API in due modi diversi. In primo luogo, la chiamata è presentata nella sua Formato API, una rappresentazione del 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 la modalità di formulazione di 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 con successo con l’API. Il percorso di base deve essere pre-apposto a tutti gli endpoint. Ad esempio, /global/classes endpoint diventa https://platform.adobe.io/data/foundation/schemaregistry/global/classes. Vedrai il formato/modello di richiesta API in tutta la documentazione e devi utilizzare il percorso completo mostrato nella richiesta di esempio quando effettui chiamate alle API di Platform.

Esempio di richiesta API

Di seguito è riportato un esempio di richiesta API che dimostra il formato che verrà mostrato 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 questa richiesta di esempio, alle variabili del formato API vengono dati i valori effettivi nel percorso della richiesta. Inoltre, tutte le intestazioni richieste sono mostrate 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: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'

Risposta

La risposta illustra cosa ci si aspetta di ricevere in seguito a una chiamata all’API riuscita, in base alla richiesta inviata. Talvolta la risposta viene troncata per lo 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 Platform fornisce un elenco degli errori che si possono verificare quando si utilizza un servizio Experience Platform.

Per le guide alla risoluzione dei problemi sui singoli servizi di Platform, consulta la sezione directory di risoluzione dei problemi del servizio.

Per ulteriori informazioni su endpoint specifici nelle API di Platform, comprese le intestazioni richieste e i corpi di richiesta, consulta la sezione Guide all’API di Platform.

Guide all’API di Platform

Guida dell’API di Descrizione
Guida dell’API di Access Control La Access Control L’endpoint API può recuperare i criteri correnti in vigore per un utente per determinate risorse all’interno di una sandbox specifica. Tutte le altre funzionalità di controllo degli accessi sono fornite tramite Adobe Admin Console.
Guida all’API per l’acquisizione in batch Adobe Experience Platform Data Ingestion L’API ti consente di acquisire dati in Platform come file batch. I dati da acquisire possono essere i dati di profilo di un file flat in un sistema CRM (ad esempio un file Parquet) o dati conformi a uno schema noto nel Registro di sistema dello schema (XDM).
Guida dell’API di Catalog Service La Catalog Service L’API consente agli sviluppatori di gestire i metadati del set di dati in Adobe Experience Platform. Ciò include le posizioni dei dati, le fasi di elaborazione, gli errori verificatisi durante l’elaborazione e i rapporti sui dati.
Guida dell’API di Data Access La Data Access L’API consente agli sviluppatori di recuperare informazioni sui set di dati acquisiti in Experience Platform. Ciò include l'accesso e il download di file di set di dati, il recupero delle informazioni di intestazione, l'elenco dei batch con errore e con esito positivo e il download di file CSV/parquet di anteprima.
Guida dell’API di Dataset Service L’API del servizio Dataset consente di applicare e modificare le etichette di utilizzo per i set di dati. Fa parte delle funzionalità del catalogo dati di Adobe Experience Platform, ma è separato dall’API del servizio catalogo che gestisce i metadati del set di dati.
Guida dell’API di Identity Service La Identity Service L’API consente agli sviluppatori di gestire l’identificazione dei clienti in tempo reale, tra dispositivi e canali, utilizzando grafici di identità in Adobe Experience Platform.
Guida dell’API di Observability Insights Observability Insights è un’API RESTful che consente agli sviluppatori di esporre le metriche di osservabilità chiave in Adobe Experience Platform. Queste metriche forniscono informazioni approfondite sulle statistiche di utilizzo di Platform, sui controlli di integrità per i servizi Platform, sulle tendenze della cronologia e sugli indicatori di prestazioni per varie funzionalità di Platform.
Policy Service Guida all’API
(Governance dei dati)
La Policy Service L’API ti consente di creare e gestire le etichette e i criteri di utilizzo dei dati per determinare quali azioni di marketing possono essere eseguite rispetto ai dati che contengono alcune etichette di utilizzo dei dati. Per applicare etichette ai set di dati e ai campi, consulta Dataset Service API guida
Guida dell’API di Privacy Service La Privacy Service L’API consente agli sviluppatori di creare e gestire le richieste dei clienti per accedere o cancellare i loro dati personali tra le applicazioni Experience Cloud, in conformità alle normative sulla privacy legali.
Guida dell’API di Query Service La Query Service L’API consente agli sviluppatori di eseguire query sui dati Adobe Experience Platform utilizzando SQL standard.
Guida dell’API di Real-time Customer Profile L’API Profilo cliente in tempo reale consente agli sviluppatori di esplorare e lavorare con i dati del profilo, inclusa la visualizzazione dei profili, la creazione e l’aggiornamento di criteri di unione, l’esportazione o il campionamento dei dati del profilo e l’eliminazione dei dati del profilo che non sono più necessari o sono stati aggiunti per errore.
Guida all’API per sandbox L’API Sandbox consente agli sviluppatori di gestire in modo programmatico gli ambienti sandbox virtuali isolati in Adobe Experience Platform.
Schema Registry Guida all’API
(XDM)
La Schema Registry L’API consente agli sviluppatori di gestire in modo programmatico tutti gli schemi e le relative risorse Experience Data Model (XDM) all’interno di Adobe Experience Platform.
Guida dell’API di Segmentation Service La Segmentation Service L’API consente agli sviluppatori di gestire le operazioni di segmentazione in modo programmatico in Adobe Experience Platform. Ciò include la creazione di segmenti e la generazione di tipi di pubblico dai dati del profilo cliente in tempo reale.
Sensei Machine Learning Guida all’API
(Data Science Workspace)
La Sensei Machine Learning API fornisce un meccanismo per gli scienziati dei dati per organizzare e gestire i servizi di machine learning (ML) dall’onboarding degli algoritmi, dalla sperimentazione e dall’implementazione dei servizi.

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

Passaggi successivi

Questo documento illustra 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 a Adobe Experience Platform, seleziona un endpoint API da esplorare dalla pagina Tabella delle guide per l’API di Platform.

Per le risposte alle domande frequenti, consulta la sezione Guida alla risoluzione dei problemi di Platform.

Per impostare un ambiente Postman ed esplorare le raccolte Postman disponibili, consulta Guida di Platform Postman.

In questa pagina