Guida per gli sviluppatori sull’acquisizione in batch
Questo documento fornisce una guida completa all'utilizzo di endpoint API per l'acquisizione batch in Adobe Experience Platform. Per una panoramica delle API di acquisizione batch, inclusi i prerequisiti e le best practice, leggi la panoramica dell'API di acquisizione batch.
L'appendice di questo documento fornisce informazioni per i dati di formattazione da utilizzare per l'acquisizione, inclusi file di dati CSV e JSON di esempio.
Introduzione
Gli endpoint API utilizzati in questa guida fanno parte dell'API di acquisizione batch. L’acquisizione in batch viene fornita tramite un’API RESTful in cui puoi eseguire operazioni CRUD di base sui tipi di oggetto supportati.
Prima di continuare, controlla la panoramica dell'API di acquisizione batch e la guida introduttiva.
Acquisire file JSON
Crea batch
Innanzitutto, devi creare un batch, con JSON come formato di input. Durante la creazione del batch, dovrai fornire un ID set di dati. È inoltre necessario assicurarsi che tutti i file caricati come parte del batch siano conformi allo schema XDM collegato al set di dati fornito.
isMultiLineJson
. Per ulteriori informazioni, leggere la guida alla risoluzione dei problemi di acquisizione batch.Formato API
POST /batches
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
}
}'
{DATASET_ID}
Risposta
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
Carica file
Dopo aver creato un batch, puoi utilizzare l’ID batch dalla risposta di creazione del batch per caricare i file nel batch. Puoi caricare più file nel batch.
Formato API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'content-type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Risposta
200 OK
Batch completo
Una volta completato il caricamento di tutte le diverse parti del file, dovrai segnalare che i dati sono stati completamente caricati e che il batch è pronto per la promozione.
Formato API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Richiesta
curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Acquisire file Parquet ingest-parquet-files
Crea batch
In primo luogo, è necessario creare un batch, con Parquet come formato di input. Durante la creazione del batch, dovrai fornire un ID set di dati. È inoltre necessario assicurarsi che tutti i file caricati come parte del batch siano conformi allo schema XDM collegato al set di dati fornito.
Richiesta
curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "Content-Type: application/json" \
-H "x-gw-ims-org-id: {ORG_ID}" \
-H "x-api-key: {API_KEY}" \
-H "x-sandbox-name: {SANDBOX_NAME}"
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Risposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Carica file
Dopo aver creato un batch, è possibile utilizzare batchId
di prima per caricare i file nel batch. Puoi caricare più file nel batch.
Formato API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.parquet
.Risposta
200 OK
Batch completo
Una volta completato il caricamento di tutte le diverse parti del file, dovrai segnalare che i dati sono stati completamente caricati e che il batch è pronto per la promozione.
Formato API
POST /batches/{BATCH_ID}?action=complete
{BATCH_ID}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Acquisire file Parquet di grandi dimensioni
Crea batch
In primo luogo, è necessario creare un batch, con Parquet come formato di input. Durante la creazione del batch, dovrai fornire un ID set di dati. È inoltre necessario assicurarsi che tutti i file caricati come parte del batch siano conformi allo schema XDM collegato al set di dati fornito.
Formato API
POST /batches
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "parquet"
}
}'
{DATASET_ID}
Risposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Inizializza file di grandi dimensioni
Dopo aver creato il batch, sarà necessario inizializzare il file di grandi dimensioni prima di caricare i blocchi nel batch.
Formato API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=INITIALIZE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
201 Created
Carica blocchi di file di grandi dimensioni
Una volta creato il file, è possibile caricarne tutti i blocchi successivi effettuando ripetute richieste PATCH, una per ogni sezione del file.
Formato API
PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X PATCH https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'Content-Range: bytes {CONTENT_RANGE}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.parquet"
{CONTENT_RANGE}
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Risposta
200 OK
Completa file di grandi dimensioni
Dopo aver creato un batch, è possibile utilizzare batchId
di prima per caricare i file nel batch. Puoi caricare più file nel batch.
Formato API
POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
201 Created
Batch completo
Una volta completato il caricamento di tutte le diverse parti del file, dovrai segnalare che i dati sono stati completamente caricati e che il batch è pronto per la promozione.
Formato API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Acquisire file CSV
Per acquisire i file CSV, devi creare una classe, uno schema e un set di dati che supporti CSV. Per informazioni dettagliate su come creare la classe e lo schema necessari, seguire le istruzioni fornite nell'esercitazione per la creazione di schemi ad hoc.
Crea un set di dati
Dopo aver seguito le istruzioni precedenti per creare la classe e lo schema necessari, dovrai creare un set di dati che possa supportare CSV.
Formato API
POST /catalog/dataSets
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "{DATASET_NAME}",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
{TENANT_ID}
{SCHEMA_ID}
Crea batch
Successivamente, dovrai creare un batch con CSV come formato di input. Durante la creazione del batch, dovrai fornire un ID set di dati. È inoltre necessario assicurarsi che tutti i file caricati come parte del batch siano conformi allo schema collegato al set di dati fornito.
Formato API
POST /batches
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "csv"
}
}'
{DATASET_ID}
Risposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Carica file
Dopo aver creato un batch, è possibile utilizzare batchId
di prima per caricare i file nel batch. Puoi caricare più file nel batch.
Formato API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.csv \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.csv"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.csv
.Risposta
200 OK
Batch completo
Una volta completato il caricamento di tutte le diverse parti del file, dovrai segnalare che i dati sono stati completamente caricati e che il batch è pronto per la promozione.
Formato API
POST /batches/{BATCH_ID}?action=COMPLETE
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Annullare un batch
Durante l’elaborazione, il batch può comunque essere annullato. Tuttavia, una volta finalizzato un batch (ad esempio in caso di esito positivo o negativo), il batch non può essere annullato.
Formato API
POST /batches/{BATCH_ID}?action=ABORT
{BATCH_ID}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=ABORT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Eliminare un batch delete-a-batch
È possibile eliminare un batch eseguendo la seguente richiesta POST con il parametro di query action=REVERT
sull'ID del batch che si desidera eliminare. Il batch è contrassegnato come "inattivo", rendendolo idoneo per la raccolta di oggetti inattivi. Il batch verrà raccolto in modo asincrono e contrassegnato come "eliminato".
Formato API
POST /batches/{BATCH_ID}?action=REVERT
{BATCH_ID}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=REVERT \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Applicazione di patch a un batch
A volte può essere necessario aggiornare i dati nell’archivio profili della tua organizzazione. Ad esempio, potrebbe essere necessario correggere i record o modificare un valore di attributo. Adobe Experience Platform supporta l’aggiornamento o la patch dei dati dell’archivio profili tramite un’azione upsert o "l’applicazione di patch a un batch".
Per applicare la patch a un batch è necessario quanto segue:
- Set di dati abilitato per gli aggiornamenti di profili e attributi. Questa operazione viene eseguita tramite i tag del set di dati e richiede l'aggiunta di un tag
isUpsert:true
specifico all'arrayunifiedProfile
. Per i passaggi dettagliati che mostrano come creare un set di dati o configurare un set di dati esistente per l'upsert, segui l'esercitazione per abilitare un set di dati per gli aggiornamenti del profilo. - File di Parquet contenente i campi da applicare e i campi di identità per il profilo. Il formato dei dati per l'applicazione della patch a un batch è simile al normale processo di acquisizione batch. L’input richiesto è un file Parquet e, oltre ai campi da aggiornare, i dati caricati devono contenere i campi di identità in modo che corrispondano ai dati nell’archivio Profili.
Dopo aver abilitato un set di dati per Profilo e upsert e un file Parquet contenente i campi da applicare alla patch e i campi di identità necessari, puoi seguire i passaggi per acquisire i file Parquet per completare la patch tramite l'acquisizione batch.
Ripetere un batch
Se desideri sostituire un batch già acquisito, puoi farlo con "ripetizione batch": questa azione equivale all’eliminazione del batch precedente e all’acquisizione di un nuovo batch.
Crea batch
Innanzitutto, devi creare un batch, con JSON come formato di input. Durante la creazione del batch, dovrai fornire un ID set di dati. È inoltre necessario assicurarsi che tutti i file caricati come parte del batch siano conformi allo schema XDM collegato al set di dati fornito. Inoltre, devi fornire i vecchi batch come riferimento nella sezione di ripetizione. Nell'esempio seguente si stanno riproducendo i batch con ID batchIdA
e batchIdB
.
Formato API
POST /batches
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"datasetId": "{DATASET_ID}",
"inputFormat": {
"format": "json"
},
"replay": {
"predecessors": ["${batchIdA}","${batchIdB}"],
"reason": "replace"
}
}'
{DATASET_ID}
Risposta
201 Created
{
"id": "{BATCH_ID}",
"imsOrg": "{ORG_ID}",
"updated": 0,
"status": "loading",
"created": 0,
"relatedObjects": [
{
"type": "dataSet",
"id": "{DATASET_ID}"
}
],
"replay": {
"predecessors": [
"batchIdA", "batchIdB"
],
"reason": "replace"
},
"version": "1.0.0",
"tags": {},
"createdUser": "{USER_ID}",
"updatedUser": "{USER_ID}"
}
{BATCH_ID}
{DATASET_ID}
{USER_ID}
Carica file
Dopo aver creato un batch, è possibile utilizzare batchId
di prima per caricare i file nel batch. Puoi caricare più file nel batch.
Formato API
PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
{BATCH_ID}
{DATASET_ID}
{FILE_NAME}
Richiesta
curl -X PUT https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.json \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/octet-stream' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
--data-binary "@{FILE_PATH_AND_NAME}.json"
{FILE_PATH_AND_NAME}
acme/customers/campaigns/summer.json
.Risposta
200 OK
Batch completo
Una volta completato il caricamento di tutte le diverse parti del file, dovrai segnalare che i dati sono stati completamente caricati e che il batch è pronto per la promozione.
Formato API
POST /batches/{BATCH_ID}?action=COMPLETE
{BATCH_ID}
Richiesta
curl -X POST https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
200 OK
Appendice
La sezione seguente contiene informazioni aggiuntive per l’acquisizione di dati in Experience Platform tramite l’acquisizione batch.
Trasformazione dei dati per l’acquisizione batch
Per acquisire un file di dati in Experience Platform, la struttura gerarchica del file deve essere conforme allo schema Experience Data Model (XDM) associato al set di dati in fase di caricamento in.
Le informazioni su come mappare un file CSV in modo che sia conforme a uno schema XDM si trovano nel documento trasformazioni di esempio, insieme a un esempio di file di dati JSON formattato correttamente. I file di esempio forniti nel documento sono disponibili qui: