Flow Service APIを使用してData Landing ZoneをAdobe Experience Platformに接続する

IMPORTANT
このページは、Experience PlatformのData Landing Zone source コネクタに固有です。 Data Landing Zone 宛先 コネクタへの接続について詳しくは、Data Landing Zone 宛先ドキュメント ページ ​を参照してください。

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 ソース接続を正常に作成するために知っておく必要がある追加情報を示します。

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

IMPORTANT
Data Landing Zone APIを使用して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_zone
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'

応答

リクエストが成功すると、プロバイダーに応じて次の内容が返されます。

Azureでの回答
code language-json
{
    "containerName": "dlz-user-container",
    "containerTTL": "7"
}
table 0-row-2 1-row-2 2-row-2
プロパティ 説明
containerName 取得したランディングゾーンの名前。
containerTTL ランディングゾーン内のデータに適用される有効期限(日数)。 特定のランディングゾーン内のイベントは、7日後に削除されます。
AWSでの回答
code language-json
{
  "dlzPath": {
    "bucketName": "dlz-prod-sandboxName",
    "dlzFolder": "dlz-adf-connectors"
  },
  "dataTTL": {
    "timeUnit": "days",
    "timeQuantity": 7
  },
  "dlzProvider": "Amazon S3"
}

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

応答

リクエストが成功すると、プロバイダーに応じて次の内容が返されます。

Azureでの回答
code language-json
{
    "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"
}
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資格情報呼び出しが実行されたときに自動的に更新され、新しいトークンが提供されます。
AWSでの回答
code language-json
{
  "credentials": {
    "clientId": "example-client-id",
    "awsAccessKeyId": "example-access-key-id",
    "awsSecretAccessKey": "example-secret-access-key",
    "awsSessionToken": "example-session-token"
  },
  "dlzPath": {
    "bucketName": "dlz-prod-sandboxName",
    "dlzFolder": "user_drop_zone"
  },
  "dlzProvider": "Amazon S3",
  "expiryTime": 1735689599
}
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を使用した必須フィールドの取得

トークンを生成したら、次のリクエスト例を使用して、必須フィールドをプログラムで取得できます。

Python
code language-py
import requests

# API endpoint
url = "https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone"

headers = {
    "Authorization": "{TOKEN}",
    "Content-Type": "application/json",
    "x-gw-ims-org-id": "{ORG_ID}",
    "x-api-key": "{API_KEY}"
}

# Send GET request to the API
response = requests.get(url, headers=headers)

# Check if the request was successful
if response.status_code == 200:
    # Parse the response as JSON (if applicable)
    data = response.json()

    # Print or work with the fetched data
    print(" Sas Token:", data['SASToken'])
    print(" Container Name:",  data['containerName'])
    print("\n")

else:
    # Print an error message if the request failed
    print(f"Failed to fetch data. Status code: {response.status_code}")
    print(f"Response: {response.text}")
Java
code language-java
package org.example;

import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;

import org.apache.http.HttpResponse;
import org.apache.http.client.ClientProtocolException;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.impl.client.DefaultHttpClient;

import com.fasterxml.jackson.databind.JsonNode;
import com.fasterxml.jackson.databind.ObjectMapper;

public class Main {
    public static void main(String[] args) {

        ObjectMapper objectMapper = new ObjectMapper();

        try {

            DefaultHttpClient httpClient = new DefaultHttpClient();
            HttpGet getRequest = new HttpGet(
                "https://platform.adobe.io/data/foundation/connectors/landingzone/credentials?type=user_drop_zone");
            getRequest.addHeader("accept", "application/json");
            getRequest.addHeader("Authorization","<TOKEN>");
            getRequest.addHeader("Content-Type", "application/json");
            getRequest.addHeader("x-gw-ims-org-id", "<ORG_ID>");
            getRequest.addHeader("x-api-key", "<API_KEY>");

            HttpResponse response = httpClient.execute(getRequest);

            if (response.getStatusLine().getStatusCode() != 200) {
                throw new RuntimeException("Failed : HTTP error code : "
                    + response.getStatusLine().getStatusCode());
            }

            final JsonNode jsonResponse = objectMapper.readTree(response.getEntity().getContent());

            System.out.println("\nOutput from API Response .... \n");
            System.out.printf("ContainerName: %s%n", jsonResponse.at("/containerName").textValue());
            System.out.printf("SASToken: %s%n", jsonResponse.at("/SASToken").textValue());

            httpClient.getConnectionManager().shutdown();

        } catch (ClientProtocolException e) {
            e.printStackTrace();
        } catch (IOException e) {
            e.printStackTrace();
        }
    }
}

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 タイプを使用すると、APIはランディングゾーンのコンテナを、使用可能な他のタイプのコンテナと区別できます。
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' \

応答

次の応答は、SASTokenSASUriの更新された値を返します。

{
    "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}
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}
ファイルのプレビューがサポートされているかどうかを定義するブール値。
  • 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 クエリパラメーターを使用するか、ファイルに関する情報を手動で提供する場合に発生する可能性のあるさまざまなシナリオの概要を示しています。

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

応答

応答が成功すると、ファイル名とデータタイプを含むクエリされたファイルの構造と、fileTypecompressionTypecolumnDelimiterに関する情報を含むproperties キーが返されます。

クリック
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
クエリされたファイルの対応するファイルタイプ。 サポートされているファイル形式は、delimitedjsonparquetです。
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
Experience Platformに取り込むデータのフォーマット。
params.path
Experience 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の資格情報を取得し、そのファイル構造を探索してExperience Platformに取り込むファイルを見つけ、ソース接続を作成してデータをExperience Platformに取り込みます。 次のチュートリアルに進み、 Flow Service API🔗を使用してクラウドストレージデータをExperience Platformに取り込むためのデータフローを作成する方法を学習します。

recommendation-more-help
experience-platform-help-sources