Flow Service wird zur Erfassung und Zentralisierung von Kundendaten aus unterschiedlichen Quellen innerhalb von Adobe Experience Platform verwendet. Der Dienst stellt eine Benutzeroberfläche und eine RESTful-API bereit, über die alle unterstützten Quellen verbunden werden können.
In diesem Lernprogramm werden die Schritte zum Abrufen von Daten aus einem Streaming-Quellanschluss und zum Übertragen nach Experience Platform mithilfe der Flow Service API beschrieben.
Für dieses Lernprogramm benötigen Sie eine gültige Verbindungs-ID für einen Streaming-Connector. Wenn Sie diese Informationen nicht haben, lesen Sie die folgenden Lernprogramme zum Erstellen einer Streaming-Quellverbindung, bevor Sie dieses Lernprogramm durchführen:
Für dieses Lernprogramm müssen Sie außerdem die folgenden Komponenten von Adobe Experience Platform kennen:
{TENANT_ID}
, das Konzept sogenannter „Container“ und die für Anfragen erforderlichen Kopfzeilen, von denen insbesondere die Accept-Kopfzeile und deren mögliche Werte wichtig sind.Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie zur erfolgreichen Datenerfassung mit der Flow Service-API kennen müssen.
In diesem Tutorial 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:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {IMS_ORG}
Alle Ressourcen in Experience Platform, einschließlich derjenigen, die zu Flow Service gehören, 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}
Bei allen Anfragen, die eine Payload enthalten (POST, PUT, PATCH), ist eine zusätzliche Medientyp-Kopfzeile erforderlich:
Content-Type: application/json
Sie können eine Quellverbindung erstellen, indem Sie eine POST an die API Flow Service anfordern. Eine Quellverbindung besteht aus einer Verbindungs-ID, einem Pfad zur Quelldatendatei und einer Verbindungs-Spec-ID.
Um eine Quellverbindung zu erstellen, müssen Sie auch einen Enum-Wert für das Datenformatattribut definieren.
Verwenden Sie die folgenden Enum-Werte für dateibasierte Connectors:
Datenformat | Enum-Wert |
---|---|
Getrennt | delimited |
JSON | json |
Parkett | parquet |
Legen Sie für alle tabellenbasierten Connectors den Wert auf tabular
fest.
API-Format
POST /sourceConnections
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Test source connector for streaming data",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"connectionId": "f6aa6c58-3c3d-4c59-aa6c-583c3d6c599c",
"description": "Test source connector for streaming data",
"data": {
"format": "delimited"
},
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
Eigenschaft | Beschreibung |
---|---|
providerId |
Die Anbieter-ID Ihres Streaming-Connectors. |
connectionId |
Die eindeutige Verbindungs-ID des Streaming-Connectors. |
connectionSpec.id |
Die mit Ihrem spezifischen Streaming-Connector verknüpfte Verbindungsspezifikations-ID. |
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Diese ID ist in einem späteren Schritt zum Erstellen eines Datenflusses erforderlich.
{
"id": "2abd97c4-91bb-4c93-bd97-c491bbfc933d",
"etag": "\"66013508-0000-0200-0000-5f6e2ae70000\""
}
Damit die Quelldaten in Platform verwendet werden können, muss ein Zielgruppe-Schema erstellt werden, um die Quelldaten entsprechend Ihren Anforderungen zu strukturieren. Mit dem Schema Zielgruppe wird dann ein Platform-Datensatz erstellt, in dem die Quelldaten enthalten sind. Diese Zielgruppe XDM-Schema erweitert auch die XDM Individual Profile-Klasse.
Ein Zielgruppe-XDM-Schema kann erstellt werden, indem eine POST an die Schema-Registrierungs-API angefordert wird.
API-Format
POST /tenant/schemas
Anfrage
Die folgende Beispielanforderung erstellt ein XDM-Schema, das die XDM Individual Profile-Klasse erweitert.
curl -X POST \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"type": "object",
"title": "Sample schema for a streaming connector",
"description": "Sample schema for a streaming connector",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details"
}
],
"meta:containerId": "tenant",
"meta:resourceType": "schemas",
"meta:xdmType": "object",
"meta:class": "https://ns.adobe.com/xdm/context/profile"
}'
Antwort
Eine erfolgreiche Antwort gibt Details zum neu erstellten Schema einschließlich seiner eindeutigen Kennung ($id
) zurück. Diese ID ist in späteren Schritten erforderlich, um einen Zielgruppe-Datensatz, eine Zuordnung und einen Datendurchlauf zu erstellen.
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
"meta:altId": "_{TENANT_ID}.schemas.e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
"meta:resourceType": "schemas",
"version": "1.0",
"title": "Sample schema for a streaming connector",
"type": "object",
"description": "Sample schema for a streaming connector",
"allOf": [
{
"$ref": "https://ns.adobe.com/xdm/context/profile",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-person-details",
"type": "object",
"meta:xdmType": "object"
},
{
"$ref": "https://ns.adobe.com/xdm/context/profile-personal-details",
"type": "object",
"meta:xdmType": "object"
}
],
"refs": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/context/profile"
],
"imsOrg": "{IMS_ORG}",
"meta:extensible": false,
"meta:abstract": false,
"meta:extends": [
"https://ns.adobe.com/xdm/context/profile-person-details",
"https://ns.adobe.com/xdm/context/profile-personal-details",
"https://ns.adobe.com/xdm/common/auditable",
"https://ns.adobe.com/xdm/data/record",
"https://ns.adobe.com/xdm/context/profile"
],
"meta:xdmType": "object",
"meta:registryMetadata": {
"repo:createdDate": 1604960074752,
"repo:lastModifiedDate": 1604960074752,
"xdm:createdClientId": "{CREATED_CLIENT_ID}",
"xdm:lastModifiedClientId": "{MODIFIED_CLIENT_ID}",
"xdm:createdUserId": "{CREATED_USER_ID}",
"xdm:lastModifiedUserId": "{MODIFIED_USER_ID}",
"eTag": "8522a151effd974429518ed90c3eaf6efc9bf6ffb6644087a85c6d4455dcd045",
"meta:globalLibVersion": "1.16.1"
},
"meta:class": "https://ns.adobe.com/xdm/context/profile",
"meta:containerId": "tenant",
"meta:sandboxId": "{SANDBOX_ID}",
"meta:sandboxType": "production",
"meta:tenantNamespace": "_{TENANT_ID}"
}
Ein Zielgruppen-Datensatz kann erstellt werden, indem eine POST an die Katalogdienst-API angefordert wird und die ID des Zielgruppe-Schemas innerhalb der Nutzlast angegeben wird.
API-Format
POST /catalog/dataSets
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/catalog/dataSets?requestDataSource=true' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1.1"
},
"fileDescription": {
"format": "parquet"
},
"tags": {
"identity": [
"enabled:true"
],
"profile": [
"enabled:true"
]
},
"name": "Test streaming dataset"
}'
Eigenschaft | Beschreibung |
---|---|
schemaRef.id |
Die ID des XDM-Schemas der Zielgruppe. |
Antwort
Eine erfolgreiche Antwort gibt ein Array zurück, das die ID des neu erstellten Datensatzes im Format "@/datasets/{DATASET_ID}"
enthält. Die Datensatz-ID ist eine schreibgeschützte, vom System generierte Zeichenfolge, mit der in API-Aufrufen auf den Datensatz verwiesen wird. Die Zielgruppe DataSet-ID ist in späteren Schritten erforderlich, um eine Zielgruppe- und einen Datendurchlauf zu erstellen.
[
"@/dataSets/5f7187bac6d00f194fb937c0"
]
Eine Zielgruppe-Verbindung stellt die Verbindung mit dem Ziel dar, in dem die erfassten Daten landen. Um eine Zielgruppe-Verbindung zu erstellen, müssen Sie die mit dem Datensee verknüpfte feste Verbindungs-spec-ID angeben. Diese Verbindungs-Spec-ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Sie haben jetzt die eindeutigen Bezeichner, ein Zielgruppe-Schema, einen Zielgruppe-Datensatz und die Verbindungsspezifikations-ID zum Datensee. Mithilfe dieser Bezeichner können Sie eine Zielgruppe-Verbindung mit der API Flow Service erstellen, um den Datensatz anzugeben, der die eingehenden Quelldaten enthalten soll.
API-Format
POST /targetConnections
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Streaming target connection",
"description": "Streaming target connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm"
},
"params": {
"dataSetId": "5f7187bac6d00f194fb937c0"
}
}'
Eigenschaft | Beschreibung |
---|---|
params.dataSetId |
Die ID des Zielgruppe-Datensatzes. |
connectionSpec.id |
Die Verbindungsspezifikations-ID, die zum Herstellen einer Verbindung mit dem Data Lake verwendet wird. Diese ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung der neuen Zielgruppe-Verbindung (id
) zurück. Diese ID ist in späteren Schritten erforderlich.
{
"id": "d9300194-6a82-4163-b001-946a821163b8",
"etag": "\"4006d3e4-0000-0200-0000-5f7189220000\""
}
Damit die Quelldaten in einen Zielgruppe-Datensatz aufgenommen werden können, müssen sie zunächst dem Zielgruppe-Schema zugeordnet werden, dem der Zielgruppe-Datensatz entspricht. Dies wird erreicht, indem eine POST-Anforderung an den Konvertierungsdienst mit Datenzuordnungen ausgeführt wird, die innerhalb der Anforderungs-Nutzlast definiert sind.
API-Format
POST /conversion/mappingSets
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"version": 0,
"xdmSchema": "_{TENANT_ID}.schemas.e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"version": 0
}
]
}'
Eigenschaft | Beschreibung |
---|---|
xdmSchema |
Das $id des Ziel-XDM-Schemas. |
Antwort
Eine erfolgreiche Antwort gibt Details der neu erstellten Zuordnung einschließlich ihrer eindeutigen Kennung (id
) zurück. Diese ID ist in einem späteren Schritt zum Erstellen eines Datenflusses erforderlich.
{
"id": "380b032b445a46008e77585e046efe5e",
"version": 0,
"createdDate": 1604960750613,
"modifiedDate": 1604960750613,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Ein Datenaflow ist für das Sammeln von Daten aus Quellen und deren Einspeisung in Platform verantwortlich. Um einen Datenaflow zu erstellen, müssen Sie zunächst die Datenaflow-Spezifikationen abrufen, indem Sie eine GET an die Flow Service-API senden. Dataflow-Spezifikationen sind für die Datenerfassung über einen Streaming-Connector zuständig.
API-Format
GET /flowSpecs?property=name=="Steam data with transformation"
Anfrage
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="Steam data with transformation"' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Eine erfolgreiche Antwort gibt die Details der Datenaflow-Spezifikation zurück, die für das Übertragen von Daten aus Ihrem Streaming-Connector in Platform verantwortlich ist. Diese ID ist im nächsten Schritt erforderlich, um einen neuen Datenaflow zu erstellen.
{
"items": [
{
"id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
"name": "Steam data with transformation",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"version": "1.0",
"sourceConnectionSpecIds": [
"d27d4907-7351-47dd-bbc2-05a04365703d",
"51ae16c2-bdad-42fd-9fce-8d5dfddaf140",
"bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"transformationSpecs": [
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from Raw to XDM",
"properties": {
"mappingId": {
"type": "string"
}
},
"required": [
"mappingId"
]
}
}
],
"attributes": {
"uiAttributes": {
"apiFeatures": {
"deleteSupported": false,
"updateSupported": false,
"flowRunsSupported": false
}
}
},
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "StreamingSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "StreamingSource",
"permissions": [
"write"
]
}
]
}
}
]
}
Der letzte Schritt zur Datenerfassung ist die Erstellung eines Datenflusses. Inzwischen sind die folgenden erforderlichen Werte vorbereitet:
Ein Datenaflow ist für die Planung und Erfassung von Daten aus einer Quelle verantwortlich. Sie können einen Datenaflow erstellen, indem Sie eine POST anfordern, während Sie die zuvor genannten Werte innerhalb der Nutzlast angeben.
API-Format
POST /flows
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Streaming dataflow",
"description": "Streaming dataflow",
"flowSpec": {
"id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
"version": "1.0"
},
"sourceConnectionIds": [
"2abd97c4-91bb-4c93-bd97-c491bbfc933d"
],
"targetConnectionIds": [
"723222e2-6ab9-4b0b-b222-e26ab9bb0bc2"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "380b032b445a46008e77585e046efe5e",
"mappingVersion": 0
}
}
]
}'
Eigenschaft | Beschreibung |
---|---|
flowSpec.id |
Die flow spec ID, die im vorherigen Schritt abgerufen wurde. |
sourceConnectionIds |
Die Quellverbindungs-ID wurde in einem früheren Schritt abgerufen. |
targetConnectionIds |
Die Ziel-Verbindungs-ID wurde in einem früheren Schritt abgerufen. |
transformations.params.mappingId |
Die Zuordnungs-ID wurde in einem früheren Schritt abgerufen. |
Antwort
Eine erfolgreiche Antwort gibt die ID (id
) des neu erstellten Datenflusses zurück.
{
"id": "1f086c23-2ea8-4d06-886c-232ea8bd061d",
"etag": "\"8e000533-0000-0200-0000-5f3c40fd0000\""
}
In diesem Tutorial haben Sie einen Datenaflow erstellt, um Streaming-Daten von Ihrem Streaming-Connector zu erfassen. Eingehende Daten können jetzt von nachgeschalteten Platform-Diensten wie Real-time Customer Profile und Data Science Workspace verwendet werden. Weitere Informationen finden Sie in den folgenden Dokumenten: