Este tutorial trata los pasos para recuperar datos de una aplicación publicitaria de terceros e ingerirlos en Adobe Experience Platform a través de conectores de origen y el Flow Service API.
Para crear un flujo de datos, ya debe tener un ID de conexión base válido con un origen publicitario. Si no tiene este ID, consulte la información general sobre fuentes para obtener una lista de las fuentes publicitarias con las que puede crear una conexión base.
Este tutorial requiere tener una comprensión práctica de los siguientes componentes de Adobe Experience Platform:
{TENANT_ID}
, el concepto de "contenedores" y los encabezados requeridos para realizar solicitudes (con especial atención al encabezado Accept y sus posibles valores).Para obtener información sobre cómo realizar llamadas correctamente a las API de Platform, consulte la guía de introducción a las API de Platform.
Puede crear una conexión de origen realizando una solicitud de POST al Flow Service API. Una conexión de origen consiste en un ID de conexión, una ruta al archivo de datos de origen y un ID de especificación de conexión.
Para crear una conexión de origen, también debe definir un valor de enumeración para el atributo de formato de datos.
Utilice los siguientes valores de enumeración para conectores basados en archivos:
Formato de datos | Valor de enumeración |
---|---|
Delimitado | delimited |
JSON | json |
Parqué | parquet |
Para todos los conectores basados en tablas, establezca el valor en tabular
.
Formato de API
POST /sourceConnections
Solicitud
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"
}
}'
Propiedad | Descripción |
---|---|
baseConnectionId |
ID de conexión único de la aplicación publicitaria a la que está accediendo. |
params.path |
Ruta del archivo de origen. |
connectionSpec.id |
El ID de especificación de conexión asociado a la aplicación publicitaria. |
Respuesta
Una respuesta correcta devuelve el identificador único (id
) de la conexión de origen recién creada. Almacene este valor tal como es necesario en pasos posteriores para crear una conexión de destino.
{
"id": "ca7b8baa-587e-4223-bb8b-aa587e4223e3",
"etag": "\"5701cdf0-0000-0200-0000-5e9680af0000\""
}
Para que los datos de origen se utilicen en Platform, se debe crear un esquema de destino para estructurar los datos de origen según sus necesidades. A continuación, el esquema de destino se utiliza para crear un conjunto de datos de Platform en el que se contienen los datos de origen.
Se puede crear un esquema XDM de destino realizando una solicitud de POST al API del Registro de esquemas.
Para ver los pasos detallados sobre cómo crear un esquema XDM de destino, consulte el tutorial sobre creación de un esquema con la API.
Se puede crear un conjunto de datos de destino realizando una solicitud de POST al API del servicio de catálogo, que proporciona el ID del esquema de destino dentro de la carga útil.
Para ver los pasos detallados sobre cómo crear un conjunto de datos de destinatario, consulte el tutorial en creación de un conjunto de datos mediante la API.
Una conexión de destino representa la conexión con el destino en el que llegan los datos introducidos. Para crear una conexión de destino, debe proporcionar el ID de especificación de conexión fija asociado al lago de datos. Este ID de especificación de conexión es: c604ff05-7f1a-43c0-8e18-33bf874cb11c
.
Ahora tiene los identificadores únicos, un esquema de destino, un conjunto de datos de destino y el ID de especificación de conexión a un lago de datos. Al usar la variable Flow Service API, puede crear una conexión de destino especificando estos identificadores junto con el conjunto de datos que contendrán los datos de origen entrantes.
Formato de API
POST /targetConnections
Solicitud
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"
}
}'
Propiedad | Descripción |
---|---|
data.schema.id |
La variable $id del esquema XDM de destino. |
data.schema.version |
Versión del esquema. Este valor debe establecerse application/vnd.adobe.xed-full+json;version=1 , que devuelve la última versión secundaria del esquema. |
params.dataSetId |
El ID del conjunto de datos de destino. |
connectionSpec.id |
El ID de especificación de conexión utilizado para conectarse al lago de datos. Este ID es: c604ff05-7f1a-43c0-8e18-33bf874cb11c . |
{
"id": "41af25df-cd99-4372-af25-dfcd99b37291",
"etag": "\"4d01178a-0000-0200-0000-5e9683380000\""
}
Para que los datos de origen se introduzcan en un conjunto de datos de destino, primero deben asignarse al esquema de destino al que se adhiera el conjunto de datos de destino.
Para crear un conjunto de asignaciones, realice una solicitud de POST al mappingSets
punto final del Data Prep API al proporcionar el esquema XDM de destino $id
y los detalles de los conjuntos de asignación que desea crear.
Formato de API
POST /conversion/mappingSets
Solicitud
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
}
]
}'
Propiedad | Descripción |
---|---|
xdmSchema |
El ID del esquema XDM de destino. |
Respuesta
Una respuesta correcta devuelve detalles de la asignación recién creada, incluido su identificador único (id
). Este valor es necesario en un paso posterior para crear un flujo de datos.
{
"id": "febec6a6785e45ea9ed594422cc483d7",
"version": 0,
"createdDate": 1589398562232,
"modifiedDate": 1589398562232,
"createdBy": "{CREATED_BY}",
"modifiedBy": "{MODIFIED_BY}"
}
Un flujo de datos es responsable de recopilar datos de las fuentes y traerlos a Platform. Para crear un flujo de datos, primero debe obtener las especificaciones de flujo de datos responsables de recopilar datos publicitarios.
Formato de API
GET /flowSpecs?property=name=="CRMToAEP"
Solicitud
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}'
Respuesta
Una respuesta correcta devuelve los detalles de la especificación de flujo de datos responsable de traer los datos de su origen a Platform. La respuesta incluye la especificación de flujo único id
necesario para crear un nuevo flujo de datos.
{
"items": [
{
"id": "14518937-270c-4525-bdec-c2ba7cce3860",
"name": "CRMToAEP",
"providerId": "0ed90a81-07f4-4586-8190-b40eccef1c5a",
"version": "1.0",
"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"
],
"targetConnectionSpecIds": [
"c604ff05-7f1a-43c0-8e18-33bf874cb11c"
],
"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
}
}
}
},
"transformationSpecs": [
{
"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"
}
}
}
}
],
"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
}
}
}
}
}
},
"attributes": {
"notification": {
"category": "sources",
"flowRun": {
"enabled": true
}
}
},
"permissionsInfo": {
"view": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"read"
]
}
],
"manage": [
{
"@type": "lowLevel",
"name": "EnterpriseSource",
"permissions": [
"write"
]
}
]
}
}
]
}
El último paso para recopilar datos publicitarios es crear un flujo de datos. A partir de ahora, se han preparado los siguientes valores obligatorios:
Un flujo de datos es responsable de programar y recopilar datos de un origen. Puede crear un flujo de datos realizando una solicitud de POST mientras proporciona los valores mencionados anteriormente dentro de la carga útil.
Para programar una ingesta, primero debe establecer el valor de la hora de inicio en hora de inicio en segundos. A continuación, debe establecer el valor de frecuencia en una de las cinco opciones: once
, minute
, hour
, day
o week
. El valor de intervalo designa el periodo entre dos ingestas consecutivas y la creación de una ingesta única no requiere que se establezca un intervalo. Para las demás frecuencias, el valor del intervalo debe establecerse en igual o bueno que 15
.
Formato de API
POST /flows
Solicitud
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"
}
}'
Propiedad | Descripción |
---|---|
flowSpec.id |
La variable ID de especificación de flujo recuperado en el paso anterior. |
sourceConnectionIds |
La variable ID de conexión de origen recuperado en un paso anterior. |
targetConnectionIds |
La variable ID de conexión de target recuperado en un paso anterior. |
transformations.params.mappingId |
La variable ID de asignación recuperado en un paso anterior. |
transformations.params.deltaColum |
La columna designada se utiliza para diferenciar entre datos nuevos y existentes. Los datos incrementales se incorporarán en función de la marca de tiempo de la columna seleccionada. El formato de fecha admitido para deltaColumn es yyyy-MM-dd HH:mm:ss . |
transformations.params.mappingId |
ID de asignación asociado a la base de datos. |
scheduleParams.startTime |
Hora de inicio del flujo de datos en tiempo de época. |
scheduleParams.frequency |
Frecuencia con la que el flujo de datos recopilará datos. Los valores aceptables incluyen: once , minute , hour , day o week . |
scheduleParams.interval |
El intervalo designa el periodo entre dos ejecuciones de flujo consecutivas. El valor del intervalo debe ser un número entero distinto de cero. El intervalo no es necesario cuando la frecuencia está establecida como once y debe ser bueno o igual que 15 para otros valores de frecuencia. |
Respuesta
Una respuesta correcta devuelve el ID (id
) del flujo de datos recién creado.
{
"id": "e0bd8463-0913-4ca1-bd84-6309134ca1f6",
"etag": "\"04004fe9-0000-0200-0000-5ebc4c8b0000\""
}
Una vez creado el flujo de datos, puede supervisar los datos que se están incorporando a través de él para ver información sobre ejecuciones de flujo, estado de finalización y errores. Para obtener más información sobre cómo monitorizar los flujos de datos, consulte el tutorial en monitorización de flujos de datos en la API
Siguiendo este tutorial, ha creado un conector de origen para recopilar datos de un sistema de publicidad de forma programada. Los datos entrantes ahora se pueden usar en servicios de Platform descendentes como Real-time Customer Profile y Data Science Workspace. Consulte los siguientes documentos para obtener más información: