Flow Service API を使用した CRM ソースのデータフローの作成
このチュートリアルでは、CRM ソースからデータを取得し、Flow Service API を使用してExperience Platformに取り込む手順を説明します。
- データフローを作成するには、CRM ソースとの有効なベース接続 ID が必要となります。 この ID がない場合は、ベース接続を作成できる CRM ソースのリストについて ソースの概要を参照してください。
- Experience Platformでデータを取り込むには、すべてのテーブルベースのバッチソースのタイムゾーンを UTC に設定する必要があります。
はじめに
このチュートリアルでは、Adobe Experience Platform の次のコンポーネントについて十分に理解していることを前提にしています。
-
Experience Data Model (XDM) System：Experience Platform が顧客体験データを整理するための標準的なフレームワーク。
- スキーマ構成の基本：スキーマ構成の主要な原則やベストプラクティスなど、XDM スキーマの基本的な構成要素について説明します。
- スキーマレジストリ開発者ガイドには、Schema Registry API の呼び出しを正常に実行するために知っておくべき重要な情報が含まれています。これには、
{TENANT_ID}、「コンテナ」の概念、リクエストを行うのに必要なヘッダー（Accept ヘッダーと使用可能な値には特に注意を払う）が含まれます。
-
Catalog Service：カタログは、 Experience Platform 内のデータの位置と系統を記録するシステムです。
-
Batch ingestion：Batch Ingestion API を使用すると、データをバッチファイルとして Experience Platform に取り込むことができます。
-
サンドボックス: Experience Platformには、1 つのExperience Platform インスタンスを別々の仮想環境に分割し、デジタルエクスペリエンスアプリケーションの開発と発展に役立つ仮想サンドボックスが用意されています。
Experience Platform API の使用
Experience Platform API を正常に呼び出す方法について詳しくは、Experience Platform API の概要を参照してください。
ソース接続の作成 source
Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
ソース接続を作成するには、データ形式属性の列挙値も定義する必要があります。
ファイルベースのコネクタには、次の列挙値を使用します。
delimitedjsonparquetすべてのテーブルベースのコネクタで、値をtabularに設定します。
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": "Salesforce source connection",
"baseConnectionId": "4cb0c374-d3bb-4557-b139-5712880adc55",
"description": "Salesforce source connection",
"data": {
"format": "tabular",
},
"params": {
"tableName": "Accounts",
"columns": [
{
"name": "first_name",
"type": "string",
"xdm": {
"type": "String"
}
},
{
"name": "last_name",
"type": "string",
"xdm": {
"type": "String"
}
},
{
"name": "email",
"type": "string",
"xdm": {
"type": "String"
}
}
]
},
"connectionSpec": {
"id": "ccfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"version": "1.0"
}
}'
baseConnectionIdparams.pathconnectionSpec.id応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "9a603322-19d2-4de9-89c6-c98bd54eb184"
"etag": "\"4a00038b-0000-0200-0000-5ebc47fd0000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータをExperience Platformで使用するには、必要に応じてターゲットスキーマを作成してソースデータを構造化する必要があります。 次に、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットが作成されます。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成
ターゲット接続は、取り込まれたデータが取り込まれる宛先への接続を表します。 ターゲット接続を作成するには、データレイクに関連付けられた固定接続仕様 ID を提供する必要があります。この接続仕様 ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。
これで、ターゲットスキーマとターゲットデータセットの一意の識別子、およびデータレイクに対する接続仕様 ID が得られました。 Flow Service API を使用すると、受信ソースデータを格納するデータセットと共にこれらの識別子を指定することで、ターゲット接続を作成できます。
API 形式
POST /targetConnections
リクエスト
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": "Salesforce target connection",
"description": "Salesforce target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/417a33eg81a221bd10495920574gfa2d",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "5c8c3c555033b814b69f947f"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
data.schema.id$id。data.schema.versionapplication/vnd.adobe.xed-full+json;version=1 に設定する必要があります。params.dataSetIdconnectionSpec.idc604ff05-7f1a-43c0-8e18-33bf874cb11c です。{
"id": "4ee890c7-519c-4291-bd20-d64186b62da8",
"etag": "\"2a007aa8-0000-0200-0000-5e597aaf0000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。
マッピングセットを作成するには、Data Prep API の mappingSets エンドポイントに POST リクエストを実行し、その際にターゲット XDM スキーマ $id および作成するマッピングセットの詳細を指定します。
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/417a33eg81a221bd10495920574gfa2d",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "first_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "last_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "personalEmail.address",
"sourceAttribute": "email",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchema応答
リクエストが成功した場合は、一意の ID（id）を含む、新しく作成されたマッピングの詳細が返されます。この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "500a9b747fcf4908a21917d49bd61780",
"version": 0,
"createdDate": 1591043336298,
"modifiedDate": 1591043336298,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
データフロー仕様の取得 specs
データフローは、ソースからデータを収集し、それらをExperience Platformに取り込む役割を果たします。 データフローを作成するには、まずは CRM データの収集を担うデータフロー仕様を取得する必要があります。
API 形式
GET /flowSpecs?property=name=="CRMToAEP"
リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CRMToAEP%22' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
リクエストが成功した場合は、ソースからExperience Platformにデータを取り込む必要があるデータフローの仕様の詳細が返されます。 応答には、新しいデータフローを作成するために必要な、一意のフロー仕様 id が含まれます。
| code language-json |
|---|
|
データフローの作成
CRM データを収集するための最後の手順は、データフローを作成することです。現時点で、次の必要な値の準備ができています。
データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。ペイロードに前述の値を提供しながら 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": "Salesforce dataflow",
"description": "Salesforce dataflow",
"flowSpec": {
"id": "9753525b-82c7-4dce-8a9b-5ccfce2b9876",
"version": "1.0"
},
"sourceConnectionIds": [
"9a603322-19d2-4de9-89c6-c98bd54eb184"
],
"targetConnectionIds": [
"4ee890c7-519c-4291-bd20-d64186b62da8"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "updatedAt",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "500a9b747fcf4908a21917d49bd61780",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1567411548",
"frequency":"minute",
"interval":"30"
}
}'
flowSpec.idsourceConnectionIdstargetConnectionIdstransformations.params.mappingIdtransformations.params.deltaColumdeltaColumn でサポートされている形式は yyyy-MM-dd HH:mm:ss です。Microsoft Dynamics を使用している場合、 deltaColumn でサポートされている形式は yyyy-MM-ddTHH:mm:ssZ です。transformations.params.mappingIdscheduleParams.startTimescheduleParams.frequencyonce、minute、hour、day、week です。scheduleParams.intervalインターバルは 2 つの連続したフロー実行の間隔を指定します。インターバルの値はゼロ以外の整数にしてください。各頻度で許容される最小のインターバル値は次のとおりです。
- 1 回：なし
- 分: 15
- 時間: 1
- 日: 1
- 週: 1
応答
リクエストが成功した場合は、新しく作成したデータフローの ID（id）が返されます。
{
"id": "8256cfb4-17e6-432c-a469-6aedafb16cd5"
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。データフローのモニタリング方法について詳しくは、API でのデータフローの監視のチュートリアルを参照してください。
次の手順
このチュートリアルでは、設定したスケジュールに従って CRM システムからデータを収集するソースコネクタを作成しました。 これで、Real-Time Customer Profile や Data Science Workspace などのダウンストリームのExperience Platform サービスで受信データを使用できるようになりました。 詳しくは、次のドキュメントを参照してください。
付録
次の節では、様々な CRM ソースコネクタとその接続仕様をリストに示します。
接続仕様
38ad80fe-8b06-4938-94f4-d4ee80266b07cfc0fee1-7dc0-40ef-b73e-d8b134c436f5