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 API の概要を読んで、Experience Platform API への認証方法と、ドキュメントに記載されている呼び出し例を解釈する方法についても確認する必要があります。
次の節では、Flow Service API を使用して Data Landing Zone ソース接続を正常に作成するために必要な追加情報を示しています。
使用可能なランディングゾーンの取得
type=user_drop_zone
ータを取得するには、ソースの管理 アクセス制御権限が必要です。 詳しくは、 アクセス制御の概要を参照するか、製品管理者に問い合わせて、必要な権限を取得してください。API を使用して Data Landing Zone にアクセスする最初の手順は、Connectors API の /landingzone
エンドポイントに対してGET リクエストを実行し、その際にリクエストヘッダーの一部として type=user_drop_zone
を指定することです。
API 形式
GET /data/foundation/connectors/landingzone?type=user_drop_zone
user_drop_zone
user_drop_zone
タイプを使用すると、ランディングゾーンコンテナを、使用可能な他のタイプのコンテナと区別できます。リクエスト
次のリクエストでは、既存のランディングゾーンが取得されます。
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_zone
user_drop_zone
タイプを使用すると、ランディングゾーンコンテナを、使用可能な他のタイプのコンテナと区別できます。refresh
refresh
のアクションを使用すると、ランディングゾーンの資格情報をリセットし、新しい 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}
delimited
json
parquet
{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 のファイルプロパティ情報を自動検出します
determineProperties
パラメーターを使用すると、ソースの内容と構造を調べるためにGETを呼び出す際に、Data Landing Zone ージのファイルコンテンツのプロパティ情報を自動検出できます。
determineProperties
の使用例
次の表は、determineProperties
クエリパラメーターを使用する際や、ファイルに関する情報を手動で指定する際に発生する可能性がある様々なシナリオの概要を説明しています。
determineProperties
queryParams
determineProperties
がクエリパラメーターとして指定されている場合、ファイルプロパティの検出が行われ、応答は、ファイルタイプ、圧縮タイプ、列の区切り文字に関する情報を含んだ新しい properties
キーを返します。queryParams
の一部として手動で指定された場合、これらの値がスキーマの生成に使用され、同じプロパティが応答の一部として返されます。API 形式
GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
determineProperties
true
リクエスト
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.fileType
delimited
、json
、parquet
です。properties.compressionType
クエリされたファイルに使用される、対応する圧縮タイプ。 サポートされている圧縮タイプは次の通りです。
bzip2
gzip
zipDeflate
tarGzip
tar
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"
}
}'
name
data.format
params.path
connectionSpec.id
26f526f2-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へのデータの取り込みを開始するソース接続を作成しました。 次のチュートリアルに進むことができます。ここでは、API を使用してクラウドストレージデータをExperience Platformに取り込むためのデータフローを作成する方法を説明し Flow Service す。