[Beta]{class="badge informative"}

Connetti Capillary Streaming Events ad Experience Platform utilizzando l'API Flow Service

Leggi questa guida per scoprire come utilizzare Capillary Streaming Events e l'Flow Service API per inviare dati dal tuo account Capillary a Adobe Experience Platform.

Introduzione

Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:

Raccogli le credenziali richieste

Per informazioni sull'autenticazione, leggere la Capillary Streaming Events panoramica.

Utilizzo delle API di Experience Platform

Per informazioni su come effettuare correttamente chiamate alle API di Experience Platform, leggi la guida guida introduttiva alle API di Experience Platform.

Elenco di controllo del processo sviluppatore

Creare una connessione di base base-connection

Una connessione di base conserva le credenziali e i dettagli di connessione. Per creare una connessione di base per Capillary, effettuare una richiesta POST all'endpoint /connections dell'API Flow Service e fornire le credenziali Capillary nel corpo della richiesta.

Formato API

POST /connections

Richiesta

La richiesta seguente crea una connessione di base per 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}"
      }
    }
  }'

Risposta

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

Creare una connessione sorgente

Per creare una connessione di origine, eseguire una richiesta POST all'endpoint /sourceConnections fornendo l'ID connessione di base.

Formato API

POST /flowservice/sourceConnections

Richiesta

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

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 201 con informazioni dettagliate sulla connessione di origine appena creata, incluso il relativo identificatore univoco (id).

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

Configurazioni schema

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

Migrazione dei dati storici

Puoi inserire in Experience Platform i dati storici relativi a fidelizzazione e transazioni. È sufficiente esportare i dati come file CSV strutturati da Capillary, trasferirli in modo sicuro utilizzando SFTP e acquisirli nei set di dati di Experience Platform. Dopo la migrazione iniziale, i dati rimarranno aggiornati in tempo reale tramite il connettore basato su eventi.

Creare uno schema XDM di destinazione target-schema

Uno schema Experience Data Model (XDM) fornisce un modo standardizzato per organizzare e descrivere i dati sull’esperienza del cliente in Experience Platform. Per acquisire i dati di origine in Experience Platform, devi innanzitutto creare uno schema XDM di destinazione che definisca la struttura e i tipi di dati da acquisire. Questo schema funge da blueprint per il set di dati di Experience Platform in cui risiederanno i dati acquisiti.

È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST all'API Schema Registry. Per i passaggi dettagliati su come creare uno schema XDM di destinazione, leggi le seguenti guide:

Una volta creato, lo schema XDM di destinazione $id sarà necessario in seguito per il set di dati di destinazione e la mappatura.

Creare un set di dati di destinazione target-dataset

Un set di dati è un costrutto di archiviazione e gestione per una raccolta di dati, in genere strutturato come una tabella con colonne (schema) e righe (campi). I dati acquisiti correttamente in Experience Platform vengono memorizzati nel data lake come set di dati. Durante questo passaggio, puoi creare un nuovo set di dati o utilizzarne uno esistente.

È possibile creare un set di dati di destinazione effettuando una richiesta POST all'API Catalog Service, fornendo al tempo stesso l'ID dello schema di destinazione all'interno del payload. Per i passaggi dettagliati su come creare un set di dati di destinazione, consulta la guida su creazione di un set di dati utilizzando l'API.

Creare una connessione di destinazione target

Una connessione di destinazione rappresenta la connessione alla destinazione in cui arrivano i dati acquisiti. Per creare una connessione di destinazione, devi fornire l’ID di specifica della connessione fissa associato al data lake. ID della specifica di connessione: c604ff05-7f1a-43c0-8e18-33bf874cb11c.

Formato API

POST /targetConnections

Richiesta

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

Creare una mappatura mapping

Quindi, mappa i dati di origine con lo schema di destinazione a cui aderisce il set di dati di destinazione. Per creare una mappatura, effettuare una richiesta POST all'endpoint mappingSets dell'Data Prep API. Includi l’ID dello schema XDM di destinazione e i dettagli dei set di mappatura che desideri creare.

Mappa i campi Capillary ai campi dello schema XDM corrispondenti come segue:

Creare un flusso di dati flow

Dopo aver creato la connessione di origine, la mappatura e la connessione di destinazione, puoi configurare un flusso di dati per spostare i dati da Capillary ad Experience Platform.

I flussi di dati tipici includono:

Richiesta

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

Risposta

In caso di esito positivo, la risposta restituisce il flusso di dati con l’ID del flusso di dati corrispondente.

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

Gestione degli errori

Il connettore include una solida gestione degli errori per i seguenti scenari:

Tutti gli errori vengono registrati con dettagli quali il tipo di errore, la marca temporale, il payload della richiesta e la risposta API di Adobe per facilitare la risoluzione dei problemi e il debug.

Verifica la connessione

Segui i passaggi seguenti per scoprire i passaggi da seguire per verificare la connessione:

Appendice

Consulta la seguente documentazione per guide su operazioni aggiuntive