使用流程服務API編輯目的地連線
本教學課程涵蓋編輯目的地連線各種元件的步驟。 瞭解如何使用Flow Service API更新驗證認證、匯出位置等。
快速入門 get-started
本教學課程要求您具備有效的資料流ID。 如果您沒有有效的資料流ID,請從目的地目錄中選取您選擇的目的地,並依照概述的步驟連線至目的地和啟用資料,然後再嘗試進行此教學課程。
本教學課程也要求您實際瞭解下列Adobe Experience Platform元件:
下列章節提供您需瞭解的其他資訊,才能使用Flow Service API成功更新資料流。
讀取範例 API 呼叫 reading-sample-api-calls
本教學課程提供範例API呼叫,示範如何格式化您的請求。 這些包括路徑、必要的標頭和正確格式化的請求承載。 此外,也提供 API 回應中傳回的範例 JSON。 如需檔案中所使用之範例API呼叫慣例的詳細資訊,請參閱Experience Platform疑難排解指南中有關如何讀取範例API呼叫的章節。
收集所需標頭的值 gather-values-for-required-headers
若要呼叫Platform API,您必須先完成驗證教學課程。 完成驗證教學課程,在所有Experience Platform API呼叫中提供每個必要標題的值,如下所示:
Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}
Experience Platform中的所有資源(包括屬於Flow Service的資源)都與特定的虛擬沙箱隔離。 對Platform API的所有請求都需要標頭,以指定將在其中進行操作的沙箱名稱:
x-sandbox-name: {SANDBOX_NAME}
x-sandbox-name
標頭,則在prod
沙箱下解析請求。包含裝載(POST
、PUT
、PATCH
)的所有要求都需要額外的媒體型別標頭:
Content-Type: application/json
查詢資料流詳細資料 look-up-dataflow-details
編輯目的地連線的第一個步驟,是使用流量ID擷取資料流詳細資訊。 您可以透過向/flows
端點發出GET要求來檢視現有資料流的目前詳細資料。
![使用Experience PlatformUI取得目的地ID](./media_121fb114eccc684d4fdf263e7f850f423ad144b71.png?width=750&format=png&optimize=medium)
API格式
GET /flows/{FLOW_ID}
{FLOW_ID}
id
值。要求
以下請求會擷取有關您的流量ID的資訊。
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flows/226fb2e1-db69-4760-b67e-9e671e05abfc' \
-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}'
回應
成功的回應會傳回資料流的目前詳細資料,包括其版本、唯一識別碼(id
)及其他相關資訊。 與本教學課程最相關的內容,是下列回應中醒目提示的目標連線和基本連線ID。 您將在下一節中使用這些ID來更新目的地連線的各種元件。
{
"items":[
{
"id":"226fb2e1-db69-4760-b67e-9e671e05abfc",
"createdAt":"{CREATED_AT}",
"updatedAt":"{UPDATED_BY}",
"createdBy":"{CREATED_BY}",
"updatedBy":"{UPDATED_BY}",
"createdClient":"{CREATED_CLIENT}",
"updatedClient":"{UPDATED_CLIENT}",
"sandboxId":"{SANDBOX_ID}",
"sandboxName":"prod",
"imsOrgId":"{ORG_ID}",
"name":"2021 winter campaign",
"description":"ACME company holiday campaign for high fidelity customers",
"flowSpec":{
"id":"71471eba-b620-49e4-90fd-23f1fa0174d8",
"version":"1.0"
},
"state":"enabled",
"version":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
"etag":"\"8b0351ca-0000-0200-0000-61c4d6700000\"",
"sourceConnectionIds":[
"5e45582a-5336-4ea1-9ec9-d0004a9f344a"
],
"targetConnectionIds":[
"8ce3dc63-3766-4220-9f61-51d2f8f14618"
],
"inheritedAttributes":{
"sourceConnections":[
{
"id":"5e45582a-5336-4ea1-9ec9-d0004a9f344a",
"connectionSpec":{
"id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
"version":"1.0"
},
"baseConnection":{
"id":"0a82f29f-b457-47f7-bb30-33856e2ae5aa",
"connectionSpec":{
"id":"8a9c3494-9708-43d7-ae3f-cda01e5030e1",
"version":"1.0"
}
},
"typeInfo":{
"type":"ProfileFragments",
"id":"ups"
}
}
],
"targetConnections":[
{
"id":"8ce3dc63-3766-4220-9f61-51d2f8f14618",
"connectionSpec":{
"id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
"version":"1.0"
},
"baseConnection":{
"id":"7fbf542b-83ed-498f-8838-8fde0c4d4d69",
"connectionSpec":{
"id":"0b23e41a-cb4a-4321-a78f-3b654f5d7d97",
"version":"1.0"
}
}
}
]
},
"transformations":[
"shortened for brevity"
]
}
]
編輯目標連線元件(儲存位置和其他元件) patch-target-connection
目標連線的元件會依目的地而有所不同。 例如,對於Amazon S3目的地,您可以更新檔案匯出的貯體和路徑。 若為Pinterest目的地,您可以更新您的Pinterest Advertiser ID,若為Google Customer Match,您可以更新Pinterest Account ID。
若要更新目標連線的元件,請對/targetConnections/{TARGET_CONNECTION_ID}
端點執行PATCH
要求,同時提供您的目標連線ID、版本以及您要使用的新值。 請記住,您在上一個步驟中取得目標連線ID,當時您檢查到所要目的地的現有資料流。
PATCH
請求時需要If-Match
標頭。 此標頭的值是您要更新之目標連線的唯一版本。 每次成功更新資料流、目標連線等流程實體時,etag值都會隨之更新。/targetConnections/{TARGET_CONNECTION_ID}
端點執行GET要求,其中{TARGET_CONNECTION_ID}
是您要更新的目標連線ID。PATCH
請求時,請務必將If-Match
標頭的值括在雙引號中,如下例所示。以下是一些為不同型別的目的地更新目標連線規格中引數的範例。 但更新任何目的地引數的一般規則如下:
取得連線的資料流ID >取得目標連線識別碼> PATCH
目標連線,並更新所需引數的值。
API格式
PATCH /targetConnections/{TARGET_CONNECTION_ID}
要求
下列要求會更新Amazon S3目的地連線的bucketName
和path
引數。
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
屬性 | 說明 |
op |
用於定義更新資料流所需動作的操作呼叫。 作業包括: add 、replace 和remove 。 |
path |
定義要更新的流程部分。 |
value |
您想要用來更新引數的新值。 |
回應
成功的回應會傳回目標連線ID和更新的Etag。 您可以向Flow Service API發出GET要求,同時提供目標連線ID以驗證更新。
code language-json |
---|
|
要求
下列要求會更新Google Ad Manager或Google Ad Manager 360 目的地連線的引數,以將新的 附加對象ID新增至對象名稱 欄位。
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
屬性 | 說明 |
op |
用於定義更新資料流所需動作的操作呼叫。 作業包括: add 、replace 和remove 。 |
path |
定義要更新的流程部分。 |
value |
您想要用來更新引數的新值。 |
回應
成功的回應會傳回目標連線ID和更新的etag。 您可以向Flow Service API發出GET要求,同時提供目標連線ID以驗證更新。
code language-json |
---|
|
要求
下列要求會更新Pinterest 目的地連線的advertiserId
引數。
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
屬性 | 說明 |
op |
用於定義更新資料流所需動作的操作呼叫。 作業包括: add 、replace 和remove 。 |
path |
定義要更新的流程部分。 |
value |
您想要用來更新引數的新值。 |
回應
成功的回應會傳回目標連線ID和更新的etag。 您可以向Flow Service API發出GET要求,同時提供目標連線ID以驗證更新。
code language-json |
---|
|
編輯基本連線元件(驗證引數和其他元件) patch-base-connection
當您想要更新目的地的認證時,請編輯基本連線。 基礎連線的元件會因目的地而異。 例如,對於Amazon S3目的地,您可以將存取金鑰和秘密金鑰更新至您的Amazon S3位置。
若要更新基底連線的元件,請在提供您的基底連線ID、版本以及您要使用的新值時,對/connections
端點執行PATCH
要求。
請記住,當您在先前的步驟中檢查到引數baseConnection
所需目的地的現有資料流時,已取得您的基礎連線ID。
PATCH
請求時需要If-Match
標頭。 此標頭的值是您要更新的基礎連線的唯一版本。 每次成功更新資料流、基本連線等流程實體時,etag值都會隨之更新。/connections/{BASE_CONNECTION_ID}
端點執行GET要求,其中{BASE_CONNECTION_ID}
是您要更新的基礎連線ID。PATCH
請求時,請務必將If-Match
標頭的值括在雙引號中,如下例所示。以下是一些範例,說明如何為不同型別的目的地更新基本連線規格中的引數。 但更新任何目的地引數的一般規則如下:
取得連線的資料流識別碼>取得基底連線識別碼> PATCH
具有所需引數更新值的基底連線。
API格式
PATCH /connections/{BASE_CONNECTION_ID}
要求
下列要求會更新Amazon S3目的地連線的accessId
和secretKey
引數。
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
屬性 | 說明 |
op |
用於定義更新資料流所需動作的操作呼叫。 作業包括: add 、replace 和remove 。 |
path |
定義要更新的流程部分。 |
value |
您想要用來更新引數的新值。 |
回應
成功的回應會傳回您的基本連線ID和更新的etag。 您可以透過向Flow Service API發出GET要求來驗證更新,同時提供您的基本連線ID。
code language-json |
---|
|
要求
下列要求會更新Azure Blob 目的地連線的引數,以更新連線至Azure Blob執行個體所需的連線字串。
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
屬性 | 說明 |
op |
用於定義更新資料流所需動作的操作呼叫。 作業包括: add 、replace 和remove 。 |
path |
定義要更新的流程部分。 |
value |
您想要用來更新引數的新值。 |
回應
成功的回應會傳回您的基本連線ID和更新的etag。 您可以透過向Flow Service API發出GET要求來驗證更新,同時提供您的基本連線ID。
code language-json |
---|
|
API錯誤處理 api-error-handling
本教學課程中的API端點會遵循一般Experience PlatformAPI錯誤訊息原則。 如需解譯錯誤回應的詳細資訊,請參閱Platform疑難排解指南中的API狀態碼和要求標頭錯誤。
後續步驟 next-steps
依照本教學課程,您已瞭解如何使用Flow Service API更新目的地連線的各種元件。 如需目的地的詳細資訊,請參閱目的地概觀。