即時 Amazon Kinesis CDP Azure Event Hubs 中的目標和目標當前處於測試階段。 文件和功能可能會有所變更。
本教學課程示範如何使用API呼叫來連線至您的Adobe Experience Platform資料、建立串流雲端儲存目的地(Amazon Kinesis 或 Azure事件中樞)的連線、建立資料流至新建立的目的地,以及將資料啟動至新建立的目的地。
本教學課程在所 Amazon Kinesis 有範例中都使用目標,但步驟完全相同 Azure Event Hubs。
如果您偏好使用Adobe即時CDP中的使用者介面來連線至目標並啟用資料,請參閱 Connect destination and Activate profiles and segments to a destinational 。
本指南需要有效瞭解Adobe Experience Platform的下列元件:
以下各節提供您需要瞭解的其他資訊,以便在即時CDP中將資料激活到串流目標。
要完成本教學課程中的步驟,您應準備好下列憑證,這取決於您要連接和啟用區段的目標類型。
accessKeyId
、 secretKey
、 region
or connectionUrl
sasKeyName
, sasKey
namespace
本教學課程提供範例API呼叫,以示範如何設定請求的格式。 這些包括路徑、必要標題和正確格式化的請求負載。 也提供API回應中傳回的範例JSON。 如需範例API呼叫檔案中所用慣例的詳細資訊,請參閱「Experience Platform疑難排解指 南」中有關如何讀取範例API呼叫的章節 。
若要呼叫平台API,您必須先完成驗證教 學課程。 完成驗證教學課程後,所有Experience Platform API呼叫中每個必要標題的值都會顯示在下方:
{ACCESS_TOKEN}
{API_KEY}
{IMS_ORG}
Experience Platform中的資源可以隔離至特定的虛擬沙盒。 在對平台API的請求中,您可以指定要進行操作的沙盒的名稱和ID。 這些是可選參數。
{SANDBOX_NAME}
如需Experience Platform中沙盒的詳細資訊,請參閱沙盒 概觀檔案。
所有包含裝載(POST、PUT、PATCH)的請求都需要額外的媒體類型標題:
application/json
您可在Swagger的本教學課程中,找到所有API呼叫的隨附參考檔案。 請參閱 Adobe.io上的Flow Service API檔案。 建議您同時使用本教學課程和Swagger檔案頁面。
首先,您應決定要啟動資料的串流目的地。 首先,請執行呼叫以請求可連接並啟用區段至的可用目的地清單。 對端點執行以下GET請 connectionSpecs
求以返回可用目標清單:
API格式
GET /connectionSpecs
請求
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'
回應
成功的響應包含可用目標及其唯一標識符(id
)的清單。 儲存您計畫使用之目的地的值,因為後續步驟中將會要求它。 例如,如果您想要連線區段並傳送至或 Amazon Kinesis ,請 Azure Event Hubs在回應中尋找下列程式碼片段:
{
"id": "86043421-563b-46ec-8e6c-e23184711bf6",
"name": "Amazon Kinesis",
...
...
}
{
"id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
"name": "Azure Event Hubs",
...
...
}
接著,您必須連線至您的Experience Platform資料,以便匯出描述檔資料並在您偏好的目的地啟用它。 這包括兩個子步驟,如下所述。
API格式
POST /connections
請求
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Base connection to Experience Platform",
"description": "This call establishes the connection to Experience Platform data",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
}
}'
{CONNECTION_SPEC_ID}
:使用統一配置式服務的連接規範ID - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
。回應
成功的響應包含基本連接的唯一標識符(id
)。 在下一步驟中根據需要儲存此值以建立源連接。
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
API格式
POST /sourceConnections
請求
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connecting to Unified Profile Service",
"description": "Optional",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"baseConnectionId": "{BASE_CONNECTION_ID}",
"data": {
"format": "json"
},
"params" : {}
}'
{BASE_CONNECTION_ID}
:使用您在上一步驟中取得的ID。{CONNECTION_SPEC_ID}
:使用統一配置式服務的連接規範ID - 8a9c3494-9708-43d7-ae3f-cda01e5030e1
。回應
成功的響應返回新建立的源連接id
到統一配置檔案服務的唯一標識符()。 這可確認您已成功連線至您的Experience Platform資料。 在後續步驟中,視需要儲存此值。
{
"id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}
在此步驟中,您要設定與所要串流目的地的連線。 這包括兩個子步驟,如下所述。
API格式
POST /connections
請求
下列範例包含前置詞的程式碼註解 //
。 這些註解會反白標示不同串流目的地必須使用不同值的位置。 請先移除注釋,再使用程式碼片段。
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Connection for Amazon Kinesis/ Azure Event Hubs",
"description": "summer advertising campaign",
"connectionSpec": {
"id": "{_CONNECTION_SPEC_ID}",
"version": "1.0"
},
"auth": {
"specName": "{AUTHENTICATION_CREDENTIALS}",
"params": { // use these values for Amazon Kinesis connections
"accessKeyId": "{ACCESS_ID}",
"secretKey": "{SECRET_KEY}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"sasKeyName": "{SAS_KEY_NAME}",
"sasKey": "{SAS_KEY}",
"namespace": "{EVENT_HUB_NAMESPACE}"
}
}
}'
{CONNECTION_SPEC_ID}
:使用在步驟獲取可用目標清單 中獲得的連接規範ID。{AUTHENTICATION_CREDENTIALS}
:填寫您的串流目的地名稱: Aws Kinesis authentication credentials
或 Azure EventHub authentication credentials
者。{ACCESS_ID}
: 用於 Amazon Kinesis 連接。 Amazon Kinesis儲存位置的訪問ID。{SECRET_KEY}
: 用於 Amazon Kinesis 連接。 Amazon Kinesis儲存位置的密鑰。{REGION}
: 用於 Amazon Kinesis 連接。 您帳戶中即 Amazon Kinesis 時CDP將串流您資料的地區。{SAS_KEY_NAME}
: 用於 Azure Event Hubs 連接。 填寫您的SAS密鑰名稱。 瞭解 Azure Event Hubs Microsoft文檔中 如何使用SAS密鑰驗證。{SAS_KEY}
: 用於 Azure Event Hubs 連接。 填寫SAS密鑰。 瞭解 Azure Event Hubs Microsoft文檔中 如何使用SAS密鑰驗證。{EVENT_HUB_NAMESPACE}
: 用於 Azure Event Hubs 連接。 填寫Real- Azure Event Hubs time CDP將在其中流資料的命名空間。 如需詳細資訊,請 參閱檔案中的建立事件中樞 ,命名 Microsoft 空間。回應
成功的響應包含基本連接的唯一標識符(id
)。 在下個步驟中,如需儲存此值以建立目標連線。
{
"id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}
API格式
POST /targetConnections
請求
下列範例包含前置詞的程式碼註解 //
。 這些註解會反白標示不同串流目的地必須使用不同值的位置。 請先移除注釋,再使用程式碼片段。
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Amazon Kinesis/ Azure Event Hubs target connection",
"description": "Connection to Amazon Kinesis/ Azure Event Hubs",
"baseConnectionId": "{BASE_CONNECTION_ID}",
"connectionSpec": {
"id": "{CONNECTION_SPEC_ID}",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": { // use these values for Amazon Kinesis connections
"stream": "{NAME_OF_DATA_STREAM}",
"region": "{REGION}"
},
"params": { // use these values for Azure Event Hubs connections
"eventHubName": "{EVENT_HUB_NAME}"
}
}'
{BASE_CONNECTION_ID}
:使用您在上述步驟中取得的基本連線ID。{CONNECTION_SPEC_ID}
:使用在步驟獲取可用目標列 表中獲得的連接規範。{NAME_OF_DATA_STREAM}
: 用於 Amazon Kinesis 連接。 提供帳戶中現有資料流的名 Amazon Kinesis 稱。 即時CDP將將資料導出到此流。{REGION}
: 用於 Amazon Kinesis 連接。 Amazon Kinesis帳戶中即時CDP將流資料的區域。{EVENT_HUB_NAME}
: 用於 Azure Event Hubs 連接。 填寫Real- Azure Event Hub time CDP將在其中流資料的名稱。 如需詳細資訊,請 參閱檔案中的建立事件 Microsoft 中心。回應
成功的回應會傳回新建立之目標連線id
的唯一識別碼(),以連至您的串流目的地。 在後續步驟中,視需要儲存此值。
{
"id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}
使用您在前述步驟中取得的ID,您現在可以在Experience Platform資料和要啟用資料的目標之間建立資料流。 將此步驟設想成在Experience Platform和您所要的目的地之間建構資料稍後會透過的管道。
要建立資料流,請執行如下所示的POST請求,同時在裝載中提供以下提及的值。
執行以下POST請求以建立資料流。
API格式
POST /flows
請求
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: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Azure Event Hubs",
"description": "Azure Event Hubs",
"flowSpec": {
"id": "{FLOW_SPEC_ID}",
"version": "1.0"
},
"sourceConnectionIds": [
"{SOURCE_CONNECTION_ID}"
],
"targetConnectionIds": [
"{TARGET_CONNECTION_ID}"
],
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
]
},
"segmentSelectors": {
"selectors": [
]
}
}
}
]
}
{FLOW_SPEC_ID}
:基於配置檔案的目標的流規範ID是 71471eba-b620-49e4-90fd-23f1fa0174d8
。 在呼叫中使用此值。{SOURCE_CONNECTION_ID}
:使用您在步驟「連線至您的Experience Platform」中 取得的來源連線ID。{TARGET_CONNECTION_ID}
:使用您在步驟「連線至串流目的地」中 取得的目標連線ID。回應
成功的響應返回新創id
建的資料流的ID()和 etag
。 請記下這兩個值。 如同您在下個步驟中所做的,啟動區段。
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
"etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}
建立完所有連線和資料流後,您現在可以將個人檔案資料啟動至串流平台。 在此步驟中,您可以選擇要傳送至目的地的區段和描述檔屬性,並可排程資料並傳送至目的地。
若要將區段啟用至新目的地,您必須執行JSON PATCH作業,如下例所示。 您可以在一次呼叫中啟用多個區段和描述檔屬性。 若要進一步瞭解JSON修補程式,請參閱 RFC規格。
API格式
PATCH /flows
請求
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
{
"op": "add",
"path": "/transformations/0/params/segmentSelectors/selectors/-",
"value": {
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Name of the segment that you are activating",
"description": "Description of the segment that you are activating",
"id": "{SEGMENT_ID}"
}
}
},
{
"op": "add",
"path": "/transformations/0/params/profileSelectors/selectors/-",
"value": {
"type": "JSON_PATH",
"value": {
"operator": "EXISTS",
"path": "{PROFILE_ATTRIBUTE}"
}
}
}
]
{DATAFLOW_ID}
:使用您在上一步驟中取得的資料流。{ETAG}
:使用您在上一步驟中取得的標籤。{SEGMENT_ID}
:提供您要匯出至此目的地的區段ID。 若要擷取您要啟用之區段的區段ID,請前往 https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/,在左側導覽功能表中選取「區段服務API 」,然後在「區段定義」 中尋找 GET /segment/definitions
操作 。{PROFILE_ATTRIBUTE}
:例如, personalEmail.address
或 person.lastName
回應
尋找202 OK回應。 不會傳回任何回應內文。 若要驗證請求是否正確,請參閱下一步「驗證資料流」。
在教學課程的最後一個步驟中,您應驗證區段和描述檔屬性確實已正確對應至資料流。
若要驗證此功能,請執行下列GET要求:
API格式
GET /flows
請求
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"'
{DATAFLOW_ID}
:使用上一步驟的資料流。{ETAG}
:使用上一步驟的etag。回應
傳回的回應應包含在參 transformations
數中您在上一步驟中提交的區段和描述檔屬性。 回應中 transformations
的範例參數可能如下所示:
"transformations": [
{
"name": "GeneralTransform",
"params": {
"profileSelectors": {
"selectors": [
{
"type": "JSON_PATH",
"value": {
"path": "personalEmail.address",
"operator": "EXISTS"
}
},
{
"type": "JSON_PATH",
"value": {
"path": "person.lastname",
"operator": "EXISTS"
}
}
]
},
"segmentSelectors": {
"selectors": [
{
"type": "PLATFORM_SEGMENT",
"value": {
"name": "Men over 50",
"description": "",
"id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
}
}
]
}
}
}
],
匯出的資料
{
"person": {
"email": "yourstruly@adobe.con"
},
"segmentMembership": {
"ups": {
"72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
"lastQualificationTime": "2020-03-03T21:24:39Z",
"status": "exited"
},
"7841ba61-23c1-4bb3-a495-00d695fe1e93": {
"lastQualificationTime": "2020-03-04T23:37:33Z",
"status": "existing"
}
}
},
"identityMap": {
"ecid": [
{
"id": "14575006536349286404619648085736425115"
},
{
"id": "66478888669296734530114754794777368480"
}
],
"email_lc_sha256": [
{
"id": "655332b5fa2aea4498bf7a290cff017cb4"
},
{
"id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
}
]
}
}
若要以更簡化的方式連接至本教學課程中所述的串流目的地,您可使用 Postman。
Postman 是一種工具,可用來進行API呼叫並管理預先定義之呼叫和環境的程式庫。
在本特定教學課程中,已附 Postman 加下列系列:
按一 下這裡 ,下載系列封存。
每個系列分別包含必要的要求和環 AWS Kinesis境變 Azure Event Hub數。
若要使用附加的系列成功連線至目 Postman 標,請遵循下列步驟:
通過本教程,您成功將即時CDP連接到您首選的流目標之一,並設定資料流到相應目標。 傳出資料現在可用於客戶分析或您想要執行的任何其他資料作業的目標。 如需詳細資訊,請參閱下列頁面: