Flow Service APIを使用してOneTrust Integration ソースのデータフローを作成します
NOTE
OneTrust Integration ソースは、同意データと環境設定データの取り込みのみをサポートし、Cookieはサポートしません。
次のチュートリアルでは、Flow Service APIを使用して、ソース接続とデータフローを作成し、履歴データとスケジュールされた同意データの両方をOneTrust IntegrationからAdobe Experience Platformに取り込む手順について説明します。
前提条件
IMPORTANT
OneTrust Integration ソースコネクタとドキュメントは、OneTrust Integration チームによって作成されました。 問い合わせやアップデートのリクエストについては、OneTrust チーム に直接お問い合わせください。
OneTrust IntegrationをExperience Platformに接続する前に、まずアクセストークンを取得する必要があります。 アクセストークンの検索方法について詳しくは、OneTrust Integration OAuth 2 ガイド を参照してください。
システム間の更新トークンはOneTrustでサポートされていないため、有効期限が切れた後にアクセストークンが自動的に更新されません。 したがって、アクセストークンが期限切れになる前に、接続で更新されていることを確認する必要があります。 アクセストークンの設定可能な最大有効期間は1年です。 アクセストークンの更新について詳しくは、OAuth 2.0 クライアント資格情報の管理🔗に関するOneTrust ドキュメントを参照してください。
Flow Service APIを使用してOneTrust IntegrationをExperience Platformに接続します
NOTE
データ取り込みのために、OneTrust Integration API仕様をAdobeと共有しています。
次のチュートリアルでは、OneTrust Integration ソース接続を作成し、Flow Service APIを使用してOneTrust Integration データをExperience Platformに取り込むためのデータフローを作成する手順について説明します。
ベース接続の作成 base-connection
ベース接続は、ソースの認証情報、接続の現在の状態、一意のベース接続IDなど、ソースとExperience Platform間の情報を保持します。 ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続IDを作成するには、OneTrust Integration認証情報をリクエスト本文の一部として提供しながら、/connections エンドポイントにPOST リクエストを行います。
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 Experience Platform",
"connectionSpec": {
"id": "cf16d886-c627-4872-9936-fb08d6cba8cc",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Refresh Code",
"params": {
"accessToken": "{ACCESS_TOKEN}"
}
}
}'
プロパティ
説明
nameベース接続の名前。 ベース接続の情報を検索する際に使用できるので、ベース接続の名前はわかりやすいものにしてください。
descriptionベース接続に関する詳細情報を提供するために含めることができるオプション値。
connectionSpec.idソースの接続仕様 ID。 この ID は、ソースが登録および承認された後に、Flow Service API から取得することができます。
auth.specNameExperience Platformに対するソースの認証に使用する認証タイプ。
auth.params.APIに接続するためのアクセストークンなど、ソースの認証に必要な資格情報が含まれます。
auth.params.accessTokenOneTrust Integration アカウントに対応するアクセストークン。
応答
リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。 この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "622124ca-6d18-47f7-999c-66f599955309",
"etag": "\"2e026443-0000-0200-0000-621f1af80000\""
}
ソースを参照 explore
前の手順で生成したベース接続 ID を使用することで、GET リクエストを実行してファイルとディレクトリを調べることができます。
次の呼び出しを使用して、Experience Platformに取り込むファイルのパスを見つけます。
API 形式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}
ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。
パラメーター
説明
{BASE_CONNECTION_ID}前の手順で生成したベース接続 ID。
objectType=rest探索するオブジェクトのタイプ。 現在、この値は常に
restに設定されています。{OBJECT}このパラメーターは、特定のディレクトリを表示する場合にのみ必要です。 値は、参照するディレクトリのパスを表します。
fileType=jsonExperience Platformに取り込むファイルの種類。 現在、
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}'
応答
応答が成功すると、クエリされたファイルの構造を返します。
NOTE
以下のJSON応答ペイロードは簡潔にするために非表示になっています。 「Click me」を選択して、応答ペイロードを表示します。
クリック
| 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含めることでソース接続に関する詳細情報を提供できるオプションの値です。
baseConnectionIdOneTrust Integration のベース接続 ID。 この ID は、前の手順で生成されました。
connectionSpec.idソースに対応する接続仕様の ID。
data.format取り込む OneTrust Integration データの形式。 現在、サポートされているデータ形式は
json のみです。応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "eb5833d3-230d-4700-80cc-bda396e7af8a",
"etag": "\"da04c07f-0000-0200-0000-621f1afc0000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータをExperience Platformで使用するには、必要に応じてソースデータを構造化するターゲットスキーマを作成する必要があります。 その後、ターゲットスキーマを使用して、ソースデータが含まれるExperience 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.idData Lakeに対応する接続仕様 ID。 この修正済み ID は
c604ff05-7f1a-43c0-8e18-33bf874cb11c です。data.formatExperience Platformに取り込むOneTrust Integration データのフォーマット。
params.dataSetId前の手順で取得したターゲットデータセット ID。
応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。 この ID は、後の手順で必要になります。
{
"id": "495f761f-310a-4a7b-ae78-5b1152d74b38",
"etag": "\"410a7b0c-0000-0200-0000-621f1afd0000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。 これは、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep APIに対してPOST リクエストを実行することで実現します。
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"
},
{
"sourceType": "ATTRIBUTE",
"source": "content.LinkToken",
"destination": "_exchangesandboxbravo.LinkToken",
"description": "Link Token"
}
]
}'
プロパティ
説明
xdmSchema以前の手順で生成されたターゲット XDM スキーマの ID。
mappings.destinationXdmPathソース属性がマッピングされている宛先 XDM パス。
mappings.sourceAttribute宛先 XDM パスにマッピングする必要があるソース属性。
応答
リクエストが成功した場合は、一意の ID（id）を含む、新しく作成されたマッピングの詳細が返されます。 この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "a87f130e82f04d5188da01f087805c4b",
"version": 0,
"createdDate": 1646205694395,
"modifiedDate": 1646205694395,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
フローの作成 flow
OneTrust IntegrationからExperience 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データフローの作成に必要なフロー仕様 ID。 この修正済み ID は
6499120c-0b15-42dc-936e-847ea3c24d72 です。flowSpec.versionフロー仕様 ID の対応するバージョン。 この値のデフォルトは
1.0 です。sourceConnectionIds以前の手順で生成されたソース接続 ID。
targetConnectionIds以前の手順で生成されたターゲット接続 ID。
transformationsこのプロパティには、データに適用する必要がある様々な変換が含まれています。 このプロパティは、XDMに準拠していないデータをExperience Platformに取り込む場合に必要です。
transformations.name変換に割り当てられた名前。
transformations.params.mappingId以前の手順で生成されたマッピング ID。
transformations.params.mappingVersionマッピング ID の対応するバージョン。 この値のデフォルトは
0 です。scheduleParams.startTimeこのプロパティには、データフローの取り込みスケジュールに関する情報が含まれます。
scheduleParams.frequencyデータフローがデータを収集する頻度。 指定できる値は、
once、minute、hour、day、week です。scheduleParams.intervalインターバルは 2 つの連続したフロー実行の間隔を指定します。 インターバルの値はゼロ以外の整数にしてください。 頻度が
once に設定されている場合、間隔は必須ではありません。また、頻度は他の頻度の値に対して、15 よりも大きいか、等しい必要があります。応答
正常な応答は、新しく作成したデータフローの ID（id）を返します。 この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "70045189-42f0-493d-9b9e-be1045a9f4fa",
"etag": "\"1601e900-0000-0200-0000-621f1b080000\""
}
付録
次の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。 完全な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