接続 Data Landing Zone フローサービス API を使用してAdobe Experience Platformに送信する

IMPORTANT
このページは、 Data Landing Zone ソース コネクタのExperience Platform に接続する方法については、 Data Landing Zone 宛先 コネクタ ( Data Landing Zone 宛先のドキュメントページ.

Data Landing Zone は、ファイルをAdobe Experience Platformに取り込む、クラウドベースの安全なファイルストレージ機能です。 データは Data Landing Zone 7 日後

このチュートリアルでは、 Data Landing Zone を使用したソース接続 Flow Service API. このチュートリアルでは、 Data Landing Zoneを参照し、資格情報を表示および更新します。

はじめに

このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。

  • ソース:Experience Platform を使用すると、データを様々なソースから取得しながら、Platform サービスを使用して受信データの構造化、ラベル付け、拡張を行うことができます。
  • サンドボックス:Experience Platform には、単一の Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスが用意されています。

以下の節では、 Data Landing Zone を使用したソース接続 Flow Service API.

また、このチュートリアルでは、 Platform API の概要 を参照して、Platform API に対する認証方法と、ドキュメントに記載されている呼び出し例の解釈方法について確認してください。

使用可能なランディングゾーンの取得

API を使用してにアクセスする際の最初の手順 Data Landing Zone は、 /landingzone エンドポイント Connectors を提供する際の API type=user_drop_zone をリクエストヘッダーの一部として追加する必要があります。

API 形式

GET /data/foundation/connectors/landingzone?type=user_drop_zone
ヘッダー
説明
user_drop_zone
The user_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'

応答

次の応答は、ランディングゾーンに関する情報(対応するランディングゾーンも含む)を返します containerName および containerTTL.

{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}
プロパティ
説明
containerName
取得したランディングゾーンの名前。
containerTTL
ランディングゾーン内のデータに適用される有効期限(日数)。 特定のランディングゾーン内のすべては、7 日後に削除されます。

取得 Data Landing Zone 資格情報

の資格情報を取得するには Data Landing Zoneを使用して、 /credentials エンドポイント Connectors API.

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' \

応答

次の応答は、現在の SASToken, SASUri, storageAccountName、および有効期限日。

{
    "containerName": "dlz-user-container",
    "SASToken": "sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "storageAccountName": "dlblobstore99hh25i3dflek",
    "SASUri": "https://dlblobstore99hh25i3dflek.blob.core.windows.net/dlz-user-container?sv=2020-04-08&si=dlz-ed86a61d-201f-4b50-b10f-a1bf173066fd&sr=c&sp=racwdlm&sig=4yTba8voU3L0wlcLAv9mZLdZ7NlMahbfYYPTMkQ6ZGU%3D",
    "expiryDate": "2024-01-06"
}
プロパティ
説明
containerName
ランディングゾーンの名前。
SASToken
ランディングゾーンの共有アクセス署名トークン。 この文字列には、リクエストの承認に必要な情報がすべて含まれています。
SASUri
ランディングゾーンの共有アクセス署名 URI です。 この文字列は、認証先のランディングゾーンへの URI と、対応する SAS トークンの組み合わせです。
expiryDate
SAS トークンの有効期限が切れる日付です。 データランディングゾーンにデータをアップロードするためにアプリケーションでトークンを引き続き使用するには、有効期限の前にトークンを更新する必要があります。 指定した有効期限より前に手動でトークンを更新しない場合、GET資格情報の呼び出しが実行されると、自動的に更新され、新しいトークンが提供されます。

更新 Data Landing Zone 資格情報

次の項目を更新: SASToken に対してPOSTリクエストを行う /credentials エンドポイント Connectors API.

API 形式

POST /data/foundation/connectors/landingzone/credentials?type=user_drop_zone&action=refresh
ヘッダー
説明
user_drop_zone
The user_drop_zone タイプを使用すると、API はランディングゾーンコンテナを、使用可能な他のタイプのコンテナと区別できます。
refresh
The 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"
}

ランディングゾーンのファイル構造とコンテンツの参照

に対してGETリクエストをおこなうことで、ランディングゾーンのファイル構造とコンテンツを確認できます。 connectionSpecs エンドポイント Flow Service API.

API 形式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=root
パラメーター
説明
{CONNECTION_SPEC_ID}
Data Landing Zone に対応する接続仕様 ID。 この修正済み 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}
Data Landing Zone に対応する接続仕様 ID。 この修正済み ID は 26f526f2-58f4-4712-961d-e41bf1ccc0e8 です。
{OBJECT_TYPE}
アクセスするオブジェクトのタイプ。
file
{OBJECT}
アクセスするオブジェクトのパスと名前。
dlz-user-container/data8.csv
{FILE_TYPE}
ファイルのタイプ。
  • delimited
  • json
  • parquet
{PREVIEW}
ファイルのプレビューがサポートされるかどうかを定義する boolean 値です。
  • 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 ファイルコンテンツのプロパティ情報を自動検出するためのパラメータ Data Landing Zone GET呼び出しを実行してソースのコンテンツと構造を調べる場合。

determineProperties 使用例

次の表に、 determineProperties クエリパラメーターを使用するか、手動でファイルに関する情報を指定します。

determineProperties
queryParams
応答
True
なし
次の場合 determineProperties がクエリパラメーターとして指定された場合、ファイルのプロパティの検出が発生し、応答が新しい properties ファイルタイプ、圧縮タイプおよび列区切り文字に関する情報を含むキー。
なし
True
ファイルタイプ、圧縮タイプ、列区切りの値が queryParamsの場合、スキーマの生成に使用され、同じプロパティが応答の一部として返されます。
True
True
両方のオプションが同時に実行された場合は、エラーが返されます。
なし
なし
2 つのオプションのどちらも指定されていない場合は、応答のプロパティを取得する方法がないので、エラーが返されます。

API 形式

GET /connectionSpecs/{CONNECTION_SPEC_ID}/explore?objectType=file&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&determineProperties=true
パラメーター
説明
determineProperties
このクエリパラメーターを使用すると、 Flow Service ファイルタイプ、圧縮タイプ、列区切り文字に関する情報など、ファイルのプロパティに関する情報を検出する API です。
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}'

応答

正常な応答は、クエリされたファイルの構造と、ファイル名、データ型、および properties キー、次の情報を含む fileType, compressionType、および columnDelimiter.

ここをクリック
code language-json
{
    "properties": {
        "fileType": "delimited",
        "compressionType": "tarGzip",
        "columnDelimiter": "~"
    },
    "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": "birthday",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    },
    "data": [
        {
            "birthday": "1313-0505-19731973",
            "firstName": "Yvonne",
            "lastName": "Thilda",
            "id": "100",
            "email": "Yvonne.Thilda@yopmail.com"
        },
        {
            "birthday": "1515-1212-19731973",
            "firstName": "Mary",
            "lastName": "Pillsbury",
            "id": "101",
            "email": "Mary.Pillsbury@yopmail.com"
        },
        {
            "birthday": "0505-1010-19751975",
            "firstName": "Corene",
            "lastName": "Joeann",
            "id": "102",
            "email": "Corene.Joeann@yopmail.com"
        },
        {
            "birthday": "2727-0303-19901990",
            "firstName": "Dari",
            "lastName": "Greenwald",
            "id": "103",
            "email": "Dari.Greenwald@yopmail.com"
        },
        {
            "birthday": "1717-0404-19651965",
            "firstName": "Lucy",
            "lastName": "Magdalen",
            "id": "199",
            "email": "Lucy.Magdalen@yopmail.com"
        }
    ]
}
プロパティ
説明
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 Landing Zone ソース接続。
data.format
Platform に取り込むデータの形式。
params.path
Platform に取り込むファイルへのパス。
connectionSpec.id
Data Landing Zone に対応する接続仕様 ID。 この修正済み ID は 26f526f2-58f4-4712-961d-e41bf1ccc0e8 です。

応答

リクエストが成功した場合は、新しく作成されたソース接続の一意の ID(id)が返されます。この ID は、次のチュートリアルでデータフローを作成する際に必要です。

{
    "id": "f5b46949-8c8d-4613-80cc-52c9c039e8b9",
    "etag": "\"1400d460-0000-0200-0000-613be3520000\""
}

次の手順

このチュートリアルに従うことで、 Data Landing Zone 資格情報は、Platform に取り込むファイルを見つけるためにファイル構造を調べ、ソース接続を作成してデータの Platform への取り込みを開始します。 次のチュートリアルに進み、次の方法を学ぶことができます。 を使用してデータフローを作成し、クラウドストレージデータを Platform に取り込みます。 Flow Service API.

recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089