Skapa en källanslutning och ett dataflöde för Oracle NetSuite Entities med API:t för Flow Service
Läs följande självstudiekurs om du vill veta mer om hur du kan ta med kontakter och kunddata från ditt Oracle NetSuite Activities Entities-konto till Adobe Experience Platform med Flow Service API.
Komma igång
Handboken kräver en fungerande förståelse av följande komponenter i Experience Platform:
- Källor: Med Experience Platform kan data hämtas från olika källor samtidigt som du kan strukturera, etikettera och förbättra inkommande data med hjälp av Experience Platform tjänster.
- Sandlådor: Experience Platform tillhandahåller virtuella sandlådor som partitionerar en enda Experience Platform-instans till separata virtuella miljöer för att utveckla och utveckla program för digitala upplevelser.
I följande avsnitt finns ytterligare information som du behöver känna till för att kunna ansluta till Oracle NetSuite Entities med API:t Flow Service.
Autentisering
Läs Oracle NetSuite översikten om du vill ha mer information om hur du hämtar autentiseringsuppgifter.
Använda Experience Platform API:er
Information om hur du kan anropa Experience Platform API:er finns i guiden Komma igång med Experience Platform API:er.
Anslut Oracle NetSuite Entities till Experience Platform med API:t Flow Service
Följande beskriver de steg som du måste utföra för att autentisera din Oracle NetSuite Entities-källa, skapa en källanslutning och skapa ett dataflöde för att skicka dina kund- och kontaktdata till Experience Platform.
Skapa en basanslutning base-connection
En basanslutning bevarar information mellan källan och Experience Platform, inklusive autentiseringsuppgifter för källan, anslutningens aktuella tillstånd och ditt unika basanslutnings-ID. Med det grundläggande anslutnings-ID:t kan du utforska och navigera bland filer inifrån källan och identifiera de specifika objekt som du vill importera, inklusive information om deras datatyper och format.
Om du vill skapa ett basanslutnings-ID skapar du en POST-begäran till /connections-slutpunkten och anger dina Oracle NetSuite Entities-autentiseringsuppgifter som en del av begärandetexten.
API-format
POST /connections
Begäran
Följande begäran skapar en basanslutning för 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.auth.params.clientSecret5c98.....1b46.auth.params.accessTokenUrlhttps://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token, där du ersätter ACCOUNT_ID med ditt NetSuite konto-ID.auth.params.accessTokeneyJr......f4V0.Svar
Ett svar returnerar den nyskapade basanslutningen, inklusive dess unika anslutnings-ID (id). Detta ID krävs för att undersöka källans filstruktur och innehåll i nästa steg.
{
"id": "60c81023-99b4-4aae-9c31-472397576dd2",
"etag": "\"fa003785-0000-0200-0000-6555c5310000\""
}
Utforska din källa explore
När du har ditt basanslutnings-ID kan du nu utforska innehållet och strukturen i dina källdata genom att utföra en GET-begäran till /connections-slutpunkten och samtidigt ange ditt basanslutnings-ID som en frågeparameter.
API-format
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Begäran
När du utför GET-förfrågningar om källans filstruktur och innehåll måste du inkludera de frågeparametrar som anges i tabellen nedan:
{BASE_CONNECTION_ID}objectType=restrest.{OBJECT}json.fileType=jsonjson den enda filtypen som stöds.{PREVIEW}{SOURCE_PARAMS}Definierar parametrar för källfilen som du vill hämta till Experience Platform. Om du vill hämta den godkända formattypen för {SOURCE_PARAMS} måste du koda hela strängen i base64.
Oracle NetSuite Entities har stöd för både kund- och kontaktdatahämtning. Beroende på vilken objekttyp du använder kan du skicka något av följande:
customer: Hämta specifika kunddata, inklusive information som kundnamn, adresser och nyckelidentifierare.contact: Hämta kontaktnamn, e-post, telefonnummer och anpassade kontaktrelaterade fält som är kopplade till kunder.
För Oracle NetSuite Entities skickas värdet för {SOURCE_PARAMS} som {"object_type":"customer"} om du vill hämta kontaktdata. När den kodas i base64 är den lika med eyAib2JqZWN0X3R5cGUiOiAiY3VzdG9tZXIifQ%3D%3D enligt nedan.
| code language-shell |
|---|
|
För Oracle NetSuite Entities skickas värdet för {SOURCE_PARAMS} som {"object_type":"contact"} om du vill hämta kontaktdata. När den kodas i base64 är den lika med eyAib2JqZWN0X3R5cGUiOiAiY29udGFjdCJ9 enligt nedan.
| code language-shell |
|---|
|
Svar
Beroende på vilken objekttyp du använder ser svaret ut som nedan:
Ett lyckat svar returnerar en struktur enligt nedan.
| accordion | ||
|---|---|---|
| Välj för att visa JSON-nyttolasten | ||
|
Ett lyckat svar returnerar en struktur enligt nedan.
| accordion | ||
|---|---|---|
| Välj för att visa JSON-nyttolasten | ||
|
Skapa en källanslutning source-connection
Du kan skapa en källanslutning genom att göra en POST-begäran till /sourceConnections-slutpunkten i Flow Service API:t. En källanslutning består av ett anslutnings-ID, en sökväg till källdatafilen och ett anslutnings-spec-ID.
API-format
POST /sourceConnections
Begäran
Följande begäran skapar en källanslutning för Oracle NetSuite Entities:
När kunddata hämtas ska egenskapsvärdet object_type vara customer.
| code language-shell |
|---|
|
När kontaktdata hämtas ska egenskapsvärdet object_type vara contact.
| code language-shell |
|---|
|
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson.object_typeOracle NetSuite Entities har stöd för både kund- och kontakthämtning. Beroende på vilken enhet du vill använda skickar du något av följande:
customer: Hämta specifika kunddata, inklusive information som kundnamn, adresser och nyckelidentifierare.contact: Hämta kontaktnamn, e-post, telefonnummer och anpassade kontaktrelaterade fält som är kopplade till kunder.
Svar
Ett lyckat svar returnerar den unika identifieraren (id) för den nyligen skapade källanslutningen. Detta ID krävs i ett senare steg för att skapa ett dataflöde.
{
"id": "574c049f-29fc-411f-be0d-f80002025f51",
"etag": "\"0704acb3-0000-0200-0000-6555c5470000\""
}
Skapa ett mål-XDM-schema target-schema
För att källdata ska kunna användas i Experience Platform måste ett målschema skapas för att strukturera källdata efter dina behov. Målschemat används sedan för att skapa en Experience Platform-datauppsättning där källdata finns.
Ett mål-XDM-schema kan skapas genom att en POST-begäran till schemats register-API utförs.
Detaljerade steg om hur du skapar ett mål-XDM-schema finns i självstudiekursen Skapa ett schema med API:t.
Skapa en måldatauppsättning target-dataset
En måldatauppsättning kan skapas genom att en POST-begäran till katalogtjänstens API utförs, med ID:t för målschemat i nyttolasten.
Detaljerade steg om hur du skapar en måldatauppsättning finns i självstudiekursen Skapa en datauppsättning med API:t.
Skapa en målanslutning target-connection
En målanslutning representerar anslutningen till målet där inmatade data ska lagras. Om du vill skapa en målanslutning måste du ange det fasta anslutnings-spec-ID som motsvarar datasjön. Detta ID är: c604ff05-7f1a-43c0-8e18-33bf874cb11c.
Nu har du de unika identifierarna ett målschema, en måldatamängd och ett anslutningsspec-ID till datasjön. Med hjälp av dessa identifierare kan du skapa en målanslutning med API:t Flow Service för att ange den datauppsättning som ska innehålla inkommande källdata.
API-format
POST /targetConnections
Begäran
Följande begäran skapar en målanslutning för 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.dataSetIdSvar
Ett svar returnerar den nya målanslutningens unika identifierare (id). Detta ID krävs i senare steg.
{
"id": "382fc614-3c5b-46b9-a971-786fb0ae6c5d",
"etag": "\"e0016100-0000-0200-0000-655707a40000\""
}
Skapa en mappning mapping
För att källdata ska kunna hämtas till en måldatamängd måste den först mappas till målschemat som måldatamängden följer. Detta uppnås genom att utföra en POST-begäran till Data Prep API med datamappningar definierade i nyttolasten för begäran.
API-format
POST /conversion/mappingSets
Begäran
I följande begäran skapas en mappning för 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.destinationSvar
Ett lyckat svar returnerar information om den nyligen skapade mappningen inklusive dess unika identifierare (id). Detta värde krävs i ett senare steg för att skapa ett dataflöde.
{
"id": "ddf0592bcc9d4ac391803f15f2429f87",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Skapa ett flöde flow
Det sista steget mot att överföra data från Oracle NetSuite Entities till Experience Platform är att skapa ett dataflöde. Nu har du förberett följande obligatoriska värden:
Ett dataflöde ansvarar för att schemalägga och samla in data från en källa. Du kan skapa ett dataflöde genom att utföra en POST-begäran samtidigt som du anger de tidigare nämnda värdena i nyttolasten.
API-format
POST /flows
Begäran
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.intervalSvar
Ett lyckat svar returnerar ID:t (id) för det nyskapade dataflödet. Du kan använda det här ID:t för att övervaka, uppdatera eller ta bort dataflödet.
{
"id": "84c64142-1741-4b0b-95a9-65644eba0cf6",
"etag": "\"3901770b-0000-0200-0000-655708970000\""
}
Bilaga
Följande avsnitt innehåller information om hur du övervakar, uppdaterar och tar bort dataflödet.
Övervaka dataflödet
När dataflödet har skapats kan du övervaka de data som importeras genom det för att se information om flödeskörningar, slutförandestatus och fel. Fullständiga API-exempel finns i handboken om att övervaka källans dataflöden med API:t.
Uppdatera ditt dataflöde
Uppdatera informationen om dataflödet, till exempel namn och beskrivning, samt körningsschema och associerade mappningsuppsättningar genom att göra en PATCH-begäran till /flows-slutpunkten för Flow Service API, samtidigt som du anger ID:t för dataflödet. När du gör en PATCH-begäran måste du ange dataflödets unika etag i rubriken If-Match. Fullständiga API-exempel finns i guiden om att uppdatera källkodsdataflöden med API:t.
Uppdatera ditt konto
Uppdatera namn, beskrivning och autentiseringsuppgifter för källkontot genom att utföra en PATCH-begäran till Flow Service-API:t och ange ditt grundläggande anslutnings-ID som en frågeparameter. När du gör en PATCH-begäran måste du ange källkontots unika etag i rubriken If-Match. Fullständiga API-exempel finns i handboken Uppdatera ditt källkonto med API.
Ta bort ditt dataflöde
Ta bort dataflödet genom att utföra en DELETE-begäran till Flow Service-API:t och ange ID:t för det dataflöde som du vill ta bort som en del av frågeparametern. Fullständiga API-exempel finns i guiden om att ta bort dataflöden med API:t.
Ta bort ditt konto
Ta bort ditt konto genom att utföra en DELETE-begäran till Flow Service-API:t och ange det grundläggande anslutnings-ID:t för kontot som du vill ta bort. Fullständiga API-exempel finns i guiden om att ta bort ditt källkonto med API.