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.
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:
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.
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
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:
{ACCESS_TOKEN}
{API_KEY}
{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:
{SANDBOX_NAME}
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:
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. |
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.
Die folgenden Beispiele verwenden das Parquet-Dateiformat. Ein Beispiel, das das JSON-Dateiformat verwendet, finden Sie im Entwicklerhandbuch zur Batch-Erfassung.
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
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
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
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
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:
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. |