[Beta]{class="badge informative"}
Creare una connessione di origine e un flusso di dati per Oracle NetSuite Entities utilizzando l'API del servizio Flusso
Leggi l'esercitazione seguente per scoprire come portare i contatti e i dati dei clienti dal tuo account Oracle NetSuite Activities Entities a Adobe Experience Platform utilizzando Flow Service API.
Introduzione
Questa guida richiede una buona conoscenza dei seguenti componenti di Experience Platform:
- Origini: Experience Platform consente di acquisire dati da varie origini e allo stesso tempo di strutturare, etichettare e migliorare i dati in arrivo tramite i servizi di Platform.
- Sandbox: Experience Platform fornisce sandbox virtuali che suddividono una singola istanza Platform in ambienti virtuali separati, utili per le attività di sviluppo e aggiornamento delle applicazioni di esperienza digitale.
Le sezioni seguenti forniscono informazioni aggiuntive che è necessario conoscere per connettersi correttamente a Oracle NetSuite Entities utilizzando l'API Flow Service.
Autenticazione
Leggi la Oracle NetSuite panoramica per informazioni su come recuperare le credenziali di autenticazione.
Utilizzo delle API di Platform
Per informazioni su come effettuare correttamente chiamate alle API di Platform, consulta la guida in guida introduttiva alle API di Platform.
Connetti Oracle NetSuite Entities a Platform utilizzando l'API Flow Service
Di seguito vengono descritti i passaggi necessari per autenticare l'origine Oracle NetSuite Entities, creare una connessione di origine e creare un flusso di dati per portare in Experience Platform i dati di clienti e contatti.
Creare una connessione di base base-connection
Una connessione di base mantiene le informazioni tra l’origine e Platform, incluse le credenziali di autenticazione dell’origine, lo stato corrente della connessione e l’ID univoco della connessione di base. L’ID della connessione di base consente di esplorare e navigare tra i file dall’interno dell’origine e identificare gli elementi specifici che desideri acquisire, comprese le informazioni relative ai tipi di dati e ai formati.
Per creare un ID di connessione di base, effettuare una richiesta POST all'endpoint /connections fornendo le credenziali di autenticazione Oracle NetSuite Entities come parte del corpo della richiesta.
Formato API
POST /connections
Richiesta
La richiesta seguente crea una connessione di base per 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, in cui sostituirai ACCOUNT_ID con l'ID account NetSuite.auth.params.accessTokeneyJr......f4V0.Risposta
In caso di esito positivo, la risposta restituisce la connessione di base appena creata, incluso il relativo identificatore univoco di connessione (id). Questo ID è necessario per esplorare la struttura e il contenuto del file sorgente nel passaggio successivo.
{
"id": "60c81023-99b4-4aae-9c31-472397576dd2",
"etag": "\"fa003785-0000-0200-0000-6555c5310000\""
}
Esplora l’origine explore
Una volta ottenuto l'ID connessione di base, è ora possibile esplorare il contenuto e la struttura dei dati di origine eseguendo una richiesta di GET all'endpoint /connections e fornendo l'ID connessione di base come parametro di query.
Formato API
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Richiesta
Quando si eseguono richieste di GET per esplorare la struttura e il contenuto dei file dell’origine, è necessario includere i parametri di query elencati nella tabella seguente:
{BASE_CONNECTION_ID}objectType=restrest.{OBJECT}json.fileType=jsonjson è l'unico tipo di file supportato.{PREVIEW}{SOURCE_PARAMS}Definisce i parametri per il file sorgente da portare a Platform. Per recuperare il tipo di formato accettato per {SOURCE_PARAMS}, è necessario codificare l'intera stringa in base64.
Oracle NetSuite Entities supporta sia il recupero dei dati dei clienti che dei contatti. A seconda del tipo di oggetto utilizzato, passare una delle seguenti operazioni:
customer: recupera dati cliente specifici, inclusi dettagli quali nomi cliente, indirizzi e identificatori chiave.contact: Recupera i nomi dei contatti, le e-mail, i numeri di telefono ed eventuali campi personalizzati relativi ai contatti associati ai clienti.
Per Oracle NetSuite Entities, per recuperare i dati di contatto il valore per {SOURCE_PARAMS} è passato come {"object_type":"customer"}. Codificato in base64, equivale a eyAib2JqZWN0X3R5cGUiOiAiY3VzdG9tZXIifQ%3D%3D come mostrato di seguito.
| code language-shell |
|---|
|
Per Oracle NetSuite Entities, per recuperare i dati di contatto il valore per {SOURCE_PARAMS} è passato come {"object_type":"contact"}. Codificato in base64, equivale a eyAib2JqZWN0X3R5cGUiOiAiY29udGFjdCJ9 come mostrato di seguito.
| code language-shell |
|---|
|
Risposta
Analogamente, a seconda del tipo di oggetto che si sta sfruttando la risposta ricevuta, è il seguente:
In caso di esito positivo, la risposta restituisce una struttura come indicato di seguito.
| accordion | ||
|---|---|---|
| Seleziona per visualizzare il payload JSON | ||
|
In caso di esito positivo, la risposta restituisce una struttura come indicato di seguito.
| accordion | ||
|---|---|---|
| Seleziona per visualizzare il payload JSON | ||
|
Creare una connessione sorgente source-connection
È possibile creare una connessione di origine effettuando una richiesta POST all'endpoint /sourceConnections dell'API Flow Service. Una connessione di origine è costituita da un ID di connessione, un percorso del file di dati di origine e un ID della specifica di connessione.
Formato API
POST /sourceConnections
Richiesta
La richiesta seguente crea una connessione di origine per Oracle NetSuite Entities:
Quando si recuperano i dati del cliente, il valore della proprietà object_type deve essere customer.
| code language-shell |
|---|
|
Durante il recupero dei dati di contatto, il valore della proprietà object_type deve essere contact.
| code language-shell |
|---|
|
namedescriptionbaseConnectionIdconnectionSpec.iddata.formatjson.object_typeOracle NetSuite Entities supporta il recupero di clienti e contatti. A seconda dell’entità desiderata, passa una delle seguenti opzioni:
customer: recupera dati cliente specifici, inclusi dettagli quali nomi cliente, indirizzi e identificatori chiave.contact: Recupera i nomi dei contatti, le e-mail, i numeri di telefono ed eventuali campi personalizzati relativi ai contatti associati ai clienti.
Risposta
In caso di esito positivo, la risposta restituisce l'identificatore univoco (id) della connessione di origine appena creata. Questo ID è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "574c049f-29fc-411f-be0d-f80002025f51",
"etag": "\"0704acb3-0000-0200-0000-6555c5470000\""
}
Creare uno schema XDM di destinazione target-schema
Per utilizzare i dati sorgente in Platform, è necessario creare uno schema di destinazione che strutturi i dati sorgente in base alle tue esigenze. Lo schema di destinazione viene quindi utilizzato per creare un set di dati di Platform in cui sono contenuti i dati di origine.
È possibile creare uno schema XDM di destinazione eseguendo una richiesta POST all'API Schema Registry.
Per i passaggi dettagliati su come creare uno schema XDM di destinazione, consulta l'esercitazione su creazione di uno schema utilizzando l'API.
Creare un set di dati di destinazione target-dataset
È possibile creare un set di dati di destinazione eseguendo una richiesta POST all'API Catalog Service, fornendo l'ID dello schema di destinazione all'interno del payload.
Per i passaggi dettagliati su come creare un set di dati di destinazione, consulta l'esercitazione su creazione di un set di dati utilizzando l'API.
Creare una connessione di destinazione target-connection
Una connessione di destinazione rappresenta la connessione alla destinazione in cui devono essere memorizzati i dati acquisiti. Per creare una connessione di destinazione, devi fornire l’ID della specifica di connessione fissa che corrisponde al data lake. ID: c604ff05-7f1a-43c0-8e18-33bf874cb11c.
Ora disponi degli identificatori univoci, di uno schema di destinazione, di un set di dati di destinazione e dell’ID della specifica di connessione al data lake. Utilizzando questi identificatori, è possibile creare una connessione di destinazione utilizzando l'API Flow Service per specificare il set di dati che conterrà i dati di origine in entrata.
Formato API
POST /targetConnections
Richiesta
La richiesta seguente crea una connessione di destinazione per 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.dataSetIdRisposta
Una risposta corretta restituisce l'identificatore univoco della nuova connessione di destinazione (id). Questo ID è richiesto nei passaggi successivi.
{
"id": "382fc614-3c5b-46b9-a971-786fb0ae6c5d",
"etag": "\"e0016100-0000-0200-0000-655707a40000\""
}
Creare una mappatura mapping
Per poter acquisire i dati di origine in un set di dati di destinazione, è necessario prima mapparli sullo schema di destinazione a cui il set di dati di destinazione aderisce. Ciò si ottiene eseguendo una richiesta POST all'API Data Prep API con mappature dati definite nel payload della richiesta.
Formato API
POST /conversion/mappingSets
Richiesta
La richiesta seguente crea una mappatura per 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.destinationRisposta
In caso di esito positivo, la risposta restituisce i dettagli della mappatura appena creata, incluso il relativo identificatore univoco (id). Questo valore è necessario in un passaggio successivo per creare un flusso di dati.
{
"id": "ddf0592bcc9d4ac391803f15f2429f87",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Creare un flusso flow
L'ultimo passaggio per portare i dati da Oracle NetSuite Entities a Platform consiste nel creare un flusso di dati. A questo punto sono stati preparati i seguenti valori obbligatori:
Un flusso di dati è responsabile della pianificazione e della raccolta di dati da un’origine. Puoi creare un flusso di dati eseguendo una richiesta POST e fornendo i valori precedentemente menzionati all’interno del payload.
Formato API
POST /flows
Richiesta
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.intervalRisposta
In caso di esito positivo, la risposta restituisce l'ID (id) del flusso di dati appena creato. Puoi usare questo ID per monitorare, aggiornare o eliminare il flusso di dati.
{
"id": "84c64142-1741-4b0b-95a9-65644eba0cf6",
"etag": "\"3901770b-0000-0200-0000-655708970000\""
}
Appendice
La sezione seguente fornisce informazioni sui passaggi possibili per monitorare, aggiornare ed eliminare il flusso di dati.
Monitorare il flusso di dati
Una volta creato il flusso di dati, puoi monitorare i dati che vengono acquisiti tramite di esso per visualizzare informazioni sulle esecuzioni del flusso, sullo stato di completamento e sugli errori. Per esempi API completi, consulta la guida su monitoraggio dei flussi di dati di origine tramite API.
Aggiornare il flusso di dati
Aggiorna i dettagli del flusso di dati, ad esempio il nome e la descrizione, nonché la pianificazione dell'esecuzione e i set di mappatura associati, effettuando una richiesta PATCH all'endpoint /flows dell'API Flow Service e fornendo al contempo l'ID del flusso di dati. Quando si effettua una richiesta PATCH, è necessario fornire etag univoco del flusso di dati nell'intestazione If-Match. Per esempi API completi, leggere la guida sull'aggiornamento dei flussi di dati di origine in tramite API.
Aggiornare l’account
Aggiornare il nome, la descrizione e le credenziali dell'account di origine eseguendo una richiesta PATCH all'API Flow Service e fornendo l'ID connessione di base come parametro di query. Quando si effettua una richiesta PATCH, è necessario fornire etag univoco dell'account di origine nell'intestazione If-Match. Per esempi API completi, consulta la guida in aggiornamento dell'account di origine tramite l'API.
Eliminare il flusso di dati
Elimina il flusso di dati eseguendo una richiesta DELETE all'API Flow Service e fornendo l'ID del flusso di dati che desideri eliminare come parte del parametro di query. Per esempi API completi, consulta la guida su eliminazione dei flussi di dati tramite l'API.
Elimina l’account
Eliminare l'account eseguendo una richiesta DELETE all'API Flow Service e fornendo l'ID connessione di base dell'account che si desidera eliminare. Per esempi API completi, leggere la guida in eliminazione dell'account di origine tramite l'API.