Flow Service APIを使用してOracle NetSuite Entitiesのソース接続とデータフローを作成する
Flow Service APIを使用してOracle NetSuite Activities Entities アカウントからAdobe Experience Platformに連絡先と顧客データを取り込む方法については、次のチュートリアルを参照してください。
はじめに
このガイドは、Adobe Experience Platform の次のコンポーネントを実際に利用および理解しているユーザーを対象としています。
- ソース : Experience Platformを使用すると、様々なソースからデータを取り込むことができますが、Experience Platform サービスを使用して着信データを構造化、ラベル付け、強化することができます。
- サンドボックス : Experience Platformは、1つのExperience Platform インスタンスを個別のバーチャル環境に分割して、デジタルエクスペリエンスアプリケーションの開発と進化に役立つバーチャルサンドボックスを提供します。
次の節では、Flow Service APIを使用してOracle NetSuite Entitiesに正常に接続するために知っておく必要がある追加情報を示します。
認証
認証情報を取得する方法について詳しくは、Oracle NetSuite 概要を参照してください。
Experience Platform APIの使用
Experience Platform APIの呼び出しを正常に行う方法について詳しくは、Experience Platform APIの概要に関するガイドを参照してください。
Flow Service APIを使用してOracle NetSuite EntitiesをExperience Platformに接続します
次の手順では、Oracle NetSuite Entities ソースの認証、ソース接続の作成、お客様と連絡先のデータをExperience Platformに取り込むためのデータフローの作成を行う必要があります。
ベース接続の作成 base-connection
ベース接続は、ソースの認証情報、接続の現在の状態、一意のベース接続IDなど、ソースとExperience Platform間の情報を保持します。 ベース接続 ID により、ソース内からファイルを参照および移動し、データタイプやフォーマットに関する情報を含む、取り込みたい特定の項目を識別することができます。
ベース接続IDを作成するには、Oracle NetSuite Entities認証情報をリクエスト本文の一部として提供しながら、/connections エンドポイントにPOST リクエストを行います。
API 形式
POST /connections
リクエスト
次のリクエストは、Oracle NetSuite Entities のベース接続を作成します。
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": "Oracle NetSuite Entities base connection",
"description": "Authenticated base connection for Oracle NetSuite Entities",
"connectionSpec": {
"id": "fdf850b4-5a8d-4a5a-9ce8-4caef9abb2a8",
"version": "1.0"
},
"auth": {
"specName": "OAuth2 Client Credential",
"params": {
"clientId": "{CLIENT_ID}",
"clientSecret": "{CLIENT_SECRET}"
"accessTokenUrl": "{ACCESS_TOKEN_URL}",
"accessToken": "{ACCESS_TOKEN_URL}"
}
}
}'
namedescriptionconnectionSpec.idauth.specNameauth.params.clientId7fce.....b42fに似た64文字の文字列です。auth.params.clientSecret5c98.....1b46に似た64文字の文字列です。auth.params.accessTokenUrlhttps://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/tokenと同様です。auth.params.accessTokeneyJr......f4V0と同様にJSON Web Token （JWT）としてフォーマットされた1024文字の文字列です。応答
リクエストが成功した場合は、一意の接続識別子（id）を含む、新しく作成されたベース接続が返されます。 この ID は、次の手順でソースのファイル構造と内容を調べるために必要です。
{
"id": "60c81023-99b4-4aae-9c31-472397576dd2",
"etag": "\"fa003785-0000-0200-0000-6555c5310000\""
}
ソースを参照 explore
ベース接続IDを取得したら、ベース接続IDをクエリパラメーターとして提供しながら、/connections エンドポイントに対してGET リクエストを実行して、ソースデータのコンテンツと構造を調査できるようになりました。
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}jsonになります。fileType=jsonjsonはサポートされている唯一のファイル形式です。{PREVIEW}{SOURCE_PARAMS}Experience Platformに取り込むソースファイルのパラメーターを定義します。 {SOURCE_PARAMS}に対して許可された書式型を取得するには、文字列全体をbase64でエンコードする必要があります。
Oracle NetSuite Entitiesは、顧客と連絡先の両方のデータ取得をサポートしています。 使用しているオブジェクトタイプに応じて、次のいずれかを渡します。
customer：顧客の名前、住所、キー識別子などの詳細を含む特定の顧客データを取得します。contact：連絡先名、電子メール、電話番号、および顧客に関連付けられているカスタム連絡先関連フィールドを取得します。
Oracle NetSuite Entitiesの場合、連絡先データを取得するには、{SOURCE_PARAMS}の値が{"object_type":"customer"}として渡されます。 base64でエンコードした場合、次に示すようにeyAib2JqZWN0X3R5cGUiOiAiY3VzdG9tZXIifQ%3D%3Dと等しくなります。
| code language-shell |
|---|
|
Oracle NetSuite Entitiesの場合、連絡先データを取得するには、{SOURCE_PARAMS}の値が{"object_type":"contact"}として渡されます。 base64でエンコードした場合、次に示すようにeyAib2JqZWN0X3R5cGUiOiAiY29udGFjdCJ9と等しくなります。
| code language-shell |
|---|
|
応答
同様に、受信した応答を活用しているオブジェクトタイプに応じて、次のようになります。
応答が成功すると、次のような構造が返されます。
| accordion | ||
|---|---|---|
| 選択してJSON ペイロードを表示します | ||
|
応答が成功すると、次のような構造が返されます。
| accordion | ||
|---|---|---|
| 選択してJSON ペイロードを表示します | ||
|
ソース接続の作成 source-connection
ソース接続を作成するには、Flow Service APIの/sourceConnections エンドポイントに対してPOST リクエストを行います。 ソース接続は、接続 ID、ソースデータファイルへのパス、接続仕様 ID から構成されます。
API 形式
POST /sourceConnections
リクエスト
次のリクエストは、Oracle NetSuite Entities のソース接続を作成します。
顧客データを取得する場合、object_type プロパティ値はcustomerである必要があります。
| code language-shell |
|---|
|
連絡先データを取得する場合、object_type プロパティ値はcontactである必要があります。
| code language-shell |
|---|
|
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson のみです。object_typeOracle NetSuite Entitiesは、顧客と連絡先の両方の取得をサポートしています。 必要なエンティティに応じて、次のいずれかを渡します。
customer：顧客の名前、住所、キー識別子などの詳細を含む特定の顧客データを取得します。contact：連絡先名、電子メール、電話番号、および顧客に関連付けられているカスタム連絡先関連フィールドを取得します。
応答
リクエストが成功した場合は、新たに作成されたソース接続の一意の ID（id）が返されます。 この ID は、後の手順でデータフローを作成する際に必要になります。
{
"id": "574c049f-29fc-411f-be0d-f80002025f51",
"etag": "\"0704acb3-0000-0200-0000-6555c5470000\""
}
ターゲット XDM スキーマの作成 target-schema
ソースデータをExperience Platformで使用するには、必要に応じてソースデータを構造化するターゲットスキーマを作成する必要があります。 その後、ターゲットスキーマを使用して、ソースデータが含まれるExperience Platform データセットを作成します。
Schema Registry API に POST リクエストを実行することで、ターゲット XDM スキーマを作成できます。
ターゲット XDM スキーマの作成手順について詳しくは、 API を使用したスキーマの作成に関するチュートリアルを参照してください。
ターゲットデータセットの作成 target-dataset
Catalog Service API に POST リクエストを実行し、その際にペイロード内でターゲットスキーマの ID を指定することで、ターゲットデータセットを作成できます。
ターゲットデータセットの作成手順について詳しくは、 API を使用したデータセットの作成に関するチュートリアルを参照してください。
ターゲット接続の作成 target-connection
ターゲット接続は、取り込んだデータを格納する宛先への接続を表します。 ターゲット接続を作成するには、データレイクに対応する固定接続仕様IDを指定する必要があります。 この ID は c604ff05-7f1a-43c0-8e18-33bf874cb11c です。
ターゲットスキーマ、ターゲットデータセット、データレイクへの接続仕様IDなどの一意の識別子が作成されました。 これらの識別子を使用すると、受信ソースデータを格納するデータセットを指定する Flow Service API を使用して、ターゲット接続を作成することができます。
API 形式
POST /targetConnections
リクエスト
次のリクエストは、Oracle NetSuite Entities のターゲット接続を作成します。
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": "Oracle NetSuite Entities Target Connection Generic Rest",
"description": " Oracle NetSuite Entities Connection Generic Rest",
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
},
"data": {
"format": "parquet_xdm",
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/325fd5394ba421246b05c0a3c2cd5efeec2131058a63d473",
"version": "1.2"
}
},
"params": {
"dataSetId": "65004470082ac828d2c3d6a0"
}
}'
namedescriptionconnectionSpec.id6b137bf6-d2a0-48c8-914b-d50f4942eb85 です。data.formatparams.dataSetId応答
リクエストが成功した場合は、新しいターゲット接続の一意の ID（id）が返されます。 この ID は、後の手順で必要になります。
{
"id": "382fc614-3c5b-46b9-a971-786fb0ae6c5d",
"etag": "\"e0016100-0000-0200-0000-655707a40000\""
}
マッピングの作成 mapping
ソースデータをターゲットデータセットに取り込むには、まず、ターゲットデータセットが準拠するターゲットスキーマにマッピングする必要があります。 これは、リクエストペイロード内で定義されたデータマッピングを使用して、Data Prep APIに対してPOST リクエストを実行することで実現します。
API 形式
POST /conversion/mappingSets
リクエスト
次のリクエストは、DNL NetSuite Entitiesのマッピングを作成します
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 '{
"outputSchema": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b156e6f818f923e048199173c45e55e20fd2487f5eb03d22",
"contentType": "application/vnd.adobe.xed-full+json;version=1"
}
},
"mappings": [
{
"sourceType": "ATTRIBUTE",
"source": "items.id",
"destination": "_extconndev.NS_ID"
},
{
"sourceType": "ATTRIBUTE",
"source": "items.entitytitle",
"destination": "_extconndev.NS_entity_title"
},
{
"sourceType": "ATTRIBUTE",
"source": "items.datecreated",
"destination": "_extconndev.NS_datecreated"
},
{
"sourceType": "ATTRIBUTE",
"destination": "_extconndev.NS_email",
"source": "items.email"
},
{
"sourceType": "ATTRIBUTE",
"source": "items.lastmodifieddate",
"destination": "_extconndev.NS_lastmodified"
}
]
}'
outputSchema.schemaRef.idmappings.sourceTypemappings.sourcemappings.destination応答
リクエストが成功した場合は、一意の ID（id）を含む、新しく作成されたマッピングの詳細が返されます。 この値は、後の手順でデータフローを作成する際に必要になります。
{
"id": "ddf0592bcc9d4ac391803f15f2429f87",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
フローの作成 flow
Oracle NetSuite EntitiesからExperience Platformにデータを取り込む最後の手順は、データフローを作成することです。 現時点で、次の必要な値の準備ができています。
データフローは、ソースからデータをスケジュールおよび収集する役割を果たします。 ペイロードに前述の値を提供しながら POST リクエストを実行することで、データフローを作成することができます。
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": "Oracle NetSuite Entities connector Flow Generic Rest",
"description": "Oracle NetSuite Entities connector Description Flow Generic Rest",
"flowSpec": {
"id": "6499120c-0b15-42dc-936e-847ea3c24d72",
"version": "1.0"
},
"sourceConnectionIds": [
"d8827440-339f-428d-bf38-5e2ab1f0f7bb"
],
"targetConnectionIds": [
"e349a15e-c639-4047-8b2a-154aa7a857d7"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "10787532e0994eb686e76bdab69a9e88",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": 1700202649,
"frequency": "once"
}
}'
namedescriptionflowSpec.id6499120c-0b15-42dc-936e-847ea3c24d72 です。flowSpec.version1.0 です。sourceConnectionIdstargetConnectionIdstransformationstransformations.nametransformations.params.mappingIdtransformations.params.mappingVersion0 です。scheduleParams.startTimescheduleParams.frequencyscheduleParams.interval応答
正常な応答は、新しく作成したデータフローの ID（id）を返します。 この ID を使用して、データフローを監視、更新または削除できます。
{
"id": "84c64142-1741-4b0b-95a9-65644eba0cf6",
"etag": "\"3901770b-0000-0200-0000-655708970000\""
}
付録
次の節では、データフローを監視、更新、削除する手順について説明します。
データフローの監視
データフローが作成されると、それを通して取り込まれるデータを監視し、フローの実行状況、完了状況、エラーなどの情報を確認することができます。 完全な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を使用したソースアカウントの削除に関するガイドを参照してください。