文件Experience Platform來源連接器指南

[Ultimate]{class="badge positive"}

使用Flow Service API建立Azure Event Hubs來源連線

Last update: Mon Jul 15 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 開發人員
IMPORTANT
Azure Event Hubs來源可在來源目錄中提供給已購買Real-time Customer Data Platform Ultimate的使用者。

閱讀本教學課程以瞭解如何使用Flow Service API將Azure Event Hubs （以下稱為"Event Hubs"）連線至Experience Platform。

快速入門

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

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

下列章節提供您需瞭解的其他資訊，才能使用Flow Service API成功連線Event Hubs至Platform。

收集必要的認證

為了讓Flow Service與您的Event Hubs帳戶連線，您必須提供下列連線屬性的值：

標準驗證
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
認證 說明
sasKeyName 授權規則的名稱，也稱為SAS金鑰名稱。
sasKey Event Hubs名稱空間的主索引鍵。 sasKey對應的sasPolicy必須已設定manage許可權，才能填入Event Hubs清單。
namespace 您正在存取的Event Hub的名稱空間。 Event Hub名稱空間提供唯一的範圍設定容器，您可以在其中建立一或多個Event Hubs。
connectionSpec.id 連線規格會傳回來源的聯結器屬性，包括與建立基礎連線和來源連線相關的驗證規格。 Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e。
SAS驗證
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
認證 說明
sasKeyName 授權規則的名稱，也稱為SAS金鑰名稱。
sasKey Event Hubs名稱空間的主索引鍵。 sasKey對應的sasPolicy必須已設定manage許可權，才能填入Event Hubs清單。
namespace 您正在存取的Event Hub的名稱空間。 Event Hub名稱空間提供唯一的範圍設定容器，您可以在其中建立一或多個Event Hubs。
eventHubName 填寫您的Azure Event Hub名稱。 閱讀Microsoft檔案以瞭解Event Hub名稱的詳細資訊。
connectionSpec.id 連線規格會傳回來源的聯結器屬性，包括與建立基礎連線和來源連線相關的驗證規格。 Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e。

如需有關Event Hubs的共用存取簽章(SAS)驗證的詳細資訊，請閱讀使用SAS🔗的Azure 指南。

事件中心Azure Active Directory驗證
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
認證 說明
tenantId 您要向其請求許可權的租使用者ID。 您可以將您的租使用者ID格式化為GUID或友好名稱。 注意：租使用者ID在Microsoft Azure介面中稱為「目錄ID」。
clientId 指派給應用程式的應用程式ID。 您可以從您註冊Azure Active Directory的Microsoft Entra ID入口網站擷取此ID。
clientSecretValue 使用者端密碼與使用者端ID搭配使用，用來驗證您的應用程式。 您可以從您註冊Azure Active Directory的Microsoft Entra ID入口網站擷取您的使用者端密碼。
namespace 您正在存取的Event Hub的名稱空間。 Event Hub名稱空間提供唯一的範圍設定容器，您可以在其中建立一或多個Event Hubs。

如需Azure Active Directory的詳細資訊，請閱讀使用Microsoft Entra ID的Azure指南。

事件中樞範圍的Azure Active Directory驗證
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
認證 說明
tenantId 您要向其請求許可權的租使用者ID。 您可以將您的租使用者ID格式化為GUID或友好名稱。 注意：租使用者ID在Microsoft Azure介面中稱為「目錄ID」。
clientId 指派給應用程式的應用程式ID。 您可以從您註冊Azure Active Directory的Microsoft Entra ID入口網站擷取此ID。
clientSecretValue 使用者端密碼與使用者端ID搭配使用，用來驗證您的應用程式。 您可以從您註冊Azure Active Directory的Microsoft Entra ID入口網站擷取您的使用者端密碼。
namespace 您正在存取的Event Hub的名稱空間。 Event Hub名稱空間提供唯一的範圍設定容器，您可以在其中建立一或多個Event Hubs。
eventHubName 填寫您的Azure Event Hub名稱。 閱讀Microsoft檔案以瞭解Event Hub名稱的詳細資訊。

如需這些值的詳細資訊，請參閱此「事件中樞」檔案。

使用平台API

如需如何成功呼叫Platform API的詳細資訊，請參閱Platform API快速入門的指南。

建立基礎連線

TIP
建立後，您無法變更Event Hubs基本連線的驗證型別。 若要變更驗證型別，您必須建立新的基礎連線。

建立來源連線的第一個步驟是驗證您的Event Hubs來源並產生基本連線識別碼。 基礎連線ID可讓您從來源內部探索及導覽檔案，並識別您要擷取的特定專案，包括其資料型別和格式的資訊。

若要建立基底連線ID，請在提供Event Hubs驗證認證作為要求引數的一部分時，向/connections端點提出POST要求。

API格式

POST /connections
標準驗證

若要使用標準驗證建立帳戶，請在提供您的sasKeyName、sasKey和namespace的值時向/connections端點提出POST要求。

accordion
要求
code language-shell 
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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Azure EventHub authentication credentials",
          "params": {
              "sasKeyName": "{SAS_KEY_NAME}",
              "sasKey": "{SAS_KEY}",
              "namespace": "{NAMESPACE}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2
屬性 說明
auth.params.sasKeyName 授權規則的名稱，也稱為SAS金鑰名稱。
auth.params.sasKey 產生的共用存取權簽章。
auth.params.namespace 您正在存取的Event Hubs的名稱空間。
connectionSpec.id Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e
accordion
回應

成功的回應會傳回新建立的基礎連線的詳細資料，包括其唯一識別碼(id)。 建立來源連線的下一個步驟需要此連線ID。

code language-json 
{
    "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
    "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\""
}
SAS驗證

若要使用SAS驗證建立帳戶，請在提供您的sasKeyName、sasKey、namespace和eventHubName的值時向/connections端點提出POST要求。

accordion
要求
code language-shell 
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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Azure EventHub authentication credentials",
          "params": {
              "sasKeyName": "{SAS_KEY_NAME}",
              "sasKey": "{SAS_KEY}",
              "namespace": "{NAMESPACE}",
              "eventHubName": "{EVENT_HUB_NAME}
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
屬性 說明
auth.params.sasKeyName 授權規則的名稱，也稱為SAS金鑰名稱。
auth.params.sasKey 產生的共用存取權簽章。
auth.params.namespace 您正在存取的Event Hubs的名稱空間。
params.eventHubName 您的Event Hubs來源的名稱。
connectionSpec.id Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e
accordion
回應

成功的回應會傳回新建立的基礎連線的詳細資料，包括其唯一識別碼(id)。 建立來源連線的下一個步驟需要此連線ID。

code language-json 
{
    "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
    "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\""
}
事件中心Azure Active Directory驗證

若要使用Azure Active Directory驗證建立帳戶，請在提供您的tenantId、clientId、clientSecretValue和namespace的值時向/connections端點提出POST要求。

accordion
要求
code language-shell 
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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Event Hub Azure Active Directory Auth",
          "params": {
              "tenantId": "{TENANT_ID}",
              "clientId": "{CLIENT_ID}",
              "clientSecretValue": "{CLIENT_SECRET_VALUE}",
              "namespace": "{NAMESPACE}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
屬性 說明
auth.params.tenantId 您應用程式的租使用者ID。 注意：租使用者ID在Microsoft Azure介面中稱為「目錄ID」。
auth.params.clientId 您組織的使用者端ID。
auth.params.clientSecretValue 您組織的使用者端密碼值。
auth.params.namespace 您正在存取的Event Hubs的名稱空間。
connectionSpec.id Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e
accordion
回應

成功的回應會傳回新建立的基礎連線的詳細資料，包括其唯一識別碼(id)。 建立來源連線的下一個步驟需要此連線ID。

code language-json 
{
    "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
    "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\""
}
事件中樞範圍的Azure Active Directory驗證

若要使用Azure Active Directory驗證建立帳戶，請在提供您的tenantId、clientId、clientSecretValue、namespace和eventHubName的值時向/connections端點提出POST要求。

accordion
要求
code language-shell 
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": "Azure Event Hubs connection",
      "description": "Connector for Azure Event Hubs",
      "auth": {
          "specName": "Event Hub Scoped Azure Active Directory Auth",
          "params": {
              "tenantId": "{TENANT_ID}",
              "clientId": "{CLIENT_ID}",
              "clientSecretValue": "{CLIENT_SECRET_VALUE}",
              "namespace": "{NAMESPACE}",
              "eventHubName": "{EVENT_HUB_NAME}"
          }
      },
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      }
  }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2
屬性 說明
auth.params.tenantId 您應用程式的租使用者ID。 注意：租使用者ID在Microsoft Azure介面中稱為「目錄ID」。
auth.params.clientId 您組織的使用者端ID。
auth.params.clientSecretValue 您組織的使用者端密碼值。
auth.params.namespace 您正在存取的Event Hubs的名稱空間。
auth.params.eventHubName 您的Event Hubs來源的名稱。
connectionSpec.id Event Hubs連線規格識別碼為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e
accordion
回應

成功的回應會傳回新建立的基礎連線的詳細資料，包括其唯一識別碼(id)。 建立來源連線的下一個步驟需要此連線ID。

code language-json 
{
    "id": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
    "etag": "\"6507cfd8-0000-0200-0000-5e18fc600000\""
}

建立來源連線

TIP
Event Hubs使用者群組只能在指定時間用於單一流量。

來源連線會建立和管理與擷取資料的外部來源的連線。 來源連線包含資料來源、資料格式等資訊，以及建立資料流所需的來源連線ID。 租使用者和組織專屬的來源連線例項。

若要建立來源連線，請向Flow Service API的/sourceConnections端點提出POST要求。

API格式

POST /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": "Azure Event Hubs source connection",
      "description": "A source connection for Azure Event Hubs",
      "baseConnectionId": "4cdbb15c-fb1e-46ee-8049-0f55b53378fe",
      "connectionSpec": {
          "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      },
      "params": {
          "eventHubName": "{EVENT_HUB_NAME}",
          "dataType": "raw",
          "reset": "latest",
          "consumerGroup": "{CONSUMER_GROUP}"
      }
  }'
屬性
說明
name
來源連線的名稱。 確保來源連線的名稱是描述性的，因為您可以使用此名稱來查詢來源連線的資訊。
description
您可以提供的選用值，包含來源連線的詳細資訊。
baseConnectionId
您在上一步中產生的Event Hubs來源的連線ID。
connectionSpec.id
Event Hubs的固定連線規格識別碼。 此ID為： bf9f5905-92b7-48bf-bf20-455bc6b60a4e。
data.format
您要擷取的Event Hubs資料格式。 目前唯一支援的資料格式為json。
params.eventHubName
您的Event Hubs來源的名稱。
params.dataType
此引數會定義所擷取的資料型別。 支援的資料型別包括： raw和xdm。
params.reset
此引數會定義資料的讀取方式。 使用latest開始讀取最近的資料，並使用earliest開始讀取資料流中第一個可用的資料。 此引數為選用引數，若未提供，則預設為earliest。
params.consumerGroup
要用於Event Hubs的發佈或訂閱機制。 此引數為選用引數，若未提供，則預設為$Default。 如需詳細資訊，請參閱此Event Hubs 活動消費者指南。 注意： Event Hubs消費者群組只能在指定時間用於單一流量。

後續步驟

依照此教學課程，您已使用Flow Service API建立Event Hubs來源連線。 您可以在下一個教學課程中使用此來源連線ID來使用 Flow Service API建立串流資料流。

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089