[Beta]{class="badge informative"}
Erstellen Sie eine Quellverbindung und einen Datenfluss für Oracle NetSuite Entities Verwenden der Flow Service-API
In diesem Tutorial erfahren Sie, wie Sie Kontakte und Kundendaten aus Ihren Oracle NetSuite Activities Entities -Konto in Adobe Experience Platform mithilfe der Flow Service API.
Erste Schritte
Dieses Handbuch setzt ein Verständnis der folgenden Komponenten von Experience Platform voraus:
- Quellen: Experience Platform ermöglicht die Aufnahme von Daten aus verschiedenen Quellen und bietet Ihnen die Möglichkeit, die eingehenden Daten mithilfe von Platform-Services zu strukturieren, zu kennzeichnen und anzureichern.
- Sandboxes: Experience Platform bietet virtuelle Sandboxes, die eine einzelne Platform-Instanz in separate virtuelle Umgebungen unterteilen, damit Sie Programme für digitale Erlebnisse entwickeln und weiterentwickeln können.
Die folgenden Abschnitte enthalten zusätzliche Informationen, die Sie benötigen, um eine erfolgreiche Verbindung zu Oracle NetSuite Entities mithilfe der Flow Service API.
Authentifizierung
Lesen Sie die Oracle NetSuite Übersicht für Informationen zum Abrufen Ihrer Authentifizierungsberechtigungen.
Verwenden von Platform-APIs
Informationen darüber, wie Sie Platform-APIs erfolgreich aufrufen können, finden Sie im Handbuch unter Erste Schritte mit Platform-APIs.
Verbinden Oracle NetSuite Entities zur Plattform mithilfe der Flow Service API
Im Folgenden werden die Schritte beschrieben, die Sie zur Authentifizierung Ihrer Oracle NetSuite Entities -Quelle, erstellen Sie eine Quellverbindung und erstellen Sie einen Datenfluss, um Ihre Kunden- und Kontaktdaten an Experience Platform zu übertragen.
Erstellen einer Basisverbindung base-connection
Bei einer Basisverbindung werden Informationen zwischen Ihrer Quelle und Platform gespeichert, einschließlich der Authentifizierungsdaten Ihrer Quelle, des aktuellen Verbindungsstatus und Ihrer eindeutigen Kennung der Basisverbindung. Mit der Kennung der Basisverbindung können Sie Dateien aus Ihrer Quelle heraus analysieren und darin navigieren und die spezifischen Elemente identifizieren, die Sie erfassen möchten, einschließlich Informationen zu ihren Datentypen und Formaten.
Um eine Basis-Verbindungs-ID zu erstellen, stellen Sie eine POST-Anfrage an die /connections
Endpunkt beim Bereitstellen Oracle NetSuite Entities Authentifizierungsberechtigungen als Teil des Anfragetexts.
API-Format
POST /connections
Anfrage
Die folgende Anfrage erstellt eine Basisverbindung 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}"
}
}
}'
name
description
connectionSpec.id
auth.specName
auth.params.clientId
7fce.....b42f
.auth.params.clientSecret
5c98.....1b46
.auth.params.accessTokenUrl
https://{ACCOUNT_ID}.suitetalk.api.netsuite.com/services/rest/auth/oauth2/v1/token
wobei Sie ACCOUNT_ID durch Ihre NetSuite Konto-ID.auth.params.accessToken
eyJr......f4V0
.Antwort
Eine erfolgreiche Antwort gibt die neu erstellte Basisverbindung zurück, einschließlich ihrer eindeutigen Verbindungskennung (id
). Diese ID ist erforderlich, um die Dateistruktur und Inhalte Ihrer Quelle im nächsten Schritt zu untersuchen.
{
"id": "60c81023-99b4-4aae-9c31-472397576dd2",
"etag": "\"fa003785-0000-0200-0000-6555c5310000\""
}
Durchsuchen der Quelle explore
Sobald Sie über Ihre Basis-Verbindungs-ID verfügen, können Sie jetzt den Inhalt und die Struktur Ihrer Quelldaten analysieren, indem Sie eine GET-Anfrage an die /connections
-Endpunkt hinzugefügt, während Sie Ihre Basis-Verbindungs-ID als Abfrageparameter angeben.
API-Format
GET /connections/{BASE_CONNECTION_ID}/explore?objectType=rest&object={OBJECT}&fileType={FILE_TYPE}&preview={PREVIEW}&sourceParams={SOURCE_PARAMS}
Anfrage
Bei der Durchführung von GET-Anfragen zur Analyse der Dateistruktur und des Inhalts Ihrer Quelle müssen Sie die in der folgenden Tabelle aufgeführten Abfrageparameter einbeziehen:
{BASE_CONNECTION_ID}
objectType=rest
rest
.{OBJECT}
json
.fileType=json
json
ist der einzige unterstützte Dateityp.{PREVIEW}
{SOURCE_PARAMS}
Definiert Parameter für die Quelldatei, die Sie in Platform laden möchten. So rufen Sie den akzeptierten Formattyp für ab: {SOURCE_PARAMS}
müssen Sie die gesamte Zeichenfolge in base64 kodieren.
Oracle NetSuite Entities unterstützt sowohl den Abruf von Kunden- als auch Kontaktdaten. Übergeben Sie je nach dem von Ihnen verwendeten Objekttyp einen der folgenden Schritte:
customer
: Rufen Sie bestimmte Kundendaten ab, einschließlich Details wie Kundennamen, Adressen und Schlüsselkennungen.contact
: Rufen Sie Kontaktnamen, E-Mails, Telefonnummern und alle benutzerdefinierten Kontaktfelder ab, die mit Kunden verknüpft sind.
Für Oracle NetSuite Entities, um Kontaktdaten abzurufen, für die der Wert {SOURCE_PARAMS}
wird übergeben als {"object_type":"customer"}
. Bei der Kodierung in base64 entspricht es eyAib2JqZWN0X3R5cGUiOiAiY3VzdG9tZXIifQ%3D%3D
wie unten dargestellt.
code language-shell |
---|
|
Für Oracle NetSuite Entities, um Kontaktdaten abzurufen, für die der Wert {SOURCE_PARAMS}
wird übergeben als {"object_type":"contact"}
. Bei der Kodierung in base64 entspricht es eyAib2JqZWN0X3R5cGUiOiAiY29udGFjdCJ9
wie unten dargestellt.
code language-shell |
---|
|
Antwort
Je nachdem, welcher Objekttyp Sie verwenden, lautet die erhaltene Antwort wie folgt:
Eine erfolgreiche Antwort gibt eine Struktur zurück, wie unten dargestellt.
accordion | ||
---|---|---|
Auswählen zum Anzeigen der JSON-Payload | ||
|
Eine erfolgreiche Antwort gibt eine Struktur zurück, wie unten dargestellt.
accordion | ||
---|---|---|
Auswählen zum Anzeigen der JSON-Payload | ||
|
Erstellen einer Quellverbindung source-connection
Sie können eine Quellverbindung erstellen, indem Sie eine POST-Anfrage an die /sourceConnections
Endpunkt der Flow Service API. Eine Quellverbindung besteht aus einer Verbindungs-ID, einem Pfad zur Quelldatendatei und einer Verbindungsspezifikations-ID.
API-Format
POST /sourceConnections
Anfrage
Die folgende Anfrage erstellt eine Quellverbindung für Oracle NetSuite Entities:
Beim Abrufen von Kundendaten wird die object_type
Eigenschaftswert sollte customer
.
code language-shell |
---|
|
Beim Abrufen von Kontaktdaten wird die object_type
Eigenschaftswert sollte contact
.
code language-shell |
---|
|
name
description
baseConnectionId
connectionSpec.id
data.format
json
unterstützt.object_type
Oracle NetSuite Entities unterstützt sowohl den Abruf von Kunden als auch von Kontakten. Übergeben Sie je nach gewünschter Entität einen der folgenden Schritte:
customer
: Rufen Sie bestimmte Kundendaten ab, einschließlich Details wie Kundennamen, Adressen und Schlüsselkennungen.contact
: Rufen Sie Kontaktnamen, E-Mails, Telefonnummern und alle benutzerdefinierten Kontaktfelder ab, die mit Kunden verknüpft sind.
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Diese ID ist in einem späteren Schritt erforderlich, um einen Datenfluss zu erstellen.
{
"id": "574c049f-29fc-411f-be0d-f80002025f51",
"etag": "\"0704acb3-0000-0200-0000-6555c5470000\""
}
Erstellen eines XDM-Zielschemas target-schema
Damit die Quelldaten in Platform verwendet werden können, muss ein Zielschema erstellt werden, das die Quelldaten entsprechend Ihren Anforderungen strukturiert. Das Zielschema wird dann verwendet, um einen Platform-Datensatz zu erstellen, in dem die Quelldaten enthalten sind.
Ein Ziel-XDM-Schema kann erstellt werden, indem eine POST-Anfrage an die Schema-Registrierungs-API durchgeführt wird.
Ausführliche Schritte zum Erstellen eines XDM-Zielschemas finden Sie im Tutorial zum Erstellen eines Schemas mithilfe der API.
Erstellen eines Zieldatensatzes target-dataset
Ein Zieldatensatz kann erstellt werden, indem eine POST-Anfrage an die Catalog Service API durchgeführt wird, wodurch die ID des Zielschemas in der Payload angegeben wird.
Ausführliche Anweisungen zum Erstellen eines Zieldatensatzes finden Sie im Tutorial zu Erstellen eines Datensatzes mithilfe der API.
Erstellen einer Zielverbindung target-connection
Eine Zielverbindung stellt die Verbindung zum Ziel dar, an dem die aufgenommenen Daten gespeichert werden sollen. Um eine Zielverbindung zu erstellen, müssen Sie die feste Verbindungsspezifikations-ID angeben, die dem Data Lake entspricht. Diese ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Sie verfügen jetzt über die eindeutigen Kennungen eines Zielschemas, eines Zieldatensatzes und der Verbindungsspezifikations-ID zum Data Lake. Anhand dieser Kennungen können Sie mit der Flow Service-API eine Zielverbindung erstellen, um den Datensatz anzugeben, der die eingehenden Quelldaten enthalten wird.
API-Format
POST /targetConnections
Anfrage
Die folgende Anfrage erstellt eine Zielverbindung 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"
}
}'
name
description
connectionSpec.id
6b137bf6-d2a0-48c8-914b-d50f4942eb85
.data.format
params.dataSetId
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung der neuen Zielverbindung an (id
). Diese ID ist in späteren Schritten erforderlich.
{
"id": "382fc614-3c5b-46b9-a971-786fb0ae6c5d",
"etag": "\"e0016100-0000-0200-0000-655707a40000\""
}
Erstellen einer Zuordnung mapping
Damit die Quelldaten in einen Zieldatensatz aufgenommen werden können, müssen sie zunächst dem Zielschema zugeordnet werden, zu dem der Zieldatensatz gehört. Dies wird erreicht, indem eine POST-Anfrage an Data Prep API mit Datenzuordnungen, die in der Anfrage-Payload definiert sind.
API-Format
POST /conversion/mappingSets
Anfrage
Die folgende Anfrage erstellt eine Zuordnung 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.id
mappings.sourceType
mappings.source
mappings.destination
Antwort
Eine erfolgreiche Antwort gibt Details zur neu erstellten Zuordnung an, einschließlich der eindeutigen Kennung (id
). Dieser Wert ist in einem späteren Schritt zum Erstellen eines Datenflusses erforderlich.
{
"id": "ddf0592bcc9d4ac391803f15f2429f87",
"version": 0,
"createdDate": 1597784069368,
"modifiedDate": 1597784069368,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Erstellen eines Flusses flow
Der letzte Schritt zur Datenübermittlung von Oracle NetSuite Entities in Platform einen Datenfluss erstellen. Bislang haben Sie die folgenden erforderlichen Werte vorbereitet:
Ein Datenfluss ist für die Planung und Erfassung von Daten aus einer Quelle verantwortlich. Sie können einen Datenfluss erstellen, indem Sie eine POST-Anfrage ausführen und dabei die oben genannten Werte in der Payload angeben.
API-Format
POST /flows
Anfrage
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
6499120c-0b15-42dc-936e-847ea3c24d72
.flowSpec.version
1.0
festgelegt.sourceConnectionIds
targetConnectionIds
transformations
transformations.name
transformations.params.mappingId
transformations.params.mappingVersion
0
festgelegt.scheduleParams.startTime
scheduleParams.frequency
scheduleParams.interval
Antwort
Bei einer erfolgreichen Antwort wird die ID (id
) des neu erstellten Datenflusses angegeben. Mit dieser ID können Sie Ihren Datenfluss überwachen, aktualisieren oder löschen.
{
"id": "84c64142-1741-4b0b-95a9-65644eba0cf6",
"etag": "\"3901770b-0000-0200-0000-655708970000\""
}
Anhang
Im folgenden Abschnitt finden Sie Informationen zu den Schritten, mit denen Sie Ihren Datenfluss überwachen, aktualisieren und löschen können.
Überwachen Ihres Datenflusses
Nachdem Ihr Datenfluss erstellt wurde, können Sie die Datenaufnahme überwachen, um Informationen über die Datenflussausführungen, den Abschlussstatus und Fehler anzuzeigen. Die vollständigen API-Beispiele finden Sie im Handbuch unter Überwachen der Datenflüsse Ihrer Quellen mithilfe der API.
Aktualisieren des Datenflusses
Aktualisieren Sie die Details Ihres Datenflusses, z. B. seinen Namen und seine Beschreibung, sowie den Ausführungszeitplan und die zugehörigen Zuordnungssätze, indem Sie eine PATCH-Anfrage an die /flows
Endpunkt von Flow Service API verwenden, während Sie die Kennung Ihres Datenflusses angeben. Bei einer PATCH-Anfrage müssen Sie die eindeutige etag
im If-Match
-Kopfzeile. Die vollständigen API-Beispiele finden Sie im Handbuch unter Aktualisieren von Datenflüssen für Quellen mithilfe der API.
Konto aktualisieren
Aktualisieren Sie den Namen, die Beschreibung und die Anmeldeinformationen Ihres Quellkontos, indem Sie eine PATCH-Anfrage an die Flow Service API bei der Bereitstellung Ihrer Basis-Verbindungs-ID als Abfrageparameter. Bei einer PATCH-Anfrage müssen Sie die eindeutige etag
im If-Match
-Kopfzeile. Die vollständigen API-Beispiele finden Sie im Handbuch unter Aktualisieren Ihres Quellkontos mithilfe der API.
Löschen des Datenflusses
Löschen Sie Ihren Datenfluss, indem Sie eine DELETE-Anfrage an die Flow Service API bei Angabe der Kennung des Datenflusses, den Sie als Teil des Abfrageparameters löschen möchten. Die vollständigen API-Beispiele finden Sie im Handbuch unter Löschen Ihrer Datenflüsse mithilfe der API.
Konto löschen
Löschen Sie Ihr Konto, indem Sie eine DELETE-Anfrage an die Flow Service API bei Angabe der grundlegenden Verbindungs-ID des Kontos, das Sie löschen möchten. Die vollständigen API-Beispiele finden Sie im Handbuch unter Löschen Ihres Quellkontos mithilfe der API.