[Beta]{class="badge informative"}

Connexion de Capillary Streaming Events à Experience Platform à l’aide de l’API Flow Service

Lisez ce guide pour savoir comment utiliser le Capillary Streaming Events et l’Flow Service API pour diffuser des données de votre compte Capillary vers Adobe Experience Platform.

Prise en main

Ce guide nécessite une compréhension professionnelle des composants suivants d’Experience Platform :

Collecter les informations d’identification requises

Lisez la Capillary Streaming Events présentation pour plus d’informations sur l’authentification.

Utilisation des API Experience Platform

Lisez le guide sur Prise en main des API Experience Platform pour plus d’informations sur la manière d’effectuer avec succès des appels vers les API Experience Platform.

Liste de contrôle du processus du développeur

Créer une connexion de base base-connection

Une connexion de base conserve les informations d’identification et de connexion. Pour créer une connexion de base pour Capillary, envoyez une requête POST au point d’entrée /connections de l’API Flow Service et indiquez vos informations d’identification de Capillary dans le corps de la requête.

Format d’API

POST /connections

Requête

La requête suivante permet de créer une connexion de base pour 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}"
      }
    }
  }'

Réponse

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

Créer une connexion source

Pour créer une connexion source, envoyez une requête POST au point d’entrée /sourceConnections et indiquez votre identifiant de connexion de base.

Format d’API

POST /flowservice/sourceConnections

Requête

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

Réponse

Une réponse réussie renvoie le statut HTTP 201 avec les détails de la connexion source nouvellement créée, y compris son identifiant unique (id).

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

Configurations de schéma

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

Migration des données historiques

Vous pouvez importer vos données historiques de fidélité et de transaction dans Experience Platform. Il vous suffit d’exporter vos données au format CSV structuré à partir de Capillary, de les transférer en toute sécurité à l’aide de SFTP et de les ingérer dans vos jeux de données Experience Platform. Après la migration initiale, vos données restent à jour en temps réel grâce au connecteur piloté par les événements.

Créer un schéma XDM cible target-schema

Un schéma de modèle de données d’expérience (XDM) offre un moyen normalisé d’organiser et de décrire les données d’expérience client dans Experience Platform. Pour ingérer les données sources dans Experience Platform, vous devez d’abord créer un schéma XDM cible qui définit la structure et les types de données à ingérer. Ce schéma sert de plan directeur pour le jeu de données Experience Platform où se trouveront vos données ingérées.

Un schéma XDM cible peut être créé en adressant une requête POST à l’API Schema Registry. Pour obtenir des instructions détaillées sur la création d’un schéma XDM cible, consultez les guides suivants :

Une fois créé, le schéma XDM cible $id sera requis ultérieurement pour votre jeu de données cible et votre mappage.

Créer un jeu de données cible target-dataset

Un jeu de données est une structure de stockage et de gestion pour une collection de données, généralement structurée comme un tableau avec des colonnes (schéma) et des lignes (champs). Les données correctement ingérées par Experience Platform sont stockées dans le lac de données sous forme de jeux de données. Au cours de cette étape, vous pouvez créer un jeu de données ou en utiliser un existant.

Vous pouvez créer un jeu de données cible en adressant une requête POST à l’API Catalog Service, tout en fournissant l’identifiant du schéma cible dans la payload. Pour obtenir des instructions détaillées sur la création d’un jeu de données cible, consultez le guide création d’un jeu de données à l’aide de l’API.

Créer une connexion cible target

Une connexion cible représente la connexion à la destination où se trouvent les données ingérées. Pour créer une connexion cible, vous devez fournir l’identifiant fixe de spécification de connexion associé au lac de données. Cet identifiant de spécification de connexion est : c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Format d’API

POST /targetConnections

Requête

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

Créer un mappage mapping

Mappez ensuite vos données source au schéma cible auquel votre jeu de données cible se conforme. Pour créer un mappage, envoyez une requête POST au point d’entrée mappingSets de l’Data Prep API. Incluez votre identifiant de schéma XDM cible et les détails des jeux de mappages que vous souhaitez créer.

Mappez les champs capillaires aux champs de schéma XDM correspondants comme suit :

Créer un flux de données flow

Après avoir créé la connexion source, le mappage et la connexion cible, vous pouvez configurer un flux de données pour déplacer les données de Capillary vers Experience Platform.

Les flux de données standard incluent :

Requête

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

Réponse

Une réponse réussie renvoie votre flux de données avec son identifiant de flux de données correspondant.

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

Traitement des erreurs

Le connecteur offre une gestion des erreurs robuste pour les scénarios suivants :

Toutes les erreurs sont consignées avec des détails tels que le type d’erreur, l’horodatage, la payload de la requête et la réponse de l’API Adobe pour faciliter le dépannage et le débogage.

Tester votre connexion

Suivez les étapes ci-dessous pour découvrir les étapes à suivre pour tester votre connexion :

Annexe

Consultez la documentation suivante pour obtenir des guides sur les opérations supplémentaires