Der Flow Service dient zur Erfassung und Zentralisierung von Kundendaten aus verschiedenen Quellen innerhalb von Adobe Experience Platform. Der Dienst stellt eine Benutzeroberfläche und eine RESTful-API bereit, über die alle unterstützten Quellen verbunden werden können.
Dieses Lernprogramm verwendet die API Flow Service, um Sie durch die Schritte zum Erstellen einer Streaming-Verbindung mit der Flow Service API zu führen.
Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Adobe Experience Platform voraus:
Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um die APIs für die Streaming-Erfassung erfolgreich aufrufen zu können.
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
Um Platform-APIs aufzurufen, müssen Sie zunächst das Authentifizierungs-Tutorial abschließen. Durch Abschluss des Authentifizierungs-Tutorials werden die Werte für die einzelnen erforderlichen Header in allen Experience Platform-API-Aufrufen bereitgestellt, wie unten dargestellt:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
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:
{SANDBOX_NAME}
Weitere Informationen zu Sandboxen in Platform finden Sie in der Sandbox-Übersichtsdokumentation.
Bei allen Anfragen mit einer Payload (POST, PUT, PATCH) ist eine zusätzliche Kopfzeile erforderlich:
Eine Verbindung gibt die Quelle an und enthält die Informationen, die erforderlich sind, um den Fluss mit Streaming-Erfassungs-APIs kompatibel zu machen. Beim Erstellen einer Verbindung haben Sie die Möglichkeit, eine nicht authentifizierte und eine authentifizierte Verbindung zu erstellen.
Nicht authentifizierte Verbindungen sind die Standard-Streaming-Verbindung, die Sie erstellen können, wenn Sie Daten in Plattform streamen möchten.
API-Format
POST /flowservice/connections
Anfrage
Um eine Streaming-Verbindung zu erstellen, müssen die Anbieter-ID und die Verbindungs-ID als Teil der POST angegeben werden. Die Anbieter-ID ist 521eee4d-8cbe-4906-bb48-fb6bd4450033
und die Verbindungs-ID ist bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-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 '{
"name": "Sample streaming connection",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection",
"dataType": "xdm",
"name": "Sample connection"
}
}
}
Eigenschaft | Beschreibung |
---|---|
auth.params.sourceId |
Die ID der Streaming-Verbindung, die Sie erstellen möchten. |
auth.params.dataType |
Der Datentyp für die Streaming-Verbindung. Dieser Wert muss xdm sein. |
auth.params.name |
Der Name der Streaming-Verbindung, die Sie erstellen möchten. |
connectionSpec.id |
Die Verbindungsspezifikation id für Streaming-Verbindungen. |
Antwort
Eine erfolgreiche Antwort gibt HTTP-Status 201 mit Details zur neu erstellten Verbindung zurück, einschließlich der eindeutigen Kennung (id
).
{
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
Eigenschaft | Beschreibung |
---|---|
id |
Die id Ihrer neu erstellten Verbindung. Dies wird hier als {CONNECTION_ID} bezeichnet. |
etag |
Ein der Verbindung zugewiesener Identifikator, die die Revision der Verbindung angibt. |
Authentifizierte Verbindungen sollten verwendet werden, wenn Sie zwischen Datensätzen aus vertrauenswürdigen und nicht vertrauenswürdigen Quellen unterscheiden müssen. Benutzer, die Informationen mit persönlich identifizierbaren Informationen (PII) senden möchten, sollten beim Streaming von Informationen an die Plattform eine authentifizierte Verbindung herstellen.
API-Format
POST /flowservice/connections
Anfrage
Um eine Streaming-Verbindung zu erstellen, müssen die Anbieter-ID und die Verbindungs-ID als Teil der POST angegeben werden. Die Anbieter-ID ist 521eee4d-8cbe-4906-bb48-fb6bd4450033
und die Verbindungs-ID ist bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-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 '{
"name": "Sample streaming connection",
"providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection",
"dataType": "xdm",
"name": "Sample connection",
"authenticationRequired": true
}
}
}
Eigenschaft | Beschreibung |
---|---|
auth.params.sourceId |
Die ID der Streaming-Verbindung, die Sie erstellen möchten. |
auth.params.dataType |
Der Datentyp für die Streaming-Verbindung. Dieser Wert muss xdm sein. |
auth.params.name |
Der Name der Streaming-Verbindung, die Sie erstellen möchten. |
auth.params.authenticationRequired |
Der Parameter, der die erstellte Streaming-Verbindung angibt |
connectionSpec.id |
Die Verbindungsspezifikation id für Streaming-Verbindungen. |
Antwort
Eine erfolgreiche Antwort gibt HTTP-Status 201 mit Details zur neu erstellten Verbindung zurück, einschließlich der eindeutigen Kennung (id
).
{
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
Eigenschaft | Beschreibung |
---|---|
id |
Die id Ihrer neu erstellten Verbindung. Dies wird hier als {CONNECTION_ID} bezeichnet. |
etag |
Ein der Verbindung zugewiesener Identifikator, die die Revision der Verbindung angibt. |
Mit der erstellten Verbindung können Sie jetzt Ihre Streaming-Endpunkt-URL abrufen.
API-Format
GET /flowservice/connections/{CONNECTION_ID}
Parameter | Beschreibung |
---|---|
{CONNECTION_ID} |
Der id -Wert der zuvor von Ihnen erstellten Verbindung. |
Anfrage
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID} \
-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
Eine erfolgreiche Antwort gibt HTTP-Status 200 mit detaillierten Informationen zur angeforderten Verbindung zurück. Die Streaming-Endpunkt-URL wird automatisch mit der Verbindung erstellt und kann mit dem Wert inletUrl
abgerufen werden.
{
"items": [
{
"createdAt": 1583971856947,
"updatedAt": 1583971856947,
"createdBy": "{API_KEY}",
"updatedBy": "{API_KEY}",
"createdClient": "{USER_ID}",
"updatedClient": "{USER_ID}",
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"name": "Another new sample connection (Experience Event)",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection (ExperienceEvent)",
"inletUrl": "https://dcs.adobedc.net/collection/a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
"inletId": "a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
"dataType": "xdm",
"name": "Sample connection (ExperienceEvent)"
}
},
"version": "\"56008aee-0000-0200-0000-5e697e150000\"",
"etag": "\"56008aee-0000-0200-0000-5e697e150000\""
}
]
}
In diesem Lernprogramm haben Sie eine Streaming-HTTP-Verbindung erstellt, über die Sie den Streaming-Endpunkt zum Erfassen von Daten in die Plattform verwenden können. Anweisungen zum Erstellen einer Streaming-Verbindung in der Benutzeroberfläche finden Sie im Tutorial Erstellen einer Streaming-Verbindung.
Informationen zum Streamen von Daten auf die Plattform finden Sie im Tutorial zu Streaming-Zeitreihendaten oder im Tutorial zu Streaming-Datensatzdaten.
Dieser Abschnitt enthält zusätzliche Informationen zum Erstellen von Streaming-Verbindungen mit der API.
Wenn für eine Streaming-Verbindung die Authentifizierung aktiviert ist, muss der Client die Authorization
-Kopfzeile zu seiner Anfrage hinzufügen.
Wenn die Authorization
-Kopfzeile nicht vorhanden ist oder ein ungültiges/abgelaufenes Zugriffstoken gesendet wird, wird eine HTTP 401 Unerlaubt-Antwort zurückgegeben, mit einer ähnlichen Antwort wie folgt:
Antwort
{
"type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
"status": "401",
"title": "Authorization",
"report": {
"message": "[id] Ims service token is empty"
}
}