Batch IngestionÜbersicht

The Batch Ingestion API allows you to ingest data into Adobe Experience Platform as batch files. Data being ingested can be the profile data from a flat file in a CRM system (such as a parquet file), or data that conforms to a known schema in the Experience Data Model (XDM) registry.

Der Datenaufnahme-API-Verweis enthält weitere Informationen zu diesen API-Aufrufen.

Das folgende Diagramm zeigt den Vorgang der Batch-Erfassung.

Verwenden der API

The Data Ingestion API allows you to ingest data as batches (a unit of data that consists of one or more files to be ingested as a single unit) into Experience Platform in three basic steps:

Erstellen eines neuen Batches.
Hochladen von Dateien in einen angegebenen Datensatz, der dem XDM-Schema der Daten entspricht.
Signalisieren des Batch-Endes.

Data Ingestion Voraussetzungen

Die hochzuladenden Daten müssen im Parquet- oder JSON-Format vorliegen.
Ein Datensatz, der in der Catalog servicesDatei erstellt wurde.
Der Inhalt der Parquet-Datei muss mit einer Untergruppe des Schemas des hochgeladenen Datensatzes übereinstimmen.
Lassen Sie sich nach der Authentifizierung Ihr eindeutiges Zugriffstoken anzeigen.

Best Practices zur Batch-Erfassung

Die empfohlene Batch-Größe liegt zwischen 256 MB und 100 GB.
Jeder Batch sollte maximal 1500 Dateien enthalten.

Um eine Datei hochzuladen, die größer als 512 MB ist, muss die Datei in kleinere Abschnitte unterteilt werden. Anweisungen zum Hochladen einer großen Datei finden Sie hier.

Lesen von Beispiel-API-Aufrufen

In diesem Handbuch wird anhand von Beispielen für API-Aufrufe die korrekte Formatierung von Anfragen aufgezeigt. Dazu gehören Pfade, erforderliche Kopfzeilen und ordnungsgemäß formatierte Anfrage-Payloads. Außerdem wird ein Beispiel für eine von der API im JSON-Format zurückgegebene Antwort bereitgestellt. Informationen zu den Konventionen, die in der Dokumentation für Beispiel-API-Aufrufe verwendet werden, finden Sie im Abschnitt zum Lesen von Beispiel-API-Aufrufen im Handbuch zur Fehlerbehebung für Experience Platform

Sammeln von Werten für erforderliche Kopfzeilen

Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:

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

All resources in Experience Platform are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

x-sandbox-name: {SANDBOX_NAME}

HINWEIS

For more information on sandboxes in Platform, see the sandbox overview documentation.

Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile erforderlich:

Content-Type: application/json

Erstellen eines Batches

Bevor Daten zu einem Datensatz hinzugefügt werden können, müssen sie mit einem Batch verknüpft werden, der später in einen bestimmten Datensatz hochgeladen wird.

POST /batches

Anfrage

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}" 
      }'

Eigenschaft	Beschreibung
`datasetId`	Die ID des Datensatzes, in den die Dateien hochgeladen werden sollen.

Antwort

{
    "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}"
}

Eigenschaft	Beschreibung
`id`	Die ID des soeben erstellten Batches (in nachfolgenden Anfragen verwendet).
`relatedObjects.id`	Die ID des Datensatzes, in den die Dateien hochgeladen werden sollen.

Datei-Upload

Nachdem Sie erfolgreich einen neuen Batch zum Hochladen erstellt haben, können Dateien in einen bestimmten Datensatz hochgeladen werden.

Sie können Dateien mit der Small File Upload-API hochladen. Wenn Ihre Dateien jedoch zu groß sind und das Gateway-Limit überschritten wird (z. B. längere Timeouts, Anfragen für überschrittene Dateigröße und andere Einschränkungen), können Sie zur Large File Upload-API wechseln. Diese API lädt die Datei in Teilen hoch und fügt die Daten mithilfe des Aufrufs Large File Upload Complete-API wieder zusammen.

HINWEIS

Die folgenden Beispiele verwenden das Parquet-Dateiformat. Ein Beispiel, das das JSON-Dateiformat verwendet, finden Sie im Entwicklerhandbuch zur Batch-Erfassung.

Hochladen von kleinen Dateien

Nachdem ein Batch erstellt wurde, können Daten in einen bereits vorhandenen Datensatz hochgeladen werden. Die hochgeladene Datei muss mit dem referenzierten XDM-Schema übereinstimmen.

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

Eigenschaft	Beschreibung
`{BATCH_ID}`	Die Batch-ID.
`{DATASET_ID}`	Die Datensatz-ID, in den Dateien hochgeladen werden sollen.
`{FILE_NAME}`	Der Dateiname, wie er im Datensatz angezeigt wird.

Anfrage

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"

Eigenschaft	Beschreibung
`{FILE_PATH_AND_NAME}`	Pfad und Dateiname der Datei, die in den Datensatz hochgeladen werden soll.

Antwort

#Status 200 OK, with empty response body

Hochladen großer Dateien – Datei erstellen

Um eine große Datei hochzuladen, muss die Datei in kleinere Abschnitte aufgeteilt und diese Abschnitte müssen einzeln hochgeladen werden.

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

Eigenschaft	Beschreibung
`{BATCH_ID}`	Die Batch-ID.
`{DATASET_ID}`	Die ID des Datensatzes, in den die Dateien aufgenommen werden.
`{FILE_NAME}`	Der Dateiname, wie er im Datensatz angezeigt wird.

Anfrage

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}"

Antwort

#Status 201 CREATED, with empty response body

Hochladen großer Dateien – nachfolgende Teile hochladen

Nachdem die Datei erstellt wurde, können alle nachfolgenden Teile durch wiederholte PATCH-Anfragen hochgeladen werden, jeweils einen für jeden Abschnitt der Datei.

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

Eigenschaft	Beschreibung
`{BATCH_ID}`	Die Batch-ID.
`{DATASET_ID}`	Die ID des Datensatzes, in den die Dateien hochgeladen werden sollen.
`{FILE_NAME}`	Dateiname, wie er im Datensatz angezeigt wird.

Anfrage

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"

Eigenschaft	Beschreibung
`{FILE_PATH_AND_NAME}`	Pfad und Dateiname der Datei, die in den Datensatz hochgeladen werden soll.

Antwort

#Status 200 OK, with empty response

Kennzeichnen der Fertigstellung eines Batches

Nachdem alle Dateien in den Batch hochgeladen wurden, kann dieser als fertiggestellt gekennzeichnet werden. By doing this, the Catalog DataSetFile entries are created for the completed files and associated with the batch generated above. The Catalog batch is then marked as successful, which triggers downstream flows to ingest the available data.

Anfrage

POST /batches/{BATCH_ID}?action=COMPLETE

Eigenschaft	Beschreibung
`{BATCH_ID}`	Die ID des Batches, der in den Datensatz hochgeladen werden soll.

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}"

Antwort

#Status 200 OK, with empty response

Prüfen des Batch-Status

Während darauf gewartet wird, dass die Dateien in den Batch hochgeladen werden, kann der Status des Stapels überprüft werden, um den Fortschritt zu sehen.

API-Format

GET /batch/{BATCH_ID}

Eigenschaft	Beschreibung
`{BATCH_ID}`	Die ID des geprüften Batches.

Anfrage

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}"

Antwort

{
    "{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"
        }
    }
}

Eigenschaft	Beschreibung
`{USER_ID}`	Die ID des Benutzers, der den Batch erstellt oder aktualisiert hat.

Das "status"-Feld zeigt den aktuellen Status des angeforderten Batches an. Die Batches können einen der folgenden Status haben:

Batch-Erfassungstatus

Status	Beschreibung
Vorzeitig beendet	Der Batch wurde nicht im erwarteten Zeitrahmen fertiggestellt.
Abgebrochen	Für den angegebenen Stapel wurde explizit ein Unterbrechungsvorgang (über die Batch-Aufnahme-API) aufgerufen. Wenn sich der Stapel im Status "geladen"befindet, kann er nicht abgebrochen werden.
Aktiv	Der Batch wurde erfolgreich gefördert und steht für den nachgelagerten Verbrauch zur Verfügung. Dieser Status kann synonym mit "Erfolg"verwendet werden.
Gelöscht	Die Daten für den Batch wurden vollständig entfernt.
Fehlgeschlagen	Ein Terminal-Status, der entweder auf eine fehlerhafte Konfiguration und/oder auf fehlerhafte Daten zurückzuführen ist. Daten für einen fehlgeschlagenen Batch werden nicht angezeigt. Dieser Status kann synonym mit "Failure"verwendet werden.
Inaktiv	Der Batch wurde erfolgreich gefördert, wurde jedoch zurückgesetzt oder ist abgelaufen. Der Batch ist nicht mehr für den nachgelagerten Verbrauch verfügbar.
Geladen	Die Daten für den Batch sind abgeschlossen und der Stapel kann gefördert werden.
Wird geladen	Daten für diesen Batch werden hochgeladen und der Batch kann derzeit noch nicht gefördert werden.
Wird wiederholt	Die Daten für diesen Batch werden verarbeitet. Aufgrund eines System- oder vorübergehenden Fehlers ist der Batch jedoch fehlgeschlagen. Daher wird für diesen Batch ein erneuter Versuch unternommen.
Staging	Die Staging-Phase des Förderungsprozesses für einen Batch ist abgeschlossen und der Aufnahmeauftrag wurde ausgeführt.
Staging	Die Daten für den Batch werden verarbeitet.
Angehalten	Die Daten für den Batch werden verarbeitet. Die Batch-Förderung wurde jedoch nach einigen weiteren erneuten Versuchen angehalten.

Materialien auf adobe.com

Version History Content Management Triggered Emails Lookalike Modeling Data Ingestion Cohort Analysis

Batch IngestionÜbersicht

Verwenden der API

Data Ingestion Voraussetzungen

Best Practices zur Batch-Erfassung

Lesen von Beispiel-API-Aufrufen

Sammeln von Werten für erforderliche Kopfzeilen

Erstellen eines Batches

Datei-Upload

Hochladen von kleinen Dateien

Hochladen großer Dateien – Datei erstellen

Hochladen großer Dateien – nachfolgende Teile hochladen

Kennzeichnen der Fertigstellung eines Batches

Prüfen des Batch-Status

Batch-Erfassungstatus

Materialien auf adobe.com

Auf dieser Seite

Als Nächstes anzeigen: