[Beta]{class="badge informative"}
使用Flow Service API為Oracle NetSuite Entities建立來源連線和資料流
NOTE
Oracle NetSuite Entities來源是測試版。 如需使用Beta版標示來源的相關資訊，請參閱來源概觀。
閱讀下列教學課程，瞭解如何使用Flow Service API將連絡人和客戶資料從您的Oracle NetSuite Activities Entities帳戶帶入Adobe Experience Platform。
快速入門
本指南需要您實際瞭解下列Experience Platform元件：
下列章節提供您需瞭解的其他資訊，才能使用Flow Service API成功連線到Oracle NetSuite Entities。
驗證
請閱讀Oracle NetSuite 總覽，瞭解如何擷取您的驗證認證的相關資訊。
使用平台API
如需如何成功呼叫Platform API的詳細資訊，請參閱Platform API快速入門的指南。
使用Flow Service API連線Oracle NetSuite Entities至平台
以下概述驗證Oracle NetSuite Entities來源、建立來源連線，以及建立資料流以將客戶和連絡人資料帶到Experience Platform所需執行的步驟。
建立基礎連線 base-connection
基礎連線會保留您的來源和平台之間的資訊，包括來源的驗證認證、連線的目前狀態，以及您唯一的基本連線ID。 基礎連線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}"
}
}
}'
屬性
說明
name基礎連線的名稱。 確定基本連線的名稱是描述性的，因為您可以使用此名稱來查詢基本連線的資訊。
description您可以納入的選用值，可提供基礎連線的詳細資訊。
connectionSpec.id來源的連線規格ID。 在您的來源已透過Flow Service API註冊並核准後，即可擷取此ID。
auth.specName您用來向Platform驗證來源的驗證型別。
auth.params.clientId建立整合記錄時的使用者端ID值。 您可以在這裡找到建立互動記錄的程式。 值是類似於
7fce.....b42f的64個字元字串。auth.params.clientSecret建立整合記錄時的使用者端ID值。 您可以在這裡找到建立互動記錄的程式。 值是類似於
5c98.....1b46的64個字元字串。auth.params.accessTokenUrlNetSuite存取權杖URL，類似
https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token，您會將ACCOUNT_ID取代為NetSuite帳戶識別碼。auth.params.accessToken在OAuth 2.0授權代碼授予流程教學課程的步驟二的結尾產生存取權杖值。 存取權杖的有效期限僅為60分鐘。 此值是格式為JSON Web權杖(JWT)的1024字元字串，類似於
eyJr......f4V0。回應
成功的回應會傳回新建立的基礎連線，包括其唯一的連線識別碼(id)。 在下一步中探索來源的檔案結構和內容時，需要此ID。
{
"id": "60c81023-99b4-4aae-9c31-472397576dd2",
"etag": "\"fa003785-0000-0200-0000-6555c5310000\""
}
探索您的來源 explore
取得基礎連線ID後，您現在可以透過對/connections端點執行GET要求，同時提供基礎連線ID作為查詢引數，以探索來源資料的內容和結構。
API格式
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
要求
執行GET請求以探索來源的檔案結構和內容時，您必須包括下表列出的查詢引數：
參數
說明
{BASE_CONNECTION_ID}在上一步中產生的基本連線ID。
objectType=rest您要探索的物件型別。 目前，此值一律設為
rest。{OBJECT}只有在檢視特定目錄時才需要此引數。 其值代表您要探索的目錄路徑。 對於此來源，值為
json。fileType=json您要帶到Platform的檔案型別。 目前，
json是唯一受支援的檔案型別。{PREVIEW}布林值，定義連線的內容是否支援預覽。
{SOURCE_PARAMS}定義您要帶到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 |
|---|
|
回應
同樣地，視您要利用收到的回應之物件型別而定，如下所示：
NOTE
部分記錄已截斷，以提供更好的簡報。
客戶
成功的回應會傳回結構，如下所示。
| 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 |
|---|
|
屬性
說明
name來源連線的名稱。 確保來源連線的名稱是描述性的，因為您可以使用此名稱來查詢來源連線的資訊。
description您可以納入的選用值，可提供來源連線的詳細資訊。
baseConnectionIdOracle NetSuite Entities的基本連線識別碼。 此ID是在先前步驟中產生的。
connectionSpec.id與您的來源對應的連線規格ID。
data.format您要擷取的Oracle NetSuite Entities資料格式。 目前唯一支援的資料格式為
json。object_typeOracle NetSuite Entities同時支援客戶和連絡人擷取。 根據您想要的實體，傳遞下列其中一項：
customer：擷取特定客戶資料，包括客戶名稱、地址和金鑰識別碼等詳細資訊。contact：擷取聯絡人姓名、電子郵件、電話號碼，以及與客戶相關聯的任何自訂聯絡人相關欄位。
回應
成功的回應會傳回新建立的來源連線的唯一識別碼(id)。 在後續步驟中需要此ID才能建立資料流。
{
"id": "574c049f-29fc-411f-be0d-f80002025f51",
"etag": "\"0704acb3-0000-0200-0000-6555c5470000\""
}
建立目標XDM結構描述 target-schema
為了在Platform中使用來源資料，必須建立目標結構描述，以根據您的需求來建構來源資料。 然後目標結構描述會用來建立包含來源資料的Platform資料集。
可透過對結構描述登入API執行POST要求來建立目標XDM結構描述。
如需有關如何建立目標XDM結構描述的詳細步驟，請參閱有關使用API 建立結構描述的教學課程。
建立目標資料集 target-dataset
可以透過對目錄服務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"
}
}'
屬性
說明
name目標連線的名稱。 請確定目標連線的名稱是描述性的，因為您可以使用此名稱來查詢目標連線的資訊。
description您可以納入的選用值，可提供目標連線的詳細資訊。
connectionSpec.id對應至資料湖的連線規格ID。 此固定ID為：
6b137bf6-d2a0-48c8-914b-d50f4942eb85。data.format您要擷取的Oracle NetSuite Entities資料格式。
params.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.id在先前步驟中產生的目標XDM結構描述識別碼。
mappings.sourceType正在對應的來源屬性型別。
mappings.source需要對映至目的地XDM路徑的來源屬性。
mappings.destination來源屬性對應到的目的地XDM路徑。
回應
成功的回應會傳回新建立的對應詳細資料，包括其唯一識別碼(id)。 在後續步驟中需要此值，才能建立資料流。
{
"id": "ddf0592bcc9d4ac391803f15f2429f87",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
建立流程 flow
將資料從Oracle NetSuite Entities引進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"
}
}'
屬性
說明
name資料流的名稱。 確保資料流的名稱是描述性的，因為您可以使用此名稱來查閱資料流上的資訊。
description您可以納入的選用值，可提供資料流的詳細資訊。
flowSpec.id建立資料流所需的流量規格ID。 此固定ID為：
6499120c-0b15-42dc-936e-847ea3c24d72。flowSpec.version流程規格ID的對應版本。 此值預設為
1.0。sourceConnectionIds在先前步驟中產生的來源連線識別碼。
targetConnectionIds在先前步驟中產生的目標連線識別碼。
transformations此屬性包含套用至資料所需的各種轉換。 將非XDM相容的資料引進Platform時，需要此屬性。
transformations.name指定給轉換的名稱。
transformations.params.mappingId在先前步驟中產生的對應ID。
transformations.params.mappingVersion對應ID的對應版本。 此值預設為
0。scheduleParams.startTime此屬性包含資料流擷取排程的相關資訊。
scheduleParams.frequency資料流收集資料的頻率。
scheduleParams.interval間隔會指定兩個連續資料流執行之間的期間。 間隔的值應為非零整數。
回應
成功的回應會傳回新建立的資料流識別碼(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刪除來源帳戶的指南。
recommendation-more-help
337b99bb-92fb-42ae-b6b7-c7042161d089