Panoramica API per l’acquisizione in batch

L’API di acquisizione dati di Adobe Experience Platform consente di acquisire dati in Platform come file batch. I dati da acquisire possono essere dati di profilo provenienti da un file flat (ad esempio un file Parquet) o dati conformi a uno schema noto nel Experience Data Model (XDM).

La Riferimento API per l’acquisizione dei dati fornisce informazioni aggiuntive su queste chiamate API.

Il diagramma seguente illustra il processo di acquisizione batch:

Introduzione

Gli endpoint API utilizzati in questa guida fanno parte del API di acquisizione dati. Prima di continuare, controlla la guida introduttiva per i collegamenti alla documentazione correlata, una guida alla lettura delle chiamate API di esempio in questo documento e importanti informazioni sulle intestazioni richieste necessarie per effettuare correttamente le chiamate a qualsiasi API di Experience Platform.

Data Ingestion prerequisiti

• I dati da caricare devono essere in formato Parquet o JSON.
• Un set di dati creato in Catalog services.
• Il contenuto del file Parquet deve corrispondere a un sottoinsieme dello schema del set di dati in cui viene caricato.
• Richiedi il token di accesso univoco dopo l’autenticazione.

Best practice per l’acquisizione in batch

• La dimensione consigliata del batch è compresa tra 256 MB e 100 GB.
• Ogni batch deve contenere al massimo 1500 file.

Vincoli di inserimento in batch

L’inserimento dei dati in batch presenta alcuni vincoli:

• Numero massimo di file per batch: 1500
• Dimensione massima del batch: 100 GB
• Numero massimo di proprietà o campi per riga: 10000
• Numero massimo di batch al minuto per utente: 138

Tipi

Durante l’acquisizione dei dati, è importante comprendere come Experience Data Model Gli schemi (XDM) funzionano. Per ulteriori informazioni sulla mappatura dei tipi di campo XDM su formati diversi, consulta la sezione Guida per gli sviluppatori del Registro di sistema dello schema.

È possibile acquisire i dati in modo flessibile: se un tipo non corrisponde a quello presente nello schema di destinazione, i dati verranno convertiti nel tipo di destinazione espresso. In caso contrario, il batch non riuscirà con un TypeCompatibilityException.

Ad esempio, né JSON né CSV hanno un date o date-time digitare. Di conseguenza, questi valori vengono espressi utilizzando Stringhe formattate ISO 8061 ("2018-07-10T15:05:59.000-08:00") o Tempo Unix formattato in millisecondi (1531263959000) e convertito al momento dell’acquisizione nel tipo XDM di destinazione.

La tabella seguente mostra le conversioni supportate durante l’acquisizione dei dati.

Mediante l’API

La Data Ingestion L’API ti consente di acquisire i dati come batch (un’unità di dati costituita da uno o più file da acquisire come una singola unità) in Experience Platform in tre fasi di base:

1. Crea un nuovo batch.
2. Carica i file in un set di dati specifico che corrisponde allo schema XDM dei dati.
3. Segnala la fine del batch.

Creare un batch

Prima di poter aggiungere dati a un set di dati, questi devono essere collegati a un batch che verrà successivamente caricato in un set di dati specifico.

POST /batches

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "Content-Type: application/json" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"
  -d '{ 
          "datasetId": "{DATASET_ID}" 
      }'

Risposta

{
    "id": "{BATCH_ID}",
    "imsOrg": "{IMS_ORG}",
    "updated": 0,
    "status": "loading",
    "created": 0,
    "relatedObjects": [
        {
            "type": "dataSet",
            "id": "{DATASET_ID}"
        }
    ],
    "version": "1.0.0",
    "tags": {},
    "createdUser": "{USER_ID}",
    "updatedUser": "{USER_ID}"
}

Caricamento file

Dopo aver creato correttamente un nuovo batch per il caricamento, i file possono quindi essere caricati in un set di dati specifico.

Puoi caricare i file utilizzando l’API di caricamento file di piccole dimensioni. Tuttavia, se i file sono troppo grandi e il limite del gateway viene superato (ad esempio timeout estesi, richieste di dimensioni del corpo superate e altre restrizioni), puoi passare all’API di caricamento file di grandi dimensioni. Questa API carica il file in blocchi e unisce i dati utilizzando la chiamata API di caricamento file di grandi dimensioni Complete.

Caricamento di file di piccole dimensioni

Una volta creato un batch, i dati possono essere caricati in un set di dati preesistente. Il file caricato deve corrispondere al relativo schema XDM di riferimento.

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Richiesta

curl -X PUT "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Risposta

#Status 200 OK, with empty response body

Caricamento di file di grandi dimensioni - crea file

Per caricare un file di grandi dimensioni, è necessario suddividerlo in blocchi più piccoli e caricarlo uno alla volta.

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}?action=initialize

Richiesta

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet?action=initialize" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}"

Risposta

#Status 201 CREATED, with empty response body

Caricamento di file di grandi dimensioni - caricamento di parti successive

Dopo la creazione del file, è possibile caricare tutti i blocchi successivi effettuando richieste PATCH ripetute, una per ogni sezione del file.

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}

Richiesta

curl -X PATCH "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}/datasets/{DATASET_ID}/files/part1=a/part2=b/{FILE_NAME}.parquet" \
  -H "content-type: application/octet-stream" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "Content-Range: bytes {CONTENT_RANGE}" \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"

Risposta

#Status 200 OK, with empty response

Completamento batch del segnale

Dopo che tutti i file sono stati caricati nel batch, il batch può essere segnalato per il completamento. Facendo questo, il Catalog Le voci DataSetFile vengono create per i file completati e associate al batch generato in precedenza. La Catalog batch viene quindi contrassegnato come riuscito, che attiva i flussi a valle per acquisire i dati disponibili.

Richiesta

POST /batches/{BATCH_ID}?action=COMPLETE

curl -X POST "https://platform.adobe.io/data/foundation/import/batches/{BATCH_ID}?action=COMPLETE" \
-H "x-gw-ims-org-id: {IMS_ORG}" \
-H "x-sandbox-name: {SANDBOX_NAME}" \
-H "Authorization: Bearer {ACCESS_TOKEN}" \
-H "x-api-key: {API_KEY}"

Risposta

#Status 200 OK, with empty response

Verifica stato batch

In attesa del caricamento dei file nel batch, è possibile controllare lo stato del batch per verificarne l'avanzamento.

Formato API

GET /batch/{BATCH_ID}

Richiesta

curl GET "https://platform.adobe.io/data/foundation/catalog/batch/{BATCH_ID}" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Risposta

{
    "{BATCH_ID}": {
        "imsOrg": "{IMS_ORG}",
        "created": 1494349962314,
        "createdClient": "MCDPCatalogService",
        "createdUser": "{USER_ID}",
        "updatedUser": "{USER_ID}",
        "updated": 1494349963467,
        "externalId": "{EXTERNAL_ID}",
        "status": "success",
        "errors": [
            {
                "code": "err-1494349963436"
            }
        ],
        "version": "1.0.3",
        "availableDates": {
            "startDate": 1337,
            "endDate": 4000
        },
        "relatedObjects": [
            {
                "type": "batch",
                "id": "foo_batch"
            },
            {
                "type": "connection",
                "id": "foo_connection"
            },
            {
                "type": "connector",
                "id": "foo_connector"
            },
            {
                "type": "dataSet",
                "id": "foo_dataSet"
            },
            {
                "type": "dataSetView",
                "id": "foo_dataSetView"
            },
            {
                "type": "dataSetFile",
                "id": "foo_dataSetFile"
            },
            {
                "type": "expressionBlock",
                "id": "foo_expressionBlock"
            },
            {
                "type": "service",
                "id": "foo_service"
            },
            {
                "type": "serviceDefinition",
                "id": "foo_serviceDefinition"
            }
        ],
        "metrics": {
            "foo": 1337
        },
        "tags": {
            "foo_bar": [
                "stuff"
            ],
            "bar_foo": [
                "woo",
                "baz"
            ],
            "foo/bar/foo-bar": [
                "weehaw",
                "wee:haw"
            ]
        },
        "inputFormat": {
            "format": "parquet",
            "delimiter": ".",
            "quote": "`",
            "escape": "\\",
            "nullMarker": "",
            "header": "true",
            "charset": "UTF-8"
        }
    }
}

La "status" Il campo indica lo stato corrente del batch richiesto. I batch possono avere uno dei seguenti stati:

Stati di inserimento batch