[Beta]{class="badge informative"}

Conectar Capillary Streaming Events a Experience Platform mediante la API Flow Service

Lea esta guía para aprender a usar Capillary Streaming Events y la Flow Service API para transmitir datos de su cuenta de Capillary a Adobe Experience Platform.

Introducción

Esta guía requiere una comprensión práctica de los siguientes componentes de Experience Platform:

Recopilar credenciales necesarias

Lea la Capillary Streaming Events descripción general para obtener información sobre la autenticación.

Uso de API de Experience Platform

Lea la guía sobre introducción a las API de Experience Platform para obtener información sobre cómo realizar llamadas a las API de Experience Platform correctamente.

Lista de comprobación de procesos de desarrollador

Crear una conexión base base-connection

Una conexión base conserva las credenciales y los detalles de conexión. Para crear una conexión base para Capillary, realice una petición POST al extremo /connections de la API Flow Service y proporcione sus credenciales Capillary en el cuerpo de la solicitud.

Formato de API

POST /connections

Solicitud

La siguiente solicitud crea una conexión base para 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}"
      }
    }
  }'

Respuesta

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

Crear una conexión de origen

Para crear una conexión de origen, realice una petición POST al extremo /sourceConnections y proporcione el identificador de conexión base.

Formato de API

POST /flowservice/sourceConnections

Solicitud

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

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 con información detallada de la conexión de origen recién creada, incluido su identificador único (id).

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

Configuraciones de esquema

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

Migración de datos históricos

Puede introducir sus datos históricos de lealtad y transacciones en Experience Platform. Simplemente exporte sus datos como archivos CSV estructurados de Capillary, transfiéralos de forma segura mediante SFTP e ingréselos en sus conjuntos de datos de Experience Platform. Después de la migración inicial, los datos se mantendrán actualizados en tiempo real a través del conector impulsado por evento.

Creación de un esquema XDM de destino target-schema

Un esquema del Modelo de datos de experiencia (XDM) proporciona una forma estandarizada de organizar y describir los datos de experiencia del cliente dentro de Experience Platform. Para introducir los datos de origen en Experience Platform, primero debe crear un esquema XDM de destino que defina la estructura y los tipos de datos que desea introducir. Este esquema sirve como modelo para el conjunto de datos de Experience Platform donde residirán los datos ingeridos.

Se puede crear un esquema XDM de destino realizando una petición POST a la API del Registro de esquemas. Para ver los pasos detallados sobre cómo crear un esquema XDM de destino, lea las siguientes guías:

Una vez creado, el esquema XDM de destino $id se requerirá más adelante para el conjunto de datos de destino y la asignación.

Crear un conjunto de datos de destinatario target-dataset

Un conjunto de datos es una construcción de almacenamiento y administración para una colección de datos, normalmente estructurada como una tabla con columnas (esquema) y filas (campos). Los datos que se incorporan correctamente a Experience Platform se almacenan dentro del lago de datos como conjuntos de datos. Durante este paso, puede crear un nuevo conjunto de datos o utilizar uno existente.

Puede crear un conjunto de datos de destino realizando una petición POST a la API del servicio de catálogo, al mismo tiempo que proporciona el ID del esquema de destino en la carga útil. Para ver los pasos detallados sobre cómo crear un conjunto de datos de destinatario, lea la guía sobre crear un conjunto de datos mediante la API.

Creación de una conexión de destino target

Una conexión de destino representa la conexión con el destino donde aterrizan los datos introducidos. Para crear una conexión de destino, debe proporcionar el ID de especificación de conexión fija asociado al lago de datos. Este id. de especificación de conexión es: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Formato de API

POST /targetConnections

Solicitud

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

Creación de una asignación mapping

A continuación, asigne los datos de origen al esquema de destino al que se adhiere el conjunto de datos de destino. Para crear una asignación, realice una petición POST al extremo mappingSets de la Data Prep API. Incluya el ID del esquema XDM de destino y los detalles de los conjuntos de asignaciones que desee crear.

Asigne los campos capilares a los campos de esquema XDM correspondientes de la siguiente manera:

Creación de un flujo de datos flow

Después de crear la conexión de origen, la asignación y la conexión de destino, puede configurar un flujo de datos para mover datos de Capillary a Experience Platform.

Los flujos de datos habituales incluyen:

Solicitud

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

Respuesta

Una respuesta correcta devuelve el flujo de datos con su ID de flujo de datos correspondiente.

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

Control de errores

El conector incluye un control de errores sólido para los siguientes casos:

Todos los errores se registran con detalles como el tipo de error, la marca de tiempo, la carga útil de solicitud y la respuesta de la API de Adobe para facilitar la resolución de problemas y la depuración.

Prueba de la conexión

Siga los pasos a continuación para conocer los pasos que puede seguir para probar la conexión:

Apéndice

Visite la siguiente documentación para obtener guías sobre operaciones adicionales