Flow Service APIを使用してHTTP API ストリーミング接続を作成します
Flow Serviceは、Adobe Experience Platform内の様々なソースから顧客データを収集し、一元化するために使用されます。 このサービスは、ユーザーインターフェイスとRESTful APIを提供し、サポートされているすべてのソースを接続できます。
このチュートリアルでは、Flow Service APIを使用して、Flow Service APIを使用してストリーミング接続を作成する手順を説明します。
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- Experience Data Model (XDM): Experience Platformがエクスペリエンスデータを整理するための標準化されたフレームワークです。
- Real-Time Customer Profile:複数のソースからの集約データに基づいて、統合された消費者プロファイルをリアルタイムで提供します。
さらに、ストリーミング接続を作成するには、ターゲット XDM スキーマとデータセットが必要です。 これらの作成方法については、 ストリーミングレコードデータ に関するチュートリアルまたは ストリーミング時系列データ に関するチュートリアルをご覧ください。
Experience Platform APIの使用
Experience Platform APIの呼び出しを正常に行う方法について詳しくは、Experience Platform APIの概要に関するガイドを参照してください。
ベース接続の作成
ベース接続は、ソースを指定し、フローをストリーミング取得APIと互換性を持たせるために必要な情報を含みます。 ベース接続を作成する場合は、認証済み接続と非認証済み接続を作成するオプションがあります。
未認証の接続
未認証の接続は、Experience Platformにデータをストリーミングする場合に作成できる標準的なストリーミング接続です。
認証されていないベース接続を作成するには、接続の名前、データタイプ、およびHTTP API接続仕様IDを指定しながら、/connections エンドポイントにPOST リクエストを行います。 このIDはbc7b00d6-623a-4dfc-9fdb-f1240aeadaebです。
API 形式
POST /flowservice/connections
リクエスト
次のリクエストは、HTTP APIのベース接続を作成します。
| code language-shell |
|---|
|
| code language-shell |
|---|
|
namedescriptionconnectionSpec.idbc7b00d6-623a-4dfc-9fdb-f1240aeadaebです。auth.params.dataTypexdmとrawです。auth.params.name応答
応答が成功すると、HTTP ステータス 201が、新しく作成された接続の詳細(一意の識別子(id)を含む)で返されます。
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
idid。etag認証済み接続
認証済み接続は、信頼できるソースと信頼できないソースからのレコードを区別する必要がある場合に使用する必要があります。 個人情報(PII)を使用してデータを送信する場合は、情報をExperience Platformにストリーミングする際に、認証済みの接続を作成する必要があります。
認証されたベース接続を作成するには、リクエストにauthenticationRequired パラメーターを含め、その値をtrueとして指定する必要があります。 この手順では、認証済みのベース接続のソース IDを指定することもできます。 このパラメーターはオプションで、指定されていない場合はname属性と同じ値を使用します。
API 形式
POST /flowservice/connections
リクエスト
次のリクエストは、HTTP API用に認証されたベース接続を作成します。
| code language-shell |
|---|
|
| code language-shell |
|---|
|
auth.params.sourceIdname属性と同じ値を使用します。auth.params.authenticationRequiredauthenticationRequiredがtrueに設定されている場合、ストリーミング接続に認証を指定する必要があります。 authenticationRequiredがfalseに設定されている場合、認証は必要ありません。応答
応答が成功すると、HTTP ステータス 201が、新しく作成された接続の詳細(一意の識別子(id)を含む)で返されます。
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
ストリーミングエンドポイント URLの取得
ベース接続を作成したら、ストリーミングエンドポイント URLを取得できるようになりました。
API 形式
GET /flowservice/connections/{BASE_CONNECTION_ID}
{BASE_CONNECTION_ID}id 値。リクエスト
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{BASE_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": [
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"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": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "ACME Streaming Connection XDM Data",
"inletUrl": "https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"authenticationRequired": false,
"inletId": "667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"dataType": "xdm",
"name": "ACME Streaming Connection XDM Data"
}
},
"version": "\"f50185ed-0000-0200-0000-637e8fad0000\"",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
]
}
ソース接続の作成 source
ソース接続を作成するには、ベース接続IDを指定しながら、/sourceConnections エンドポイントにPOST リクエストを行います。
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": "ACME Streaming Source Connection for Customer Data",
"description": "A streaming source connection for ACME XDM Customer Data",
"baseConnectionId": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
応答
応答が成功すると、HTTP ステータス 201が、新しく作成されたソース接続の詳細(一意の識別子(id)を含む)で返されます。
{
"id": "34ece231-294d-416c-ad2a-5a5dfb2bc69f",
"etag": "\"d505125b-0000-0200-0000-637eb7790000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータをExperience Platformで使用するには、必要に応じてソースデータを構造化するターゲットスキーマを作成する必要があります。 その後、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットを作成します。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成 target
ターゲット接続は、取り込まれたデータが取り込まれる宛先への接続を表します。 ターゲット接続を作成するには、ターゲット データセットとターゲット XDM スキーマにIDを指定しながら、/targetConnectionsにPOST リクエストを行います。 この手順では、データレイク接続仕様IDも指定する必要があります。 このIDはc604ff05-7f1a-43c0-8e18-33bf874cb11cです。
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": "ACME Streaming Target Connection",
"description": "ACME Streaming Target Connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "637eb7fadc8a211b6312b65b"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
応答
応答が成功すると、HTTP ステータス 201が、新しく作成されたターゲット接続の詳細(一意の識別子(id)を含む)で返されます。
{
"id": "07f2f6ff-1da5-4704-916a-c615b873cba9",
"etag": "\"340680f7-0000-0200-0000-637eb8730000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。
マッピングセットを作成するには、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": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"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$id。応答
応答が成功すると、一意の ID(id)など、新しく作成されたマッピングの詳細が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "79a623960d3f4969835c9e00dc90c8df",
"version": 0,
"createdDate": 1669249214031,
"modifiedDate": 1669249214031,
"createdBy": "acme@AdobeID",
"modifiedBy": "acme@AdobeID"
}
データフローの作成
ソース接続とターゲット接続を作成したら、データフローを作成できます。 データフローは、ソースからのデータのスケジュール設定と収集を担当します。 /flows エンドポイントに対してPOST リクエストを実行することで、データフローを作成できます。
API 形式
POST /flows
リクエスト
次のリクエストは、XDM データのストリーミングデータフローを作成します。
| code language-shell |
|---|
|
次のリクエストは、生データのストリーミングデータフローを作成します。
変換を使用してデータフローを作成する場合、name パラメーターを変更できません。 この値は常にMappingに設定する必要があります。
| code language-shell |
|---|
|
namedescriptionflowSpec.idc1a19761-d2c7-4702-b9fa-fe91f0613e81を使用する必要があります。 変換なしでデータフローを作成するには、d8a6f005-7eaf-4153-983e-e8574508b877を使用します。sourceConnectionIdstargetConnectionIdstransformations.params.mappingId応答
応答が成功すると、HTTP ステータス 201が、一意の識別子(id)を含め、新しく作成したデータフローの詳細とともに返されます。
{
"id": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"etag": "\"dc0459ae-0000-0200-0000-637ebaec0000\""
}
Experience Platformに取り込むデータの投稿 ingest-data
フローを作成したら、以前に作成したストリーミングエンドポイントにJSON メッセージを送信できます。
API 形式
POST /collection/{INLET_URL}
{INLET_URL}/connections エンドポイントにGET リクエストを行います。{FLOW_ID}リクエスト
| code language-shell |
|---|
|
生データを送信する場合、フローIDをクエリパラメーターまたはHTTP ヘッダーの一部として指定できます。 次の例では、HTTP ヘッダーとしてフローIDを指定します。
| code language-shell |
|---|
|
生データを送信する場合、フローIDをクエリパラメーターまたはHTTP ヘッダーとして指定できます。 次の例では、クエリパラメーターとしてフローIDを指定します。
| code language-shell |
|---|
|
応答
応答が成功すると、HTTP ステータス 200が、新しく取り込まれた情報の詳細とともに返されます。
{
"inletId": "{BASE_CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507
}
{BASE_CONNECTION_ID}xactionIdreceivedTimeMs次の手順
このチュートリアルでは、ストリーミング HTTP接続を作成し、ストリーミングエンドポイントを使用してExperience Platformにデータを取り込めるようにしました。 UIでストリーミング接続を作成する手順については、 ストリーミング接続の作成チュートリアル を参照してください。
Experience 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"
}
}