Guida dell’API di Catalog Service
Catalog Service è il sistema di registrazione per la posizione e la derivazione dei dati in Adobe Experience Platform. Catalog funge da archivio o "catalogo" di metadati in cui è possibile trovare informazioni sui dati in Experience Platform, senza dover accedere ai dati stessi. Per ulteriori informazioni, vedere Catalog panoramica.
Questa guida per sviluppatori descrive i passaggi per iniziare a utilizzare l’API di Catalog. La guida fornisce quindi esempi di chiamate API per eseguire operazioni chiave utilizzando Catalog.
Prerequisiti
Catalog tiene traccia dei metadati per diversi tipi di risorse e operazioni in Experience Platform. Questa guida per gli sviluppatori richiede una buona conoscenza dei vari servizi Experience Platform coinvolti nella creazione e gestione di queste risorse:
- Experience Data Model (XDM): framework standardizzato tramite il quale Platform organizza i dati sull'esperienza del cliente.
- Acquisizione in batch: in che modo Experience Platform acquisisce e memorizza i dati dai file di dati, ad esempio CSV e Parquet.
- Acquisizione in streaming: in che modo Experience Platform acquisisce e archivia dati da dispositivi lato client e lato server in tempo reale.
Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere o avere a disposizione per effettuare correttamente chiamate all'API Catalog Service.
Lettura delle chiamate API di esempio
Questa guida fornisce esempi di chiamate API per illustrare come formattare le richieste. Questi includono percorsi, intestazioni richieste e payload di richieste formattati correttamente. Viene inoltre fornito un codice JSON di esempio restituito nelle risposte API. Per informazioni sulle convenzioni utilizzate nella documentazione per le chiamate API di esempio, consulta la sezione su come leggere chiamate API di esempio nella guida alla risoluzione dei problemi di Experience Platform.
Raccogliere i valori per le intestazioni richieste
Per effettuare chiamate alle API Platform, devi prima completare l'esercitazione di autenticazione. Completando il tutorial sull’autenticazione si ottengono i valori per ciascuna delle intestazioni richieste in tutte le chiamate API di Experience Platform, come mostrato di seguito:
- Autorizzazione: Bearer
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Tutte le risorse in Experience Platform sono isolate in specifiche sandbox virtuali. Tutte le richieste alle API Platform richiedono un'intestazione che specifichi il nome della sandbox in cui verrà eseguita l'operazione:
- x-sandbox-name:
{SANDBOX_NAME}
Tutte le richieste che contengono un payload (POST, PUT, PATCH) richiedono un’intestazione aggiuntiva:
- Content-Type: application/json
Best practice per le chiamate API Catalog
Quando si eseguono richieste di GET all'API Catalog, è consigliabile includere parametri di query nelle richieste in modo da restituire solo gli oggetti e le proprietà necessarie. Le richieste non filtrate possono causare payload di risposta di dimensioni superiori a 3 GB, rallentando le prestazioni complessive.
È possibile visualizzare oggetti specifici includendo il relativo ID nel percorso della richiesta oppure utilizzare parametri di query come properties e limit per filtrare le risposte. I filtri possono essere passati come intestazioni e come parametri di query, con quelli passati come parametri di query che hanno la precedenza. Per ulteriori informazioni, vedere il documento relativo al filtro dei dati del catalogo 1.
Poiché alcune query possono comportare un carico pesante sull'API, sono stati implementati limiti globali sulle query Catalog per supportare ulteriormente le best practice.
Passaggi successivi
Questo documento tratta le conoscenze preliminari necessarie per effettuare chiamate alle API di Catalog. Ora puoi passare alle chiamate di esempio fornite in questa guida per sviluppatori e seguire le relative istruzioni.
La maggior parte degli esempi in questa guida utilizza l'endpoint /dataSets, ma i principi possono essere applicati ad altri endpoint in Catalog (ad esempio /batches). Per un elenco completo di tutte le chiamate e operazioni disponibili per ogni endpoint, vedere il riferimento API di Catalog Service.
Per un flusso di lavoro dettagliato che illustra il modo in cui l'API Catalog è coinvolta nell'acquisizione dei dati, vedere l'esercitazione sulla creazione di un set di dati.