Crear una conexión de flujo continuo de API HTTP mediante la API Flow Service
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 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 Platform
Para obtener información sobre cómo realizar llamadas correctamente a las API de Platform, consulte la guía sobre introducción a las API de 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 Platform.
Para crear una conexión base no autenticada, realice una solicitud de 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.
code language-shell |
---|
|
code language-shell |
---|
|
name
description
connectionSpec.id
bc7b00d6-623a-4dfc-9fdb-f1240aeadaeb
.auth.params.dataType
xdm
y raw
.auth.params.name
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\""
}
id
id
de su conexión base recién creada.etag
Conexió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 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.
code language-shell |
---|
|
code language-shell |
---|
|
auth.params.sourceId
name
, si no se proporciona.auth.params.authenticationRequired
authenticationRequired
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 source
Para crear una conexión de origen, realice una solicitud de 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 target-schema
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 incluyen los datos de origen.
Se puede crear un esquema XDM de destino realizando una solicitud de POST a la API de 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 target-dataset
Se puede crear un conjunto de datos de destino realizando una solicitud de POST a la API de 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 target
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 solicitud de 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 mapping
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 solicitud de 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
Con 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 solicitud de 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.
code language-shell |
---|
|
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
.
code language-shell |
---|
|
name
description
flowSpec.id
c1a19761-d2c7-4702-b9fa-fe91f0613e81
. Para crear un flujo de datos sin transformaciones, use d8a6f005-7eaf-4153-983e-e8574508b877
.sourceConnectionIds
targetConnectionIds
transformations.params.mappingId
Respuesta
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 Platform ingest-data
Ahora 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
code language-shell |
---|
|
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.
code language-shell |
---|
|
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.
code language-shell |
---|
|
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}
xactionId
receivedTimeMs
Pasos 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 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 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"
}
}