Show Menu
トピック×

APIを使用して、ストリーミング送信先に接続し、アドビのリアルタイム顧客データPlatformでデータをアクティブにします。

Adobe Real-time CDP Azure Event Hubs の宛先と宛先は、現在ベータ版です。 ドキュメントと機能は変更される場合があります。
このチュートリアルでは、API呼び出しを使用してAdobe Experience Platformデータに接続し、ストリーミングクラウドストレージ先( Amazon Kinesis または Azureイベントハブ )に接続する方法、新しく作成した宛先にデータフローを作成する方法、新しく作成した宛先にデータをアクティブ化する方法を説明します。
このチュートリアルでは、すべての例で Amazon Kinesis 宛先を使用しますが、手順はで同じで Azure Event Hubsす。
アドビのReal-time CDPのユーザーインターフェイスを使用して宛先に接続し、データをアクティブにする場合は、「宛先の 接続 」および「宛先へのプロファイルとセグメントのアク ティブ化 」のチュートリアルを参照してください。

はじめに

このガイドでは、次のAdobe Experience Platformのコンポーネントについて、十分に理解している必要があります。
  • Experience Data Model(XDM)System : Experience Platformが顧客体験データを編成する際に使用する標準化されたフレームワーク。
  • カタログサービス : カタログは、Experience Platform内のデータの場所と系列の記録システムです。
  • サンドボックス : Experience Platformは、1つのPlatformインスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスを提供します。
Adobe Real-time CDPのストリーミング宛先に対するデータをアクティブ化するために知っておく必要がある追加情報について、以下の節で説明します。

必要な資格情報の収集

このチュートリアルの手順を完了するには、セグメントを接続およびアクティブ化する宛先のタイプに応じて、次の資格情報を準備する必要があります。
  • 接続 Amazon Kinesis の場合: accessKeyId secretKey``region または connectionUrl
  • 接続 Azure Event Hubs の場合: sasKeyName , sasKey``namespace

サンプルAPI呼び出しの読み取り

このチュートリアルでは、リクエストをフォーマットする方法を示すAPI呼び出しの例を提供します。 例えば、パス、必須のヘッダー、適切にフォーマットされた要求ペイロードなどです。 API応答で返されるサンプルJSONも提供されます。 サンプルAPI呼び出しのドキュメントで使用される規則について詳しくは、Experience PlatformトラブルシューティングガイドのAPI呼び出し例 の読み方に関する節 を参照してください。

必須ヘッダーと任意選択ヘッダーの値の収集

PlatformAPIを呼び出すには、まず 認証チュートリアルを完了する必要があります 。 次に示すように、Experience PlatformAPIのすべての呼び出しに必要な各ヘッダーの値を認証チュートリアルで説明します。
  • 認証: 無記名 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}
Experience Platform内のリソースは、特定の仮想サンドボックスに分離できます。 PlatformAPIへのリクエストでは、操作を実行するサンドボックスの名前とIDを指定できます。 これらはオプションのパラメーターです。
  • x-sandbox-name: {SANDBOX_NAME}
ペイロード(POST、PUT、PATCH)を含むすべての要求には、追加のメディアタイプヘッダーが必要です。
  • Content-Type: application/json

Swaggerドキュメント

Swaggerのこのチュートリアルでは、すべてのAPI呼び出しに関する付属のリファレンスドキュメントを参照できます。 Adobe.ioの Flow Service APIドキュメントを参照してください 。 このチュートリアルとSwaggerのドキュメントページを並行して使用することをお勧めします。

使用可能なストリーミング先のリストの取得

最初の手順として、データをアクティブにするストリーミング先を決定する必要があります。 最初に、接続してセグメントをアクティブにできる、使用可能な宛先のリストをリクエストする呼び出しを実行します。 使用可能な宛先のリストを返すには、次のGETリクエストを connectionSpecs エンドポイントに実行します。
API形式
GET /connectionSpecs

リクエスト
curl --location --request GET 'https://platform.adobe.io/data/foundation/flowservice/connectionSpecs' \
--header 'accept: application/json' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}'

応答
成功した応答には、使用可能な宛先とその一意の識別子( id )のリストが含まれます。 使用する宛先の値を保存します。この値は、以降の手順で必要になります。 例えば、またはにセグメントを接続して配信する場合 Amazon Kinesis は、応答で次のスニペットを探し Azure Event Hubsます。
{
    "id": "86043421-563b-46ec-8e6c-e23184711bf6",
  "name": "Amazon Kinesis",
  ...
  ...
}

{
    "id": "bf9f5905-92b7-48bf-bf20-455bc6b60a4e",
  "name": "Azure Event Hubs",
  ...
  ...
}

Experience Platformデータに接続する

次に、Experience Platformデータに接続し、プロファイルデータを書き出して、希望の場所でアクティブにできるようにする必要があります。 これは、次に説明する2つのサブステップで構成されます。
  1. まず、ベース接続を設定して、Experience Platformでのデータへのアクセスを許可する呼び出しを実行する必要があります。
  2. 次に、ベース接続IDを使用して別の呼び出しを行い、ソース接続を作成して、Experience Platformデータとの接続を確立します。

Experience Platform内のデータへのアクセスを許可する

API形式
POST /connections

リクエスト
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME} \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Base connection to Experience Platform",
            "description": "This call establishes the connection to Experience Platform data",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            }
}'

  • {CONNECTION_SPEC_ID} : ユニファイドプロファイルングサービスの接続仕様IDを使用します — 8a9c3494-9708-43d7-ae3f-cda01e5030e1
応答
成功した応答には、ベース接続の固有な識別子( id )が含まれます。 この値は、次の手順でソース接続を作成する際に必要となる場合に保存します。
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

Experience Platformデータに接続する

API形式
POST /sourceConnections

リクエスト
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
            "name": "Connecting to Unified Profile Service",
            "description": "Optional",
            "connectionSpec": {
                "id": "{CONNECTION_SPEC_ID}",
                "version": "1.0"
            },
            "baseConnectionId": "{BASE_CONNECTION_ID}",
            "data": {
                "format": "json"
            },
            "params" : {}
}'

  • {BASE_CONNECTION_ID} : 前の手順で取得したIDを使用します。
  • {CONNECTION_SPEC_ID} : ユニファイドプロファイルングサービスの接続仕様IDを使用します — 8a9c3494-9708-43d7-ae3f-cda01e5030e1
応答
正常な応答は、新しく作成されたUnified Connection Serviceへのソース接続の固有な識別子( id )を返します。 これにより、Experience Platformデータに正常に接続できたことが確認されます。 この値は、後の手順で必要となる場合に格納します。
{
    "id": "ed48ae9b-c774-4b6e-88ae-9bc7748b6e97"
}

Connect to streaming destination

この手順では、目的のストリーミング宛先への接続を設定します。 これは、次に説明する2つのサブステップで構成されます。
  1. まず、ベース接続を設定して、ストリーミング宛先へのアクセスを許可する呼び出しを実行する必要があります。
  2. 次に、ベース接続IDを使用して別の呼び出しを行い、ターゲット接続を作成します。この呼び出しでは、エクスポートされたデータが配信されるストレージアカウント内の場所と、エクスポートされるデータの形式を指定します。

ストリーミング先へのアクセスを許可する

API形式
POST /connections

リクエスト
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/connections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Connection for Amazon Kinesis/ Azure Event Hubs",
    "description": "your company's holiday campaign",
    "connectionSpec": {
        "id": "{_CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "auth": {
        "specName": "{AUTHENTICATION_CREDENTIALS}",
        "params": { // use these values for Amazon Kinesis connections
            "accessKeyId": "{ACCESS_ID}",
            "secretKey": "{SECRET_KEY}",
            "region": "{REGION}"
        },
        "params": { // use these values for Azure Event Hubs connections
            "sasKeyName": "{SAS_KEY_NAME}",
            "sasKey": "{SAS_KEY}",
            "namespace": "{EVENT_HUB_NAMESPACE}"
        }        
    }
}'

  • {CONNECTION_SPEC_ID} : 使用可能な宛先のリストの 取得で取得した接続仕様IDを使用します
  • {AUTHENTICATION_CREDENTIALS} : ストリーミング先の名前を入力します。例: Amazon Kinesis authentication credentials または Azure Event Hubs authentication credentials
  • {ACCESS_ID} : Amazon Kinesis接続の場合。 Amazon Kinesisストレージの場所のアクセスID。
  • {SECRET_KEY} : Amazon Kinesis接続の場合。 Amazon Kinesisストレージの場所の秘密キー。
  • {REGION} : Amazon Kinesis接続の場合。 Adobe Real-time CDPがデータをストリーミングするAmazon Kinesisアカウント内の領域。
  • {SAS_KEY_NAME} : Azureイベントハブ接続の場合。 SASキー名を入力します。 SASキーを使用し Azure Event Hubs たときの認証については、 Microsoftのドキュメントを参照してください
  • {SAS_KEY} : Azureイベントハブ接続の場合。 SASキーを入力します。 SASキーを使用し Azure Event Hubs たときの認証については、 Microsoftのドキュメントを参照してください
  • {EVENT_HUB_NAMESPACE} : Azureイベントハブ接続の場合。 Adobe Real-time CDPがデータをストリーミングするAzureイベントハブ名前空間に入力します。 詳細については、Microsoftのドキュメントの「イベントハブの 作成」名前空間 を参照してください。
応答
成功した応答には、ベース接続の固有な識別子( id )が含まれます。 この値は、次の手順でターゲット接続を作成する際に必要となる場合に格納します。
{
    "id": "1ed86558-59b5-42f7-9865-5859b552f7f4"
}

ストレージの場所とデータ形式を指定する

API形式
POST /targetConnections

リクエスト
curl --location --request POST 'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Amazon Kinesis/ Azure Event Hubs target connection",
    "description": "Connection to Amazon Kinesis/ Azure Event Hubs",
    "baseConnection": "{BASE_CONNECTION_ID}",
    "connectionSpec": {
        "id": "{CONNECTION_SPEC_ID}",
        "version": "1.0"
    },
    "data": {
        "format": "json",
    },
    "params": { // use these values for Amazon Kinesis connections
        "stream": "{NAME_OF_DATA_STREAM}", 
        "region": "{REGION}"
    },
    "params": { // use these values for Azure Event Hubs connections
        "eventHubName": "{EVENT_HUB_NAME}"
    }
}'

  • {BASE_CONNECTION_ID} : 上記の手順で取得したベース接続IDを使用します。
  • {CONNECTION_SPEC_ID} : 使用可能な宛先のリストを 取得する手順で取得した接続仕様を使用します
  • {NAME_OF_DATA_STREAM} : Amazon Kinesis接続の場合。 Amazon Kinesisアカウント内の既存のデータストリームの名前を指定します。 Adobe Real-time CDPは、このストリームにデータをエクスポートします。
  • {REGION} : Amazon Kinesis接続の場合。 Adobe Real-time CDPがデータをストリーミングするAmazon Kinesisアカウント内の領域。
  • {EVENT_HUB_NAME} : Azureイベントハブ接続の場合。 Azureイベントハブ名に、Adobe Real-time CDPがデータをストリーミングする場所を入力します。 詳しくは、Microsoftのドキュメントの「イベントハブの 作成 」を参照してください。
応答
正常な応答を返すと、新たに作成されたターゲット接続からストリーミングの宛先への一意の識別子( id )が返されます。 この値は、後の手順で必要となるので保存します。
{
    "id": "12ab90c7-519c-4291-bd20-d64186b62da8"
}

データフローの作成

前の手順で取得したIDを使用して、Experience Platformデータと、データをアクティブ化する宛先との間にデータフローを作成できるようになりました。 この手順は、後でデータが流れるパイプラインをExperience Platformと目的の宛先の間に構築することと考えてください。
データフローを作成するには、以下に示すように、ペイロード内で以下に示す値を指定しながら、POSTリクエストを実行します。
次のPOST要求を実行して、データフローを作成します。
API形式
POST /flows

リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-H 'Content-Type: application/json' \
-d  '{
   
        "name": "Create dataflow to Amazon Kinesis/ Azure Event Hubs",
        "description": "This operation creates a dataflow to Amazon Kinesis/ Azure Event Hubs",
        "flowSpec": {
            "id": "{FLOW_SPEC_ID}",
            "version": "1.0"
        },
        "sourceConnectionIds": [
            "{SOURCE_CONNECTION_ID}"
        ],
        "targetConnectionIds": [
            "{TARGET_CONNECTION_ID}"
        ]
    }

応答
正常な応答は、新しく作成されたデータフローのID( id``etag )と、 両方の値を書き留めておきます。 次の手順で行うように、セグメントをアクティブにします。
{
    "id": "8256cfb4-17e6-432c-a469-6aedafb16cd5",
    "etag": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
}

新しい送信先にデータをアクティブにする

すべての接続とデータフローを作成したら、プロファイルデータをストリーミングプラットフォームに対してアクティブ化できます。 この手順では、送信先に送信するセグメントとプロファイル属性を選択し、スケジュールを設定して送信先にデータを送信できます。
新しい宛先に対してセグメントをアクティブ化するには、次の例のようなJSON PATCH操作を実行する必要があります。 1回の呼び出しで複数のセグメントとプロファイル属性をアクティブ化できます。 JSON PATCHの詳細については、 RFC仕様を参照してください
API形式
PATCH /flows

リクエスト
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: {SANDBOX_NAME}' \
--header 'If-Match: "{ETAG}"' \
--data-raw '[
    {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/segmentSelectors/selectors/-",
        "value": {
            "type": "PLATFORM_SEGMENT",
            "value": {
                "name": "Name of the segment that you are activating",
                "description": "Description of the segment that you are activating",
                "id": "{SEGMENT_ID}"
            }
        }
    },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    },
        },
        {
        "op": "add",
        "path": "/transformations/0/params/profileSelectors/selectors/-",
        "value": {
            "type": "JSON_PATH",
            "value": {
                "operator": "EXISTS",
                "path": "{PROFILE_ATTRIBUTE}"
            }
        }
    }
]

  • {DATAFLOW_ID} : 前の手順で取得したデータフローを使用します。
  • {ETAG} : 前の手順で取得したetagを使用します。
  • {SEGMENT_ID} : この宛先にエクスポートするセグメントIDを指定します。 アクティブ化するセグメントのセグメントIDを取得するには、https://www.adobe.io/apis/experienceplatform/home/api-reference.html#/にアクセスし、左側のナビゲーションメニューで Segmentation Service API (Segmentation Service API GET /segment/jobs )を選択して、操作を探します。
  • {PROFILE_ATTRIBUTE} : 例えば、 personalEmail.address または person.lastName
応答
202 OK応答を探します。 応答本文は返されません。 リクエストが正しいことを検証するには、次の手順「データフローを検証する」を参照してください。

データフローの検証

このチュートリアルの最後の手順として、セグメントとプロファイル属性が実際にデータフローに正しくマッピングされていることを検証する必要があります。
これを検証するには、次のGETリクエストを実行します。
API形式
GET /flows

リクエスト
curl --location --request PATCH 'https://platform.adobe.io/data/foundation/flowservice/flows/{DATAFLOW_ID}' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--header 'x-sandbox-name: prod' \
--header 'If-Match: "{ETAG}"' 

  • {DATAFLOW_ID} : 前の手順のデータフローを使用します。
  • {ETAG} : 前の手順のetagを使用します。
応答
返される応答には、前の手順で送信したセグメントとプロファイル属性を transformations パラメーターに含める必要があります。 応答内のサンプル transformations パラメーターは次のようになります。
"transformations": [
    {
        "name": "GeneralTransform",
        "params": {
            "profileSelectors": {
                        "selectors": [
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "personalEmail.address",
                                    "operator": "EXISTS"
                                }
                            },
                            {
                                "type": "JSON_PATH",
                                "value": {
                                    "path": "person.lastname",
                                    "operator": "EXISTS"
                                }
                            }
                        ]
                    },
            "segmentSelectors": {
                "selectors": [
                    {
                        "type": "PLATFORM_SEGMENT",
                        "value": {
                            "name": "Men over 50",
                            "description": "",
                            "id": "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02"
                        }
                    }
                ]
            }
        }
    }
],

書き出されたデータ
手順「新しい宛先にデータを アクティブ化する 」のプロファイル属性とセグメントに加えて、AWS KinesisとAzureイベントハブにエクスポートされたデータには、IDマップに関する情報も含まれます。 これは、書き出されたプロファイルのID( ECID 、モバイルID、Google ID、電子メールアドレスなど)を表します。 以下の例を参照してください。
{
  "person": {
    "email": "yourstruly@adobe.con"
  },
  "segmentMembership": {
    "ups": {
      "72ddd79b-6b0a-4e97-a8d2-112ccd81bd02": {
        "lastQualificationTime": "2020-03-03T21:24:39Z",
        "status": "exited"
      },
      "7841ba61-23c1-4bb3-a495-00d695fe1e93": {
        "lastQualificationTime": "2020-03-04T23:37:33Z",
        "status": "existing"
      }
    }
  },
  "identityMap": {
    "ecid": [
      {
        "id": "14575006536349286404619648085736425115"
      },
      {
        "id": "66478888669296734530114754794777368480"
      }
    ],
    "email_lc_sha256": [
      {
        "id": "655332b5fa2aea4498bf7a290cff017cb4"
      },
      {
        "id": "66baf76ef9de8b42df8903f00e0e3dc0b7"
      }
    ]
  }
}

次の手順

このチュートリアルに従うと、Real-time CDPを優先ストリーミング先の1つに接続し、それぞれの宛先に対するデータ・フローを設定できます。 これで、送信データを、顧客分析や実行する他の任意のデータ操作の送信先で使用できるようになりました。 詳しくは、次のページを参照してください。