Entwickeln von ETL-Integrationen für Adobe Experience Platform

Im Handbuch zur ETL-Integration werden die grundlegenden Schritte für die Erstellung von leistungsstarken, sicheren Connectoren für Experience Platform und für die Aufnahme von Daten in Platform erläutert.

Dieses Handbuch beinhaltet außerdem Beispiele für die zur Erstellung eines ETL-Connectors zu verwendenden API-Aufrufe sowie Links zu Dokumentationen, in denen die einzelnen Experience Platform-Services einschließlich der Arbeit mit der ihnen jeweils zugehörigen API erläutert werden.

Ein Beispiel für eine Integration ist auf GitHub über den ETL Ecosystem Integration Reference Code unter der Apache-Lizenz Version 2.0 verfügbar.

Workflow

Das folgende Diagramm skizziert den allgemeinen Workflow für die Integration der Komponenten von Adobe Experience Platform mit einer ETL-Anwendung und einem ETL-Connector.

Komponenten von Adobe Experience Platform

An der Integration mit ETL-Connectoren ist eine Vielzahl der Komponenten von Experience Platform beteiligt. Die folgende Liste zeigt einige der zentralen Komponenten und ihre Funktionalitäten:

Erste Schritte mit Experience Platform-APIs

Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um Experience Platform-APIs erfolgreich aufrufen zu können.

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:

Alle Ressourcen in Experience Platform sind auf bestimmte virtuelle Sandboxes beschränkt. Bei allen Anfragen an Platform-APIs ist eine Kopfzeile erforderlich, die den Namen der Sandbox angibt, in der der Vorgang ausgeführt werden soll:

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

Allgemeiner Ablauf

Zunächst meldet sich ein ETL-Anwender bei der Benutzeroberfläche von Experience Platform an und erstellt Datensätze für die Aufnahme mit einem Standard-Connector oder einem Push-Service-Connector.

In der Benutzeroberfläche erstellt der Anwender den Ausgabedatensatz, indem er ein Datensatzschema auswählt. Die Auswahl des Schemas hängt davon ab, welcher Datentyp (Datensatz- oder Zeitreihendaten) in Platform aufgenommen wird. In der Benutzeroberfläche können alle verfügbaren Schemata einschließlich des vom Schema unterstützten Verhaltenstyps über die Registerkarte „Schemata“ eingesehen werden.

Beginnt der Anwender im ETL-Tool mit der Konzeptionierung, wird seine Zuordnung nach Konfiguration der entsprechenden Verbindung (unter Verwendung seiner Anmeldedaten) umgewandelt. Es wird hier davon ausgegangen, dass für das ETL-Tool bereits Experience Platform-Connectoren installiert wurden. (Auf den entsprechenden Prozess wird in diesem Integrationshandbuch nicht eingegangen.)

Modelldarstellungen eines Beispiel-ETL-Tools und -Workflows stehen unter ETL-Workflow zur Verfügung. Die einzelnen ETL-Tools unterscheiden sich zwar in ihrem Format, sind sich in ihrer Funktion aber größtenteils ähnlich.

Anzeigen einer Liste von Datensätzen

Über die Datenquelle für die Zuordnung kann eine Liste aller verfügbaren Datensätze anhand der Catalog API abgerufen werden.

Sie können zur Auflistung aller verfügbaren Datensätze eine einzelne API-Anfrage (z. B. GET /dataSets) ausführen. Dabei empfiehlt sich als Best Practice die Angabe von Abfrageparametern, durch die die Größe der Antwort beschränkt wird.

Werden vollständige Datensatzinformationen angefragt, wächst die Größe der Antwort-Payload unter Umständen auf mehr als 3 GB an, was zu einer insgesamt verlangsamten Performance führen kann. Die Verwendung von Abfrageparametern, mittels derer aus den Informationen nur die tatsächlich benötigten gefiltert werden, ist daher ein effizienterer Ansatz für Catalog-Abfragen.

Filtern von Listen

Sie können mehrere Filter für die Antwortausgabe verwenden, indem sie die entsprechenden Parameter durch ein kaufmännisches Und-Zeichen (&) voneinander trennen. Einige Abfrageparameter akzeptieren eine durch Komma getrennte Liste von Werten, darunter etwa der für die Eigenschaften verwendete „properties“-Filter in der unten dargestellten Beispielanfrage.

Die Zahl der Catalog-Antworten wird automatisch entsprechend den konfigurierten Einschränkungen begrenzt. Mithilfe des Abfrageparameters „limit“ kann jedoch die Begrenzung der Anzahl der zurückgegebenen Objekte individuell angepasst werden. Die Begrenzung der Catalog-Antworten ist wie folgt vorkonfiguriert:

Einzelheiten zu Abfrageparametern finden Sie unter Übersicht über Catalog Service.

API-Format

GET /catalog/dataSets
GET /catalog/dataSets?{filter1}={value1},{value2}&{filter2}={value3}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=3&properties=name,description,schemaRef" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Unter Catalog Service – Übersicht finden Sie ausführliche Beispiele dazu, wie Sie Aufrufe an die Catalog API ausführen.

Antwort

Die Antwort umfasst drei (limit=3) Datensätze, die dem Abfrageparameter properties entsprechend die Objekte „name“, „description“ und „schemaRef“, also Name, Beschreibung und Schema-Verweis, umfassen.

{
    "5b95b155419ec801e6eee780": {
        "name": "Store Transactions",
        "description": "Retails Store Transactions",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c351fa2f5fee300000fa9e8": {
        "name": "Loyalty Members",
        "description": "Loyalty Program Members",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/fbc52b243d04b5d4f41eaa72a8ba58be",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    },
    "5c1823b19e6f400000993885": {
        "name": "Web Traffic",
        "description": "Retail Web Traffic",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/2025a705890c6d4a4a06b16f8cf6f4ca",
            "contentType": "application/vnd.adobe.xed+json;version=1"
        }
    }
}

Anzeigen des Datensatzschemas

Die Eigenschaft „schemaRef“ eines Datensatzes enthält einen URI, der auf das XDM-Schema verweist, auf dem der Datensatz basiert. Das XDM-Schema („schemaRef“) umfasst alle vom Datensatz potenziell verwendbaren Felder, also nicht zwingend nur die, die tatsächlich verwendet werden (siehe „observableSchema“ weiter unten).

Das XDM-Schema ist das Schema, das Sie verwenden, wenn Sie dem Anwender eine Liste aller verfügbaren Felder anzeigen möchten, die ausgefüllt werden können.

Der erste Wert für „schemaRef.id“ im vorherigen Antwortobjekt (https://ns.adobe.com/{TENANT_ID}/schemas/274f17bc5807ff307a046bab1489fb18) ist ein URI, der auf ein bestimmtes XDM-Schema in der Schema Registry verweist. Das Schema kann abgerufen werden, indem eine GET-Anfrage an die Schema Registry-API gesendet wird.

API-Format

GET /schemaregistry/tenant/schemas/{url encoded schemaRef.id}

Anfrage

Die Anfrage erfolgt über den URL-codierten id-URI des Schemas (der Wert des Attributs „schemaRef.id“) und erfordert eine Accept-Kopfzeile.

curl -X GET \
  https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas/https%3A%2F%2Fns.adobe.com%2F{TENANT_ID}%2Fschemas%2F274f17bc5807ff307a046bab1489fb18 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Accept: application/vnd.adobe.xed-full+json; version=1' \

Das Format der Antwort hängt von der in der Anfrage verwendeten Accept-Kopfzeile ab. In Anfragen zum Nachschlagen muss außerdem die version in der Accept-Kopfzeile angegeben werden. In der folgenden Tabelle sind die für Anfragen zum Nachschalgen verfügbaren Accept-Kopfzeilen aufgeführt:

Antwort

Das zurückgegebene JSON-Schema beschreibt die Struktur sowie Feldebenen-Informationen wie Typ, Format, Minimum, Maximum usw. der Daten, dies serialisiert als JSON. Für den Fall, dass für die Datenaufnahme ein anderes Serialisierungsformat als JSON verwendet wird (z. B. Parquet oder Scala), steht im Handbuch zur Schema Registry eine Tabelle mit dem gewünschten JSON-Typ („meta:xdmType“) und der entsprechenden Darstellung in anderen Formaten zur Verfügung.

Ergänzend zu dieser Tabelle umfasst das Schema Registry-Entwicklerhandbuch ausführliche Beispiele für alle mit der Schema Registry-API durchführbaren Aufrufe.

Eigenschaft „Schema“ des Datensatzes (VERALTET, EINGESTELLT AM 30.05.2019)

Datensätze enthalten unter Umständen die Eigenschaft „schema“, die inzwischen eingestellt wurde und nur vorübergehend zum Zwecke der Abwärtskompatibilität verfügbar bleibt. So würde eine Anfrage zum Auflisten (GET) wie die zuvor ausgeführte, bei der im Abfrageparameter properties „schema“ durch „schemaRef“ ersetzt wurde, etwa Folgendes zurückgeben:

{
  "5ba9452f7de80400007fc52a": {
    "name": "Sample Dataset 1",
    "description": "Description of Sample Dataset 1.",
    "schema": "@/xdms/context/person"
  }
}

Wenn die Eigenschaft „schema“ eines Datensatzes ausgefüllt ist, bedeutet dies, dass das Schema ein veraltetes /xdms-Schema ist. Soweit unterstützt, sollte der ETL-Connector dann den Wert in der Eigenschaft „schema“ mit dem Endpunkt /xdms (ein veralteter Endpunkt in der Catalog API) verwenden, um das veraltete Schema abzurufen.

API-Format

GET /catalog/{"schema" property without the "@"}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/xdms/context/person?expansion=xdm" \
  -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

Ähnlich den Schritten zum Anzeigen des Datensatzschemas, liefert auch diese Antwort ein JSON-Schema, das, ebenfalls als JSON serialisiert, die Struktur und die Feldebenen-Informationen der Daten beschreibt.

Die Eigenschaft „observableSchema“

Die Eigenschaft „observableSchema“ eines Datensatzes weist eine JSON-Struktur auf, die mit der JSON-Struktur des XDM-Schemas übereinstimmt. Das „observableSchema“ enthält die in den eingehenden Eingabedateien vorhandenen Felder. Beim Schreiben von Daten in Experience Platform müssen Anwender nicht zwingend alle Felder aus dem Zielgruppenschema verwenden. Tatsächlich sollten sie nur diejenigen Felder bereitstellen, die tatsächlich verwendetet werden.

Das beobachtbare Schema ist das Schema, das Sie verwenden würden, wenn Sie die Daten lesen oder eine Liste von zum Lesen/Zuordnen verfügbaren Feldern präsentieren.

{
    "598d6e81b2745f000015edcb": {
        "observableSchema": {
            "type": "object",
            "meta:xdmType": "object",
            "properties": {
                "name": {
                    "type": "string",
                },
                "age": {
                    "type": "string",
                }
            }
        }
    }
}

Vorschau der Daten

Die ETL-Anwendung kann eine Funktion zur Vorschau von Daten bereitstellen (siehe Abbildung 8 im ETL-Workflow). Die Data Access API bietet verschiedene Optionen für die Vorschau von Daten.

Weiterführende Informationen, einschließlich einer Schritt-für-Schritt-Anleitung für die Vorschau von Daten mithilfe der Data Access API, finden Sie im Tutorial zum Datenzugriff.

Abrufen von Details zum Datensatz mithilfe des Abfrageparameters „properties“

Wie weiter oben in den Schritten zur Ansicht einer Liste von Datensätzen dargestellt, können Sie „files“, also Dateien, über den Abfrageparameter „properties“ abrufen.

Einzelheiten zur Abfrage von Datensätzen und den verfügbaren Antwortfiltern finden Sie in unter Übersicht über den Katalog-Service.

API-Format

GET /catalog/dataSets?limit={value}&properties={value}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets?limit=1&properties=files" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Antwort

Die Antwort umfasst einen Datensatz (limit=1), der die Eigenschaft „files“ anzeigt.

{
  "5bf479a6a8c862000050e3c7": {
    "files": "@/dataSetFiles?dataSetId=5bf479a6a8c862000050e3c7"
  }
}

Anzeigen einer Liste von Datensatzdateien mithilfe des Attributs „files“

Sie können Dateien auch mittels GET-Anfrage unter Verwendung des Attributs „files“ abrufen.

API-Format

GET /catalog/dataSets/{DATASET_ID}/views/{VIEW_ID}/files

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/5bf479a6a8c862000050e3c7/views/5bf479a654f52014cfffe7f1/files" \
  -H "Accept: 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}"

Antwort

Die Antwort enthält die Datensatzdatei-ID als übergeordnete Eigenschaft, wobei die Dateidetails im ID-Objekt der Datensatzdatei enthalten sind.

{
    "194e89b976494c9c8113b968c27c1472-1": {
        "batchId": "194e89b976494c9c8113b968c27c1472",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542749145828,
        "updated": 1542749145828
    },
    "14d5758c107443e1a83c714e56ca79d0-1": {
        "batchId": "14d5758c107443e1a83c714e56ca79d0",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542752699111,
        "updated": 1542752699111
    },
    "ea40946ac03140ec8ac4f25da360620a-1": {
        "batchId": "ea40946ac03140ec8ac4f25da360620a",
        "dataSetViewId": "5bf479a654f52014cfffe7f1",
        "imsOrg": "{ORG_ID}",
        "availableDates": {},
        "createdUser": "{USER_ID}",
        "createdClient": "{API_KEY}",
        "updatedUser": "{USER_ID}",
        "version": "1.0.0",
        "created": 1542756935535,
        "updated": 1542756935535
    }
}

Abrufen von Dateidetails

Die in der vorherigen Antwort zurückgegebenen Datensatzdatei-IDs können in einer GET-Anfrage verwendet werden, um über die Data Access-API weitere Dateidetails abzurufen.

Einzelheiten zur Arbeit mit der Data Access API finden Sie unter Übersicht über den Datenzugriff.

API-Format

GET /export/files/{DATASET_FILE_ID}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1" \
  -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

[
    {
    "name": "{FILE_NAME}.parquet",
    "length": 2576,
    "_links": {
        "self": {
            "href": "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet"
            }
        }
    }
]

Vorschau von Dateidaten

Um über die Data Access API eine Vorschau von Daten abzurufen, kann die Eigenschaft „href“ verwendet werden.

API-Format

GET /export/files/{FILE_ID}?path={FILE_NAME}.{FILE_FORMAT}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/export/files/ea40946ac03140ec8ac4f25da360620a-1?path=samplefile.parquet" \
  -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}"

Die Antwort auf die obige Anfrage enthält eine Vorschau des Dateiinhalts.

Weitere Informationen zur Data Access-API, darunter auch Einzelheiten zu Anfragen und Antworten, finden Sie unter Datenzugriff – Übersicht.

Abrufen von „fileDescription“ aus dem Datensatz

Dies ist die Zielkomponente als Ausgabe der umgewandelten Daten, für die der Data Engineer einen Ausgabedatensatz auswählt (siehe Abbildung 12 im ETL-Workflow). Das XDM-Schema ist dem Ausgabedatensatz zugeordnet. Die zu schreibenden Daten werden durch das Attribut „fileDescription“, also Dateibeschreibung, der Datensatz-Entität aus den Datenerkennungs-APIs gekennzeichnet. Diese Informationen können über eine Datensatz-ID abgerufen werden ({DATASET_ID}). Die Eigenschaft „fileDescription“ in der JSON-Antwort liefert die angefragten Informationen.

API-Format

GET /catalog/dataSets/{DATASET_ID}

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/dataSets/59c93f3da7d0c00000798f68" \
-H "accept: 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}"

Antwort

{
  "59c93f3da7d0c00000798f68": {
    "version": "1.0.4",
    "fileDescription": {
        "persisted": false,
        "format": "parquet"
    }
  }
}

Das Schreiben von Daten in Experience Platform erfolgt über die Batch-Aufnahme-API. Das Schreiben von Daten ist ein asynchroner Prozess. Werden Daten in Adobe Experience Platform geschrieben, wird ein Batch erst dann erstellt und als erfolgreich markiert, wenn der Schreibvorgang der Daten vollständig abgeschlossen ist.

Zum Schreiben von Daten in Experience Platform sollte das Parquet-Dateiformat verwendet werden.

Ausführungsphase

Bei der Ausführung liest der Connector (wie in der Quellkomponente definiert) die Daten aus Experience Platform mithilfe der Data Access API. Beim Umwandlungsprozess werden die in einer bestimmten Zeitspanne erfassten Daten gelesen. Intern werden dabei Batches von Quelldatensätzen abgefragt. Bei der Abfrage werden ein parametrisiertes Datumsformat (rollierend für Zeitreihen- oder inkrementelle Daten) verwendet und Datensatzdateien für diese Batches aufgelistet sowie Anfragen für Daten dieser Datensatzdateien eingeleitet.

Beispiele für Umwandlungen

Das Dokument Beispiele für ETL-Umwandlungen enthält eine Reihe von Beispiel-Umwandlungen und geht dabei auch auf die Handhabung von Identitäten und die Zuordnung von Datentypen ein. Diese Umwandlungen können sie als Referenz verwenden.

Auslesen von Daten aus Experience Platform

Mithilfe der Catalog API können Sie alle Batches innerhalb einer festgelegten Start- und Endzeit abrufen und nach der Reihenfolge sortieren, in der sie erstellt wurden.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?dataSet=DATASETID&createdAfter=START_TIMESTAMP&createdBefore=END_TIMESTAMP&sort=desc:created" \
  -H "Accept: application/json" \
  -H "Authorization:Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {ORG_ID}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Einzelheiten zum Filtern von Batches finden Sie im Tutorial zum Datenzugriff.

Aufrufen von Dateien aus einem Batch

Sobald Sie die ID für den gesuchten Batch ({BATCH_ID}) vorliegen haben, können Sie über die Data Access API eine Liste der einem bestimmten Datensatz zugehörigen Dateien abrufen. Einzelheiten hierzu finden Sie im Data Access -Tutorial.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/export/batches/{BATCH_ID}/files" \
  -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}"

Zugreifen auf Dateien mittels Datei-ID

Unter Verwendung der eindeutigen ID einer Datei ({FILE_ID) kann über die Data Access API auf spezifische Dateidetails zugegriffen werden, darunter ihr Name, ihre Größe in Byte und ein Link, unter dem sie heruntergeladen werden kann.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{FILE_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}"

Die Antwort verweist entweder auf eine einzelne Datei oder auf ein Verzeichnis. Einzelheiten zu jedem finden Sie im Data Access -Tutorial.

Zugreifen auf den Dateiinhalt

Der Zugriff auf den Inhalt einer bestimmten Datei ist über die Data Access API möglich. Um den Inhalt abzurufen, wird eine GET-Anfrage unter Verwendung des für _links.self.href beim Zugriff auf eine Datei mittels Datei-ID zurückgegebenen Werts gesendet.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/export/files/{DATASET_FILE_ID}?path=filename1.csv" \
  -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}"

Die Antwort auf diese Anfrage liefert den Inhalt der Datei. Weitere Informationen, darunter auch Einzelheiten zur Paginierung von Antworten, finden Sie im Tutorial zur Datenabfrage mittels Data Access API.

Validieren von Datensätzen auf Einhaltung von Schema-Vorgaben

Beim Schreiben von Daten können Anwender bestimmen, dass Daten entsprechend den im XDM-Schema definierten Validierungsregeln geprüft werden. Weitere Informationen zur Validierung von Schemata finden Sie auf im ETL Ecosystem Integration Reference Code in GitHub.

Wenn Sie die auf GitHub bereitgestellte Referenzimplementierung nutzen, können Sie für diese Implementierung die Schemavalidierung mithilfe der Systemeigenschaft -DenableSchemaValidation=true aktivieren.

Die Validierung kann für logische XDM-Typen durchgeführt werden, dies unter Verwendung von Attributen wie minLength und maxlength für Zeichenfolgen, minimum und maximum für Ganzzahlen und mehr. Eine Tabelle mit den für die Validierung verwendbaren XDM-Typen und Eigenschaften finden Sie im Schema Registry-API-Entwicklerhandbuch.

Erstellen eines Batches

Hat das ETL-Tool die Daten verarbeitet, schreibt es sie mithilfe der Batch-Aufnahme-API zurück in Experience Platform. Bevor einem Datensatz Daten hinzugefügt werden können, müssen sie mit einem Batch verknüpft werden, der später in einen bestimmten Datensatz hochgeladen wird.

Anfrage

curl -X POST "https://platform.adobe.io/data/foundation/import/batches" \
  -H "accept: 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}"
      }'

Einzelheiten zur Erstellung eines Batches, einschließlich Beispiel-Anfragen und -Antworten, finden Sie unter Batch-Erfassung – Übersicht.

Schreiben in einen Datensatz

Nach erfolgreicher Erstellung eines neuen Batches können Dateien in einen bestimmten Datensatz hochgeladen werden. In einen Batch können mehrere Dateien aufgenommen werden, dies so lange, bis dieser zur Aufnahme verwendet wird. Dateien können mithilfe der Small File Upload API hochgeladen werden. Überschreitet die Größe Ihrer Dateien jedoch den Grenzwert des Gateways, müssen Sie die Large File Upload API verwenden. Einzelheiten zum Hochladen kleiner und großer Dateien finden Sie unter Batch-Erfassung – Übersicht.

Anfrage

Zum Schreiben von Daten in Experience Platform sollte das Parquet-Dateiformat verwendet werden.

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

Kennzeichnen des Batch-Uploads als fertiggestellt

Nachdem alle Dateien in den Batch hochgeladen wurden, kann dieser als fertiggestellt gekennzeichnet werden. Dies bewirkt, dass für die fertiggestellten Dateien die Catalog-Einträge „DataSetFile“ erstellt und dem erstellten Batch zugeordnet werden. Der Catalog-Batch wird dann als erfolgreich markiert, wodurch bei nachgelagerten Flüssen die Aufnahme der verfügbaren Daten ausgelöst wird.

Die Daten werden in Adobe Experience Platform zunächst in der Staging-Umgebung abgelegt, um dann nach Katalogisierung und Validierung an ihren endgültigen Speicherort verschoben zu werden. Sobald alle Daten eines Batches an einen dauerhaften Speicherort verschoben wurden, wird dieser als erfolgreich markiert.

Anfrage

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

Bei erfolgreicher Ausführung wird der HTTP-Status-Code 200 (OK) zurückgegeben, wobei der Antworttext leer bleibt.

Das ETL-Tool hält den Zeitstempel der Quelldatensätze beim Lesen der Daten fest.

Wird die Umwandlung das nächste Mal ausgeführt, dies etwa nach Zeitplan oder durch Ereignisaufruf, fordert das ETL-Tool die Daten mit dem zuvor gespeicherten Zeitstempel sowie allen darauf folgenden Daten an.

Abrufen des Status des letzten Batches

Bevor Sie neue Aufgaben im ETL-Tool ausführen können, müssen Sie sicherstellen, dass der letzte Batch erfolgreich abgeschlossen wurde. Die Catalog Service API bietet eine Option, mit deren Hilfe die spezifischen Details der betreffenden Batches abgerufen werden können.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches?limit=1&sort=desc:created" \
  -H "Accept: 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}"

Antwort

Neue Aufgaben können terminiert werden, wenn der Wert „status“ des vorherigen Batches „success“, also Erfolg, lautet (wie unten dargestellt):

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "CLIENT_USER_ID@AdobeID",
    "updatedUser": "CLIENT_USER_ID@AdobeID",
    "updated": 1494349963467,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Abrufen des Status des letzten Batches via ID

Der Status einzelner Batches kann über die Catalog Service API mittels GET-Anfrage unter Verwendung der {BATCH_ID} abgerufen werden. Für die {BATCH_ID} ist dabei die ID anzugeben, die beim Erstellen des Batches zurückgegebenen wurde.

Anfrage

curl -X GET "https://platform.adobe.io/data/foundation/catalog/batches/{BATCH_ID}" \
  -H "Accept: 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}"

Antwort – erfolgreich

Die nachfolgende Antwort zeigt mit „success“ einen Batch, der erfolgreich war.

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "success",
    "errors": [],
    "version": "1.0.1",
    "availableDates": {}
}

Antwort – fehlgeschlagen

Für fehlgeschlagene Batches können die unter „errors“ beschriebenen Fehler aus der Antwort extrahiert und als Fehlermeldungen im ETL-Tool angezeigt werden.

"{BATCH_ID}": {
    "imsOrg": "{ORG_ID}",
    "created": 1494349962314,
    "createdClient": "{API_KEY}",
    "createdUser": "{CREATED_USER}",
    "updatedUser": "{UPDATED_USER}",
    "updated": 1494349962314,
    "status": "failure",
    "errors": [
        {
            "code": "200",
            "description": "Error in validating schema for file: 'adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv' with errorMessage=adl://dataLake.azuredatalakestore.net/connectors-dev/stage/BATCHID/dataSetId/contact.csv is not a Parquet file. expected magic number at tail [80, 65, 82, 49] but found [57, 98, 55, 10] and errorType=java.lang.RuntimeException",
            "rows": []
        }
    ],
    "version": "1.0.1",
    "availableDates": {}
}

Inkrementelle gegenüber Momentaufnahmen-Daten und Ereignisse gegenüber Profilen

Daten können in einer 2-mal-2-Matrix wie folgt dargestellt werden:

Ereignisdaten werden in der Regel verwendet, wenn jede Zeile über eine indizierte Spalte mit Zeitstempel verfügt.

Profildaten werden in der Regel nur verwendet, wenn für sie kein Zeitstempel vorhanden ist und jede Zeile mit einem Primärschlüssel/zusammengesetzten Schlüssel identifiziert werden kann.

Inkrementelle Daten sind Daten, bei denen nur neue/aktualisierte Daten in das System eingehen und an aktuelle Daten in den Datensätzen angehängt werden.

Momentaufnahmen-Daten liegen vor, wenn alle in das System eingehenden Daten alle in einem Datensatz vorhandenen Daten ersetzen.

Im Falle von inkrementellen Ereignissen sollte das ETL-Tool die verfügbaren Datumsinformationen bzw. das Erstellungsdatum der Batch-Entität verwenden. Bei einem Push-Service sind keine Informationen zum Verfügbarkeitsdatum vorhanden, daher kennzeichnet das Tool die Inkremente über das Datum der Batch-Erstellung/-Aktualisierung. Batches mit inkrementellen Ereignissen müssen allesamt verarbeitet werden.

Für inkrementelle Profile verwendet das ETL-Tool das Erstellungs-/Aktualisierungsdatum der Batch-Entität. In der Regel müssen Batches mit inkrementellen Ereignissen allesamt verarbeitet werden.

Momentaufnahmen-Ereignisse sind aufgrund des Datenvolumens eher unwahrscheinlich. Wenn aber doch erforderlich, muss das ETL-Tool für die Verarbeitung nur den letzten Batch auswählen.

Wenn Momentaufnahmen-Profile verwendet werden, muss das ETL-Tool die Daten aus dem letzten Batch auswählen, der im System eingegangen sind. Besteht jedoch die Anforderung, Versionsänderungen zu dokumentieren, müssen alle Batches verarbeitet werden. Der ETL-Prozess beinhaltet eine Deduplizierung, durch die die Kosten der Datenspeicherung in Grenzen gehalten werden.

Batch-Wiederholung und erneute Datenverarbeitung

Die Wiederholung von Batches und erneute Datenverarbeitung sind unter Umständen erforderlich, wenn ein Client feststellt, dass die in den letzten „n“ Tagen mittels ETL verarbeiteten Daten nicht wie erwartet aufgetreten sind oder möglicherweise die Quelldaten selbst nicht korrekt waren.

Dies erfolgt, indem die Datenadministratoren des Clients unter Verwendung der Platform-Benutzeroberfläche die Batches mit den beschädigten Daten entfernen. Dann muss der ETL-Prozess wahrscheinlich erneut ausgeführt und somit mit korrekten Daten ausgefüllt werden. Wenn die Quelle selbst beschädigte Daten aufwies, muss der Data Engineer/Datenadministrator die Quell-Batches berichtigen und die Datenaufnahme erneut durchführen (entweder in Adobe Experience Platform oder mittels ETL-Connectoren).

Je nach Typ der zu generierenden Daten kann der Data Engineer einen einzelnen Batch oder alle Batches aus spezifischen Datensätzen entfernen. Die Daten werden gemäß den Richtlinien von Experience Platform entfernt/archiviert.

Ein wahrscheinliches Szenario ist, dass die ETL-Funktionen zum Bereinigen von Daten benötigt werden.

Nach Abschluss der Bereinigung müssen die Client-Administratoren Adobe Experience Platform dahingehend neu konfigurieren, dass die Verarbeitung für Core Services ab dem Zeitpunkt des Löschens der Batches neu gestartet wird.

Gleichzeitige Verarbeitung von Batches

Nach Ermessen des Client können Datenadministratoren/Data Engineers Daten in Abhängigkeit von den Merkmalen eines bestimmten Datensatzes entweder sequenziell oder gleichzeitig extrahieren, umwandeln und laden. Die Entscheidung hängt ab vom Anwendungsfall, auf den die umgewandelten Daten abzielen.

Wenn beispielsweise ein aktualisierbarer, persistenter Speicher beibehalten werden soll und die Sequenz oder Reihenfolge der Ereignisse wichtig ist, ist eine ausschließlich sequenzielle Verarbeitung von ETL-Umwandlungen erforderlich.

In anderen Fällen können Daten, die nicht in Reihenfolge vorliegen, von nachgelagerten Anwendungen/Prozessen verarbeitet werden, die anhand eines festgelegten Zeitstempels intern die Sortierung vornehmen. In diesen Fällen können gleichzeitige ETL-Umwandlungen zur Verbesserung der Verarbeitungszeit beitragen.

Bei Quell-Batches hängt die Entscheidung ebenfalls von der Präferenz des Client sowie von Begrenzungen seitens Verbrauchern ab. Wenn eine gleichzeitige Erfassung von Quelldaten ohne Berücksichtigung von Hierarchie/Reihenfolge einer Zeile möglich ist, kann der Umwandlungsprozess Batches für die Verarbeitung mit einem höheren Grad an Parallelität erstellen (Optimierung basierend Auftragsverarbeitung ohne Reihenfolge). Wenn bei der Umwandlung jedoch Zeitstempel berücksichtigt oder die Rangfolge geändert werden muss, muss die Data Access API oder für die Planung/den Aufruf des ETL-Tools sichergestellt sein, dass Batches soweit möglich nicht in Reihenfolge verarbeitet werden.

Rückstellung

Der Prozess der Rückstellung wird angewendet, wenn Eingabedaten noch nicht vollständig genug sind, um an nachgelagerte Prozesse übergeben zu werden, jedoch in Zukunft nützlich sein könnten. Clients legen ihre individuelle Toleranz hinsichtlich des Daten-Windowing für den zukünftigen Abgleich gegenüber den Verarbeitungskosten fest, um über ihre Entscheidung zu informieren, Daten beiseite zu legen und sie bei der nächsten Umwandlung neu zu verarbeiten. Dies geschieht in der Hoffnung, sie zu einem späteren Zeitpunkt innerhalb des Aufbewahrungsfensters anreichern und abstimmen/zusammenführen zu können. Dieser Zyklus dauert so lange an, bis die Zeile entweder ausreichend verarbeitet oder als veraltet gilt. Im letzteren Fall ist sie dann keine weitere Investition mehr wert. Bei jeder Iteration werden zurückgestellte Daten generiert, die ein Superset aller zurückgestellten Daten der vorherigen Iterationen darstellen.

Adobe Experience Platform erkennt derzeit keine zeitversetzten Daten. Daher müssen Client-Implementierungen anhand manueller ETL- und Datensatz-Konfigurationen einen weiteren Datensatz in Platform erstellen, der den Quelldatensatz spiegelt. Dieser kann dann zur Aufbewahrung zeitversetzter Daten verwendet werden. In diesem Fall sind zurückgestellte Daten Momentaufnahmen-Daten ähnlich: Bei jeder Ausführung der ETL-Umwandlung werden die Quelldaten mit verzögerten Daten zusammengeführt und zur Verarbeitung übergeben.

Änderungsprotokoll