のデータフローの作成 OneTrust Integration を使用したソース Flow Service API
次のチュートリアルでは、ソース接続とデータフローを作成し、履歴データとスケジュールされた同意データの両方をから取り込む手順について説明します。 OneTrust Integration を使用してAdobe Experience Platformに Flow Service API.
前提条件
接続する前に OneTrust Integration Platform に接続する場合は、最初にアクセストークンを取得する必要があります。 アクセストークンの検索方法について詳しくは、 OneTrust Integration OAuth 2 ガイド.
システム間の更新トークンはではサポートされていないので、有効期限が切れた後、アクセストークンは自動的に更新されません。 OneTrust. したがって、アクセストークンの有効期限が切れる前に、接続でアクセストークンを必ず更新しておく必要があります。 アクセストークンの設定可能な最大有効期間は 1 年です。 アクセストークンの更新について詳しくは、 OneTrust OAuth 2.0 クライアント資格情報の管理に関するドキュメント.
接続 OneTrust Integration を使用して Platform に Flow Service API
次のチュートリアルでは、 OneTrust Integration ソース接続と、 OneTrust Integration を使用して Platform にデータを送信する Flow Service API.
ベース接続の作成 base-connection
ベース接続は、ソースと Platform 間の情報(ソースの認証資格情報、現在の接続状態、固有のベース接続 ID など)を保持します。ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続 ID を作成するには、 /connections
エンドポイントを OneTrust Integration 認証資格情報をリクエスト本文の一部として使用します。
API 形式
POST /connections
リクエスト
次のリクエストは、OneTrust Integration のベース接続を作成します。
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/connections' \
-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": "ONETRUST base connection",
"description": "ONETRUST base connection to authenticate to Platform",
"connectionSpec": {
"id": "cf16d886-c627-4872-9936-fb08d6cba8cc",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"accessToken": "{ACCESS_TOKEN}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.
auth.params.accessToken
応答
リクエストが成功した場合は、一意の接続識別子(id
)を含む、新しく作成されたベース接続が返されます。この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "622124ca-6d18-47f7-999c-66f599955309",
"etag": "\"2e026443-0000-0200-0000-621f1af80000\""
}
ソースを参照 explore
前の手順で生成したベース接続 ID を使用することで、GET リクエストを実行してファイルとディレクトリを調べることができます。
次の呼び出しを使用して、に取り込むファイルのパスを見つけます。 Platform:
API 形式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。
{BASE_CONNECTION_ID}
objectType=rest
rest
.{OBJECT}
fileType=json
json
は、サポートされている唯一のファイルタイプです。{PREVIEW}
リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/622124ca-6d18-47f7-999c-66f599955309/explore?objectType=rest&object=json&fileType=json&preview=true' \
-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}'
応答
応答が成功すると、クエリされたファイルの構造を返します。
code language-json |
---|
|
ソース接続の作成 source-connection
Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
API 形式
POST /sourceConnections
リクエスト
次のリクエストは、OneTrust Integration のソース接続を作成します。
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": "ONETRUST Source Connection",
"description": "ONETRUST Source Connection",
"baseConnectionId": "622124ca-6d18-47f7-999c-66f599955309",
"connectionSpec": {
"id": "cf16d886-c627-4872-9936-fb08d6cba8cc",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {}
}'
name
description
baseConnectionId
connectionSpec.id
data.format
json
のみです。応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID(id
)が返されます。この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "eb5833d3-230d-4700-80cc-bda396e7af8a",
"etag": "\"da04c07f-0000-0200-0000-621f1afc0000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータを Platform で使用するには、必要に応じてターゲットスキーマを作成してソースデータを構造化する必要があります。 次に、ターゲットスキーマを使用して、ソースデータが含まれる Platform データセットを作成します。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成 target-connection
ターゲット接続は、取り込んだデータの保存先への接続を表します。 ターゲット接続を作成するには、Data Lake に対応する固定接続仕様 ID を指定する必要があります。 この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c
です。
これで、一意の識別子、ターゲットスキーマ、ターゲットデータセット、および Data Lake の接続仕様 ID が用意できました。これらの識別子を使用することで、Flow Service API を使用してターゲット接続を作成し、受信ソースデータを格納するデータセットを指定できます。
API 形式
POST /targetConnections
リクエスト
次のリクエストは、OneTrust Integration のターゲット接続を作成します。
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": "ONETRUST Target Connection",
"description": "ONETRUST Target Connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"dataSetId": "61f6ca3f33978c19486bb463"
}
}'
name
description
connectionSpec.id
c604ff05-7f1a-43c0-8e18-33bf874cb11c
です。data.format
params.dataSetId
応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID(id
)が返されます。この ID は、後の手順で必要になります。
{
"id": "495f761f-310a-4a7b-ae78-5b1152d74b38",
"etag": "\"410a7b0c-0000-0200-0000-621f1afd0000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。これは、 Data Prep API リクエストペイロード内で定義されたデータマッピングを使用して、
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/cfc8cee182e546c1fb35071185524b465e06bf1acb74f30d",
"xdmVersion": "1.0",
"id": null,
"mappings": [{
"sourceType": "ATTRIBUTE",
"source": "content.Identifier",
"destination": "_id",
"name": "id",
"description": "Identifier field"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.Identifier",
"destination": "_exchangesandboxbravo.Identifier"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.Language",
"destination": "_exchangesandboxbravo.Language",
"description": "Language field"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.CreatedDate",
"destination": "_exchangesandboxbravo.CreatedDate",
"description": "Created Date field"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.LastUpdatedDate",
"destination": "_exchangesandboxbravo.LastUpdatedDate",
"description": "Created Date field"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.DataElements",
"destination": "_exchangesandboxbravo.DataElements"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.Purposes",
"destination": "_exchangesandboxbravo.Purposes"
}
]
}'
xdmSchema
mappings.destinationXdmPath
mappings.sourceAttribute
応答
リクエストが成功した場合は、一意の ID(id
)を含む、新しく作成されたマッピングの詳細が返されます。この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "a87f130e82f04d5188da01f087805c4b",
"version": 0,
"createdDate": 1646205694395,
"modifiedDate": 1646205694395,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
フローの作成 flow
データを取り込むための最後の手順 OneTrust Integration を Platform に送信する場合、データフローを作成します。 現時点で、次の必要な値の準備ができています。
データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。ペイロードに前述の値を提供しながら 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": "ONETRUST dataflow",
"description": "ONETRUST dataflow",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"eb5833d3-230d-4700-80cc-bda396e7af8a"
],
"targetConnectionIds": [
"495f761f-310a-4a7b-ae78-5b1152d74b38"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "a87f130e82f04d5188da01f087805c4b",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "minute",
"interval": 15
}
}'
name
description
flowSpec.id
6499120c-0b15-42dc-936e-847ea3c24d72
です。flowSpec.version
1.0
です。sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
です。scheduleParams.startTime
scheduleParams.frequency
once
、minute
、hour
、day
、week
です。scheduleParams.interval
once
に設定されている場合、間隔は必須ではありません。また、頻度は他の頻度の値に対して、15
よりも大きいか、等しい必要があります。応答
正常な応答は、新しく作成したデータフローの ID(id
)を返します。この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "70045189-42f0-493d-9b9e-be1045a9f4fa",
"etag": "\"1601e900-0000-0200-0000-621f1b080000\""
}
付録
次の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。API の完全な例については、 API を使用したソースデータフローの監視.
データフローの更新
に対するPATCHリクエストを実行して、データフローの名前や説明、実行スケジュールおよび関連するマッピングセットなどの詳細を更新します。 /flows
エンドポイント Flow Service API を使用してデータフローの ID を指定します。 PATCHリクエストをおこなう場合、データフローの一意の etag
内 If-Match
ヘッダー。 API の完全な例については、 API を使用したソースデータフローの更新.
アカウントを更新
に対してPATCHリクエストを実行して、ソースアカウントの名前、説明および資格情報を更新します。 Flow Service ベース接続 ID をクエリパラメーターとして指定する際の API。 PATCHリクエストをおこなう場合、ソースアカウントの一意の etag
内 If-Match
ヘッダー。 API の完全な例については、 API を使用したソースアカウントの更新.
データフローの削除
に対してDELETEリクエストを実行して、データフローを削除 Flow Service クエリパラメーターの一部として削除するデータフローの ID を指定する際の API。 API の完全な例については、 API を使用したデータフローの削除.
アカウントを削除
アカウントを削除するには、 Flow Service 削除するアカウントのベース接続 ID を指定する際の API。 API の完全な例については、 API を使用したソースアカウントの削除.