In diesem Tutorial werden die Schritte zum Abrufen von Daten aus dem Werbeprogramm eines Drittanbieters und deren Aufnahme in Adobe Experience Platform über Quell-Connectoren sowie die Flow Service-API behandelt.
Um einen Datenfluss zu erstellen, müssen Sie bereits über eine gültige Basis-Verbindungs-ID mit einer Werbequelle verfügen. Wenn Sie diese ID nicht haben, sehen Sie sich die Quellen - Übersicht für eine Liste von Werbequellen, 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": "Google AdWords source connection",
"baseConnectionId": "2484f2df-c057-4ab5-84f2-dfc0577ab592",
"description": "Google AdWords source connection",
"data": {
"format": "tabular",
},
"params": {
"tableName": "v201809.AD_PERFORMANCE_REPORT",
"columns": [
{
"name": "CallOnlyPhoneNumber",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "AdGroupId",
"type": "long",
"xdm": {
"type": "integer",
"minimum": -9007199254740992,
"maximum": 9007199254740991
}
},
{
"name": "AdGroupName",
"type": "string",
"xdm": {
"type": "string"
}
},
{
"name": "Date",
"type": "string",
"meta:xdmType": "date-time",
"xdm": {
"type": "string",
"format": "date-time"
}
}
]
},
"connectionSpec": {
"id": "d771e9c1-4f26-40dc-8617-ce58c4b53702",
"version": "1.0"
}
}'
Eigenschaft | Beschreibung |
---|---|
baseConnectionId |
Die eindeutige Verbindungs-ID des Werbeprogramms, auf das Sie zugreifen. |
params.path |
Der Pfad der Quelldatei. |
connectionSpec.id |
Die mit Ihrem Werbeprogramm verknüpfte Verbindungsspezifikations-ID. |
Antwort
Eine erfolgreiche Antwort gibt die eindeutige Kennung (id
) der neu erstellten Quellverbindung zurück. Speichern Sie diesen Wert, da er in späteren Schritten zum Erstellen einer Zielverbindung erforderlich ist.
{
"id": "ca7b8baa-587e-4223-bb8b-aa587e4223e3",
"etag": "\"5701cdf0-0000-0200-0000-5e9680af0000\""
}
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 festgelegte Verbindungsspezifikations-ID angeben, die dem Data Lake zugeordnet 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": "Google AdWords target connection,
"description": "Google AdWords target connection,
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/b9bf50e91f28528e5213c7ed8583018f48970d69040c37dc",
"version": "application/vnd.adobe.xed-full+json;version=1"
}
},
"params": {
"dataSetId": "5e9681e389b80418ad4b3df0"
},
"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 Zieldatensatzes. |
connectionSpec.id |
Die Verbindungsspezifikations-ID, die für die Verbindung mit dem Data Lake verwendet wird. Diese ID lautet: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
{
"id": "41af25df-cd99-4372-af25-dfcd99b37291",
"etag": "\"4d01178a-0000-0200-0000-5e9683380000\""
}
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 /conversion/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/b9bf50e91f28528e5213c7ed8583018f48970d69040c37dc",
"xdmVersion": "1.0",
"id": null,
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "first_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "last_name",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
},
{
"destinationXdmPath": "personalEmail.address",
"sourceAttribute": "email",
"identity": false,
"identityGroup": null,
"namespaceCode": null,
"version": 0
}
]
}'
Eigenschaft | Beschreibung |
---|---|
xdmSchema |
Die ID des XDM-Zielschemas. |
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": "febec6a6785e45ea9ed594422cc483d7",
"version": 0,
"createdDate": 1589398562232,
"modifiedDate": 1589398562232,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Ein Datenfluss ist für die Erfassung von Daten aus Quellen und deren Aufnahme in Platform zuständig. Um einen Datenfluss zu erstellen, müssen Sie zunächst die Datenflussspezifikationen abrufen, die für die Erfassung von Werbedaten zuständig sind.
API-Format
GET /flowSpecs?property=name=="CRMToAEP"
Anfrage
curl -X GET \
'https://platform.adobe.io/data/foundation/flowservice/flowSpecs?property=name==%22CRMToAEP%22' \
-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 zur Erfassung von Werbedaten besteht in der Erstellung eines Datenflusses. 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.
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": "Google AdWords dataflow",
"description": "Google AdWords dataflow",
"flowSpec": {
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"version": "1.0"
},
"sourceConnectionIds": [
"ca7b8baa-587e-4223-bb8b-aa587e4223e3"
],
"targetConnectionIds": [
"41af25df-cd99-4372-af25-dfcd99b37291"
],
"transformations": [
{
"name": "Copy",
"params": {
"deltaColumn": {
"name": "updatedAt",
"dateFormat": "YYYY-MM-DD",
"timezone": "UTC"
}
}
},
{
"name": "Mapping",
"params": {
"mappingId": "febec6a6785e45ea9ed594422cc483d7",
"mappingVersion": 0
}
}
],
"scheduleParams": {
"startTime": "1567411548",
"frequency":"minute",
"interval":"30"
}
}'
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 . |
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": "e0bd8463-0913-4ca1-bd84-6309134ca1f6",
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
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
Mithilfe dieses Tutorials haben Sie einen Quell-Connector erstellt, um Daten aus einem Werbesystem nach einem festgelegtem 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: