[Beta]{class="badge informative"}

Verbinding maken met Experience Platform via de Capillary Streaming Events APIFlow Service

Lees deze gids om te leren hoe te om Capillary Streaming Events en Flow Service APIte gebruiken om gegevens van uw Capillary rekening aan Adobe Experience Platform te stromen.

Aan de slag

Deze handleiding vereist een goed begrip van de volgende onderdelen van Experience Platform:

Vereiste referenties verzamelen

Lees het Capillary Streaming Events overzichtvoor informatie over authentificatie.

Experience Platform API's gebruiken

Lees de gids op begonnen wordt met Experience Platform APIsvoor informatie over hoe te met succes vraag aan Experience Platform APIs maken.

Controlelijst voor ontwikkelproces

Een basisverbinding maken base-connection

Een basisverbinding behoudt referenties en verbindingsdetails. Als u een basisverbinding voor Capillary wilt maken, vraagt u een POST-aanvraag naar het /connections -eindpunt van de Flow Service API en geeft u de Capillary -gegevens op in de hoofdtekst van de aanvraag.

API formaat

POST /connections

Verzoek

Met de volgende aanvraag wordt een basisverbinding voor Capillary gemaakt:

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

Reactie

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

Een bronverbinding maken

Om een bronverbinding tot stand te brengen, doe een POST- verzoek aan het /sourceConnections eindpunt terwijl het verstrekken van uw identiteitskaart van de basisverbinding.

API formaat

POST /flowservice/sourceConnections

Verzoek

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

Reactie

Een succesvolle reactie keert status 201 van HTTP met gedetailleerde van de pas gecreëerde bronverbinding, met inbegrip van zijn uniek herkenningsteken (id) terug.

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

Schema-configuraties

{
  "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 gegevensmigratie

Je kunt je historische loyaliteit en transactiegegevens naar Experience Platform brengen. Exporteer uw gegevens gewoon als gestructureerde CSV-bestanden vanuit Capillary, breng ze veilig over met SFTP en neem ze op in uw Experience Platform-gegevenssets. Na de eerste migratie blijven uw gegevens in real-time up-to-date via de gebeurtenisgestuurde connector.

Een doel-XDM-schema maken target-schema

Een schema van de Gegevens van de Ervaring van het Model (XDM) verstrekt een gestandaardiseerde manier om gegevens van de klantenervaring binnen Experience Platform te organiseren en te beschrijven. Om uw brongegevens in Experience Platform in te voeren, moet u eerst een doelXDM schema tot stand brengen dat de structuur en de soorten gegevens bepaalt u wilt opnemen. Dit schema dient als blauwdruk voor de dataset van Experience Platform waar uw opgenomen gegevens zullen verblijven.

Een doelXDM schema kan worden gecreeerd door een POST- verzoek aan de Registratie API van het Schemauit te voeren. Lees de volgende hulplijnen voor gedetailleerde stappen over het maken van een doel-XDM-schema:

Zodra gecreeerd, zal het doelXDM schema $id later voor uw doeldataset en afbeelding worden vereist.

Een doelgegevensset maken target-dataset

Een dataset is een opslag en beheersconstructie voor een inzameling van gegevens, typisch gestructureerd zoals een lijst met kolommen (schema) en rijen (gebieden). De gegevens die met succes in Experience Platform worden opgenomen worden opgeslagen binnen het gegevensmeer als datasets. Tijdens deze stap, kunt u of een nieuwe dataset tot stand brengen of bestaande gebruiken.

U kunt een doeldataset tot stand brengen door een POST- verzoek aan de Dienst API van de Cataloguste doen, terwijl het verstrekken van identiteitskaart van het doelschema binnen de nuttige lading. Voor gedetailleerde stappen op hoe te om een doeldataset tot stand te brengen, lees de gids bij het creëren van een dataset gebruikend API.

Een doelverbinding maken target

Een doelverbinding vertegenwoordigt de verbinding aan de bestemming waar de ingesloten gegevens binnen landen. Om een doelverbinding tot stand te brengen, moet u vaste identiteitskaart van de verbindingsspecificatie verstrekken verbonden aan het gegevens meer. Deze verbindingsspecificatie-id is: c604ff05-7f1a-43c0-8e18-33bf874cb11c .

API formaat

POST /targetConnections

Verzoek

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

Een toewijzing maken mapping

Daarna, kaart uw brongegevens aan het doelschema dat uw doeldataset volgt aan. Om een afbeelding tot stand te brengen, doe een POST verzoek aan het mappingSets eindpunt van Data Prep API. Neem de doel-XDM-schema-id op en de details van de toewijzingssets die u wilt maken.

Wijs de Capillaire gebieden aan de overeenkomstige XDM schemagebieden als volgt toe:

Een gegevensstroom maken flow

Nadat u de bronverbinding, toewijzing en doelverbinding hebt gemaakt, kunt u een gegevensstroom configureren om gegevens van Capillary naar Experience Platform te verplaatsen.

De meest gangbare gegevensstromen zijn:

Verzoek

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

Reactie

Een succesvolle reactie keert uw gegevensstroom met zijn overeenkomstige dataflow ID terug.

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

Foutafhandeling

De schakelaar omvat robuuste fout behandeling voor de volgende scenario's:

Alle fouten worden geregistreerd met details zoals fouttype, timestamp, request payload, en Adobe API reactie om het oplossen van problemen en het zuiveren te vergemakkelijken.

De verbinding testen

Voer de onderstaande stappen uit om te leren hoe u uw verbinding kunt testen:

Bijlage

Bezoek de volgende documentatie voor hulplijnen voor extra bewerkingen