[Beta]{class="badge informative"}

使用Capillary Streaming Events API連線Flow Service至Experience Platform

Last update: Mon Sep 29 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

主題：

建立對象：

開發人員

AVAILABILITY

Capillary Streaming Events來源是測試版。閱讀來源概觀中的條款與條件，以取得有關使用測試版標籤之來源的詳細資訊。

閱讀本指南，瞭解如何使用Capillary Streaming Events和Flow Service API，將資料從您的Capillary帳戶串流至Adobe Experience Platform。

快速入門

本指南需要您深入瞭解下列Experience Platform元件：

來源： Experience Platform允許從各種來源擷取資料，同時讓您能夠使用Experience Platform服務來建構、加標籤以及增強傳入的資料。
沙箱： Experience Platform提供的虛擬沙箱可將單一Experience Platform執行個體分割成個別的虛擬環境，以利開發及改進數位體驗應用程式。

收集必要的認證

閱讀Capillary Streaming Events 總覽以取得驗證的相關資訊。

使用Experience Platform API

閱讀Experience Platform API快速入門的指南，瞭解如何成功呼叫Experience Platform API。

recommendation-more-help

開發人員流程檢查清單

使用結構描述登入建立或選擇您的目標 體驗資料模型(XDM)結構描述。使用此XDM結構描述在目錄服務中 建立資料集。
建立 基底連線 以儲存您的Capillary認證。
建立 來源連線 以繫結至您的baseConnectionId。
建立 目標連線 以確保您的資料登陸到資料湖。
使用「資料準備」建立對應，將您的Capillary來源欄位對應到正確的XDM欄位。
使用您的sourceConnectionId、targetConnectionId和mappingID建立資料流
使用單一範例設定檔/交易事件進行測試，以驗證您的資料流。

style

shade-box

建立基礎連線 base-connection

基礎連線會保留認證和連線詳細資料。若要為Capillary建立基底連線，請對/connections API的Flow Service端點提出POST要求，並在要求內文中提供您的Capillary認證。

API格式

POST /connections

要求

下列要求會建立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}"
      }
    }
  }'

回應

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

建立來源連線

若要建立來源連線，請在提供您的基本連線ID時，對/sourceConnections端點提出POST要求。

API格式

POST /flowservice/sourceConnections

要求

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

回應

成功的回應會傳回HTTP狀態201，其中包含新建立的來源連線的詳細資料，包括其唯一識別碼(id)。

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

結構描述設定

設定檔擷取

設定檔包含身分和忠誠度屬性。檢視下列裝載以根據Capillary設定檔結構描述的範例。您可以設定此結構並對應至XDM個別設定檔。

要求

code language-json

code language-json
`{ "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" } }`

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

回應

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

交易擷取

交易會擷取商務活動。檢視下列裝載以取得以Capillary事件結構描述為基礎的範例。您可以設定此結構並對應至XDM體驗事件。

要求

code language-json

code language-json
`{ "_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",
  "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
    }
  ]
}

回應

code language-json
`{ "id": "T0001", "status": "success", "message": "Transaction event ingested successfully" }`

歷史資料移轉

您可以將歷史忠誠度和交易資料帶入Experience Platform。只要從Capillary將您的資料匯出為結構化CSV檔案、使用SFTP安全地傳輸這些檔案，並將它們擷取到您的Experience Platform資料集中。初始移轉後，您的資料將透過事件導向聯結器即時保持最新。

建立目標XDM結構描述 target-schema

Experience Data Model (XDM)結構描述提供一種標準化方式，可在Experience Platform中組織和描述客戶體驗資料。若要將來源資料內嵌至Experience Platform，您必須先建立目標XDM結構描述，定義您要內嵌的資料結構和型別。此結構描述可作為您擷取之資料將存放的Experience Platform資料集的藍圖。

可透過對結構描述登入API執行POST要求來建立目標XDM結構描述。如需如何建立目標XDM架構的詳細步驟，請閱讀以下指南：

建立後，稍後將需要目標XDM結構描述$id以用於您的目標資料集和對應。

建立目標資料集 target-dataset

資料集是資料集合的儲存和管理結構，通常會像有欄（結構描述）和列（欄位）的表格一樣結構。成功擷取至Experience Platform的資料會以資料集的形式儲存在資料湖中。在此步驟中，您可以建立新資料集或使用現有資料集。

您可以對目錄服務API發出POST要求，同時在承載中提供目標結構描述的ID，藉此建立目標資料集。如需如何建立目標資料集的詳細步驟，請參閱使用API建立資料集的指南。

建立目標連線 target

目標連線代表與擷取資料著陸目的地之間的連線。若要建立目標連線，您必須提供與Data Lake關聯的固定連線規格ID。此連線規格識別碼為： c604ff05-7f1a-43c0-8e18-33bf874cb11c。

API格式

POST /targetConnections

要求

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

建立對應 mapping

接著，將來源資料對應至目標資料集所固定的目標結構描述。若要建立對應，請對mappingSetsAPIData Prep 的端點提出POST要求。包含您的目標XDM結構描述ID和您要建立之對應集的詳細資訊。

將「毛細管」欄位對應至對應的XDM結構描述欄位，如下所示：

來源結構描述

目標結構描述

identityMap.email.id

xdm:identityMap.email[0].id

loyalty.points

xdm:loyalty.points

loyalty.tier

xdm:loyalty.tier

commerce.order.priceTotal

xdm:commerce.order.priceTotal

productLineItems.SKU

xdm:productListItems.SKU

TIP

當您準備好對應您的資料時，可以下載和的Capillary事件和設定檔對應將檔案匯入到「資料準備」。

建立資料流 flow

建立來源連線、對應及目標連線後，您可以設定資料流，將資料從Capillary移至Experience Platform。

典型的資料流包括：

設定檔資料流：將Capillary設定檔資料擷取至XDM個別設定檔資料集。
交易資料流：將Capillary交易資料擷取至XDM ExperienceEvent資料集。

要求

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

NOTE

startTime處於UNIX紀元秒內。

回應

成功的回應會傳回您的資料流及其對應的資料流ID。

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

錯誤處理

聯結器包含下列情況的健全錯誤處理：

驗證錯誤：驗證失敗時自動重新整理Adobe認證。
速率限制錯誤：在達到API速率限制時，實作具有指數回溯的重試。
網路錯誤：記錄並重試失敗的網路要求。
資料驗證錯誤：記錄無效的裝載，以進行手動檢閱和解決。

所有錯誤都隨錯誤型別、時間戳記、請求裝載和Adobe API回應等詳細資訊一起記錄，以促進疑難排解和偵錯。

測試您的連線

請依照下列步驟，瞭解測試連線時可採取的步驟：

向/connections/{BASE_CONNECTION_ID}發出GET請求並提供您的基本連線ID，以驗證您的基本連線是否存在。在此步驟中，您也可以確認基礎連線的狀態已設為active。
向/flowservice/sourceConnections/{SOURCE_CONNECTION_ID}發出GET請求並提供您的來源連線ID以驗證您的來源連線。
使用您的串流端點URL來傳送範例設定檔裝載（使用設定檔擷取JSON）。
導覽至您在Experience Platform UI中的資料集，並對資料集執行查詢以確認您的記錄。
使用「資料準備」記錄檔來檢查錯誤。
如果您必須開啟支援票證，請確保您具備下列條件：
- 請求承載
- 回應內文
- Request-id
- 時間戳記
- 資源ID

附錄

如需其他作業指南，請瀏覽下列檔案

337b99bb-92fb-42ae-b6b7-c7042161d089