Flow Service APIを使用してLAVA データをストリーミングするソース接続とデータフローを作成します
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- ソース : Experience Platformのソースを使用すると、様々なシステムから簡単にデータを取り込むことができます。 ソースは、データの収集、整理、準備に役立ち、Experience Platformの機能を最大限に活用するのに役立ちます。
- サンドボックス ：サンドボックスを使用すると、本番データに影響を与えることなく、Experience Platformで安全にビルド、テスト、テストを行うことができます。 そうしたテンプレートでは、それぞれ個別の環境を作成して試したり、新しい機能を開発したり、チームと安全に共同作業を行ったりできます。
TIP
このチュートリアルを開始する前に、LAVA ソースコネクタの概要を確認して、すべての前提条件を満たしていることを確認してください。
LAVA パッケージを読み込む
LAVAは、Experience PlatformでLAVAを使用するための推奨フィールドグループ、スキーマ、ID名前空間およびデータセットを含むパッケージを提供します。 これらのパッケージの使用は推奨されますが、必須ではありません。
この節では、これをサンドボックスに読み込み、後の手順で必要なIDを取得する方法について説明します。
API 形式
POST /transfer/pullRequest
リクエスト
次のリクエストは、LAVAのパッケージを読み込みます。
curl -X POST \
'https://platform.adobe.io/data/foundation/exim/transfer/pullRequest' \
-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 '{
"imsOrgId": "1EF71E43679AAD1E0A495C77@AdobeOrg",
"packageId": "416a0c2a32794092aa1a957cbe9a6698"
}'
プロパティ
説明
タイプ
必須
imsOrgIdパッケージのソース組織からのID。
1EF71E43679AAD1E0A495C77@AdobeOrg である必要があります。文字列
○
packageId読み込むパッケージのID。
416a0c2a32794092aa1a957cbe9a6698 である必要があります。文字列
○
応答
応答が成功すると、インポートされた公開パッケージの詳細が返されます。
{
"id": "{ID}",
"version": 0,
"createdDate": 1729658890425,
"modifiedDate": 1729658890425,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}",
"sourceIMSOrgId": "{ORG_ID}",
"targetIMSOrgId": "{TARGET_ID}",
"packageId": "{PACKAGE_ID}",
"status": "PENDING",
"initiatedBy": "{INITIATED_BY}",
"pipelineMessageId": "{MESSAGE_ID}",
"requestType": "PUBLIC"
}
スキーマの取得
パッケージを読み込んだ後、LAVA EventsおよびLAVA Profile スキーマを取得します。
リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas?name=LAVA*' \
-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 'Accept: application/vnd.adobe.xed-id+json'
応答
応答が成功すると、スキーマのリストが返されます。 後の手順で、これらのIDをターゲット XDM スキーマとして使用します。
{
"results": [
...
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/7ff102f217d394e8beff48dcc2c27baae14e28e210d36492",
"meta:altId": "_{TENANT_ID}.schemas.7ff102f217d394e8beff48dcc2c27baae14e28e210d36492",
"version": "1.4",
"title": "LAVA Events"
},
{
"$id": "https://ns.adobe.com/{TENANT_ID}/schemas/991bed7f1d94ccf47bd392bc345ee51e7e0bd19b1de3dbff",
"meta:altId": "_{TENANT_ID}.schemas.991bed7f1d94ccf47bd392bc345ee51e7e0bd19b1de3dbff",
"version": "1.2",
"title": "LAVA Profile"
},
//...
]
}
データセットの取得
次に、次の呼び出しを使用してデータセット IDを取得します。
リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/catalog/dataSets?name=LAVA*' \
-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 'Accept: application/json'
応答
{
"6920eb494131bfcc10305302": {
"id": "6920eb494131bfcc10305302",
"name": "LAVA Member Profiles",
//...
},
"6920eb7565bd3ed93a35cd0e": {
"id": "6920eb7565bd3ed93a35cd0e",
"name": "LAVA Member Rewards",
//...
},
"6924aecd8d9c85e2d56261e3": {
"id": "6924aecd8d9c85e2d56261e3",
"name": "LAVA Events",
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/7ff102f217d394e8beff48dcc2c27baae14e28e210d36492",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
},
//...
}
}
Flow Service APIを使用してLAVAをExperience Platformに接続します
次のチュートリアルでは、LAVA ソース接続を作成し、Flow Service APIを使用してLAVA データをExperience Platformに取り込むためのデータフローを作成する手順について説明します。
ソース接続の作成 source-connection
ソースの接続仕様ID、名前と説明などの詳細、データの形式を指定しながら、Flow Service APIにPOST リクエストを実行して、ソース接続を作成します。
API 形式
POST /sourceConnections
リクエスト
次のリクエストは、LAVA のソース接続を作成します。
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 a Streaming SDK source",
"description": "Streaming Source Connection for a Streaming SDK source",
"connectionSpec": {
"id": "232dfabe-27aa-41c0-a7cf-9961661dc68b",
"version": "1.0"
},
"data": {
"format": "json"
}
}'
プロパティ
説明
nameソース接続の名前。 ソース接続の情報を検索する際に使用できるので、ソース接続の名前はわかりやすいものにしてください。
description含めることでソース接続に関する詳細情報を提供できるオプションの値です。
connectionSpec.idソースに対応する接続仕様の ID。 LAVAには
232dfabe-27aa-41c0-a7cf-9961661dc68bである必要があります。data.format取り込む LAVA データの形式。 現在、サポートされているデータ形式は
json のみです。応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}
ターゲット XDM スキーマの作成 target-schema
IMPORTANT
ターゲット XDM スキーマが含まれているため、LAVA パッケージをインポートした場合は、これをスキップします。
ソースデータをExperience Platformで使用するには、必要に応じてソースデータを構造化するターゲットスキーマを作成する必要があります。 その後、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットを作成します。 複数のLAVA データセットを使用している場合（例：メンバー残高とチケットスキャンイベントの両方）、複数のターゲット XDM スキーマが必要な場合や、複数のターゲット XDM スキーマが必要な場合があります。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
IMPORTANT
既にLAVA パッケージをインポートしている場合、パッケージがターゲット XDM データセットを提供するため、この手順をスキップできます。 ただし、複数のLAVA データセット（メンバー残高やチケットスキャンイベント用など）が必要な場合は、必要に応じて追加のターゲットデータセットを作成する必要があります。
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成 target-connection
ターゲット接続は、取り込んだデータを格納する宛先への接続を表します。 ターゲット接続を作成するには、データレイクに対応する固定接続仕様IDを指定する必要があります。 この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。
ターゲットスキーマ、ターゲットデータセット、データレイクの接続仕様IDに対する一意の識別子が作成されました。 これらの識別子を使用すると、受信ソースデータを格納するデータセットを指定する Flow Service API を使用して、ターゲット接続を作成することができます。
API 形式
POST /targetConnections
リクエスト
次のリクエストは、LAVA のターゲット接続を作成します。
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 a Streaming SDK source",
"description": "Streaming Target Connection for a Streaming SDK source",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json",
"schema": {
"id": "{TARGET_XDM_SCHEMA}",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "{TARGET_DATASET}"
}
}'
プロパティ
説明
nameターゲット接続の名前。 ターゲット接続の情報を検索に使用できるように、ターゲット接続はわかりやすい名前にしてください。
descriptionターゲット接続に関する詳細を提供するために含めることができるオプションの値です。
connectionSpec.idデータレイクに対応する接続仕様ID。 この修正済み ID は
c604ff05-7f1a-43c0-8e18-33bf874cb11c です。data.formatExperience Platformに取り込むLAVA データのフォーマット。
params.dataSetId前の手順で取得したターゲットデータセット ID。
応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。 この ID は、後の手順で必要になります。
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。 これは、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep APIに対してPOST リクエストを実行することで実現します。
LAVAが提供するスキーマを利用する場合は、次のマッピングをお勧めします。
メンバープロファイル
| code language-json |
|---|
|
メンバー残高
| code language-json |
|---|
|
組み合わせイベント
| code language-json |
|---|
|
チケットスキャンイベント
| code language-json |
|---|
|
トランザクションイベント
| code language-json |
|---|
|
元帳イベント
| code language-json |
|---|
|
API 形式
POST /conversion/mappingSets
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/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": "{TARGET_XDM_SCHEMA}",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "_{TENANT_ID}.lavaId",
"sourceAttribute": "lavaId",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "_{TENANT_ID}.balances",
"sourceAttribute": "balances",
"identity": false,
"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}"
}
フローの作成 flow
LAVAからExperience 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 a Streaming SDK source",
"description": "Streaming Dataflow for a Streaming SDK source",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": 0
}
}
]
}'
プロパティ
説明
nameデータフローの名前。 データフローの情報を検索する際に使用できるので、データフローはわかりやすい名前にしてください。
descriptionデータフローに関する詳細情報を提供するために含めることができるオプション値。
flowSpec.idデータフローの作成に必要なフロー仕様 ID。 この修正済み ID は
e77fde5a-22a8-11ed-861d-0242ac120002 です。flowSpec.versionフロー仕様 ID の対応するバージョン。 この値のデフォルトは
1.0 です。sourceConnectionIds以前の手順で生成されたソース接続 ID。
targetConnectionIds以前の手順で生成されたターゲット接続 ID。
transformationsこのプロパティには、データに適用する必要があるさまざまな変換が含まれています。 このプロパティは、XDMに準拠していないデータをExperience Platformに取り込む場合に必要です。
transformations.name変換に割り当てられた名前。
transformations.params.mappingId以前の手順で生成されたマッピング ID。
transformations.params.mappingVersionマッピング ID の対応するバージョン。 この値のデフォルトは
0 です。応答
正常な応答は、新しく作成したデータフローの ID（id）を返します。 この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}
ストリーミングエンドポイント URLの取得
データフローを作成したら、ストリーミングエンドポイント URLを取得できるようになりました。 このエンドポイント URLを使用して、ソースをWebhookに登録し、ソースがExperience Platformと通信できるようにします。
ストリーミングエンドポイント URLを取得するには、/flows エンドポイントにGET リクエストを行い、データフローのIDを指定します。
API 形式
GET /flows/{FLOW_ID}
リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flows/993f908f-3342-4d9c-9f3c-5aa9a189ca1a' \
-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}'
応答
応答が成功すると、inletUrlとしてマークされたエンドポイント URLを含む、データフローに関する情報が返されます。
{
"items": [
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"createdAt": 1669238699119,
"updatedAt": 1669238699119,
"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 a Streaming SDK source",
"description": "Streaming Dataflow for a Streaming SDK source",
"flowSpec": {
"id": "e77fde5a-22a8-11ed-861d-0242ac120002",
"version": "1.0"
},
"state": "enabled",
"version": "\"a1011225-0000-0200-0000-63c78ae60000\"",
"etag": "\"a1011225-0000-0200-0000-63c78ae60000\"",
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"inheritedAttributes": {
"properties": {
"isSourceFlow": true
},
"sourceConnections": [
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"connectionSpec": {
"id": "bdb5b792-451b-42de-acf8-15f3195821de",
"version": "1.0"
}
}
],
"targetConnections": [
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}
]
},
"options": {
"errorDiagnosticsEnabled": true,
"inletUrl": "https://dcs-int.adobedc.net/collection/ab65636c31778fb0455c439ffb48a5433a34d443f4c83c4b5beda9c5688797c5"
},
"transformations": [
{
"name": "Mapping",
"params": {
"mappingVersion": 0,
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366"
}
}
],
"runs": "/runs?property=flowId==e1514b79-f031-43b4-aab5-381a42f86ad4",
"providerRefId": "c9809ab5-71e0-4c7f-887b-61c95e4e20b5",
"lastOperation": {
"started": 0,
"updated": 0,
"operation": "enable"
}
}
]
}
LAVAをWebhookと統合する
LAVA コンソール で、Resources > Data Exportに移動します。
LAVA コンソールの「データ書き出し」メニューの
Create New Export を選択します。 宛先タイプとして Adobe Source Connector を選択し、送信するソースデータを選択します。 ストリーミングエンドポイント URLとデータフローIDを使用します。
LAVA コンソールの「新規書き出しを作成」画面の
付録
以下の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。 完全なAPIの例については、APIを使用したソースデータフローの監視に関するガイドを参照してください。
データフローの更新
データフローのIDを指定しながら、Flow Service APIの/flows エンドポイントに対してPATCH リクエストを行うことで、データフローの名前や説明、実行スケジュールおよび関連するマッピングセットなどの詳細を更新します。 PATCH リクエストを行う場合は、If-Match ヘッダーにデータフローの一意のetagを指定する必要があります。 完全なAPIの例については、APIを使用したソースデータフローの更新に関するガイドを参照してください。
アカウントを更新
ベース接続IDをクエリパラメーターとして指定しながら、Flow Service APIに対してPATCH リクエストを実行して、ソースアカウントの名前、説明、資格情報を更新します。 PATCH リクエストを行う場合、If-Match ヘッダーにソースアカウントの一意のetagを指定する必要があります。 完全なAPIの例については、APIを使用したソースアカウントの更新に関するガイドを参照してください。
データフローの削除
クエリパラメーターの一部として削除するデータフローのIDを指定しながら、Flow Service APIに対してDELETE リクエストを実行して、データフローを削除します。 完全なAPIの例については、APIを使用したデータフローの削除に関するガイドを参照してください。
アカウントを削除
削除するアカウントのベース接続IDを指定しながら、Flow Service APIに対してDELETE リクエストを実行して、アカウントを削除します。 完全なAPIの例については、APIを使用したソースアカウントの削除に関するガイドを参照してください。
recommendation-more-help
experience-platform-help-sources