フローサービスは、Adobe Experience Platform内の様々な異なるソースから顧客データを収集し、一元化するために使用されます。 このサービスは、ユーザーインターフェイスと RESTful API を提供し、サポートされるすべてのソースから接続できます。
このチュートリアルでは、 Flow Service API を参照して、Flow Service API を使用してストリーミング接続を作成する手順を説明します。
このガイドでは、Adobe Experience Platform の次のコンポーネントに関する十分な知識が必要です。
さらに、ストリーミング接続を作成するには、ターゲット XDM スキーマとデータセットが必要です。 これらの作成方法については、次のチュートリアルを参照してください。 ストリーミングレコードデータ または 時系列データのストリーミング.
以下の節では、ストリーミング取得 API の呼び出しを正常におこなうために知っておく必要がある追加情報を示します。
ここでは、リクエストの形式を説明するために API 呼び出しの例を示します。これには、パス、必須ヘッダー、適切な形式のリクエストペイロードが含まれます。また、API レスポンスで返されるサンプル JSON も示されています。ドキュメントで使用される API 呼び出し例の表記について詳しくは、 トラブルシューテングガイドのAPI 呼び出し例の読み方に関する節を参照してくださいExperience Platform。
Platform API を呼び出すには、まず認証チュートリアルを完了する必要があります。次に示すように、すべての Experience Platform API 呼び出しに必要な各ヘッダーの値は認証チュートリアルで説明されています。
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
Flow Serviceに属するリソースを含む、Experience Platform のすべてのリソースは、特定の仮想サンドボックスに分離されます。Platform API へのすべてのリクエストには、操作がおこなわれるサンドボックスの名前を指定するヘッダーが必要です。
{SANDBOX_NAME}
Platform のサンドボックスについて詳しくは、サンドボックスの概要に関するドキュメントを参照してください。
ペイロード(POST、PUT、PATCH)を含むすべてのリクエストには、以下のような追加ヘッダーが必要です。
ベース接続ではソースを指定します。また、ベース接続には、フローをストリーミング取得 API と互換性のあるものにするために必要な情報が含まれています。 ベース接続を作成する場合、非認証接続と認証済み接続を作成するオプションがあります。
非認証接続は、データを Platform にストリーミングする際に作成できる標準のストリーミング接続です。
API 形式
POST /flowservice/connections
リクエスト
ストリーミング接続を作成するには、プロバイダー ID と接続仕様 ID をPOSTリクエストの一部として指定する必要があります。 プロバイダー ID はです。 521eee4d-8cbe-4906-bb48-fb6bd4450033
接続仕様 ID は bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Sample streaming connection",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection",
"dataType": "xdm",
"name": "Sample connection"
}
}
}'
プロパティ | 説明 |
---|---|
auth.params.sourceId |
作成するストリーミング接続の ID。 |
auth.params.dataType |
ストリーミング接続のデータタイプです。 この値は、 xdm . |
auth.params.name |
作成するストリーミング接続の名前。 |
connectionSpec.id |
接続の仕様 id (ストリーミング接続用) |
応答
正常な応答は、HTTP ステータス 201 と、新しく作成された接続の詳細 ( 一意の識別子 (id
) をクリックします。
{
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
プロパティ | 説明 |
---|---|
id |
新しく作成した接続の id 。ここでは、{CONNECTION_ID} を指します。 |
etag |
接続に割り当てられ、接続のリビジョンを指定する識別子。 |
信頼できるソースと信頼できないソースからのレコードを区別する必要がある場合は、認証済みの接続を使用する必要があります。 個人情報 (PII) を含む情報を送信するユーザーは、Platform に情報をストリーミングする際に、認証済みの接続を作成する必要があります。
API 形式
POST /flowservice/connections
リクエスト
ストリーミング接続を作成するには、プロバイダー ID と接続仕様 ID をPOSTリクエストの一部として指定する必要があります。 プロバイダー ID はです。 521eee4d-8cbe-4906-bb48-fb6bd4450033
接続仕様 ID は bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Sample streaming connection",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection",
"dataType": "xdm",
"name": "Sample connection",
"authenticationRequired": true
}
}
}
プロパティ | 説明 |
---|---|
auth.params.sourceId |
作成するストリーミング接続の ID。 |
auth.params.dataType |
ストリーミング接続のデータタイプです。 この値は、 xdm . |
auth.params.name |
作成するストリーミング接続の名前。 |
auth.params.authenticationRequired |
作成したストリーミング接続を指定するパラメーター |
connectionSpec.id |
接続の仕様 id (ストリーミング接続用) |
応答
正常な応答は、HTTP ステータス 201 と、新しく作成された接続の詳細 ( 一意の識別子 (id
) をクリックします。
{
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"etag": "\"a500e689-0000-0200-0000-5e31df730000\""
}
プロパティ | 説明 |
---|---|
id |
新しく作成した接続の id 。ここでは、{CONNECTION_ID} を指します。 |
etag |
接続に割り当てられ、接続のリビジョンを指定する識別子。 |
ベース接続が作成されたら、ストリーミングエンドポイント URL を取得できます。
API 形式
GET /flowservice/connections/{CONNECTION_ID}
パラメーター | 説明 |
---|---|
{CONNECTION_ID} |
以前に作成した接続の id 値。 |
リクエスト
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{CONNECTION_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
応答
リクエストが成功した場合は、リクエストした接続についての詳細情報と HTTP ステータス 200 が返されます。ストリーミングエンドポイント URL は、接続を使用して自動的に作成され、 inletUrl
の値です。
{
"items": [
{
"createdAt": 1583971856947,
"updatedAt": 1583971856947,
"createdBy": "{API_KEY}",
"updatedBy": "{API_KEY}",
"createdClient": "{USER_ID}",
"updatedClient": "{USER_ID}",
"id": "77a05521-91d6-451c-a055-2191d6851c34",
"name": "Another new sample connection (Experience Event)",
"description": "Sample description",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Sample connection (ExperienceEvent)",
"inletUrl": "https://dcs.adobedc.net/collection/a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
"inletId": "a868e1ce678a911ef1482b083329af3cafa4bafdc781285f25911eaae9e00eb2",
"dataType": "xdm",
"name": "Sample connection (ExperienceEvent)"
}
},
"version": "\"56008aee-0000-0200-0000-5e697e150000\"",
"etag": "\"56008aee-0000-0200-0000-5e697e150000\""
}
]
}
ベース接続を作成したら、ソース接続を作成する必要があります。 ソース接続を作成する場合、 id
作成したベース接続の値。
API 形式
POST /flowservice/sourceConnections
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Sample source connection",
"description": "Sample source connection description",
"baseConnectionId": "{BASE_CONNECTION_ID}",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
応答
正常な応答は、HTTP ステータス 201 と、新しく作成されたソース接続の詳細 ( 一意の識別子 (id
) をクリックします。
{
"id": "63070871-ec3f-4cb5-af47-cf7abb25e8bb",
"etag": "\"28000b90-0000-0200-0000-6091b0150000\""
}
ソースデータを Platform で使用するには、必要に応じてターゲットスキーマを作成してソースデータを構造化する必要があります。 次に、ターゲットスキーマを使用して、ソースデータが含まれる Platform データセットを作成します。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続は、取り込まれたデータが取り込まれる宛先への接続を表します。 ターゲット接続を作成するには、データレイクに関連付けられた固定接続仕様 ID を提供する必要があります。この接続仕様 ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c
です。
これで、ターゲットスキーマとターゲットデータセット、およびデータレイクへの接続仕様 ID の一意の識別子が得られました。これらの識別子を使用すると、受信ソースデータを格納するデータセットを指定する Flow Service API を使用して、ターゲット接続を作成することができます。
API 形式
POST /flowservice/targetConnections
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "Sample target connection",
"description": "Sample target connection description",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm"
},
"params": {
"dataSetId": "{DATASET_ID}"
}
}'
応答
正常な応答は、HTTP ステータス 201 と、新しく作成されたターゲット接続の詳細(一意の識別子を含む)を返します。id
) をクリックします。
{
"id": "98a2a72e-a80f-49ae-aaa3-4783cc9404c2",
"etag": "\"0500b73f-0000-0200-0000-6091b0b90000\""
}
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。
マッピングセットを作成するには、Data Prep API の mappingSets
エンドポイントに POST リクエストを実行し、その際にターゲット XDM スキーマ $id
および作成するマッピングセットの詳細を指定します。
API 形式
POST /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": "_{TENANT_ID}.schemas.e45dd983026ce0daec5185cfddd48cbc0509015d880d6186",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"version": 0
}
]
}'
プロパティ | 説明 |
---|---|
xdmSchema |
ターゲット XDM スキーマの $id 。 |
応答
応答が成功すると、一意の ID(id
)など、新しく作成されたマッピングの詳細が返されます。この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "380b032b445a46008e77585e046efe5e",
"version": 0,
"createdDate": 1604960750613,
"modifiedDate": 1604960750613,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
ソース接続とターゲット接続を作成したら、データフローを作成できます。 データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。 データフローを作成するには、 /flows
endpoint.
API 形式
POST /flows
リクエスト
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "HTTP API streaming dataflow",
"description": "HTTP API streaming dataflow",
"flowSpec": {
"id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
"version": "1.0"
},
"sourceConnectionIds": [
"63070871-ec3f-4cb5-af47-cf7abb25e8bb"
],
"targetConnectionIds": [
"98a2a72e-a80f-49ae-aaa3-4783cc9404c2"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "380b032b445a46008e77585e046efe5e",
"mappingVersion": 0
}
}
]
}'
プロパティ | 説明 |
---|---|
flowSpec.id |
のフロー仕様 ID HTTP API. この ID は c1a19761-d2c7-4702-b9fa-fe91f0613e81 です。 |
sourceConnectionIds |
前の手順で取得したソース接続 ID。 |
targetConnectionIds |
前の手順で取得したターゲット接続 ID。 |
transformations.params.mappingId |
前の手順で取得したマッピング ID。 |
応答
正常な応答は、HTTP ステータス 201 と、新しく作成されたデータフローの詳細 ( 一意の識別子 (id
) をクリックします。
{
"id": "ab03bde0-86f2-45c7-b6a5-ad8374f7db1f",
"etag": "\"1200c123-0000-0200-0000-6091b1730000\""
}
このチュートリアルに従って、ストリーミング HTTP 接続を作成し、ストリーミングエンドポイントを使用してデータを Platform に取り込むことができます。 UI でストリーミング接続を作成する手順については、 ストリーミング接続の作成チュートリアル.
データを Platform にストリーミングする方法については、次のチュートリアルをお読みください: 時系列データのストリーミング または ストリーミングレコードデータ.
この節では、API を使用したストリーミング接続の作成に関する補足情報を提供します。
ストリーミング接続で認証が有効になっている場合、クライアントはリクエストに Authorization
ヘッダーを追加する必要があります。
Authorization
ヘッダーがない場合、または無効な/期限切れのアクセストークンが送信された場合は、HTTP 401 Unauthorized と以下のようなレスポンスが返されます。
応答
{
"type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
"status": "401",
"title": "Authorization",
"report": {
"message": "[id] Ims service token is empty"
}
}
これでフローが作成され、以前に作成したストリーミングエンドポイントに JSON メッセージを送信できます。
API 形式
POST /collection/{CONNECTION_ID}
パラメーター | 説明 |
---|---|
{CONNECTION_ID} |
新しく作成されたストリーミング接続の id 値。 |
リクエスト
この例のリクエストは、以前に作成したストリーミングエンドポイントに生データを取り込みます。
curl -X POST https://dcs.adobedc.net/collection/2301a1f761f6d7bf62c5312c535e1076bbc7f14d728e63cdfd37ecbb4344425b \
-H 'Content-Type: application/json' \
-H 'x-adobe-flow-id: 1f086c23-2ea8-4d06-886c-232ea8bd061d' \
-d '{
"name": "Johnson Smith",
"location": {
"city": "Seattle",
"country": "United State of America",
"address": "3692 Main Street"
},
"gender": "Male",
"birthday": {
"year": 1984,
"month": 6,
"day": 9
}
}'
応答
正常な応答は、HTTP ステータス 200 と、新しく取り込んだ情報の詳細を返します。
{
"inletId": "{CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507
}
プロパティ | 説明 |
---|---|
{CONNECTION_ID} |
以前に作成したストリーミング接続の ID。 |
xactionId |
送信したレコードに対してサーバー側で生成された一意の ID です。この IDは、様々なシステムやデバッグを通じて、アドビがこのレコードのライフサイクルを追跡するのに役立ちます。 |
receivedTimeMs |
リクエストが受信された時刻を示すタイムスタンプ(ミリ秒単位のエポックタイム)。 |