を使用してデータセットを書き出す Flow Service API
- この機能は、Real-Time CDP Prime および Ultimate パッケージ、Adobe Journey OptimizerまたはCustomer Journey Analyticsを購入したお客様が利用できます。 詳しくは、Adobe担当者にお問い合わせください。
この記事では、 Flow Service API エクスポートする データセット Adobe Experience Platformから目的のクラウドストレージの場所 ( Amazon S3、SFTP の場所、または Google Cloud Storage.
書き出しに使用できるデータセット datasets-to-export
書き出すデータセットは、Experience Platformアプリケーション (Real-Time CDP、Adobe Journey Optimizer)、層(Prime または Ultimate)、および購入した任意のアドオン ( 例:Data Distiller) によって異なります。
詳しくは、 UI チュートリアルページの表 を参照して、書き出すことができるデータセットを把握します。
サポートされる宛先 supported-destinations
現在、以下のスクリーンショットでハイライト表示されているクラウドストレージの宛先にデータセットを書き出すことができます。
はじめに get-started
このガイドでは、Adobe Experience Platform の次のコンポーネントに関する十分な知識が必要です。
- Experience Platform datasets: Adobe Experience Platformに正常に取り込まれたすべてのデータは、 Data Lake データセットとして。 データセットは、通常、スキーマ(列)とフィールド(行)を含むテーブルであるデータコレクションのストレージと管理をおこなう構成体です。データセットには、保存するデータの様々な側面を記述したメタデータも含まれます。
- Sandboxes:Experience Platform には、単一の Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスが用意されています。
以下の節では、データセットを Platform のクラウドストレージの宛先に書き出す際に知っておく必要がある追加情報を示します。
必要な権限 permissions
データセットを書き出すには、 宛先の表示, データセットを表示、および データセットの宛先の管理とアクティブ化 アクセス制御権限. 必要な権限を取得するには、アクセス制御の概要を参照するか、製品管理者に問い合わせてください。
データセットの書き出しに必要な権限があることと、宛先でデータセットの書き出しがサポートされていることを確認するには、宛先カタログを参照します。 宛先に「アクティブ化」または「データセットを書き出し」コントロールがある場合、適切な権限を持っています。
API 呼び出し例の読み取り reading-sample-api-calls
このチュートリアルでは、API 呼び出しの例を提供し、リクエストの形式を設定する方法を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
必須ヘッダーおよびオプションヘッダーの値の収集 gather-values-headers
を呼び出すために 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 のリソースは、特定の仮想サンドボックスに分離できます。Platform API へのリクエストでは、操作を実行するサンドボックスの名前と ID を指定できます。次に、オプションのパラメーターを示します。
- x-sandbox-name:
{SANDBOX_NAME}
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、メディアのタイプを指定する以下のような追加ヘッダーが必要です。
- Content-Type:
application/json
API リファレンスドキュメント api-reference-documentation
このチュートリアルに含まれるすべての API 操作について、付属リファレンスドキュメントが用意されています。詳しくは、 Flow Service - Adobe Developer Web サイト上の宛先 API ドキュメント. このチュートリアルと API リファレンスのドキュメントを並行して使用することをお勧めします。
用語集 glossary
この API チュートリアルで遭遇する用語の説明については、 用語集セクション API リファレンスドキュメントの
目的の宛先の接続仕様およびフロー仕様を収集します gather-connection-spec-flow-spec
データセットの書き出しワークフローを開始する前に、データセットの書き出し先の接続仕様とフロー仕様 ID を特定します。 以下の表を参考にしてください。
4fce964d-3f37-408f-9778-e597338a21ee
269ba276-16fc-47db-92b0-c1049a3c131f
6d6b59bf-fb58-4107-9064-4d246c0e5bb2
95bd8965-fc8a-4119-b9c3-944c2c2df6d2
be2c3209-53bc-47e7-ab25-145db8b873e1
17be2013-2549-41ce-96e7-a70363bec293
10440537-2a7b-4583-ac39-ed38d4b848e8
cd2fc47e-e838-4f38-a581-8fff2f99b63a
c5d93acb-ea8b-4b14-8f53-02138444ae99
585c15c4-6cbf-4126-8f87-e26bff78b657
36965a81-b1c6-401b-99f8-22508f1e6a26
354d6aad-4754-46e4-a576-1b384561c440
様々な ID を作成するには、これらの ID が必要です Flow Service エンティティ。 また、 Connection Spec 自身を使用して特定のエンティティを設定し、 Connection Spec から Flow Service APIs. この表のすべての宛先の接続仕様の取得については、以下の例を参照してください。
リクエスト
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 | ||
---|---|---|
取得 connection spec (SFTP 用) | ||
|
応答
accordion | ||
---|---|---|
SFTP - Connection spec | ||
|
以下の手順に従って、クラウドストレージの宛先へのデータセットのデータフローを設定します。 一部の手順では、クラウドストレージの様々な宛先でリクエストと応答が異なります。 このような場合は、ページのタブを使用して、接続してデータセットを書き出す宛先に固有のリクエストと応答を取得します。 正しい connection spec および flow spec を設定します。
データセットのリストの取得 retrieve-list-of-available-datasets
アクティベーションの対象となるデータセットのリストを取得するには、まず以下のエンドポイントに対して API 呼び出しをおこないます。
リクエスト
code language-shell |
---|
|
適格なデータセットを取得するには、 connection spec 要求 URL で使用される ID は、データレイクソース接続仕様 ID である必要があります。 23598e46-f560-407b-88d5-ea6207e49db0
、および 2 つのクエリパラメーター outputField=datasets
および outputType=activationDatasets
を指定する必要があります。 その他すべてのクエリパラメーターは、 カタログサービス API.
応答
code language-json |
---|
|
正常な応答は、アクティベーションの対象となるデータセットのリストを含みます。 次の手順でソース接続を構築する際に、これらのデータセットを使用できます。
返される各データセットの様々な応答パラメーターについて詳しくは、 データセット API 開発者ドキュメント.
ソース接続の作成 create-source-connection
書き出すデータセットのリストを取得したら、それらのデータセット ID を使用してソース接続を作成できます。
リクエスト
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
code language-shell line-numbers data-start-1 data-line-offset-4 h-12 h-16 |
---|
|
応答
code language-json |
---|
|
正常な応答は、ID(id
) をクリックし、新しく作成されたソース接続と etag
. 後でデータフローを作成する際に必要になるので、ソース接続 ID をメモしておきます。
また、次の点にも注意してください。
- この手順で作成したソース接続を宛先に対してアクティブ化するには、データセットをデータフローにリンクする必要があります。 詳しくは、 データフローの作成 ソース接続をデータフローにリンクする方法については、を参照してください。
- ソース接続のデータセット ID は、作成後に変更することはできません。 ソース接続にデータセットを追加または削除する必要がある場合は、新しいソース接続を作成し、新しいソース接続の 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 | |||||
---|---|---|---|---|---|
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 | |||||
---|---|---|---|---|---|
SFTP(SSH キー) — ベース接続リクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
SFTP — ベース接続応答 | ||
|
応答の接続 ID をメモします。 この ID は、次の手順でターゲット接続を作成する際に必要になります。
ターゲット接続の作成 create-target-connection
次に、データセットの書き出しパラメーターを保存するターゲット接続を作成する必要があります。 書き出しパラメーターには、場所、ファイル形式、圧縮、その他の詳細が含まれます。 詳しくは、 targetSpec
宛先の接続仕様で指定されたプロパティ。各宛先タイプでサポートされるプロパティを理解します。 以下のタブを参照して、 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 | ||
---|---|---|
Target 接続 — 応答 | ||
|
リクエスト
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target 接続リクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
Target 接続 — 応答 | ||
|
リクエスト
accordion | |||||
---|---|---|---|---|---|
Azure Blob Storage - Target 接続リクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
Target 接続 — 応答 | ||
|
リクエスト
accordion | |||||
---|---|---|---|---|---|
Data Landing Zone - Target 接続リクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
Target 接続 — 応答 | ||
|
リクエスト
accordion | |||||
---|---|---|---|---|---|
Google Cloud Storage - Target 接続リクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
Target 接続 — 応答 | ||
|
リクエスト
accordion | |||||
---|---|---|---|---|---|
SFTP - Target 接続のリクエスト | |||||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
Target 接続 — 応答 | ||
|
応答から Target 接続 ID をメモします。 この ID は、次の手順で、データセットをエクスポートするデータフローを作成する際に必要になります。
データフローの作成 create-dataflow
宛先設定の最後の手順は、データフローを設定することです。 データフローは、以前に作成したエンティティと結び付け、データセットの書き出しスケジュールを設定するオプションも提供します。 データフローを作成するには、目的のクラウドストレージの宛先に応じて、以下のペイロードを使用し、前の手順のエンティティ ID を置き換えます。
リクエスト
accordion | ||
---|---|---|
データセットのデータフローを次に作成: Amazon S3 destination — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
リクエスト
accordion | ||
---|---|---|
データセットのデータフローを次に作成: Azure Blob Storage destination — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
リクエスト
accordion | ||
---|---|---|
データセットのデータフローを次に作成: Azure Data Lake Gen 2(ADLS Gen2) destination — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
リクエスト
accordion | ||
---|---|---|
データセットのデータフローを次に作成: Data Landing Zone destination — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
リクエスト
accordion | ||
---|---|---|
データセットのデータフローを次に作成: Google Cloud Storage destination — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
リクエスト
accordion | ||
---|---|---|
SFTP 宛先へのデータセットデータフローの作成 — リクエスト | ||
リクエスト例で、インラインコメント付きの強調表示された行に注意してください。この行には、追加情報が示されています。 リクエストを任意のターミナルにコピー&ペーストする際に、リクエスト内のインラインコメントを削除します。
|
応答
accordion | ||
---|---|---|
データフローの作成 — 応答 | ||
|
応答のデータフロー ID をメモします。 この ID は、データフロー実行を取得して正常な日付セットエクスポートを検証する際に、次の手順で必要になります。
データフローの実行 get-dataflow-runs
データフローの実行を確認するには、次の Dataflow Run API を使用します。
リクエスト
データフローの実行を取得するリクエストで、前の手順で取得したデータフロー ID を、データフローの作成時にクエリパラメーターとして追加します。
code language-shell |
---|
|
応答
code language-json |
---|
|
次の項目に関する情報を検索できます。 データフロー実行 API から返される様々なパラメーター ( API リファレンスドキュメント)を参照してください。
データセットの正常な書き出しの確認 verify
データセットを書き出す際、Experience Platform は、指定されたストレージの場所に .json
または .parquet
ファイルを保存します。指定した日時に指定した書き出しスケジュールに従って、新しいファイルがストレージの場所に保存されます。 データフローの作成.
Experience Platform は、指定されたストレージの場所にフォルダー構造を作成し、書き出されたデータセットファイルを格納します。 書き出しのたびに、次のパターンに従って新しいフォルダーが作成されます。
folder-name-you-provided/datasetID/exportTime=YYYYMMDDHHMM
デフォルトのファイル名はランダムに生成され、書き出されたファイルの名前は必ず一意になります。
サンプルデータセットファイル sample-files
これらのファイルがストレージの場所に存在すれば、書き出しは成功しています。書き出されたファイルの構造を理解するには、サンプルの .parquet ファイルまたは .json ファイルをダウンロードできます。
圧縮データセットファイル compressed-dataset-files
次の手順で ターゲット接続の作成に含めると、書き出したデータセットファイルを圧縮して選択できます。
圧縮時のファイル形式の違いに注意してください。
- 圧縮 JSON ファイルを書き出す場合、書き出されるファイル形式は次のようになります。
json.gz
- 圧縮 Parquet ファイルを書き出す場合、書き出されるファイル形式は次のようになります。
gz.parquet
API エラー処理 api-error-handling
このチュートリアルの API エンドポイントは、Experience PlatformAPI エラーメッセージの一般的な原則に従います。 参照: API ステータスコード および リクエストヘッダーエラー エラー応答の解釈について詳しくは、『 Platform トラブルシューティングガイド』を参照してください。
次の手順 next-steps
このチュートリアルでは、Platform を目的のバッチクラウドストレージの宛先の 1 つに接続し、データセットを書き出すための各宛先へのデータフローを設定しました。 次のページでは、Flow Service API を使用した既存のデータフローの編集方法などの詳細を確認します。