Batch-Aufnahme-API - Übersicht

Mit der Adobe Experience Platform Batch Ingestion-API können Sie Daten als Batch-Dateien in Platform erfassen. Daten, die erfasst werden, können Profildaten aus einer reduzierten Datei (z. B. einer Parquet-Datei) oder Daten sein, die einem bekannten Schema in der Experience Data Model (XDM)-Registry entsprechen.

Die Referenz zur Batch Ingestion-API🔗 enthält zusätzliche Informationen zu diesen API-Aufrufen.

Das folgende Diagramm zeigt den Vorgang der Batch-Erfassung.

Erste Schritte

Die in diesem Handbuch verwendeten API-Endpunkte sind Teil der Batch Ingestion-API. Bevor Sie fortfahren, lesen Sie das Handbuch Erste Schritte mit Links zur zugehörigen Dokumentation, einer Anleitung zum Lesen der API-Beispielaufrufe in diesem Dokument und wichtigen Informationen zu den erforderlichen Kopfzeilen, die für die erfolgreiche Ausführung von Aufrufen an eine Experience Platform-API erforderlich sind.

Voraussetzungen für Data Ingestion

  • Die hochzuladenden Daten müssen im Parquet- oder JSON-Format vorliegen.
  • Ein Datensatz, der im Catalog services 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.

Einschränkungen bei der Batch-Erfassung

Die Erfassung von Batch-Daten unterliegt verschiedenen Einschränkungen:

  • Maximale Anzahl von Dateien pro Batch: 1.500
  • Maximale Batch-Größe: 100 GB
  • Maximale Anzahl von Eigenschaften oder Feldern pro Zeile: 10.000
  • Maximale Anzahl der Batches auf Data Lake pro Minute pro Benutzer: 2000
NOTE
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 im Abschnitt Hochladen einer großen Datei dieses Dokuments.

Typen

Beim Erfassen von Daten ist es wichtig zu verstehen, wie Experience Data Model- (XDM-)Schemas funktionieren. Weiterführende Informationen zur Zuordnung von XDM-Feldtypen zu verschiedenen Formaten finden Sie im Entwicklerhandbuch zur Schemaregistrierung.

Bei der Datenaufnahme gibt es eine gewisse Flexibilität. Wenn ein Typ nicht mit dem Zielschema übereinstimmt, werden die Daten in den ausgedrückten Zieltyp konvertiert. Wenn das nicht möglich ist, schlägt der Batch mit einer TypeCompatibilityException fehl.

Beispielsweise haben weder JSON noch CSV den Typ date oder date-time. Daher werden diese Werte mit ISO 8601 formatierten Zeichenfolgen ("2018-07-10T15:05:59.000-08:00") oder Unix-Zeit ausgedrückt und in Millisekunden formatiert (15312639599 000) und werden zur Erfassungszeit in den Ziel-XDM-Typ konvertiert.

Folgende Tabelle enthält die Konversionen, die beim Erfassen von Daten unterstützt werden.

Eingehend (Zeile) vs. Ziel (Spalte)
Zeichenfolge
Byte
Kurz
Ganzzahl
Lang
Double
Datum
Datum/Uhrzeit
Objekt
Zuordnung
Zeichenfolge
X
X
X
X
X
X
X
X
Byte
X
X
X
X
X
X
Kurz
X
X
X
X
X
X
Ganzzahl
X
X
X
X
X
X
Lang
X
X
X
X
X
X
X
X
Double
X
X
X
X
X
X
Datum
X
Datum/Uhrzeit
X
Objekt
X
X
Zuordnung
X
X
NOTE
Boolesche Werte und Arrays können nicht in andere Typen konvertiert werden.

Verwenden der API

Mit der API Data Ingestion können Sie Daten in drei grundlegenden Schritten als Batches (eine Dateneinheit, die aus einer oder mehreren Dateien besteht, die als Einheit erfasst werden sollen) in Experience Platform erfassen:

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

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: {ORG_ID}" \
  -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": "{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}"
}
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, überschrittene Anforderungen an die Textgröße und andere Einschränkungen), können Sie zur Large File Upload-API wechseln. Diese API lädt die Datei in Teilen hoch und ordnet die Daten mithilfe des Aufrufs Large File Upload Complete-API zu.

NOTE
Die Batch-Erfassung kann verwendet werden, um Daten im Profilspeicher schrittweise zu aktualisieren. Weitere Informationen finden Sie im Abschnitt zum Aktualisieren eines Batches im Entwicklerhandbuch zur Batch-Erfassung.
INFO
Die folgenden Beispiele verwenden das Dateiformat Apache Parquet . 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: {ORG_ID}" \
  -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: {ORG_ID}" \
  -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: {ORG_ID}" \
  -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. Auf diese Weise werden die Catalog DataSetFile -Einträge für die abgeschlossenen Dateien erstellt und mit dem oben generierten Batch verknüpft. Der Catalog-Batch wird dann als erfolgreich markiert, wodurch bei nachgelagerten Flüssen die Aufnahme der verfügbaren Daten ausgelöst wird.

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: {ORG_ID}" \
-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: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" \
  -H "x-api-key: {API_KEY}"

Antwort

{
    "{BATCH_ID}": {
        "imsOrg": "{ORG_ID}",
        "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. Sobald sich der Batch im Status "Geladen"befindet, kann er nicht mehr 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 "Fehler"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.
recommendation-more-help
2ee14710-6ba4-4feb-9f79-0aad73102a9a