Flow Service APIを使用してData Landing ZoneをAdobe Experience Platformに接続する
Data Landing Zoneは、Adobe Experience Platformにファイルを取り込むための、安全なクラウドベースのファイル保存機能です。 データは、7日後にData Landing Zoneから自動的に削除されます。
このチュートリアルでは、Flow Service APIを使用してData Landing Zone ソース接続を作成する手順について説明します。 このチュートリアルでは、資格情報の表示と更新だけでなく、Data Landing Zoneを取得する方法についても説明します。
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- ソース : Experience Platformを使用すると、様々なソースからデータを取り込むことができますが、Experience Platform サービスを使用して着信データを構造化、ラベル付け、強化することができます。
- サンドボックス : Experience Platformは、1つのExperience Platform インスタンスを個別のバーチャル環境に分割して、デジタルエクスペリエンスアプリケーションの開発と進化に役立つバーチャルサンドボックスを提供します。
このチュートリアルでは、Experience Platform APIの概要に関するガイドを読んで、Experience Platform APIの認証方法と、ドキュメントに記載されている呼び出しの例を理解する必要があります。
次の節では、Flow Service APIを使用してData Landing Zone ソース接続を正常に作成するために知っておく必要がある追加情報を示します。
使用可能なランディングゾーンの取得
type=user_drop_zoneを取得するには、ソースの管理 アクセス制御権限が必要です。 詳しくは、 アクセス制御の概要を参照するか、製品管理者に連絡して、必要な権限を取得してください。APIを使用してData Landing Zoneにアクセスする最初の手順は、リクエストヘッダーの一部としてtype=user_drop_zoneを提供しながら、Connectors APIの/landingzone エンドポイントにGET リクエストを行うことです。
API 形式
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zoneuser_drop_zone タイプを使用すると、APIはランディングゾーンのコンテナを、使用可能な他のタイプのコンテナと区別できます。リクエスト
次のリクエストは、既存のランディングゾーンを取得します。
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone?type=user_drop_zone' \
-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}' \
-H 'Content-Type: application/json'
応答
リクエストが成功すると、プロバイダーに応じて次の内容が返されます。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 | |
|---|---|
| プロパティ | 説明 |
containerName |
取得したランディングゾーンの名前。 |
containerTTL |
ランディングゾーン内のデータに適用される有効期限(日数)。 特定のランディングゾーン内のイベントは、7日後に削除されます。 |
| code language-json |
|---|
|
Data Landing Zone資格情報を取得
Data Landing Zoneの資格情報を取得するには、Connectors APIの/credentials エンドポイントにGET リクエストを行います。
API 形式
GET /data/foundation/connectors/landingzone/credentials?type=user_drop_zone
リクエスト
次のリクエストの例では、既存のランディングゾーンの資格情報を取得します。
curl -X GET \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone' \
-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}' \
-H 'Content-Type: application/json' \
応答
リクエストが成功すると、プロバイダーに応じて次の内容が返されます。
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
|---|---|
| プロパティ | 説明 |
containerName |
Data Landing Zoneの名前。 |
SASToken |
Data Landing Zoneの共有アクセス署名トークン。 この文字列には、リクエストの承認に必要なすべての情報が含まれます。 |
storageAccountName |
ストレージアカウントの名前。 |
SASUri |
Data Landing Zoneの共有アクセス署名URI。 この文字列は、認証対象のData Landing ZoneへのURIとそれに対応するSAS トークンの組み合わせです。 |
expiryDate |
SAS トークンの有効期限。 データをData Landing Zoneにアップロードするアプリケーションでトークンを引き続き使用するには、有効期限の前にトークンを更新する必要があります。 指定された有効期限より前にトークンを手動で更新しない場合は、GET資格情報呼び出しが実行されたときに自動的に更新され、新しいトークンが提供されます。 |
| code language-json |
|---|
|
| table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 | |
|---|---|
| プロパティ | 説明 |
credentials.clientId |
AWSのData Landing Zoneのクライアント ID。 |
credentials.awsAccessKeyId |
AWSのData Landing Zoneのアクセス キーID。 |
credentials.awsSecretAccessKey |
AWSのData Landing Zoneの秘密アクセス キー。 |
credentials.awsSessionToken |
AWSのセッショントークン。 |
dlzPath.bucketName |
AWS バケットの名前。 |
dlzPath.dlzFolder |
アクセスしているData Landing Zone フォルダー。 |
dlzProvider |
使用しているData Landing Zone プロバイダー。 Amazonの場合、これはAmazon S3になります。 |
expiryTime |
有効期限(UNIX時間)。 |
APIを使用した必須フィールドの取得
トークンを生成したら、次のリクエスト例を使用して、必須フィールドをプログラムで取得できます。
| code language-py |
|---|
|
| code language-java |
|---|
|
Data Landing Zone資格情報を更新
Connectors APIの/credentials エンドポイントにPOST リクエストを行うことで、SASTokenを更新できます。
API 形式
POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
user_drop_zoneuser_drop_zone タイプを使用すると、APIはランディングゾーンのコンテナを、使用可能な他のタイプのコンテナと区別できます。refreshrefresh アクションを使用すると、ランディングゾーンの資格情報をリセットし、新しいSASTokenを自動的に生成できます。リクエスト
次のリクエストは、ランディングゾーンの資格情報を更新します。
curl -X POST \
'https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh' \
-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}' \
-H 'Content-Type: application/json' \
応答
次の応答は、SASTokenとSASUriの更新された値を返します。
{
"containerName": "dlz-user-container",
"SASToken": "sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"storageAccountName": "dlblobstore99hh25i3dflek",
"SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-9c4d03b8-a6ff-41be-9dcf-20123e717e99&sr=c&sp=racwdlm&sig=JbRMoDmFHQU4OWOpgrKdbZ1d%2BkvslO35%2FXTqBO%2FgbRA%3D",
"expiryDate": "2024-01-06"
}
ランディングゾーンファイルの構造と内容を確認する
Flow Service APIのconnectionSpecs エンドポイントにGET リクエストを実行することで、ランディングゾーンのファイル構造とコンテンツを確認できます。
API 形式
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
{CONNECTION_SPEC_ID}26f526f2-58f4-4712-961d-e41bf1ccc0e8 です。リクエスト
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=root' \
-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}'
応答
応答が成功すると、クエリされたディレクトリ内にあるファイルとフォルダーの配列が返されます。 アップロードするファイルのpath プロパティに注意してください。このプロパティは、次の手順で構造を検査するために指定する必要があります。
[
{
"type": "file",
"name": "account.csv",
"path": "dlz-user-container/account.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "file",
"name": "data8.csv",
"path": "dlz-user-container/data8.csv",
"canPreview": true,
"canFetchSchema": true
},
{
"type": "folder",
"name": "userdata1",
"path": "dlz-user-container/userdata1/",
"canPreview": false,
"canFetchSchema": false
}
]
ランディングゾーンのファイル構造と内容のプレビュー
ランディングゾーン内のファイルの構造を調べるには、ファイルのパスとタイプをクエリパラメーターとして指定しながらGET リクエストを実行します。
API 形式
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
{CONNECTION_SPEC_ID}26f526f2-58f4-4712-961d-e41bf1ccc0e8 です。{OBJECT_TYPE}file{OBJECT}dlz-user-container/data8.csv{FILE_TYPE}delimitedjsonparquet
{PREVIEW}-
true -
false
リクエスト
curl -X GET \
'http://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/data8.csv&fileType=delimited&preview=true' \
-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}'
応答
応答が成功すると、ファイル名とデータタイプを含む、クエリされたファイルの構造が返されます。
{
"format": "flat",
"schema": {
"columns": [
{
"name": "Id",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "FirstName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "LastName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Email",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Phone",
"type": "string",
"xdm": {
"type": "string"
}
}
]
},
"data": [
{
"Email": "rsmith@abc.com",
"FirstName": "Richard",
"Phone": "111111111",
"Id": "12345",
"LastName": "Smith"
},
{
"Email": "morgan@bac.com",
"FirstName": "Morgan",
"Phone": "22222222222",
"Id": "67890",
"LastName": "Hart"
}
]
}
determinePropertiesを使用してData Landing Zoneのファイルプロパティ情報を自動検出する
GET呼び出しを行ってソースの内容と構造を調べる際に、determineProperties パラメーターを使用して、Data Landing Zoneのファイル内容のプロパティ情報を自動検出できます。
determinePropertiesの使用例
次の表は、determineProperties クエリパラメーターを使用するか、ファイルに関する情報を手動で提供する場合に発生する可能性のあるさまざまなシナリオの概要を示しています。
determinePropertiesqueryParamsdeterminePropertiesがクエリパラメーターとして指定されている場合、ファイルプロパティの検出が発生し、応答は、ファイルタイプ、圧縮タイプ、列区切り文字に関する情報を含む新しいproperties キーを返します。queryParamsの一部として手動で指定されている場合、スキーマの生成に使用され、同じプロパティが応答の一部として返されます。API 形式
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determinePropertiestrueリクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs/26f526f2-58f4-4712-961d-e41bf1ccc0e8/explore?objectType=file&object=dlz-user-container/garageWeek/file1&preview=true&determineProperties=true' \
-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}'
応答
応答が成功すると、ファイル名とデータタイプを含むクエリされたファイルの構造と、fileType、compressionType、columnDelimiterに関する情報を含むproperties キーが返されます。
| code language-json |
|---|
|
properties.fileTypedelimited、json、parquetです。properties.compressionTypeクエリされたファイルに使用される対応する圧縮タイプ。 サポートされる圧縮タイプは次のとおりです。
bzip2gzipzipDeflatetarGziptar
properties.columnDelimiter(,)です。ソース接続の作成
ソース接続は、データの取り込み元となる外部ソースへの接続を作成および管理します。 ソース接続は、データソース、データフォーマット、データフローの作成に必要なソース接続IDなどの情報で構成されます。 ソース接続インスタンスは、テナントと組織に固有です。
ソース接続を作成するには、Flow Service API の /sourceConnections エンドポイントに POST リクエストを実行します。
API 形式
POST /sourceConnections
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Data Landing Zone source connection",
"data": {
"format": "delimited"
},
"params": {
"path": "dlz-user-container/data8.csv"
},
"connectionSpec": {
"id": "26f526f2-58f4-4712-961d-e41bf1ccc0e8",
"version": "1.0"
}
}'
namedata.formatparams.pathconnectionSpec.id26f526f2-58f4-4712-961d-e41bf1ccc0e8 です。応答
リクエストが成功した場合は、新しく作成されたソース接続の一意の ID(id)が返されます。 この ID は、次のチュートリアルでデータフローを作成する際に必要です。
{
"id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
"etag": "\"1400d460-0000-0200-0000-613be3520000\""
}
次の手順
このチュートリアルでは、Data Landing Zoneの資格情報を取得し、そのファイル構造を探索してExperience Platformに取り込むファイルを見つけ、ソース接続を作成してデータをExperience Platformに取り込みます。 次のチュートリアルに進み、 Flow Service API🔗を使用してクラウドストレージデータをExperience Platformに取り込むためのデータフローを作成する方法を学習します。