In diesem Tutorial werden die Schritte zum Abrufen von Daten aus einer Datenbankquelle und zum Übertragen dieser Daten in Platform mithilfe der Flow Service -API beschrieben.
Um einen Datenfluss zu erstellen, müssen Sie bereits über eine gültige Basis-Verbindungs-ID mit einer Datenbankquelle verfügen. Wenn Sie diese ID nicht haben, sehen Sie sich die Quellen - Übersicht für eine Liste von Datenbankquellen, mit denen Sie eine Basisverbindung erstellen können.
Dieses Tutorial setzt ein Grundverständnis der folgenden Komponenten von Adobe Experience Platform voraus:
{TENANT_ID}
, das Konzept sogenannter „Container“ und die für Anfragen erforderlichen Kopfzeilen, von denen insbesondere die Accept-Kopfzeile und deren mögliche Werte wichtig sind.Informationen darüber, wie Sie Platform-APIs erfolgreich aufrufen können, finden Sie im Handbuch unter Erste Schritte mit Platform-APIs.
Sie können eine Quellverbindung herstellen, indem Sie eine POST-Anfrage an die Flow Service-API senden. Eine Quellverbindung besteht aus einer Verbindungs-ID, einem Pfad zur Quelldatendatei und einer Verbindungsspezifikations-ID.
Um eine Quellverbindung zu erstellen, müssen Sie auch einen Aufzählungswert für das Datenformat-Attribut definieren.
Verwenden Sie die folgenden Aufzählungswerte für dateibasierte Connectoren:
Datenformat | Aufzählungswert |
---|---|
Durch Trennzeichen getrennt | delimited |
JSON | json |
Parquet | parquet |
Setzen Sie für alle tabellenbasierten Connectoren den Wert auf tabular
.
API-Format
POST /sourceConnections
Anfrage
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-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": "Database source connection",
"baseConnectionId": "6990abad-977d-41b9-a85d-17ea8cf1c0e4",
"description": "Database source connection",
"data": {
"format": "tabular"
},
"params": {
"tableName": "test1.Mytable",
"columns": [
{
"name": "TestID",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Name",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Datefield",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "3c9b37f8-13a6-43d8-bad3-b863b941fedd",
"version": "1.0"
}
}'
Eigenschaft | Beschreibung |
---|---|
baseConnectionId |
Die Verbindungs-ID Ihrer Datenbankquelle. |
params.path |
Der Pfad der Quelldatei. |
connectionSpec.id |
Die Verbindungsspezifikations-ID Ihrer Datenbankquelle. Eine Liste von Datenbankspezifikations-IDs finden Sie im Anhang. |
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Diese ID ist in späteren Schritten zum Erstellen einer Zielverbindung erforderlich.
{
"id": "b7581b59-c603-4df1-a689-d23d7ac440f3",
"etag": "\"ef05d265-0000-0200-0000-6019e0080000\""
}
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.
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.
Eine Zielverbindung stellt die Verbindung zum Ziel dar, in das die aufgenommenen Daten übernommen werden. Um eine Zielverbindung zu erstellen, müssen Sie die feste Verbindungsspezifikations-ID angeben, die mit dem Data Lake verknüpft ist. Diese Verbindungsspezifikations-ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Sie verfügen jetzt über die eindeutigen Kennungen, ein Zielschema, einen Zieldatensatz und die Verbindungsspezifikations-ID zum Data Lake. Mit der Flow Service-API können Sie eine Zielverbindung erstellen, indem Sie diese Bezeichner zusammen mit dem Datensatz angeben, der die eingehenden Quelldaten enthalten soll.
API-Format
POST /targetConnections
Anfrage
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": "Database target connection",
"description": "Database target connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "6019e0e7c5dcf718db5ebc71"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Eigenschaft | Beschreibung |
---|---|
data.schema.id |
Die $id des XDM-Zielschemas. |
data.schema.version |
Die Version des Schemas. Dieser Wert muss auf application/vnd.adobe.xed-full+json;version=1 festgelegt werden, wodurch die neueste Nebenversion des Schemas zurückgegeben wird. |
params.dataSetId |
Die Kennung des im vorherigen Schritt generierten Zieldatensatzes. Hinweis: Sie müssen beim Erstellen einer Zielverbindung eine gültige Datensatz-ID angeben. Eine ungültige Datensatz-ID führt zu einem Fehler. |
connectionSpec.id |
Die Verbindungsspezifikations-ID, die für die Verbindung mit dem Data Lake verwendet wird. Diese ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung der neuen Zielverbindung (id
) zurück. Dieser Wert ist in einem späteren Schritt zum Erstellen eines Datenflusses erforderlich.
{
"id": "320f119a-5ac1-4ab1-88ea-eb19e674ea2e",
"etag": "\"c0038936-0000-0200-0000-6019e1190000\""
}
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.
Um einen Zuordnungssatz zu erstellen, senden Sie eine POST-Anfrage an den mappingSets
-Endpunkt der Data Prep API, wobei Sie das Ziel-XDM-Schema $id
und die Details der Zuordnungssätze, die Sie erstellen möchten, angeben.
API-Format
POST /mappingSets
Anfrage
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 '{
"version": 0,
"xdmSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/52b59140414aa6a370ef5e21155fd7a686744b8739ecc168",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "_id",
"sourceAttribute": "TestID",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.fullName",
"sourceAttribute": "Name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.birthDate",
"sourceAttribute": "Datefield",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
Eigenschaft | Beschreibung |
---|---|
xdmSchema |
$id des XDM-Zielschemas. |
Antwort
Eine erfolgreiche Antwort gibt Details zur neu erstellten Zuordnung zurück, einschließlich der eindeutigen Kennung (id
). Diese ID ist in einem späteren Schritt erforderlich, um einen Datenfluss zu erstellen.
{
"id": "0b090130b58b4819afc78b6dc98b484d",
"version": 0,
"createdDate": 1612309018666,
"modifiedDate": 1612309018666,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Ein Datenfluss sorgt für die Erfassung von Daten aus Quellen und deren Aufnahme in Platform. Um einen Datenfluss zu erstellen, müssen Sie zunächst die Datenflussspezifikationen abrufen, indem Sie eine GET-Anfrage an die Flow Service-API senden. Datenflussspezifikationen sind für die Erfassung von Daten aus einer externen Datenbank oder einem NoSQL-System bestimmt.
API-Format
GET /flowSpecs?property=name=="CRMToAEP"
Anfrage
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name=="CRMToAEP"' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Antwort
Bei einer erfolgreichen Antwort werden die Details der Datenflussspezifikation zurückgegeben, die für die Übermittlung von Daten aus Ihrer Quelle an Platform sorgt. Die Antwort enthält die eindeutige Flussspezifikation id
, die erforderlich ist, um einen neuen Datenfluss zu erstellen.
Die nachstehende JSON-Antwort-Payload wird für die Kürze ausgeblendet. Wählen Sie "payload"aus, um die Antwort-Payload anzuzeigen.
{
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"name": "CRMToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"attributes": {
"isSourceFlow": true,
"flacValidationSupported": true,
"frequency": "batch",
"notification": {
"category": "sources",
"flowRun": {
"enabled": true
}
}
},
"sourceConnectionSpecIds": [
"3416976c-a9ca-4bba-901a-1f08f66978ff",
"38ad80fe-8b06-4938-94f4-d4ee80266b07",
"d771e9c1-4f26-40dc-8617-ce58c4b53702",
"3c9b37f8-13a6-43d8-bad3-b863b941fedd",
"cc6a4487-9e91-433e-a3a3-9cf6626c1806",
"3000eb99-cd47-43f3-827c-43caf170f015",
"26d738e0-8963-47ea-aadf-c60de735468a",
"74a1c565-4e59-48d7-9d67-7c03b8a13137",
"cfc0fee1-7dc0-40ef-b73e-d8b134c436f5",
"4f63aa36-bd48-4e33-bb83-49fbcd11c708",
"cb66ab34-8619-49cb-96d1-39b37ede86ea",
"eb13cb25-47ab-407f-ba89-c0125281c563",
"1f372ff9-38a4-4492-96f5-b9a4e4bd00ec",
"37b6bf40-d318-4655-90be-5cd6f65d334b",
"a49bcc7d-8038-43af-b1e4-5a7a089a7d79",
"221c7626-58f6-4eec-8ee2-042b0226f03b",
"a8b6a1a4-5735-42b4-952c-85dce0ac38b5",
"6a8d82bc-1caf-45d1-908d-cadabc9d63a6",
"aac9bbd4-6c01-46ce-b47e-51c6f0f6db3f",
"8e6b41a8-d998-4545-ad7d-c6a9fff406c3",
"ecde33f2-c56f-46cc-bdea-ad151c16cd69",
"102706fb-a5cd-42ee-afe0-bc42f017ff43",
"09182899-b429-40c9-a15a-bf3ddbc8ced7",
"0479cc14-7651-4354-b233-7480606c2ac3",
"d6b52d86-f0f8-475f-89d4-ce54c8527328",
"a8f4d393-1a6b-43f3-931f-91a16ed857f4",
"1fe283f6-9bec-11ea-bb37-0242ac130002",
"fcad62f3-09b0-41d3-be11-449d5a621b69",
"ea1c2a08-b722-11eb-8529-0242ac130003",
"35d6c4d8-c9a9-11eb-b8bc-0242ac130003",
"ff4274f2-c9a9-11eb-b8bc-0242ac130003",
"ba5126ec-c9ac-11eb-b8bc-0242ac130003",
"b2e08744-4f1a-40ce-af30-7abac3e23cf3",
"929e4450-0237-4ed2-9404-b7e1e0a00309",
"2acf109f-9b66-4d5e-bc18-ebb2adcff8d5",
"2fa8af9c-2d1a-43ea-a253-f00a00c74412"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
]
},
"optionSpec": {
"name": "OptionSpec",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"errorDiagnosticsEnabled": {
"title": "Error diagnostics.",
"description": "Flag to enable detailed and sample error diagnostics summary.",
"type": "boolean",
"default": false
},
"partialIngestionPercent": {
"title": "Partial ingestion threshold.",
"description": "Percentage which defines the threshold of errors allowed before the run is marked as failed.",
"type": "number",
"exclusiveMinimum": 0
}
}
}
},
"scheduleSpec": {
"name": "PeriodicSchedule",
"type": "Periodic",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"startTime": {
"description": "epoch time",
"type": "integer"
},
"frequency": {
"type": "string",
"enum": [
"once",
"minute",
"hour",
"day",
"week"
]
},
"interval": {
"type": "integer"
},
"backfill": {
"type": "boolean",
"default": true
}
},
"required": [
"startTime",
"frequency"
],
"if": {
"properties": {
"frequency": {
"const": "once"
}
}
},
"then": {
"allOf": [
{
"not": {
"required": [
"interval"
]
}
},
{
"not": {
"required": [
"backfill"
]
}
}
]
},
"else": {
"required": [
"interval"
],
"if": {
"properties": {
"frequency": {
"const": "minute"
}
}
},
"then": {
"properties": {
"interval": {
"minimum": 15
}
}
},
"else": {
"properties": {
"interval": {
"minimum": 1
}
}
}
}
}
},
"transformationSpec": [
{
"name": "Copy",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"properties": {
"deltaColumn": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"dateFormat": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"name"
]
}
},
"required": [
"deltaColumn"
]
}
},
{
"name": "Mapping",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for different mapping from source to target",
"properties": {
"mappingId": {
"type": "string"
},
"mappingVersion": {
"type": "string"
}
}
}
}
],
"runSpec": {
"name": "ProviderParams",
"spec": {
"$schema": "http://json-schema.org/draft-07/schema#",
"type": "object",
"description": "defines various params required for creating flow run.",
"properties": {
"startTime": {
"type": "integer",
"description": "An integer that defines the start time of the run. The value is represented in Unix epoch time."
},
"windowStartTime": {
"type": "integer",
"description": "An integer that defines the start time of the window against which data is to be pulled. The value is represented in Unix epoch time."
},
"windowEndTime": {
"type": "integer",
"description": "An integer that defines the end time of the window against which data is to be pulled. The value is represented in Unix epoch time."
},
"deltaColumn": {
"type": "object",
"description": "The delta column is required to partition the data and separate newly ingested data from historic data.",
"properties": {
"name": {
"type": "string"
},
"dateFormat": {
"type": "string"
},
"timezone": {
"type": "string"
}
},
"required": [
"name"
]
}
},
"required": [
"startTime",
"windowStartTime",
"windowEndTime",
"deltaColumn"
]
}
}
}
Der letzte Schritt bei der Datenerfassung besteht darin, einen Datenfluss zu erstellen. An dieser Stelle sollten die folgenden erforderlichen Werte bereits vorhanden sein:
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 Anfrage-Payload angeben.
Um eine Aufnahme zu planen, legen Sie zunächst den Startzeitwert auf die Epochenzeit in Sekunden fest. Anschließend müssen Sie den Frequenzwert auf eine der fünf Optionen festlegen: once
, minute
, hour
, day
oder week
. Der Intervallwert gibt den Zeitraum zwischen zwei aufeinanderfolgenden Aufnahmen an. Bei der Erstellung einer einmaligen Aufnahme ist kein Intervall erforderlich. Für alle anderen Frequenzen muss der Intervallwert auf gleich oder größer als 15
festgelegt werden.
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": "Database dataflow using BigQuery",
"description": "collecting test1.Mytable",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"b7581b59-c603-4df1-a689-d23d7ac440f3"
],
"targetConnectionIds": [
"320f119a-5ac1-4ab1-88ea-eb19e674ea2e"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "Datefield",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "0b090130b58b4819afc78b6dc98b484d",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1612310466",
"frequency":"minute",
"interval":"15",
"backfill": "true"
}
}'
+++
Eigenschaft | Beschreibung |
---|---|
flowSpec.id |
Die Flussspezifikations-ID, die im vorherigen Schritt abgerufen wurde. |
sourceConnectionIds |
Die Quellverbindungs-ID, die in einem früheren Schritt abgerufen wurde. |
targetConnectionIds |
Die Zielverbindungs-ID, die in einem früheren Schritt abgerufen wurde. |
transformations.params.mappingId |
Die Zuordnungs-ID, die in einem früheren Schritt abgerufen wurde. |
transformations.params.deltaColum |
Die Spalte, die verwendet wird, um zwischen neuen und vorhandenen Daten zu unterscheiden. Inkrementelle Daten werden basierend auf dem Zeitstempel der ausgewählten Spalte aufgenommen. Das unterstützte Datumsformat für deltaColumn ist yyyy-MM-dd HH:mm:ss . Wenn Sie Azure Table Storage verwenden, ist yyyy-MM-ddTHH:mm:ssZ das unterstützte Format für deltaColumn . |
transformations.params.mappingId |
Die mit Ihrer Datenbank verknüpfte Zuordnungs-ID. |
scheduleParams.startTime |
Die Startzeit für den Datenfluss in Epochenzeit. |
scheduleParams.frequency |
Die Häufigkeit, mit der der Datenfluss Daten erfasst. Zulässige Werte sind: once , minute , hour , day oder week . |
scheduleParams.interval |
Das Intervall bezeichnet den Zeitraum zwischen zwei aufeinanderfolgenden Datenflussausführungen. Der Wert des Intervalls sollte eine Ganzzahl ungleich null sein. Das Intervall ist nicht erforderlich, wenn die Häufigkeit auf once festgelegt ist, und sollte größer oder gleich 15 für andere Frequenzwerte sein. |
Antwort
Bei einer erfolgreichen Antwort wird die ID (id
) des neu erstellten Datenflusses angegeben.
{
"id": "2edc08ac-4df5-4fe6-936f-81a19ce92f5c",
"etag": "\"770029f8-0000-0200-0000-6019e7d40000\""
}
Nachdem Ihr Datenfluss erstellt wurde, können Sie die Datenaufnahme überwachen, um Informationen über die Datenflussausführungen, den Abschlussstatus und Fehler anzuzeigen. Weitere Informationen zum Überwachen von Datenflüssen finden Sie im Tutorial Überwachen von Datenflüssen in der API
In diesem Tutorial haben Sie einen Quell-Connector erstellt,um Daten aus einer Datenbank nach einem bestimmten Zeitplan zu erfassen. Eingehende Daten können jetzt von nachgelagerten Platform-Services wie Real-Time Customer Profile und Data Science Workspace verwendet werden. Weiterführende Informationen finden Sie in folgenden Dokumenten:
Im folgenden Abschnitt finden Sie die verschiedenen Quell-Connectoren für Cloud-Speicher und deren Verbindungsspezifikationen.
Connector-Name | Verbindungsspezifikations-ID |
---|---|
Amazon Redshift | 3416976c-a9ca-4bba-901a-1f08f66978ff |
Apache Hive auf Azure HDInsights | aac9bbd4-6c01-46ce-b47e-51c6f0f6db3f |
Apache Spark auf Azure HDInsights | 6a8d82bc-1caf-45d1-908d-cadabc9d63a6 |
Azure Data Explorer | 0479cc14-7651-4354-b233-7480606c2ac3 |
Azure Synapse Analytics | a49bcc7d-8038-43af-b1e4-5a7a089a7d79 |
Azure Table Storage | ecde33f2-c56f-46cc-bdea-ad151c16cd69 |
Couchbase | 1fe283f6-9bec-11ea-bb37-0242ac130002 |
Google BigQuery | 3c9b37f8-13a6-43d8-bad3-b863b941fedd |
Greenplum | 37b6bf40-d318-4655-90be-5cd6f65d334b |
IBM DB2 | 09182899-b429-40c9-a15a-bf3ddbc8ced7 |
MariaDB | 000eb99-cd47-43f3-827c-43caf170f015 |
Microsoft SQL Server | 1f372ff9-38a4-4492-96f5-b9a4e4bd00ec |
MySQL | 26d738e0-8963-47ea-aadf-c60de735468a |
Oracle | d6b52d86-f0f8-475f-89d4-ce54c8527328 |
Phoenix | 102706fb-a5cd-42ee-afe0-bc42f017ff43 |
PostgreSQL | 74a1c565-4e59-48d7-9d67-7c03b8a13137 |