Handbuch zur Batchaufnahme-API

Dieses Dokument bietet Ihnen einen umfassenden Überblick über die Verwendung von APIs für die Batch-Erfassung.

Der Anhang zu diesem Dokument enthält Informationen zur Formatierung von Daten, die zur Erfassung verwendet werden sollen, einschließlich Beispiel-CSV- und JSON-Datendateien.

Erste Schritte

Data Ingestion bietet eine RESTful-API, mit der Sie bei unterstützten Objekttypen grundlegende CRUD-Vorgänge durchführen können.

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um die Batch Ingestion-API erfolgreich aufrufen zu können.

Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Adobe Experience Platform voraus:

  • Batch-Erfassung: Erlaubt Ihnen das Erfassen von Daten in Adobe Experience Platform in Form von Batch-Dateien.
  • Experience Data Model (XDM) System: Das standardisierte Framework, mit dem Kundenerlebnisdaten Experience Platform organisiert werden.
  • Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform Instanz in separate virtuelle Umgebung unterteilen, um Anwendungen für digitale Erlebnisse zu entwickeln und weiterzuentwickeln.

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

Alle Ressourcen in Experience Platform werden zu bestimmten virtuellen Sandboxen isoliert. Für alle Anforderungen an Platform-APIs ist ein Header erforderlich, der den Namen der Sandbox angibt, in der der Vorgang ausgeführt wird in:

  • x-sandbox-name: {SANDBOX_NAME}
HINWEIS

Weitere Informationen zu Sandboxen in Platform finden Sie in der Sandbox-Übersichtsdokumentation.

Anfragen, die eine Payload enthalten (POST, PUT, PATCH), erfordern möglicherweise eine zusätzliche Content-Type-Kopfzeile. Die für einzelne Aufrufe zulässigen Werte werden in den Aufrufparametern angegeben.

Typen

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

Bei der Erfassung von Daten 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 verfügen weder JSON noch CSV über einen Datums- oder Datum/Uhrzeit-Typ. Daher werden diese Werte mit ISO 8061-formatierten Zeichenfolgen („2018-07-10T15:05:59.000-08:00“) oder mit Unix-Zeit in Millisekunden ausgedrückt (1531263959000) und zum Erfassungszeitpunkt in den XDM-Zieltyp 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
Dublette X X X X X X
Datum X
Datum/Uhrzeit X
Objekt X X
Zuordnung X X
HINWEIS

Boolesche Werte und Arrays können nicht in andere Typen konvertiert werden.

Einschränkungen bei der 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 pro Minute und Anwender: 138

JSON-Dateien erfassen

HINWEIS

Die folgenden Schritte gelten für kleine Dateien (256 MB oder weniger). Wenn Sie einen Gateway-Timeout erreichen oder Fehler wegen der Größe des Anfragetexts erhalten, müssen Sie zum Upload großer Dateien wechseln.

Batch erstellen

Zunächst müssen Sie einen Batch erstellen, wobei JSON als Eingabeformat dient. Beim Erstellen des Batches müssen Sie eine Datensatz-ID angeben. Außerdem müssen Sie sicherstellen, dass alle im Batch hochgeladenen Dateien mit dem XDM-Schema übereinstimmen, das mit dem bereitgestellten Datensatz verknüpft ist.

HINWEIS

Die folgenden Beispiele stehen für einzeilige JSON-Dateien. Um mehrzeilige JSON zu erfassen, muss die isMultiLineJson-Markierung gesetzt werden. Weiterführende Informationen finden Sie im Handbuch zur Fehlerbehebung bei der Batch-Erfassung.

API-Format

POST /batches

Anfrage

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "json"
           }
      }'
Parameter Beschreibung
{DATASET_ID} Die Kennung des Referenzdatensatzes.

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}"
}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.

Dateien hochladen

Nach dem Erstellen eines Batches können Sie die batchId verwenden, um Dateien in den Batch hochzuladen. Sie haben die Möglichkeit, mehrere Dateien in den Batch hochzuladen.

API-Format

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der Speicherort, an dem die Adobe gespeichert wird.

Anfrage

HINWEIS

Die API unterstützt das Hochladen einzelner Teile. Stellen Sie sicher, dass der Content-Type „application/octet-stream“ lautet.

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  --data-binary "@{FILE_PATH_AND_NAME}.json"
Parameter Beschreibung
{FILE_PATH_AND_NAME} Der vollständige Pfad und Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der lokale Dateipfad, z. B. Users/sample-user/Downloads/sample.json.

Antwort

200 OK

Batch abschließen

Nachdem Sie alle Teile der Datei hochgeladen haben, müssen Sie signalisieren, dass die Daten vollständig hochgeladen worden sind und dass der Batch bereit zur Promotion ist.

API-Format

POST /batches/{BATCH_ID}?action=COMPLETE
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.

Anfrage

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

Antwort

200 OK

Parquet-Dateien erfassen

HINWEIS

Die folgenden Schritte gelten für kleine Dateien (256 MB oder weniger). Wenn Sie einen Gateway-Timeout erreichen oder Fehler wegen der Größe des Anfragetexts erhalten, müssen Sie zum Upload großer Dateien wechseln.

Batch erstellen

Zunächst müssen Sie einen Batch erstellen, bei dem Parquet als Eingabeformat dient. Beim Erstellen des Batches müssen Sie eine Datensatz-ID angeben. Außerdem müssen Sie sicherstellen, dass alle im Batch hochgeladenen Dateien mit dem XDM-Schema übereinstimmen, das mit dem bereitgestellten Datensatz verknüpft ist.

Anfrage

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: {IMS_ORG}" \
  -H "x-api-key : {API_KEY}" \
  -H "x-sandbox-name: {SANDBOX_NAME}" 
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
                "format": "parquet"
           }
      }'
Parameter Beschreibung
{DATASET_ID} Die Kennung des Referenzdatensatzes.

Antwort

201 Created
{
    "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}"
}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.
{USER_ID} Die Kennung des Anwenders, der den Batch erstellt hat.

Dateien hochladen

Nach dem Erstellen eines Batches können Sie die batchId verwenden, um Dateien in den Batch hochzuladen. Sie haben die Möglichkeit, mehrere Dateien in den Batch hochzuladen.

API-Format

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der Speicherort, an dem die Adobe gespeichert wird.

Anfrage

VORSICHT

Diese API unterstützt das Hochladen einzelner Teile. Stellen Sie sicher, dass der Content-Type „application/octet-stream“ lautet.

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Parameter Beschreibung
{FILE_PATH_AND_NAME} Der vollständige Pfad und Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der lokale Dateipfad, z. B. Users/sample-user/Downloads/sample.json.

Antwort

200 OK

Batch abschließen

Nachdem Sie alle Teile der Datei hochgeladen haben, müssen Sie signalisieren, dass die Daten vollständig hochgeladen worden sind und dass der Batch bereit zur Promotion ist.

API-Format

POST /batches/{BATCH_ID}?action=complete
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, den Sie als abschlussbereit signalisieren möchten.

Anfrage

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

Antwort

200 OK

Große Parquet-Dateien erfassen

HINWEIS

In diesem Abschnitt wird beschrieben, wie Sie Dateien hochladen, die über 256 MB groß sind. Die großen Dateien werden in Blöcken hochgeladen und dann über ein API-Signal zusammengefügt.

Batch erstellen

Zunächst müssen Sie einen Batch erstellen, bei dem Parquet als Eingabeformat dient. Beim Erstellen des Batches müssen Sie eine Datensatz-ID angeben. Außerdem müssen Sie sicherstellen, dass alle im Batch hochgeladenen Dateien mit dem XDM-Schema übereinstimmen, das mit dem bereitgestellten Datensatz verknüpft ist.

API-Format

POST /batches

Anfrage

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
          "datasetId": "{DATASET_ID}",
           "inputFormat": {
             "format": "parquet"
           }
      }'
Parameter Beschreibung
{DATASET_ID} Die Kennung des Referenzdatensatzes.

Antwort

201 Created
{
    "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}"
}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.
{USER_ID} Die Kennung des Anwenders, der den Batch erstellt hat.

Große Datei initialisieren

Nachdem Sie den Batch erstellt haben, müssen Sie die große Datei initialisieren, bevor Sie Blöcke in den Batch hochladen können.

API-Format

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.
{FILE_NAME} Der Name der Datei, die initialisiert werden soll.

Anfrage

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

Antwort

201 Created

Blöcke der großen Datei hochladen

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

API-Format

PATCH /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der Speicherort, an dem die Adobe gespeichert wird.

Anfrage

VORSICHT

Diese API unterstützt das Hochladen einzelner Teile. Stellen Sie sicher, dass der Content-Type „application/octet-stream“ lautet.

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: {IMS_ORG}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  --data-binary "@{FILE_PATH_AND_NAME}.parquet"
Parameter Beschreibung
{CONTENT_RANGE} In Ganzzahlen: Anfang und Ende des angeforderten Bereichs.
{FILE_PATH_AND_NAME} Der vollständige Pfad und Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der lokale Dateipfad, z. B. Users/sample-user/Downloads/sample.json.

Antwort

200 OK

Große Datei abschließen

Nach dem Erstellen eines Batches können Sie die batchId verwenden, um Dateien in den Batch hochzuladen. Sie haben die Möglichkeit, mehrere Dateien in den Batch hochzuladen.

API-Format

POST /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, für den der Abschluss signalisiert werden soll.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, für die der Abschluss signalisiert werden soll.

Anfrage

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

Antwort

201 Created

Batch abschließen

Nachdem Sie alle Teile der Datei hochgeladen haben, müssen Sie signalisieren, dass die Daten vollständig hochgeladen worden sind und dass der Batch bereit zur Promotion ist.

API-Format

POST /batches/{BATCH_ID}?action=COMPLETE
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, für den der Abschluss signalisiert werden soll.

Anfrage

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

Antwort

200 OK

CSV-Dateien erfassen

Um CSV-Dateien zu erfassen, müssen Sie eine Klasse, ein Schema und einen Datensatz erstellen, die CSV unterstützen. Genaue Informationen zum Erstellen der erforderlichen Klasse und des erforderlichen Schemas finden Sie in den Anweisungen im Tutorial zur Erstellung von Ad-hoc-Schemas.

HINWEIS

Die folgenden Schritte gelten für kleine Dateien (256 MB oder weniger). Wenn Sie einen Gateway-Timeout erreichen oder Fehler wegen der Größe des Anfragetexts erhalten, müssen Sie zum Upload großer Dateien wechseln.

Datensatz erstellen

Nachdem Sie die oben stehenden Anweisungen zum Erstellen der erforderlichen Klasse und des erforderlichen Schemas befolgt haben, müssen Sie einen Datensatz erzeugen, der CSV unterstützen kann.

API-Format

POST /catalog/dataSets

Anfrage

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: {IMS_ORG}' \
  -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"
      }
  }'
Parameter Beschreibung
{TENANT_ID} Diese Kennung stellt sicher, dass die von Ihnen erstellten Ressourcen den richtigen Namespace aufweisen und in Ihrer IMS-Organisation enthalten sind.
{SCHEMA_ID} Die Kennung des erstellten Schemas.

Batch erstellen

Als Nächstes müssen Sie einen Batch mit CSV als Eingabeformat erstellen. Beim Erstellen des Batches müssen Sie eine Datensatz-ID angeben. Außerdem müssen Sie sicherstellen, dass alle im Batch hochgeladenen Dateien mit dem Schema übereinstimmen, das mit dem bereitgestellten Datensatz verknüpft ist.

API-Format

POST /batches

Anfrage

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}'
  -d '{
            "datasetId": "{DATASET_ID}",
            "inputFormat": {
                "format": "csv"
            }
      }'
Parameter Beschreibung
{DATASET_ID} Die Kennung des Referenzdatensatzes.

Antwort

201 Created
{
    "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}"
}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.
{USER_ID} Die Kennung des Anwenders, der den Batch erstellt hat.

Dateien hochladen

Nach dem Erstellen eines Batches können Sie die batchId verwenden, um Dateien in den Batch hochzuladen. Sie haben die Möglichkeit, mehrere Dateien in den Batch hochzuladen.

API-Format

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der Speicherort, an dem die Adobe gespeichert wird.

Anfrage

VORSICHT

Diese API unterstützt das Hochladen einzelner Teile. Stellen Sie sicher, dass der Content-Type „application/octet-stream“ lautet.

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  --data-binary "@{FILE_PATH_AND_NAME}.csv"
Parameter Beschreibung
{FILE_PATH_AND_NAME} Der vollständige Pfad und Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der lokale Dateipfad, z. B. Users/sample-user/Downloads/sample.json.

Antwort

200 OK

Batch abschließen

Nachdem Sie alle Teile der Datei hochgeladen haben, müssen Sie signalisieren, dass die Daten vollständig hochgeladen worden sind und dass der Batch bereit zur Promotion ist.

API-Format

POST /batches/{BATCH_ID}?action=COMPLETE

Anfrage

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

Antwort

200 OK

Batch abbrechen

Solange der Batch verarbeitet wird, kann er abgebrochen werden. Sobald ein Batch jedoch finalisiert wurde (z. B. Status „Erfolg“ oder „Fehlgeschlagen“), kann er nicht mehr abgebrochen werden.

API-Format

POST /batches/{BATCH_ID}?action=ABORT
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, den Sie abbrechen möchten.

Anfrage

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

Antwort

200 OK

Batch löschen

Ein Batch kann gelöscht werden, indem Sie folgende POST-Anfrage mit dem action=REVERT-Abfrageparameter an die Kennung des Batches, den Sie löschen möchten, richten. Der Batch ist als „inaktiv“ markiert, sodass er für die Speicherbereinigung qualifiziert ist. Der Batch wird asynchron gesammelt und zu diesem Zeitpunkt als „gelöscht“ gekennzeichnet.

API-Format

POST /batches/{BATCH_ID}?action=REVERT
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, den Sie löschen möchten.

Anfrage

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

Antwort

200 OK

Batch ersetzen

Wenn Sie einen bereits erfassten Batch ersetzen möchten, können Sie dies mit „batch replace“ tun. Diese Aktion entspricht einem Löschen des alten Batches und dem Erfassen eines neuen Batches.

Batch erstellen

Zunächst müssen Sie einen Batch erstellen, wobei JSON als Eingabeformat dient. Beim Erstellen des Batches müssen Sie eine Datensatz-ID angeben. Außerdem müssen Sie sicherstellen, dass alle im Batch hochgeladenen Dateien mit dem XDM-Schema übereinstimmen, das mit dem bereitgestellten Datensatz verknüpft ist. Außerdem müssen Sie die alten Batches im Abschnitt „replace“ als Referenz angeben. Im folgenden Beispiel werden Batches mit den Kennungen batchIdA und batchIdB wiederholt.

API-Format

POST /batches

Anfrage

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: {IMS_ORG}' \
  -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"
             }
      }'
Parameter Beschreibung
{DATASET_ID} Die Kennung des Referenzdatensatzes.

Antwort

201 Created
{
    "id": "{BATCH_ID}",
    "imsOrg": "{IMS_ORG}",
    "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}"
}
Parameter Beschreibung
{BATCH_ID} Die Kennung des neu erstellten Batches.
{DATASET_ID} Die Kennung des referenzierten Datensatzes.
{USER_ID} Die Kennung des Anwenders, der den Batch erstellt hat.

Dateien hochladen

Nach dem Erstellen eines Batches können Sie die batchId verwenden, um Dateien in den Batch hochzuladen. Sie haben die Möglichkeit, mehrere Dateien in den Batch hochzuladen.

API-Format

PUT /batches/{BATCH_ID}/datasets/{DATASET_ID}/files/{FILE_NAME}
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, in den Sie hochladen möchten.
{DATASET_ID} Die Kennung des Referenzdatensatzes des Batches.
{FILE_NAME} Der Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der Speicherort, an dem die Adobe gespeichert wird.

Anfrage

VORSICHT

Diese API unterstützt das Hochladen einzelner Teile. Stellen Sie sicher, dass der Content-Type „application/octet-stream“ lautet. Verwenden Sie nicht die Option „curl -F“, da dabei standardmäßig eine mehrteilige Anfrage verwendet wird, die mit der API nicht kompatibel ist.

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: {IMS_ORG}' \
  -H 'x-api-key : {API_KEY}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  --data-binary "@{FILE_PATH_AND_NAME}.json"
Parameter Beschreibung
{FILE_PATH_AND_NAME} Der vollständige Pfad und Name der Datei, die Sie hochladen möchten. Dieser Dateipfad ist der lokale Dateipfad, z. B. Users/sample-user/Downloads/sample.json.

Antwort

200 OK

Batch abschließen

Nachdem Sie alle Teile der Datei hochgeladen haben, müssen Sie signalisieren, dass die Daten vollständig hochgeladen worden sind und dass der Batch bereit zur Promotion ist.

API-Format

POST /batches/{BATCH_ID}?action=COMPLETE
Parameter Beschreibung
{BATCH_ID} Die Kennung des Batches, den Sie abschließen möchten.

Anfrage

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

Antwort

200 OK

Anhang

Datenumwandlung für die Batch-Erfassung

Um eine Datendatei in Experience Platform zu erfassen, muss die hierarchische Dateistruktur dem Schema Erlebnisdatenmodell (XDM) entsprechen, das mit dem hochgeladenen Datensatz verknüpft ist.

Informationen dazu, wie Sie eine CSV-Datei einem XDM-Schema konform zuordnen, finden Sie im Dokument mit Beispielumwandlungen. Hier finden Sie außerdem ein Beispiel für eine richtig formatierte JSON-Datendatei. Im Dokument bereitgestellte Beispieldateien finden Sie hier:

Auf dieser Seite