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

[ベータ版]{class="badge informative"}

のソース接続とデータフローの作成 Customer.io フローサービス API の使用

Last update: Wed Nov 01 2023 00:00:00 GMT+0000 (Coordinated Universal Time)

作成対象：

  • 開発者
NOTE
Customer.io ソースはベータ版です。詳しくは、 ソースの概要 ベータラベル付きのソースの使用に関する詳細

次のチュートリアルでは、 Customer.io 取り込むソース接続とデータフロー Customer.io イベントデータをAdobe Experience Platformに Flow Service API.

はじめに getting-started

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

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

接続 Customer.io を使用して Platform に Flow Service API connect-platform-to-flow-api

次に、 Customer.io イベントデータからExperience Platformへ。

ソース接続の作成 source-connection

に対してPOSTリクエストを実行してソース接続を作成 Flow Service API：ソースの接続仕様 ID、名前、説明、データの形式などの詳細を指定します。

API 形式

POST /sourceConnections

リクエスト

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

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": "Streaming Source Connection for Customer.io",
      "providerId": "521eee4d-8cbe-4906-bb48-fb6bd4450033",
      "description": "Streaming Source Connection for customer.io",
      "connectionSpec": {
          "id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
          "version": "1.0"
      },
      "data": {
          "format": "json"
      }
    }'
プロパティ
説明
name
ソース接続の名前。 ソース接続の情報を検索する際に使用できるので、ソース接続の名前はわかりやすいものにしてください。
description
含めることでソース接続に関する詳細情報を提供できるオプションの値です。
connectionSpec.id
ソースに対応する接続仕様の ID。
data.format
取り込む Customer.io データの形式。現在、サポートされているデータ形式は json のみです。

応答

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

{
    "id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
    "etag": "\"af00a717-0000-0200-0000-63ef2cbd0000\""
}

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

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

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

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

ターゲットデータセットの作成 target-dataset

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

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

ターゲット接続の作成 target-connection

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

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

API 形式

POST /targetConnections

リクエスト

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

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": "Streaming Target Connection for Customer.io",
      "description": "Streaming Target Connection for Customer.io",
      "connectionSpec": {
          "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
          "version": "1.0"
      },
      "data": {
          "format": "json",
          "schema": {
              "id": "https://ns.adobe.com/extconndev/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
              "version": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
      "params": {
          "dataSetId": "63ec807d3f5ce91bd2d06c65"
      }
  }'
プロパティ
説明
name
ターゲット接続の名前。ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。
description
ターゲット接続に関する詳細を提供するために含めることができるオプションの値です。
connectionSpec.id
データレイクに対応する接続仕様 ID。 この修正済み ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。
data.format
取り込む Customer.io データの形式。
params.dataSetId
前の手順で取得したターゲットデータセット ID。

応答

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

{
    "id": "da8b75ad-f6ee-4991-95df-291e62936e98",
    "etag": "\"70003dff-0000-0200-0000-63ef4a090000\""
}

マッピングの作成 mapping

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

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 '{
      "outputSchema": {
          "schemaRef": {
              "id": "https://ns.adobe.com/{TENANT_ID}/schemas/945546112b746524bfd9f1264b26c2b7d8e7f5b7fadb953a",
              "contentType": "application/vnd.adobe.xed-full+json;version=1"
          }
      },
    "mappings": [
        {
            "destinationXdmPath": "_extconndev.cio_id",
            "sourceAttribute": "data.identifiers.cio_id",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.email",
            "sourceAttribute": "data.identifiers.email",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.event_id0",
            "sourceAttribute": "event_id",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.metricx",
            "sourceAttribute": "metric",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.object_type1",
            "sourceAttribute": "object_type",
            "identity": false,
            "version": 0
        },
        {
            "destinationXdmPath": "_extconndev.timestampx",
            "sourceAttribute": "timestamp",
            "identity": false,
            "version": 0
        }
    ]
  }'
プロパティ
説明
outputSchema.schemaRef.id
以前の手順で生成されたターゲット XDM スキーマの ID。
mappings.sourceType
マッピングするソース属性タイプ。
mappings.source
宛先 XDM パスにマッピングする必要があるソース属性。
mappings.destination
ソース属性がマッピングされている宛先 XDM パス。

応答

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

{
    "id": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
    "version": 0,
    "createdDate": 1676627988129,
    "modifiedDate": 1676627988129,
    "createdBy": "{CREATED_BY}",
    "modifiedBy": "{MODIFIED_BY}"
}

フローの作成 flow

からデータを取り込むための最後の手順 Customer.io を Platform に送信する場合、データフローを作成します。 現時点で、次の必要な値の準備ができています。

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

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": "Streaming Dataflow for Customer.io",
      "description": "Streaming Dataflow for Customer.io",
      "flowSpec": {
          "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
          "version": "1.0"
      },
      "sourceConnectionIds": [
          "133bb51f-f310-4b4a-b8b2-731aef1e223c"
      ],
      "targetConnectionIds": [
          "da8b75ad-f6ee-4991-95df-291e62936e98"
      ],
      "transformations": [
      {
        "name": "Mapping",
        "params": {
          "mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
          "mappingVersion": 0
        }
      }
    ]
  }'
プロパティ
説明
name
データフローの名前。データフローの情報を検索する際に使用できるので、データフローはわかりやすい名前にしてください。
description
データフローの詳細を指定するために含めることができるオプションの値です。
flowSpec.id
データフローの作成に必要なフロー仕様 ID。この修正済み ID は e77fde5a-22a8-11ed-861d-0242ac120002 です。
flowSpec.version
フロー仕様 ID の対応するバージョン。この値のデフォルトは 1.0 です。
sourceConnectionIds
以前の手順で生成されたソース接続 ID。
targetConnectionIds
以前の手順で生成されたターゲット接続 ID。
transformations
このプロパティには、データに適用する必要がある様々な変換が含まれています。このプロパティは、XDM に準拠していないデータを Platform に取り込む場合に必要です。
transformations.name
変換に割り当てられた名前。
transformations.params.mappingId
以前の手順で生成されたマッピング ID。
transformations.params.mappingVersion
マッピング ID の対応するバージョン。この値のデフォルトは 0 です。

応答

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

{
    "id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
    "etag": "\"4c012103-0000-0200-0000-63ef57db0000\""
}

ストリーミングエンドポイント URL を取得する get-streaming-endpoint-url

データフローを作成したら、ストリーミングエンドポイント URL を取得できます。 このエンドポイント URL を使用して、ソースを Webhook に登録し、ソースとの通信を可能にします。Experience Platform

ストリーミングエンドポイント URL を取得するには、に対してGETリクエストを実行します。 /flows エンドポイントに接続し、データフローの ID を指定します。

API 形式

GET /flows/{FLOW_ID}

リクエスト

curl -X GET \
  'https://platform.adobe.io/data/foundation/flowservice/flows/4982698b-e6b3-48c2-8dcf-040e20121fd2' \
  -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}'

応答

正常な応答は、としてマークされたエンドポイント URL を含む、データフローに関する情報を返します。 inletUrl. 詳しくは、 Webhook を設定 ページを開き、必要な値を取得します。

{
    "items": [
        {
            "id": "4982698b-e6b3-48c2-8dcf-040e20121fd2",
            "createdAt": 1676629979503,
            "updatedAt": 1676629985390,
            "createdBy": "acme@AdobeID",
            "updatedBy": "acme@AdobeID",
            "createdClient": "{CREATED_CLIENT}",
            "updatedClient": "{UPDATED_CLIENT}",
            "sandboxId": "{SANDBOX_ID}",
            "sandboxName": "{SANDBOX_NAME}",
            "imsOrgId": "{ORG_ID}",
            "name": "Streaming Dataflow for Customer.io",
            "description": "Streaming Dataflow for Customer.io",
            "flowSpec": {
                "id": "e77fde5a-22a8-11ed-861d-0242ac120002",
                "version": "1.0"
            },
            "state": "enabled",
            "version": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
            "etag": "\"4c01c003-0000-0200-0000-63ef57e10000\"",
            "sourceConnectionIds": [
                "133bb51f-f310-4b4a-b8b2-731aef1e223c"
            ],
            "targetConnectionIds": [
                "da8b75ad-f6ee-4991-95df-291e62936e98"
            ],
            "inheritedAttributes": {
                "properties": {
                    "isSourceFlow": true
                },
                "sourceConnections": [
                    {
                        "id": "133bb51f-f310-4b4a-b8b2-731aef1e223c",
                        "connectionSpec": {
                            "id": "96479064-7b8a-4d69-b9ed-21c5683837ea",
                            "version": "1.0"
                        }
                    }
                ],
                "targetConnections": [
                    {
                        "id": "da8b75ad-f6ee-4991-95df-291e62936e98",
                        "connectionSpec": {
                            "id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
                            "version": "1.0"
                        }
                    }
                ]
            },
            "options": {
                "inletUrl": "https://dcs.adobedc.net/collection/e75dcb5247eb65e7385df30270192e80b145566f52ed74d570505bd2e82463f3"
            },
            "transformations": [
                {
                    "name": "Mapping",
                    "params": {
                        "mappingId": "59c0e53a2dc84f7791ecc1b3d6e51d5e",
                        "mappingVersion": 0
                    }
                }
            ],
            "runs": "/runs?property=flowId==4982698b-e6b3-48c2-8dcf-040e20121fd2",
            "providerRefId": "c4726e6f-64b4-4b3b-97e3-f128ace0cc74",
            "lastOperation": {
                "started": 0,
                "updated": 0,
                "operation": "enable"
            }
        }
    ]
}

付録 appendix

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

データフローの監視 monitor-dataflow

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

データフローの更新 update-dataflow

に対するPATCHリクエストを実行して、データフローの名前や説明、実行スケジュールおよび関連するマッピングセットなどの詳細を更新します。 /flows の終点 Flow Service API を使用してデータフローの ID を指定します。 PATCHリクエストをおこなう場合、データフローの一意の etag （内） If-Match ヘッダー。 API の完全な例については、 API を使用したソースデータフローの更新

アカウントを更新 update-account

に対してPATCHリクエストを実行して、ソースアカウントの名前、説明および資格情報を更新します。 Flow Service ベース接続 ID をクエリパラメーターとして指定する際の API。 PATCHリクエストをおこなう場合、ソースアカウントの一意の etag （内） If-Match ヘッダー。 API の完全な例については、 API を使用したソースアカウントの更新.

データフローの削除 delete-dataflow

に対してDELETEリクエストを実行して、データフローを削除する Flow Service クエリパラメーターの一部として削除するデータフローの ID を指定する際の API。 API の完全な例については、 API を使用したデータフローの削除.

アカウントを削除 delete-account

アカウントを削除するには、 Flow Service 削除するアカウントのベース接続 ID を指定する際の API。 API の完全な例については、 API を使用したソースアカウントの削除.

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