ドキュメントExperience Platformソースコネクタガイド

Flow Service API を使用した Data Landing Zone のAdobe Experience Platformへの接続

Last update: Wed Oct 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • トピック：

作成対象：

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

次の節では、Flow Service API を使用して Data Landing Zone ソース接続を正常に作成するために必要な追加情報を示しています。

また、このチュートリアルでは Platform API の基本を学ぶに関するガイドを読んで、Platform API への認証方法と、ドキュメントに記載されている呼び出し例を解釈する方法も確認する必要があります。

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

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'

応答

次の応答は、ランディングゾーンに関する情報（対応する containerName と containerTTL を含む）を返します。

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

資格情報 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' \

応答

次の応答では、現在の 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資格情報の呼び出しが実行されると、自動的に更新され、新しいトークンが提供されます。

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 タイプを使用すると、ランディングゾーンコンテナを、使用可能な他のタイプのコンテナと区別できます。
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}
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 のファイルプロパティ情報を自動検出します

determineProperties パラメーターを使用すると、ソースの内容と構造を調べるためにGET呼び出しを行う際に、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}'

応答

応答が成功すると、クエリされたファイルの構造（ファイル名とデータタイプを含む）と、fileType、compressionType、columnDelimiter に関する情報を含む 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
クエリされたファイルの対応するファイルタイプ。 サポートされているファイルタイプは、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 へのデータの取り込みを開始するためのソース接続を作成しました。 次のチュートリアルに進むことができます。ここでは、API を使用してクラウドストレージデータを Platform に取り込むためのデータフローを作成する方法を説明し Flow Service す。

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