Crear una conexión de flujo continuo de API HTTP mediante la API Flow Service
Creado para:
- Desarrollador
Flow Service se utiliza para recopilar y centralizar datos de clientes de diferentes fuentes dentro de Adobe Experience Platform. El servicio proporciona una interfaz de usuario y una API RESTful desde las que se pueden conectar todas las fuentes de datos admitidas.
Este tutorial usa la Flow Service API para guiarle por los pasos para crear una conexión de flujo continuo usando la API Flow Service.
Introducción
Esta guía requiere una comprensión práctica de los siguientes componentes de Adobe Experience Platform:
- Experience Data Model (XDM): el marco estandarizado mediante el cual Experience Platform organiza los datos de experiencia.
- Real-Time Customer Profile: proporciona un perfil de consumidor unificado en tiempo real en función de los datos agregados de varios orígenes.
Además, la creación de una conexión de flujo continuo requiere que tenga un esquema XDM de destino y un conjunto de datos. Para aprender a crearlos, lea el tutorial sobre datos de registros de transmisión o el tutorial sobre datos de series de tiempo de transmisión.
Uso de API de Experience Platform
Para obtener información sobre cómo realizar llamadas correctamente a las API de Experience Platform, consulte la guía sobre introducción a las API de Experience Platform.
Crear una conexión base
Una conexión base especifica el origen y contiene la información necesaria para que el flujo sea compatible con las API de ingesta de flujo continuo. Al crear una conexión base, tiene la opción de crear una conexión no autenticada y autenticada.
Conexión no autenticada
Las conexiones no autenticadas son la conexión de flujo continuo estándar que puede crear cuando desea transmitir datos a Experience Platform.
Para crear una conexión base no autenticada, realice una petición POST al extremo /connections y proporcione un nombre para la conexión, el tipo de datos y el identificador de especificación de la conexión HTTP API. Este identificador es bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb.
Formato de API
POST /flowservice/connections
Solicitud
La siguiente solicitud crea una conexión base para la API HTTP.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"dataType": "xdm"
}
}
}'
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection Raw Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"dataType": "raw"
}
}
}'
namedescriptionconnectionSpec.idbc7b00d6-623a-4dfc-9fdb-f1240aeadaeb.auth.params.dataTypexdm y raw.auth.params.nameRespuesta
Una respuesta correcta devuelve el estado HTTP 201 con detalles de la conexión recién creada, incluido su identificador único (id).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
idid de su conexión base recién creada.etagConexión autenticada
Las conexiones autenticadas deben utilizarse cuando necesite diferenciar entre registros procedentes de fuentes de confianza y no fiables. Los usuarios que deseen enviar información con Información de identificación personal (PII) deben crear una conexión autenticada al transmitir información a Experience Platform.
Para crear una conexión base autenticada, debe incluir el parámetro authenticationRequired en la solicitud y especificar su valor como true. Durante este paso, también puede proporcionar un ID de origen para la conexión base autenticada. Este parámetro es opcional y utilizará el mismo valor que el atributo name, si no se proporciona.
Formato de API
POST /flowservice/connections
Solicitud
La siguiente solicitud crea una conexión base autenticada para la API HTTP.
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection XDM Data Authenticated",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Authenticated XDM streaming connection",
"dataType": "xdm",
"name": "Authenticated XDM streaming connection",
"authenticationRequired": true
}
}
}
curl -X POST https://platform.adobe.io/data/foundation/flowservice/connections \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Connection Raw Data Authenticated",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "Authenticated raw streaming connection",
"dataType": "raw",
"name": "Authenticated raw streaming connection",
"authenticationRequired": true
}
}
}
auth.params.sourceIdname, si no se proporciona.auth.params.authenticationRequiredauthenticationRequired está establecido en true, se debe proporcionar autenticación para la conexión de flujo continuo. Si authenticationRequired está establecido en false, no se requiere autenticación.Respuesta
Una respuesta correcta devuelve el estado HTTP 201 con detalles de la conexión recién creada, incluido su identificador único (id).
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
Obtener URL del extremo de flujo continuo
Con la conexión base creada, ahora puede recuperar la dirección URL del extremo de flujo continuo.
Formato de API
GET /flowservice/connections/{BASE_CONNECTION_ID}
{BASE_CONNECTION_ID}id de la conexión que creó anteriormente.Solicitud
curl -X GET https://platform.adobe.io/data/foundation/flowservice/connections/{BASE_CONNECTION_ID} \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con información detallada sobre la conexión solicitada. La dirección URL del extremo de flujo continuo se crea automáticamente con la conexión y se puede recuperar con el valor inletUrl.
{
"items": [
{
"id": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"createdAt": 1669238699119,
"updatedAt": 1669238699119,
"createdBy": "acme@AdobeID",
"updatedBy": "acme@AdobeID",
"createdClient": "{CREATED_CLIENT}",
"updatedClient": "{UPDATED_CLIENT}",
"sandboxId": "{SANDBOX_ID}",
"sandboxName": "{SANDBOX_NAME}",
"imsOrgId": "{ORG_ID}",
"name": "ACME Streaming Connection XDM Data",
"description": "ACME streaming connection for customer data",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
},
"state": "enabled",
"auth": {
"specName": "Streaming Connection",
"params": {
"sourceId": "ACME Streaming Connection XDM Data",
"inletUrl": "https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"authenticationRequired": false,
"inletId": "667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec",
"dataType": "xdm",
"name": "ACME Streaming Connection XDM Data"
}
},
"version": "\"f50185ed-0000-0200-0000-637e8fad0000\"",
"etag": "\"f50185ed-0000-0200-0000-637e8fad0000\""
}
]
}
Crear una conexión de origen
Para crear una conexión de origen, realice una petición POST al extremo /sourceConnections y proporcione el identificador de conexión base.
Formato de API
POST /flowservice/sourceConnections
Solicitud
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/sourceConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Source Connection for Customer Data",
"description": "A streaming source connection for ACME XDM Customer Data",
"baseConnectionId": "a59d368a-1152-4673-a46e-bd52e8cdb9a9",
"connectionSpec": {
"id": "bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb",
"version": "1.0"
}
}'
Respuesta
Una respuesta correcta devuelve el estado HTTP 201 con información detallada de la conexión de origen recién creada, incluido su identificador único (id).
{
"id": "34ece231-294d-416c-ad2a-5a5dfb2bc69f",
"etag": "\"d505125b-0000-0200-0000-637eb7790000\""
}
Creación de un esquema XDM de destino
Para que los datos de origen se utilicen en Experience 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 Experience Platform en el que se incluyen los datos de origen.
Se puede crear un esquema XDM de destino realizando una petición POST a la API del Registro de esquemas.
Para ver los pasos detallados sobre cómo crear un esquema XDM de destino, consulte el tutorial de creación de un esquema mediante la API.
Crear un conjunto de datos de destinatario
Se puede crear un conjunto de datos de destino realizando una petición POST en la API del servicio de catálogo, que proporcione el ID del esquema de destino en la carga útil.
Para ver los pasos detallados sobre cómo crear un conjunto de datos de destino, consulte el tutorial de creación de un conjunto de datos mediante la API.
Creación de una conexión de destino
Una conexión de destino representa la conexión con el destino donde aterrizan los datos introducidos. Para crear una conexión de destino, realice una petición POST a /targetConnections mientras proporciona los ID para el conjunto de datos de destino y el esquema XDM de destino. Durante este paso, también debe proporcionar el ID de especificación de conexión del lago de datos. Este identificador es c604ff05-7f1a-43c0-8e18-33bf874cb11c.
Formato de API
POST /flowservice/targetConnections
Solicitud
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/targetConnections' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Target Connection",
"description": "ACME Streaming Target Connection",
"data": {
"schema": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"version": "application/vnd.adobe.xed-full+json;version=1.0"
}
},
"params": {
"dataSetId": "637eb7fadc8a211b6312b65b"
},
"connectionSpec": {
"id": "c604ff05-7f1a-43c0-8e18-33bf874cb11c",
"version": "1.0"
}
}'
Respuesta
Una respuesta correcta devuelve el estado HTTP 201 con detalles de la conexión de destino recién creada, incluido su identificador único (id).
{
"id": "07f2f6ff-1da5-4704-916a-c615b873cba9",
"etag": "\"340680f7-0000-0200-0000-637eb8730000\""
}
Creación de una asignación
Para que los datos de origen se incorporen en un conjunto de datos de destino, primero deben asignarse al esquema de destino al que se adhiere el conjunto de datos de destino.
Para crear un conjunto de asignaciones, realice una petición POST al extremo mappingSets de la Data Prep API y proporcione el esquema XDM de destino $id y los detalles de los conjuntos de asignaciones que desee crear.
Formato de API
POST /mappingSets
Solicitud
curl -X POST \
'https://platform.adobe.io/data/foundation/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}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"xdmVersion": "1.0",
"mappings": [
{
"destinationXdmPath": "person.name.firstName",
"sourceAttribute": "firstName",
"identity": false,
"version": 0
},
{
"destinationXdmPath": "person.name.lastName",
"sourceAttribute": "lastName",
"identity": false,
"version": 0
}
]
}'
xdmSchema$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 ID es necesario en un paso posterior para crear un flujo de datos.
{
"id": "79a623960d3f4969835c9e00dc90c8df",
"version": 0,
"createdDate": 1669249214031,
"modifiedDate": 1669249214031,
"createdBy": "acme@AdobeID",
"modifiedBy": "acme@AdobeID"
}
Creación de un flujo de datos
NOTECon las conexiones de origen y destino creadas, ahora puede crear un flujo de datos. El flujo de datos es responsable de programar y recopilar datos de una fuente. Puede crear un flujo de datos realizando una petición POST al extremo /flows.
Formato de API
POST /flows
Solicitud
La siguiente solicitud crea un flujo de datos de flujo continuo para los datos XDM.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "ACME Streaming Dataflow",
"description": "ACME streaming dataflow for customer data",
"flowSpec": {
"id": "d8a6f005-7eaf-4153-983e-e8574508b877",
"version": "1.0"
},
"sourceConnectionIds": [
"34ece231-294d-416c-ad2a-5a5dfb2bc69f"
],
"targetConnectionIds": [
"07f2f6ff-1da5-4704-916a-c615b873cba9"
]
}'
Las siguientes solicitudes crean un flujo de datos de flujo continuo para los datos sin procesar.
Al crear un flujo de datos con transformaciones, el parámetro name no se puede cambiar. Este valor siempre debe establecerse en Mapping.
curl -X POST \
'https://platform.adobe.io/data/foundation/flowservice/flows' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "<name>",
"description": "<description>",
"flowSpec": {
"id": "c1a19761-d2c7-4702-b9fa-fe91f0613e81",
"version": "1.0"
},
"sourceConnectionIds": [
"34ece231-294d-416c-ad2a-5a5dfb2bc69f"
],
"targetConnectionIds": [
"07f2f6ff-1da5-4704-916a-c615b873cba9"
],
"transformations": [
{
"name": "Mapping",
"params": {
"mappingId": "79a623960d3f4969835c9e00dc90c8df",
"mappingVersion": 0
}
}
]
}'
namedescriptionflowSpec.idc1a19761-d2c7-4702-b9fa-fe91f0613e81. Para crear un flujo de datos sin transformaciones, use d8a6f005-7eaf-4153-983e-e8574508b877.sourceConnectionIdstargetConnectionIdstransformations.params.mappingIdRespuesta
Una respuesta correcta devuelve el estado HTTP 201 con detalles del flujo de datos recién creado, incluido su identificador único (id).
{
"id": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"etag": "\"dc0459ae-0000-0200-0000-637ebaec0000\""
}
Publicar datos para ingerirlos en Experience Platform
NOTEAhora que ha creado el flujo, puede enviar el mensaje JSON al extremo de flujo continuo creado anteriormente.
Formato de API
POST /collection/{INLET_URL}
{INLET_URL}/connections y proporcionando al mismo tiempo su ID de conexión base.{FLOW_ID}Solicitud
curl -X POST https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec \
-H 'Content-Type: application/json' \
-d '{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
},
"flowId": "f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2",
"datasetId": "604a18a3bae67d18db6d258c"
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT}/schemas/7f682c29f887512a897791e7161b90a1ae7ed3dd07a177b1",
"contentType": "application/vnd.adobe.xed-full-notext+json; version=1.0"
}
},
"xdmEntity": {
"_id": "http-source-connector-acme-01",
"person": {
"name": {
"firstName": "suman",
"lastName": "nolan"
}
},
"workEmail": {
"primary": true,
"address": "suman@acme.com",
"type": "work",
"status": "active"
}
}
}
}'
Al enviar datos sin procesar, puede especificar el ID de flujo como parámetro de consulta o como parte del encabezado HTTP. El siguiente ejemplo especifica el ID de flujo como un encabezado HTTP.
curl -X POST https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec \
-H 'Content-Type: application/json'
-H 'x-adobe-flow-id=f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2' \
-d '{
"name": "Johnson Smith",
"location": {
"city": "Seattle",
"country": "United State of America",
"address": "3692 Main Street"
},
"gender": "Male",
"birthday": {
"year": 1984,
"month": 6,
"day": 9
}
}'
Al enviar datos sin procesar, puede especificar el ID de flujo como parámetro de consulta o como encabezado HTTP. El ejemplo siguiente especifica el ID de flujo como parámetro de consulta.
curl -X POST https://dcs.adobedc.net/collection/667b41cf2dbf3509927da1ebf7e93c20afa727cc8d8373e51da18b62e1b985ec?x-adobe-flow-id=f2ae0194-8bd8-4a40-a4d9-f07bdc3e6ce2 \
-H 'Content-Type: application/json' \
-d '{
"name": "Johnson Smith",
"location": {
"city": "Seattle",
"country": "United State of America",
"address": "3692 Main Street"
},
"gender": "Male",
"birthday": {
"year": 1984,
"month": 6,
"day": 9
}
}'
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con detalles de la información recién introducida.
{
"inletId": "{BASE_CONNECTION_ID}",
"xactionId": "1584479347507:2153:240",
"receivedTimeMs": 1584479347507
}
{BASE_CONNECTION_ID}xactionIdreceivedTimeMsPasos siguientes
Al seguir este tutorial, ha creado una conexión HTTP de flujo continuo que le permite utilizar el extremo de flujo continuo para introducir datos en Experience Platform. Para obtener instrucciones para crear una conexión de flujo continuo en la interfaz de usuario, lea el tutorial sobre la creación de una conexión de flujo continuo.
Para aprender a transmitir datos a Experience Platform, lea el tutorial sobre transmisión de datos de series temporales o el tutorial sobre transmisión de datos de registros.
Apéndice
Esta sección proporciona información complementaria sobre la creación de conexiones de flujo continuo mediante la API.
Envío de mensajes a una conexión de flujo continuo autenticada
Si una conexión de flujo continuo tiene habilitada la autenticación, el cliente deberá agregar el encabezado Authorization a su solicitud.
Si el encabezado Authorization no está presente, o si se envía un token de acceso no válido o caducado, se devolverá una respuesta HTTP 401 no autorizada, con una respuesta similar a la siguiente:
Respuesta
{
"type": "https://ns.adobe.com/adobecloud/problem/data-collection-service-authorization",
"status": "401",
"title": "Authorization",
"report": {
"message": "[id] Ims service token is empty"
}
}