Flow Service API を使用した YOURSOURCE 接続の作成

最終更新日： 2025年4月4日

トピック：

作成対象：

開発者

このテンプレートを使用する場合は、（この段落から始めて）斜体のすべての段落を置き換えるか削除します。

まず、ページ上部のメタデータ（タイトルと説明）を更新します。このページの DNL のインスタンスをすべて無視してください。これは、機械翻訳プロセスが、サポートする複数の言語にページを正しく翻訳するのに役立つタグです。ドキュメントを送信したら、タグをドキュメントに追加します。

概要

顧客に提供する価値を含め、会社の概要を入力します。さらに読むために、製品ドキュメントのホームページへのリンクを含めます。

IMPORTANT

このソースコネクタとドキュメントページは、YourSource チームによって作成および管理されます。お問い合わせや更新のリクエストについては、リンクまたはメールアドレスを挿入 まで直接ご連絡ください。

前提条件

Adobe Experience Platform ユーザーインターフェイスでソースの設定を開始する前にお客様が認識しておく必要のある情報については、この節で説明します。次に示す内容を使用できます。

許可リストに追加する必要があります
メールハッシュの要件
お客様側のアカウント詳細
プラットフォームに接続するための API キーを取得する方法

必要な資格情報の収集

YOURSOURCE をExperience Platformに接続するには、次の接続プロパティの値を指定する必要があります。

資格情報	説明	例
認証情報 1	ソースの認証情報に簡単な説明を追加してください	ソースの認証情報の例をここに追加してください
認証情報 2	ソースの認証情報に簡単な説明を追加してください	ソースの認証情報の例をここに追加してください
認証情報 3	ソースの認証情報に簡単な説明を追加してください	ソースの認証情報の例をここに追加してください

これらの資格情報について詳しくは、YOURSOURCE 認証ドキュメントを参照してください。 プラットフォームの認証ドキュメントへのリンクをここに追加してください。

Flow Service API を使用したExperience Platformへの YOURSOURCE の接続

以下のチュートリアルでは、YOURSOURCE ソース接続を作成し、Flow Service API を使用して YOURSOURCE データをExperience Platformに取り込むデータフローを作成する手順を詳しく説明します。

ベース接続の作成

ベース接続は、ソースとExperience Platform間の情報（ソースの認証資格情報、現在の接続状況、一意のベース接続 ID など）を保持します。ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。

ベース接続 ID を作成するには、/connections エンドポイントに対して POST リクエストを実行し、その際に YOURSOURCE 認証資格情報をリクエスト本文の一部として指定します。

API 形式

POST /connections

リクエスト

次のリクエストは、YOURSOURCE のベース接続を作成します。

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/connections' \
    -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": "{YOURSOURCE} base connection",
        "description": "{YOURSOURCE} base connection to authenticate to Experience Platform",
        "connectionSpec": {
            "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
            "version": "1.0"
        },
        "auth": {
            "specName": "OAuth generic-rest-connector",
            "params": {
                "accessToken": "{ACCESS_TOKEN}",
                "refreshToken": "{REFRESH_TOKEN}",
                "expirationDate": "{EXPIRATION_DATE}"
            }
        }
    }'

プロパティ

説明

name

ベース接続の名前。ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。

description

含めることでベース接続に関する詳細情報を提供できるオプションの値です。

connectionSpec.id

ソースの接続仕様 ID。この ID は、ソースが登録および承認された後に、Flow Service API から取得することができます。

auth.specName

Experience Platformに対するソースの認証に使用する認証タイプ。

auth.params.

ソースの認証に必要な資格情報が含まれます。

応答

リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。

{
     "id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
     "etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}

ソースを参照

前の手順で生成したベース接続 ID を使用すると、GET リクエストを実行してファイルとディレクトリを調べることができます。
次の呼び出しを使用して、Experience Platform に取り込むファイルのパスを検索します。

API 形式

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}

ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。

パラメーター

説明

{BASE_CONNECTION_ID}

前の手順で生成したベース接続 ID。

objectType=rest

参照するオブジェクトのタイプ。現在、この値は常に rest に設定されています。

{OBJECT}

このパラメーターは、特定のディレクトリを表示する場合にのみ必要です。値は、参照するディレクトリのパスを表します。

fileType=json

Experience Platformに取り込むファイルのファイルタイプ。現在、サポートされているファイルタイプは json のみです。

{PREVIEW}

接続のコンテンツがプレビューをサポートするかどうかを定義するブール値です。

{SOURCE_PARAMS}

Experience Platformに取り込むソースファイルのパラメーターを定義します。 {SOURCE_PARAMS} で受け入れ可能な形式タイプを取得するには、list_id 文字列全体を base64 にエンコードする必要があります。次の例では、base64 にエンコードされた "list_id": "10c097ca71" は eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0= と等しくなります。

リクエスト

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
    -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}'

応答

応答が成功すると、クエリされたファイルの構造を返します。

{
  "data": [
    {
      "members": [
        {
          "id": "cff65fb4c5f5828666ad846443720efd",
          "email_address": "roykent@gmail.com",
          "unique_email_id": "72c758cbf1",
          "full_name": "Roy Kent",
          "web_id": 547094062,
          "email_type": "html",
          "status": "subscribed",
          "merge_fields": {
            "FNAME": "Roy",
            "LNAME": "Kent",
            "ADDRESS": {
              "addr1": "",
              "addr2": "",
              "city": "Richmond",
              "state": "Virginia",
              "zip": "",
              "country": "US"
            },
            "PHONE": "",
            "BIRTHDAY": ""
          },
          "stats": {
            "avg_open_rate": 0,
            "avg_click_rate": 0
          },
          "ip_signup": "",
          "timestamp_signup": "",
          "ip_opt": "103.43.112.97",
          "timestamp_opt": "2021-06-01T15:31:36+00:00",
          "member_rating": 2,
          "last_changed": "2021-06-01T15:31:36+00:00",
          "language": "",
          "vip": false,
          "email_client": "",
          "location": {
            "latitude": 0,
            "longitude": 0,
            "gmtoff": 0,
            "dstoff": 0,
            "country_code": "",
            "timezone": ""
          },
          "source": "Admin Add",
          "tags_count": 0,
          "tags": [

          ],
          "list_id": "10c097ca71"
        }
      ],
      "list_id": "10c097ca71",
      "total_items": 2,
      "_links": [
        {
          "rel": "self",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
          "method": "GET",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
          "schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
        },
        {
          "rel": "parent",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
          "method": "GET",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
        },
        {
          "rel": "create",
          "href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
          "method": "POST",
          "targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
          "schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
        }
      ]
    }
  ]
}

ソース接続の作成

Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。

API 形式

POST /sourceConnections

リクエスト

次のリクエストは、YOURSOURCE のソース接続を作成します。

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": "{YOURSOURCE} Source Connection",
        "description": "{YOURSOURCE} Source Connection",
        "baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
        "connectionSpec": {
            "id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
            "version": "1.0"
        },
        "data": {
            "format": "json"
        },
        "params": {
            "server": "us6",
            "listId": "10c097ca71"
        }
    }'

プロパティ

説明

name

ソース接続の名前。ソース接続の情報を検索する際に使用できるので、ソース接続の名前はわかりやすいものにしてください。

description

含めることでソース接続に関する詳細情報を提供できるオプションの値です。

baseConnectionId

YOURSOURCE のベース接続 ID。この ID は、前の手順で生成されました。

connectionSpec.id

ソースに対応する接続仕様の ID。

data.format

取り込む YOURSOURCE データの形式。現在、サポートされているデータ形式は json のみです。

応答

リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。この ID は、後の手順でデータフローを作成する際に必要になります。

{
     "id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
     "etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}

ターゲット XDM スキーマの作成

ソースデータをExperience Platformで使用するには、必要に応じてターゲットスキーマを作成してソースデータを構造化する必要があります。次に、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットが作成されます。

Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。

ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。

ターゲットデータセットの作成

Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。

ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。

ターゲット接続の作成

ターゲット接続は、取り込まれたデータが保存される宛先への接続を表します。ターゲット接続を作成するには、Data Lake に対応する固定接続仕様 ID を指定する必要があります。この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。

これで、一意の識別子、ターゲットスキーマ、ターゲットデータセット、および Data Lake の接続仕様 ID が用意できました。これらの識別子を使用することで、Flow Service API を使用してターゲット接続を作成し、受信ソースデータを格納するデータセットを指定できます。

API 形式

POST /targetConnections

リクエスト

次のリクエストは、YOURSOURCE のターゲット接続を作成します。

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
    -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": "{YOURSOURCE} Target Connection",
        "description": "{YOURSOURCE} Target Connection",
        "connectionSpec": {
            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
            "version": "1.0"
        },
        "data": {
            "format": "json"
        },
        "params": {
            "dataSetId": "5ef4551c52e054191a61a99f"
        }
    }'

プロパティ

説明

name

ターゲット接続の名前。ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。

description

ターゲット接続に関する詳細を提供するために含めることができるオプションの値です。

connectionSpec.id

Data Lakeに対応する接続仕様 ID。この修正済み ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。

data.format

Experience Platformに取り込む YOURSOURCE データの形式。

params.dataSetId

前の手順で取得したターゲットデータセット ID。

応答

リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。この ID は、後の手順で必要になります。

{
     "id": "7c96c827-3ffd-460c-a573-e9558f72f263",
     "etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}

マッピングの作成

ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。これを実現するには、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep API に対して POST リクエストを実行します。

API 形式

POST /conversion/mappingSets

リクエスト

curl -X POST \
    'https://platform.adobe.io/data/foundation/conversion/mappingSets' \
    -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 '{
        "version": 0,
        "xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
        "xdmVersion": "1.0",
        "id": null,
        "mappings": [
            {
                "destinationXdmPath": "_id",
                "sourceAttribute": "Id",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "person.name.firstName",
                "sourceAttribute": "FirstName",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            },
            {
                "destinationXdmPath": "person.name.lastName",
                "sourceAttribute": "LastName",
                "identity": false,
                "identityGroup": null,
                "namespaceCode": null,
                "version": 0
            }
        ]
    }'

プロパティ

説明

xdmSchema

以前の手順で生成されたターゲット XDM スキーマの ID。

mappings.destinationXdmPath

ソース属性がマッピングされている宛先 XDM パス。

mappings.sourceAttribute

宛先 XDM パスにマッピングする必要があるソース属性。

mappings.identity

マッピングセットに Identity Service のマークを付けるかどうかを指定するブール値。

応答

リクエストが成功した場合は、一意の ID（id）を含む、新しく作成されたマッピングの詳細が返されます。この値は、後の手順でデータフローを作成する際に必要になります。

{
    "id": "bf5286a9c1ad4266baca76ba3adc9366",
    "version": 0,
    "createdDate": 1597784069368,
    "modifiedDate": 1597784069368,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

フローの作成

YOURSOURCE からExperience Platformにデータを取り込むための最後の手順は、データフローを作成することです。現時点で、次の必要な値の準備ができています。

ソース接続 ID
ターゲット接続 ID
マッピング ID

データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。ペイロードに前述の値を提供しながら POST リクエストを実行することで、データフローを作成することができます。

取り込みをスケジュールするには、まず開始時刻の値をエポック時間（秒）に設定する必要があります。次に、頻度の値を次の 5 つのオプションのいずれかに設定する必要があります。once、minute、hour、day または week。インターバルの値は、2 つの連続した取り込みの間隔を指定しますが、1 回のみの取り込みを作成する場合は、インターバルを設定する必要はありません。それ以外の頻度では、間隔の値を 15 以上に設定する必要があります。

API 形式

POST /flows

リクエスト

curl -X POST \
    'https://platform.adobe.io/data/foundation/flowservice/flows' \
    -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": "{YOURSOURCE} dataflow",
        "description": "{YOURSOURCE} dataflow",
        "flowSpec": {
            "id": "6499120c-0b15-42dc-936e-847ea3c24d72",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "246d052c-da4a-494a-937f-a0d17b1c6cf5"
        ],
        "targetConnectionIds": [
            "7c96c827-3ffd-460c-a573-e9558f72f263"
        ],
        "transformations": [
            {
                "name": "Mapping",
                "params": {
                    "mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
                    "mappingVersion": "0"
                }
            }
        ],
        "scheduleParams": {
            "startTime": "1625040887",
            "frequency": "minute",
            "interval": 15
        }
    }'

プロパティ

説明

name

データフローの名前。データフローの情報を検索する際に使用できるので、データフローはわかりやすい名前にしてください。

description

データフローの詳細を提供するために含めることができるオプションの値です。

flowSpec.id

データフローの作成に必要なフロー仕様 ID。この修正済み ID は 6499120c-0b15-42dc-936e-847ea3c24d72 です。

flowSpec.version

フロー仕様 ID の対応するバージョン。この値のデフォルトは 1.0 です。

sourceConnectionIds

以前の手順で生成されたソース接続 ID。

targetConnectionIds

以前の手順で生成されたターゲット接続 ID。

transformations

このプロパティには、データに適用する必要がある様々な変換が含まれています。このプロパティは、XDM に準拠していないデータをExperience Platformに取り込む場合に必要です。

transformations.name

変換に割り当てられた名前。

transformations.params.mappingId

以前の手順で生成されたマッピング ID。

transformations.params.mappingVersion

マッピング ID の対応するバージョン。この値のデフォルトは 0 です。

scheduleParams.startTime

このプロパティには、データフローの取り込みスケジュールに関する情報が含まれています。

scheduleParams.frequency

データフローがデータを収集する頻度。指定できる値は、once、minute、hour、day、week です。

scheduleParams.interval

インターバルは 2 つの連続したフロー実行の間隔を指定します。インターバルの値はゼロ以外の整数にしてください。頻度が once に設定されている場合、間隔は必須ではありません。また、頻度は他の頻度の値に対して、15 よりも大きいか、等しい必要があります。

応答

正常な応答は、新しく作成したデータフローの ID（id）を返します。この ID を使用して、データフローを監視、更新または削除できます。

{
     "id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
     "etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}

付録

次の節では、データフローの監視、更新、削除を行う手順について説明します。

データフローの監視

データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。完全な API の例については、API を使用したソースデータフローのモニタリングに関するガイドを参照してください。

データフローの更新

データフローの ID を指定しながら、API の /flows エンドポイントに対してPATCH リクエストを実行することで、名前や説明、実行スケジュールおよび関連するマッピングセットなど、データフローの詳細 Flow Service 更新します。 PATCH リクエストを行う場合は、データフローの一意の etag を If-Match ヘッダーで指定する必要があります。完全な API の例については、API を使用したソースデータフローの更新に関するガイドを参照してください

アカウントを更新

ベース接続 ID をクエリパラメーターとして指定して Flow Service API に対してPATCH リクエストを実行することで、ソースアカウントの名前、説明、資格情報を更新します。 PATCH リクエストを行う場合は、ソースアカウントの一意の etag を If-Match ヘッダーで指定する必要があります。完全な API の例については、API を使用したソースアカウントの更新に関するガイドを参照してください。

データフローの削除

クエリパラメーターの一部として削除するデータフローの ID を指定したうえで Flow Service API に対してDELETE リクエストを実行することで、データフローを削除します。完全な API の例については、API を使用したデータフローの削除に関するガイドを参照してください。

アカウントを削除

Flow Service API にDELETE リクエストを実行し、その際に削除するアカウントのベース接続 ID を指定することで、アカウントを削除します。完全な API の例については、API を使用したソースアカウントの削除に関するガイドを参照してください。

recommendation-more-help