[Beta]{class="badge informative"}

Verbinden von Capillary Streaming Events mit Experience Platform mithilfe der Flow Service-API

Lesen Sie dieses Handbuch, um zu erfahren, wie Sie mit dem Capillary Streaming Events und der Flow Service API Daten von Ihrem Capillary an Adobe Experience Platform streamen.

Erste Schritte

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

Sammeln erforderlicher Anmeldedaten

Informationen zur Authentifizierung Capillary Streaming Events Sie inÜbersicht“.

Verwenden von Experience Platform-APIs

Lesen Sie das Handbuch Erste Schritte mit Experience Platform-APIs um Informationen darüber zu erhalten, wie Sie Experience Platform-APIs erfolgreich aufrufen können.

Checkliste für Entwicklerprozesse

Erstellen einer Basisverbindung base-connection

Eine Basisverbindung behält Anmeldeinformationen und Verbindungsdetails bei. Um eine Basisverbindung für Capillary zu erstellen, stellen Sie eine POST-Anfrage an den /connections-Endpunkt der Flow Service-API und geben Sie im Anfragetext Ihre Capillary-Anmeldeinformationen an.

API-Format

POST /connections

Anfrage

Die folgende Anfrage erstellt eine Basisverbindung für Capillary:

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/connections' \
  -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 'Content-Type: application/json' \
  -d '{
    "name": "Capillary base connection",
    "description": "Base connection to authenticate the Capillary source.",
    "connectionSpec": {
      "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
      "version": "1.0"
    },
    "auth": {
      "specName": "OAuth generic-rest-connector",
      "params": {
        "clientId": "{CLIENT_ID}",
        "clientSecret": "{CLIENT_SECRET}",
        "accessToken": "{ACCESS_TOKEN}"
      }
    }
  }'

Antwort

A successful response returns the newly created base connection, including its unique connection identifier (id). This ID is required to explore your source's file structure and contents in the next step.

{
     "id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
     "etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}

Erstellen einer Quellverbindung

Um eine Quellverbindung zu erstellen, stellen Sie eine POST-Anfrage an den /sourceConnections-Endpunkt, während Sie Ihre Basisverbindungs-ID angeben.

API-Format

POST /flowservice/sourceConnections

Anfrage

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
      "name": "Capillary Streaming",
      "description": "Capillary Streaming",
      "baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
      "connectionSpec": {
          "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
          "version": "1.0"
      }
    }'

Antwort

Eine erfolgreiche Antwort gibt den HTTP-Status 201 mit Details zur neu erstellten Quellverbindung zurück, einschließlich ihrer eindeutigen Kennung (id).

{
  "id": "34ece231-294d-416c-ad2a-5a5dfb2bc69f",
  "etag": "\"d505125b-0000-0200-0000-637eb7790000\""
}

Schemakonfigurationen

{
  "identityMap": {
    "email": [
      {
        "authenticatedState": "ambiguous",
        "id": "john.doe@capillarytech.com",
        "primary": true
      }
    ]
  },
  "loyalty": {
    "tier": "gold",
    "points": 1250,
    "lifetimePoints": 122,
    "expiredPoints": 12,
    "pointsRedeemed": 500,
    "program": "loyalty program name",
    "status": "active"
  }
}

{
  "id": "8c19f1c3-4b91-47cd-8cb5-b152a93f7349",
  "status": "success",
  "message": "Profile record ingested successfully"
}

{
  "_id": "T0001",
  "timestamp": "2025-07-14T12:00:00-06:00",
  "identityMap": {
    "email": [
      {
        "authenticatedState": "ambiguous",
        "id": "john@capillarytech.com",
        "primary": true
      }
    ]
  },
  "commerce": {
    "commerceScope": {
      "storeCode": "HSR"
    },
    "order": {
      "priceTotal": 90
    }
  },
  "productLineItems": [
    {
      "SKU": "sku_01",
      "quantity": 1,
      "priceTotal": 100,
      "name": "Kitkat",
      "discountAmount": 10
    }
  ]
}

{
  "id": "T0001",
  "status": "success",
  "message": "Transaction event ingested successfully"
}

Historische Datenmigration

Sie können Ihre historischen Treue- und Transaktionsdaten in Experience Platform importieren. Exportieren Sie einfach Ihre Daten als strukturierte CSV-Dateien aus Capillary, übertragen Sie sie mithilfe von SFTP sicher und nehmen Sie sie in Ihre Experience Platform-Datensätze auf. Nach der ersten Migration bleiben Ihre Daten über den ereignisgesteuerten Connector in Echtzeit auf dem neuesten Stand.

Erstellen eines XDM-Zielschemas target-schema

Ein Experience-Datenmodell (XDM)-Schema bietet eine standardisierte Möglichkeit, Kundenerlebnisdaten in Experience Platform zu organisieren und zu beschreiben. Um Ihre Quelldaten in Experience Platform aufzunehmen, müssen Sie zunächst ein Ziel-XDM-Schema erstellen, das die Struktur und die Datentypen definiert, die Sie aufnehmen möchten. Dieses Schema dient als Blueprint für den Experience Platform-Datensatz, in dem sich Ihre aufgenommenen Daten befinden.

Sie können ein Ziel-XDM-Schema erstellen, indem Sie eine POST-Anfrage an die Schema Registry-API senden. Ausführliche Anweisungen zum Erstellen eines XDM-Zielschemas finden Sie in den folgenden Handbüchern:

Nach der Erstellung ist das Ziel-XDM-Schema $id später für Ihren Zieldatensatz und Ihre Zuordnung erforderlich.

Erstellen eines Zieldatensatzes target-dataset

Ein Datensatz ist ein Konstrukt zur Datenspeicherung und -verwaltung, das typischerweise wie eine Tabelle mit Spalten (Schema) und Zeilen (Feldern) strukturiert ist. Daten, die erfolgreich in Experience Platform aufgenommen werden, werden im Data Lake als Datensätze gespeichert. In diesem Schritt können Sie entweder einen neuen Datensatz erstellen oder einen vorhandenen Datensatz verwenden.

Sie können einen Zieldatensatz erstellen, indem Sie eine POST-Anfrage an die Catalog Service API senden und dabei die ID des Zielschemas in der Payload angeben. Ausführliche Anweisungen zum Erstellen eines Zieldatensatzes finden Sie im Handbuch unter Erstellen eines Datensatzes mithilfe der API.

Erstellen einer Zielverbindung target

Eine Zielverbindung stellt die Verbindung zum Ziel dar, in das die aufgenommenen Daten übernommen werden. Um eine Zielverbindung zu erstellen, müssen Sie die feste Verbindungsspezifikations-ID angeben, die mit dem Data Lake verknüpft ist. Diese Verbindungsspezifikations-ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

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: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -H 'Content-Type: application/json' \
  -d '{
      "name": "Capillary Target Connection",
      "description": "Capillary Target Connection",
      "data": {
          "schema": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "6889f4f89b982b2b90bc1207"
      },
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      }
    }'

Erstellen einer Zuordnung mapping

Ordnen Sie anschließend Ihre Quelldaten dem Zielschema zu, dem Ihr Zieldatensatz entspricht. Um eine Zuordnung zu erstellen, stellen Sie eine POST-Anfrage an den mappingSets der Data Prep API. Geben Sie Ihre Ziel-XDM-Schema-ID und die Details der Zuordnungssätze an, die Sie erstellen möchten.

Ordnen Sie die Kapillarfelder den entsprechenden XDM-Schemafeldern wie folgt zu:

Erstellen eines Datenflusses flow

Nachdem Sie die Quellverbindung, die Zuordnung und die Zielverbindung erstellt haben, können Sie einen Datenfluss konfigurieren, um Daten aus Capillary in Experience Platform zu verschieben.

Typische Datenflüsse sind:

Anfrage

curl -X POST \
  'https://platform.adobe.io/data/foundation/flowservice/flows' \
  -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 'Content-Type: application/json' \
  -d '{
    "name": "Capillary dataflow",
    "description": "Capillary → Experience Platform dataflow",
    "flowSpec": {
      "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
      "version": "1.0"
    },
    "sourceConnectionIds": "{SOURCE_CONNECTION_ID}",
    "targetConnectionIds": "{TARGET_CONNECTION_ID}",
    "transformations": [
      {
        "name": "Mapping",
        "params": {
          "mappingId": "{MAPPING_ID}",
          "mappingVersion": "0"
        }
      }
    ],
    "scheduleParams": {
      "startTime": "1625040887",
      "frequency": "minute",
      "interval": 15
    }
  }'

Antwort

Bei einer erfolgreichen Antwort wird Ihr Datenfluss mit der entsprechenden Datenfluss-ID zurückgegeben.

{
  "id": "92f11b8c-0a9f-45a9-8239-60b4e8430a88",
  "status": "enabled",
  "message": "Dataflow created successfully"
}

Umgang mit Fehlern

Der Connector umfasst eine robuste Fehlerbehandlung für die folgenden Szenarien:

Alle Fehler werden mit Details wie Fehlertyp, Zeitstempel, Anfrage-Payload und Adobe-API-Antwort protokolliert, um die Fehlerbehebung und das Debugging zu erleichtern.

Testen der Verbindung

Gehen Sie wie folgt vor, um zu erfahren, wie Sie Ihre Verbindung testen können:

Anhang

In der folgenden Dokumentation finden Sie Handbücher zu zusätzlichen Vorgängen