Flow Service 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}
Flow Service に属するリソースを含む、Experience Platform内のすべてのリソースは、特定の仮想サンドボックスに分離されます。 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 リクエストを実行することで、既存のデータフローの現在の詳細を表示できます。
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 とベース接続 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 を取得/ ターゲット接続 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 が返されます。 更新を検証するには、ターゲット接続 ID を指定する際に Flow Service API へGETリクエストを行います。
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 を返します。 更新を検証するには、ターゲット接続 ID を指定する際に Flow Service API へGETリクエストを行います。
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 を返します。 更新を検証するには、ターゲット接続 ID を指定する際に Flow Service API へGETリクエストを行います。
code language-json |
---|
|
ベース接続コンポーネント(認証パラメーターおよびその他のコンポーネント)の編集 patch-base-connection
宛先の資格情報を更新する場合は、ベース接続を編集します。 ベース接続のコンポーネントは、宛先によって異なります。 例えば、Amazon S3 の宛先の場合、アクセスキーと秘密鍵を Amazon S3 の場所に更新できます。
ベース接続のコンポーネントを更新するには、/connections
エンドポイントに PATCH
リクエストを実行し、その際にベース接続 ID、バージョン、使用する新しい値を指定します。
ベース接続 ID を取得したのは、 前の手順で、既存のデータフローを目的の宛先に調査してパラメーター baseConnection
を取得したときです。
PATCH
リクエストを行う場合、If-Match
ヘッダーは必須です。 このヘッダーの値は、更新するベース接続の一意のバージョンです。 etag の値は、データフロー、ベース接続など、フローエンティティが正常に更新されるたびに更新されます。/connections/{BASE_CONNECTION_ID}
エンドポイントに対してGETリクエストを実行します。{BASE_CONNECTION_ID}
は、更新するベース接続 ID です。PATCH
リクエストを行う場合は、以下の例のように、If-Match
ヘッダーの値を必ず二重引用符で囲みます。様々なタイプの宛先に対して、ベース接続仕様のパラメーターを更新する例を以下に示します。 ただし、宛先のパラメーターを更新するための一般的なルールは次のとおりです。
接続のデータフロー ID を取得/ ベース接続 ID を取得/目的のパラメーターの更新された値を使用してベース接続を 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 が返されます。ベース接続 ID を指定した状態で Flow Service API にGETリクエストを行うことで、更新を確認することができます。
code language-json |
---|
|
リクエスト
次のリクエストは、Azure Blob destination 接続のパラメーターを更新して、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 が返されます。ベース接続 ID を指定した状態で Flow Service API にGETリクエストを行うことで、更新を確認することができます。
code language-json |
---|
|
API エラー処理 api-error-handling
このチュートリアルの API エンドポイントは、一般的なExperience PlatformAPI エラーメッセージの原則に従っています。 エラー応答の解釈について詳しくは、Platform トラブルシューティングガイドの API ステータスコードおよび リクエストヘッダーエラーを参照してください。
次の手順 next-steps
このチュートリアルでは、Flow Service API を使用して宛先接続の様々なコンポーネントを更新する方法を学びました。 宛先について詳しくは、 宛先の概要を参照してください。