Flow Service APIを使用して、ファイルベースの宛先にオーディエンスをアクティベートします
強化されたファイル書き出し機能を使用すると、Experience Platformからファイルを書き出す際に強化されたカスタマイズ機能にアクセスできます。
- 追加のファイル命名オプション。
- 書き出されたファイルにカスタムファイルヘッダーを設定する機能(マッピングステップの改善による)
- 書き出されたファイルの ファイルタイプ を選択できます。
- 書き出された CSV データファイルの形式をカスタマイズする機能。
この機能は、次に示す6つのクラウドストレージカードでサポートされています。
この記事では、Flow Service APIを使用して、適格なプロファイルをAdobe Experience Platformから上記にリンクされたクラウドストレージの場所のいずれかに書き出すために必要なワークフローについて説明します。
はじめに get-started
このガイドでは、Adobe Experience Platformの次のコンポーネントについて実際に理解する必要があります。
- Experience Data Model (XDM) System:顧客体験データを編成する際に Experience Platform に使用される標準化されたフレームワーク。
- Segmentation Service: Adobe Experience Platform Segmentation ServiceはAdobe Experience Platform データからReal-Time Customer Profileのオーディエンスを構築します。
- Sandboxes:Experience Platform には、単一の Experience Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスが用意されています。
次の節では、Experience Platformのファイルベースの宛先にデータをアクティベートするために知っておく必要がある追加情報を提供します。
必要な権限 permissions
プロファイルをエクスポートするには、View Destinations、Activate Destinations、View ProfilesおよびView Segments アクセス制御権限が必要です。 アクセス制御の概要を参照するか、製品管理者に問い合わせて必要な権限を取得してください。
IDをエクスポートするには、View Identity Graph アクセス制御権限が必要です。
API 呼び出し例の読み取り reading-sample-api-calls
このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーおよびオプションヘッダーの値の収集 gather-values-headers
Experience Platform個のAPIを呼び出すには、まずExperience Platform認証チュートリアル を完了する必要があります。 次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
- Authorization: Bearer
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Experience Platform のリソースは、特定の仮想サンドボックスに分離できます。Experience Platform API へのリクエストでは、操作を実行するサンドボックスの名前と ID を指定できます。次に、オプションのパラメーターを示します。
- x-sandbox-name:
{SANDBOX_NAME}
ペイロード (POST、PUT、PATCH)を含むすべてのリクエストには、追加のメディアタイプヘッダーが必要です。
- Content-Type:
application/json
API リファレンスドキュメント api-reference-documentation
このチュートリアルに含まれるすべての API 操作について、付属リファレンスドキュメントが用意されています。Adobe Developer web サイト のFlow Service - Destinations API ドキュメントを参照してください。 このチュートリアルと API リファレンスのドキュメントを並行して使用することをお勧めします。
用語集 glossary
このAPI チュートリアルで使用される用語については、API リファレンスドキュメントの用語集セクション を参照してください。
オーディエンスの書き出し先を選択 select-destination
プロファイルの書き出しワークフローを開始する前に、オーディエンスの書き出し先の接続仕様とフロー仕様IDを特定します。 参考までに、以下の表を使用してください。
4fce964d-3f37-408f-9778-e597338a21ee1a0514a6-33d4-4c7f-aff8-594799c475496d6b59bf-fb58-4107-9064-4d246c0e5bb2752d422f-b16f-4f0d-b1c6-26e448e3b388be2c3209-53bc-47e7-ab25-145db8b873e117be2013-2549-41ce-96e7-a70363bec29310440537-2a7b-4583-ac39-ed38d4b848e8cd2fc47e-e838-4f38-a581-8fff2f99b63ac5d93acb-ea8b-4b14-8f53-02138444ae99585c15c4-6cbf-4126-8f87-e26bff78b65736965a81-b1c6-401b-99f8-22508f1e6a26fd36aaa4-bf2b-43fb-9387-43785eeeb799このチュートリアルの次の手順で、様々なフローサービスエンティティを構築するには、これらのIDが必要です。 また、特定のエンティティを設定するために、接続仕様自体の一部を参照して、Flow Service APIから接続仕様を取得できるようにする必要もあります。 以下の例では、テーブル内のすべての宛先の接続仕様を取得しています。
リクエスト
| accordion | ||
|---|---|---|
| connection specのAmazon S3を取得 | ||
|
応答
| accordion | ||
|---|---|---|
| Amazon S3 – 接続仕様 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| connection specのAzure Blob Storageを取得 | ||
|
応答
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection spec | ||
|
リクエスト
| accordion | ||
|---|---|---|
| connection specのAzure Data Lake Gen 2(ADLS Gen2を取得) | ||
|
応答
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection spec | ||
|
リクエスト
| accordion | ||
|---|---|---|
| connection specのData Landing Zone(DLZ)を取得 | ||
|
応答
| accordion | ||
|---|---|---|
| Data Landing Zone(DLZ) - Connection spec | ||
|
リクエスト
| accordion | ||
|---|---|---|
| connection specのGoogle Cloud Storageを取得 | ||
|
応答
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection spec | ||
|
リクエスト
| accordion | ||
|---|---|---|
| SFTP用にconnection specを取得 | ||
|
応答
| accordion | ||
|---|---|---|
| SFTP - Connection spec | ||
|
クラウドストレージ宛先へのオーディエンス書き出しデータフローを設定するには、次の手順に従います。 一部の手順では、様々なクラウドストレージの宛先間でリクエストと応答が異なります。 そのような場合は、ページ上のタブを使用して、オーディエンスを接続して書き出す宛先に固有のリクエストと応答を取得します。 設定する宛先に対して、正しいconnection specとflow specを使用してください。
Source接続の作成 create-source-connection
オーディエンスを書き出す宛先を決定したら、ソース接続を作成する必要があります。 ソース接続は、内部Experience Platform プロファイル ストア への接続を表します。
リクエスト
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、インラインコメントを削除します。
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
応答が成功すると、新しく作成されたソース接続のID (id)とetagが返されます。 データフローの作成時に後で必要になるソース接続IDをメモします。
ベース接続の作成 create-base-connection
ベース接続は、資格情報を宛先に安全に保存します。 宛先のタイプに応じて、その宛先に対して認証するために必要な資格情報は異なる場合があります。 これらの認証パラメーターを見つけるには、「connection spec オーディエンスを書き出す宛先を選択」の説明に従って、まず目的の宛先のを取得し、応答のauthSpecを確認します。 サポートされているすべての宛先のauthSpec プロパティについては、以下のタブを参照してください。
| accordion | ||
|---|---|---|
| Amazon S3 - Connection specにauth specが表示されています | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。この行は、connection specの認証パラメーターの検索場所に関する追加情報を提供します。
|
| accordion | ||
|---|---|---|
| Azure Blob Storage - Connection specにauth specが表示されています | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。この行は、connection specの認証パラメーターの検索場所に関する追加情報を提供します。
|
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Connection specにauth specが表示されています | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。この行は、connection specの認証パラメーターの検索場所に関する追加情報を提供します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - Connection specにauth specが表示されています | |||||
|
| accordion | ||
|---|---|---|
| Google Cloud Storage - Connection specにauth specが表示されています | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。この行は、connection specの認証パラメーターの検索場所に関する追加情報を提供します。
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Connection spec (auth specを表示) | |||||
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。この行は、connection specの認証パラメーターの検索場所に関する追加情報を提供します。
|
認証仕様で指定されたプロパティ(応答からauthSpecです)を使用して、以下の例に示すように、各宛先タイプに固有の必要な資格情報を含むベース接続を作成できます。
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - アクセスキーと秘密鍵認証を使用したベース接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 – 想定される役割の認証によるベース接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| Amazon S3 ベース接続応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - ベース接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| Azure Blob Storage - ベース接続応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - ベース接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - ベース接続応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone(DLZ) - ベース接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| Data Landing Zone - ベース接続応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - ベース接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| Google Cloud Storage - ベース接続応答 | ||
|
リクエスト
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| パスワード付きSFTP - ベース接続リクエスト | |||||||||||||||||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| SSH キーを使用したSFTP - ベース接続リクエスト | |||||||||||||||||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| SFTP - ベース接続応答 | ||
|
書き出したファイルに暗号化を追加する add-encryption
オプションで、書き出したファイルに暗号化を追加できます。 これを行うには、encryption オブジェクトから項目を追加する必要があります。 必須パラメーターが強調表示されたリクエストの例を以下に示します。
| code language-json line-numbers data-start-1 data-line-offset-4 h-26-27 |
|---|
|
リクエスト
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、インラインコメントを削除します。
| code language-shell line-numbers data-start-1 data-line-offset-4 h-19 |
|---|
|
応答
| code language-json |
|---|
|
応答の接続IDをメモします。 このIDは、ターゲット接続の作成時に次の手順で必要になります。
ターゲット接続の作成 create-target-connection
次に、ターゲット接続を作成する必要があります。 Target接続には、書き出されたオーディエンスの書き出しパラメーターが保存されます。 書き出しパラメーターには、書き出し場所、ファイル形式、圧縮などの詳細が含まれます。 例えば、CSV ファイルの場合、複数の書き出しオプションを選択できます。 サポートされているすべてのCSV書き出しオプションに関する詳細は、 ファイル形式設定ページ を参照してください。
宛先のtargetSpecで提供されるconnection spec プロパティを参照して、各宛先タイプでサポートされているプロパティを確認してください。 サポートされているすべての宛先のtargetSpec プロパティについては、以下のタブを参照してください。
| accordion | ||
|---|---|---|
| ターゲット接続パラメーターを示すAmazon S3 ~ Connection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
| accordion | ||
|---|---|---|
| ターゲット接続パラメーターを示すAzure Blob Storage ~ Connection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
| accordion | ||
|---|---|---|
| ターゲット接続パラメーターを示すAzure Data Lake Gen 2(ADLS Gen2) ~ Connection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
| accordion | ||
|---|---|---|
| ターゲット接続パラメーターを示すData Landing Zone(DLZ) ~ Connection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
| accordion | ||
|---|---|---|
| ターゲット接続パラメーターを示すGoogle Cloud Storage ~ Connection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
| accordion | ||
|---|---|---|
| SFTP - ターゲット接続パラメーターを示すConnection spec | ||
|
以下のconnection spec例のインラインコメントを含む強調表示された行に注意してください。これにより、接続仕様のtarget spec パラメーターの検索場所に関する追加情報が提供されます。 以下の例では、オーディエンスの書き出し先に適用できるターゲットパラメーターが not であることも確認できます。
|
上記の仕様を使用すると、以下のタブに示すように、目的のクラウドストレージ宛先に固有のターゲット接続リクエストを作成できます。
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Amazon S3 - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Blob Storage - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2) - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Data Landing Zone - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| Google Cloud Storage - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
リクエスト
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - Target接続リクエスト | |||||
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
| accordion | |||||
|---|---|---|---|---|---|
| SFTP - CSV オプションを使用したTarget接続リクエスト | |||||
|
応答
| accordion | ||
|---|---|---|
| ターゲット接続 – 応答 | ||
|
応答のtarget connection IDに注意してください。 このIDは、オーディエンスを書き出すデータフローを作成する際に、次の手順で必要になります。
応答が成功すると、新しいターゲットソース接続のID (id)とetagが返されます。 後でデータフローを作成する際に必要になるので、ターゲット接続IDをメモしておきます。
データフローの作成 create-dataflow
宛先設定の次の手順は、データフローを作成することです。 データフローは、以前に作成したエンティティと関連付けられ、オーディエンス書き出しスケジュールを設定するためのオプションも提供します。 データフローを作成するには、目的のクラウドストレージの宛先に応じて、以下のペイロードを使用し、以前の手順で使用したフローエンティティ IDを置き換えます。 この手順では、属性またはID マッピングに関連する情報をデータフローに追加していないことに注意してください。 これは次のステップで続きます。
リクエスト
| accordion | ||
|---|---|---|
| Amazon S3宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| Azure Blob Storage宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| Azure Data Lake Gen 2(ADLS Gen2)宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| Data Landing Zone宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| Google Cloud Storage宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
リクエスト
| accordion | ||
|---|---|---|
| SFTP宛先へのオーディエンス書き出しデータフローの作成 – リクエスト | ||
|
リクエストサンプルのインラインコメントを含むハイライト表示された行に注意してください。これにより、追加情報が提供されます。 リクエストを任意の端末にコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
| accordion | ||
|---|---|---|
| データフローの作成 – 応答 | ||
|
応答のデータフローIDをメモします。 このIDは、後の手順で必要になります。
書き出しにオーディエンスを追加 add-audiences
この手順では、宛先に書き出すオーディエンスを選択することもできます。 この手順とデータフローにオーディエンスを追加するリクエスト形式について詳しくは、API リファレンスドキュメントの「宛先データフローを更新」セクションの例を参照してください。
属性とID マッピングの設定 attribute-and-identity-mapping
データフローを作成したら、書き出す属性とIDのマッピングを設定する必要があります。 これは、次の3つのステップで構成されます。
- 入力スキーマの作成
- 出力スキーマの作成
- 作成したスキーマを接続するためのマッピングセットの設定
例えば、UIに表示されている次のマッピングを取得するには、上記の3つの手順を実行し、次の見出しで詳しく説明する必要があります。
入力スキーマの作成 create-input-schema
入力スキーマを作成するには、まず結合スキーマ と、宛先に書き出すことができるIDを取得する必要があります。 これは、ソースマッピングとして選択できる属性とIDのスキーマです。
属性とIDを取得するためのリクエストとレスポンスの例を以下に示します。
属性を取得するリクエスト
| code language-shell |
|---|
|
応答
以下の応答は簡潔に短縮されています。
| code language-json |
|---|
|
IDを取得するリクエスト
| code language-shell |
|---|
|
応答
応答は、入力スキーマの作成時に使用できるIDを返します。 この応答では、Experience Platformで設定したstandardとcustomのID名前空間の両方が返されることに注意してください。
| code language-json |
|---|
|
次に、上から応答をコピーし、それを使用して入力スキーマを作成する必要があります。 上記の応答からJSON応答全体をコピーし、以下に示すjsonSchema オブジェクトに配置できます。
入力スキーマの作成リクエスト
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
応答のIDは、作成した入力スキーマの一意の識別子を表します。 後の手順で再利用するので、応答からIDをコピーします。
出力スキーマの作成 create-output-schema
次に、書き出しの出力スキーマを設定する必要があります。 まず、既存のパートナースキーマを見つけて検査する必要があります。
リクエスト
以下の例では、Amazon S3にconnection spec IDを使用しています。 この値を、宛先に固有の接続仕様IDに置き換えてください。
| code language-shell |
|---|
|
スキーマの例を使用した応答
上記の呼び出しを実行する際に取得した応答を調べます。 応答をドリルダウンしてオブジェクト targetSpec.attributes.partnerSchema.jsonSchemaを見つける必要があります
| code language-json |
|---|
|
次に、出力スキーマを作成する必要があります。 上記のJSON応答をコピーし、下のjsonSchema オブジェクトに貼り付けます。
リクエスト
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
応答のIDは、作成した入力スキーマの一意の識別子を表します。 後の手順で再利用するので、応答からIDをコピーします。
マッピングセットを作成 create-mapping-set
次に、 データ準備APIを使用して、入力スキーマ ID、出力スキーマ ID、および目的のフィールドマッピングを使用してマッピングセットを作成します。
リクエスト
| note important |
|---|
| IMPORTANT |
|
| code language-shell line-numbers data-start-1 data-line-offset-4 h-16-38 |
|---|
|
応答
| code language-json |
|---|
|
マッピングセット IDを使用して既存のデータフローを更新するには、次の手順で必要になるマッピングセットのIDをメモします。
次に、更新するデータフローのIDを取得します。
データフローのIDの取得について詳しくは、宛先データフローの詳細の取得を参照してください。
最後に、作成したばかりのマッピングセット情報を含むデータフローをPATCHする必要があります。
リクエスト
| code language-shell |
|---|
|
応答
Flow Service APIからの応答は、更新されたデータフローのIDを返します。
| code language-json |
|---|
|
その他のデータフローの更新 other-dataflow-updates
データフローを更新するには、PATCH操作を使用します。 例えば、データフローにマーケティングアクションを追加したり、データフローを更新して必須キーまたは重複排除キーとしてフィールドを選択したり、既存の宛先にファイルマニフェスト生成を追加したりできます。
マーケティングアクションの追加 add-marketing-action
マーケティングアクション を追加するには、以下のリクエストと応答の例を参照してください。
If-Match ヘッダーは、PATCH リクエストを行う際に必要です。 このヘッダーの値は、更新するデータフローの一意のバージョンです。 etag値は、データフロー、ターゲット接続などのフローエンティティが正常に更新されるたびに更新されます。https://platform.adobe.io/data/foundation/flowservice/flows/{ID} エンドポイントに対してGET リクエストを実行します。{ID}は、更新するデータフローIDです。If-Match要求を行う際は、以下の例のように、PATCH ヘッダーの値を二重引用符で囲んでください。リクエスト
| code language-shell |
|---|
|
応答
応答が成功すると、応答コード 200が、更新されたデータフローと更新されたeTagのIDと共に返されます。
| code language-json |
|---|
|
必須キーを追加 add-mandatory-key
必須キーを追加するには、以下のリクエストと応答の例を参照してください。
If-Match ヘッダーは、PATCH リクエストを行う際に必要です。 このヘッダーの値は、更新するデータフローの一意のバージョンです。 etag値は、データフロー、ターゲット接続などのフローエンティティが正常に更新されるたびに更新されます。https://platform.adobe.io/data/foundation/flowservice/flows/{ID} エンドポイントに対してGET リクエストを実行します。{ID}は、更新するデータフローIDです。If-Match要求を行う際は、以下の例のように、PATCH ヘッダーの値を二重引用符で囲んでください。リクエスト
| code language-shell |
|---|
|
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
重複排除キーの追加 add-deduplication-key
重複排除キーを追加するには、以下のリクエストと応答の例を参照してください
If-Match ヘッダーは、PATCH リクエストを行う際に必要です。 このヘッダーの値は、更新するデータフローの一意のバージョンです。 etag値は、データフロー、ターゲット接続などのフローエンティティが正常に更新されるたびに更新されます。https://platform.adobe.io/data/foundation/flowservice/flows/{ID} エンドポイントに対してGET リクエストを実行します。{ID}は、更新するデータフローIDです。If-Match要求を行う際は、以下の例のように、PATCH ヘッダーの値を二重引用符で囲んでください。リクエスト
| code language-shell |
|---|
|
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
ファイルマニフェスト生成を既存の宛先に追加 add-file-manifest
マニフェスト JSON ファイルには、書き出しの場所や書き出しサイズなどの情報が含まれます。 マニフェストの名前は、形式manifest-<<destinationId>>-<<dataflowRunId>>.jsonを使用して指定されています。 サンプルマニフェストファイル を表示します。 マニフェストファイルには、次のフィールドが含まれます。
flowRunId: エクスポートされたファイルを生成した データフロー実行。scheduledTime: ファイルがエクスポートされたUTCの時間。exportResults.sinkPath:書き出されたファイルが格納されているストレージの場所のパス。exportResults.name: エクスポートされたファイルの名前。size:書き出されたファイルのサイズ (バイト単位)。
既存の宛先にファイルマニフェスト生成を追加するには、PATCH操作を使用してターゲット接続パラメーターを更新する必要があります。 これにより、書き出されたファイルに関するメタデータを提供する宛先のマニフェストファイルの生成が有効になります。
If-Match ヘッダーは、PATCH リクエストを行う際に必要です。 このヘッダーの値は、更新するターゲット接続の一意のバージョンです。 etag値は、データフロー、ターゲット接続などのフローエンティティが正常に更新されるたびに更新されます。https://platform.adobe.io/data/foundation/flowservice/targetConnections/{ID} エンドポイントに対してGET リクエストを実行します。{ID}は、更新する対象のコネクション IDです。If-Match要求を行う際は、以下の例のように、PATCH ヘッダーの値を二重引用符で囲んでください。リクエスト
| code language-shell |
|---|
|
データフローの検証(データフロー実行の取得) get-dataflow-runs
データフローの実行を確認するには、Dataflow Runs APIを使用します。
リクエスト
| code language-shell |
|---|
|
応答
| code language-json |
|---|
|
データフロー実行APIによって返される様々なパラメーターに関する情報は、API リファレンスドキュメントで確認できます。
API エラー処理 api-error-handling
このチュートリアルのAPI エンドポイントは、一般的なExperience Platform API エラーメッセージの原則に従っています。 エラー応答の解釈について詳しくは、Experience Platform トラブルシューティングガイドのAPI ステータスコード および リクエストヘッダーエラーを参照してください。
次の手順 next-steps
Experience Platformを任意のクラウドストレージの宛先に正常に接続し、オーディエンスを書き出すために各宛先にデータフローを設定しました。 次のページでは、Flow Service API を使用した既存のデータフローの編集方法などの詳細を確認します。