使用API建立串流連線

本教學課程將協助您開始使用串流擷取API,這是Adobe Experience Platform資料API的一 Ingestion Service 部分。

快速入門

必須註冊串流連線,才能開始將資料串流至Adobe Experience Platform。 在註冊串流連線時,您需要提供一些關鍵詳細資訊,例如串流資料來源。

在註冊串流連線後,身為資料產生者的您將擁有可用來將資料串流至平台的唯一URL。

本教學課程也需要具備各種Adobe Experience Platform服務的相關知識。 在開始本教學課程之前,請先閱讀下列服務的檔案:

以下章節提供您需要知道的其他資訊,以便成功呼叫串流擷取API。

讀取範例API呼叫

本指南提供範例API呼叫,以示範如何格式化您的請求。 這些包括路徑、必要標題和正確格式化的請求負載。 也提供API回應中傳回的範例JSON。 如需範例API呼叫檔案中所用慣例的詳細資訊,請參閱疑難排解指 南中有關如何讀取範例API呼叫的 Experience Platform 章節。

收集必要標題的值

若要呼叫API,您必 Platform 須先完成驗證教 學課程。 完成驗證教學課程後,將提供所有 Experience Platform API呼叫中每個必要標題的值,如下所示:

  • 授權:生產者 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

中的所有資 Experience Platform 源都與特定虛擬沙盒隔離。 對API的所 Platform 有請求都需要一個標題,該標題會指定要在中執行的操作的沙盒名稱:

  • x-sandbox-name: {SANDBOX_NAME}
注意

如需中沙盒的詳細資訊 Platform,請參閱沙 盒概述檔案

所有包含裝載(POST、PUT、PATCH)的請求都需要額外的標題:

  • 內容類型:application/json

建立連線

連線會指定來源,並包含讓流與串流擷取API相容所需的資訊。

API格式

POST /flowservice/connections

請求

注意

必須使用列 providerId 出和的 connectionSpec​,如示例中所示,因為它們是您為串流擷取建立串流連線的API所指定的值。

curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -d '{
     "name": "Sample name",
     "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
     "description": "Sample description",
     "connectionSpec": {
         "id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
         "version": "1.0"
     },
     "auth": {
         "specName": "Streaming Connection",
         "params": {
             "sourceId": "Sample connection",
             "dataType": "xdm",
             "name": "Sample connection"
         }
     }
 }

回應

成功的回應會傳回HTTP狀態201,並包含新建連線的詳細資訊。

{
    "id": "77a05521-91d6-451c-a055-2191d6851c34",
    "etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
屬性 說明
id 新建 id 的連線的名稱。 這在這裡稱為 {CONNECTION_ID}
etag 指派給連接的標識符,指定連接的修訂版本。

取得資料收集URL

建立連線後,您現在可以擷取資料收集URL。

API格式

GET /flowservice/connections/{CONNECTION_ID}
參數 說明
{CONNECTION_ID} id 先前建立的連接的值。

請求

curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID} \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'x-gw-ims-org-id: {IMS_ORG}' \
 -H 'x-api-key: {API_KEY}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}'

回應

成功的響應返回HTTP狀態200,其中包含所請求連接的詳細資訊。 資料收集URL會自動與連線建立,並可使用值來擷 inletUrl 取。

{
    "items": [
        {
            "createdAt": 1583971856947,
            "updatedAt": 1583971856947,
            "createdBy": "{API_KEY}",
            "updatedBy": "{API_KEY}",
            "createdClient": "{USER_ID}",
            "updatedClient": "{USER_ID}",
            "id": "77a05521-91d6-451c-a055-2191d6851c34",
            "name": "Another new sample connection (Experience Event)",
            "description": "Sample description",
            "connectionSpec": {
                "id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
                "version": "1.0"
            },
            "state": "enabled",
            "auth": {
                "specName": "Streaming Connection",
                "params": {
                    "sourceId": "Sample connection (ExperienceEvent)",
                    "inletUrl": "https://dcs.adobedc.net/collection/a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
                    "inletId": "a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
                    "dataType": "xdm",
                    "name": "Sample connection (ExperienceEvent)"
                }
            },
            "version": "\"56008aee-0000-0200-0000-5e697e150000\"",
            "etag": "\"56008aee-0000-0200-0000-5e697e150000\""
        }
    ]
}

後續步驟

現在您已建立串流連線,您可以串流化時間系列或記錄資料,讓您在其中內嵌資料 Platform。 若要瞭解如何將時間系列資料串流 Platform至,請前往串 流時間系列資料教學課程。 若要瞭解如何將記錄資料串流 Platform至,請至串流 記錄資料教學課程

附錄

本節提供有關使用API建立串流連線的補充資訊。

驗證的串流連線

驗證資料收集可讓Adobe Experience Platform服務(例如 Real-time Customer Profile 和 Identity)區隔來自受信任來源和不受信任來源的記錄。 想要傳送個人識別資訊(PII)的客戶可以透過傳送IMS存取Token作為POST要求的一部分進行傳送——如果IMS Token有效,則記錄會標示為從受信任來源收集。

如需建立已驗證串流連線的詳細資訊,請參閱建立已驗 證串流連線教學課程

本頁內容