Flow Service APIを使用して YOURSOURCE 接続を作成します
このテンプレートを使用する際に、斜体のすべての段落(この段落から始まる)を置き換えるか削除します。
最初に、ページ上部のメタデータ(タイトルと説明)を更新します。 このページのDNLのインスタンスはすべて無視してください。 これは、機械翻訳プロセスが適切にサポートする複数の言語にページを翻訳するのに役立つタグです。 ドキュメントを送信すると、ドキュメントにタグが追加されます。
概要
顧客に提供する価値を含め、会社の概要を簡単に説明します。 製品ドキュメントのホームページへのリンクを追加して、詳細をご覧ください。
前提条件
Adobe Experience Platform ユーザーインターフェイスでソースの設定を開始する前に、お客様が認識しておく必要がある情報をこのセクションに追加します。 次の程度である可能性があります:
- 様は許可リストに追加する必要があります
- 電子メールハッシュの要件
- お客様の側にあるアカウントの詳細
- プラットフォームに接続するためのAPI キーを取得する方法
必要な資格情報の収集
YOURSOURCEをExperience Platformに接続するには、次の接続プロパティの値を指定する必要があります。
これらの資格情報について詳しくは、YOURSOURCE認証ドキュメントを参照してください。 プラットフォームの認証ドキュメントへのリンクをここに追加してください。
Flow Service APIを使用して YOURSOURCE をExperience Platformに接続します
次のチュートリアルでは、Flow Service APIを使用してYOURSOURCE ソース接続を作成し、YOURSOURCE データをExperience Platformに取り込むデータフローを作成する手順について説明します。
ベース接続の作成 base-connection
ベース接続は、ソースの認証情報、接続の現在の状態、一意のベース接続IDなど、ソースとExperience Platform間の情報を保持します。 ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続IDを作成するには、YOURSOURCE認証資格情報をリクエスト本文の一部として提供しながら、/connections エンドポイントにPOST リクエストを行います。
API 形式
POST /connections
リクエスト
次のリクエストは、YOURSOURCEのベース接続を作成します。
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": "{YOURSOURCE} base connection",
"description": "{YOURSOURCE} base connection to authenticate to Experience Platform",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"auth": {
"specName": "OAuth generic-rest-connector",
"params": {
"accessToken": "{ACCESS_TOKEN}",
"refreshToken": "{REFRESH_TOKEN}",
"expirationDate": "{EXPIRATION_DATE}"
}
}
}'
namedescriptionconnectionSpec.idauth.specNameauth.params.応答
リクエストが成功した場合は、一意の接続識別子(id)を含む、新しく作成されたベース接続が返されます。 この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"etag": "\"d64c8298-add4-4667-9a49-28195b2e2a84\""
}
ソースを参照 explore
前の手順で生成したベース接続IDを使用して、GET リクエストを実行してファイルとディレクトリを探索できます。
次の呼び出しを使用して、Experience Platformに取り込むファイルのパスを見つけます。
API 形式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
ソースのファイル構造とコンテンツを調べるために GET リクエストを実行する場合、次の表に示すクエリのパラメーターを含める必要があります。
{BASE_CONNECTION_ID}objectType=restrestに設定されています。{OBJECT}fileType=jsonjsonはサポートされている唯一のファイル形式です。{PREVIEW}{SOURCE_PARAMS}{SOURCE_PARAMS} で受け入れ可能な形式タイプを取得するには、list_id 文字列全体を base64 にエンコードする必要があります。 以下の例では、base64でエンコードされた"list_id": "10c097ca71"はeyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=と同じです。リクエスト
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/connections/70383d02-2777-4be7-a309-9dd6eea1b46d/explore?objectType=rest&object=json&fileType=json&preview=true&sourceParams=eyJsaXN0SWQiOiIxMGMwOTdjYTcxIn0=' \
-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}'
応答
応答が成功すると、クエリされたファイルの構造を返します。
{
"data": [
{
"members": [
{
"id": "cff65fb4c5f5828666ad846443720efd",
"email_address": "roykent@gmail.com",
"unique_email_id": "72c758cbf1",
"full_name": "Roy Kent",
"web_id": 547094062,
"email_type": "html",
"status": "subscribed",
"merge_fields": {
"FNAME": "Roy",
"LNAME": "Kent",
"ADDRESS": {
"addr1": "",
"addr2": "",
"city": "Richmond",
"state": "Virginia",
"zip": "",
"country": "US"
},
"PHONE": "",
"BIRTHDAY": ""
},
"stats": {
"avg_open_rate": 0,
"avg_click_rate": 0
},
"ip_signup": "",
"timestamp_signup": "",
"ip_opt": "103.43.112.97",
"timestamp_opt": "2021-06-01T15:31:36+00:00",
"member_rating": 2,
"last_changed": "2021-06-01T15:31:36+00:00",
"language": "",
"vip": false,
"email_client": "",
"location": {
"latitude": 0,
"longitude": 0,
"gmtoff": 0,
"dstoff": 0,
"country_code": "",
"timezone": ""
},
"source": "Admin Add",
"tags_count": 0,
"tags": [
],
"list_id": "10c097ca71"
}
],
"list_id": "10c097ca71",
"total_items": 2,
"_links": [
{
"rel": "self",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/CollectionResponse.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Paths/Lists/Members/Collection.json"
},
{
"rel": "parent",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71",
"method": "GET",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json"
},
{
"rel": "create",
"href": "https://us6.api.mailchimp.com/3.0/lists/10c097ca71/members",
"method": "POST",
"targetSchema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/Response.json",
"schema": "https://us6.api.mailchimp.com/schema/3.0/Definitions/Lists/Members/POST.json"
}
]
}
]
}
ソース接続の作成 source-connection
Flow Service API に対して POST リクエストを実行することで、ソース接続を作成することができます。 ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
API 形式
POST /sourceConnections
リクエスト
次のリクエストは、YOURSOURCEのソース接続を作成します。
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": "{YOURSOURCE} Source Connection",
"description": "{YOURSOURCE} Source Connection",
"baseConnectionId": "70383d02-2777-4be7-a309-9dd6eea1b46d",
"connectionSpec": {
"id": "6360f136-5980-4111-8bdf-15d29eab3b5a",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"server": "us6",
"listId": "10c097ca71"
}
}'
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson のみです。応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID(id)が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "246d052c-da4a-494a-937f-a0d17b1c6cf5",
"etag": "\"712a8c08-fda7-41c2-984b-187f823293d8\""
}
ターゲット 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
リクエスト
次のリクエストは、YOURSOURCEのターゲット接続を作成します。
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": "{YOURSOURCE} Target Connection",
"description": "{YOURSOURCE} Target Connection",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "json"
},
"params": {
"dataSetId": "5ef4551c52e054191a61a99f"
}
}'
namedescriptionconnectionSpec.idc604ff05-7f1a-43c0-8e18-33bf874cb11c です。data.formatparams.dataSetId応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID(id)が返されます。 この ID は、後の手順で必要になります。
{
"id": "7c96c827-3ffd-460c-a573-e9558f72f263",
"etag": "\"a196f685-f5e8-4c4c-bfbd-136141bb0c6d\""
}
マッピングの作成 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/995dabbea86d58e346ff91bd8aa741a9f36f29b1019138d4",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "Id",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "FirstName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "LastName",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
xdmSchemamappings.destinationXdmPathmappings.sourceAttributemappings.identity応答
リクエストが成功した場合は、一意の ID(id)を含む、新しく作成されたマッピングの詳細が返されます。 この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "bf5286a9c1ad4266baca76ba3adc9366",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
フローの作成 flow
YOURSOURCEから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": "{YOURSOURCE} dataflow",
"description": "{YOURSOURCE} dataflow",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"246d052c-da4a-494a-937f-a0d17b1c6cf5"
],
"targetConnectionIds": [
"7c96c827-3ffd-460c-a573-e9558f72f263"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "bf5286a9c1ad4266baca76ba3adc9366",
"mappingVersion": "0"
}
}
],
"scheduleParams": {
"startTime": "1625040887",
"frequency": "minute",
"interval": 15
}
}'
namedescriptionflowSpec.id6499120c-0b15-42dc-936e-847ea3c24d72 です。flowSpec.version1.0 です。sourceConnectionIdstargetConnectionIdstransformationstransformations.nametransformations.params.mappingIdtransformations.params.mappingVersion0 です。scheduleParams.startTimescheduleParams.frequencyonce、minute、hour、day、week です。scheduleParams.intervalonce に設定されている場合、間隔は必須ではありません。また、頻度は他の頻度の値に対して、15 よりも大きいか、等しい必要があります。応答
正常な応答は、新しく作成したデータフローの ID(id)を返します。 この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "993f908f-3342-4d9c-9f3c-5aa9a189ca1a",
"etag": "\"510bb1d4-8453-4034-b991-ab942e11dd8a\""
}
付録
次の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。 完全な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を使用したソースアカウントの削除に関するガイドを参照してください。