Enviar varios mensajes en una única solicitud HTTP
Al transmitir datos a Adobe Experience Platform, realizar numerosas llamadas HTTP puede resultar caro. Por ejemplo, en lugar de crear 200 solicitudes HTTP con cargas útiles de 1 KB, es mucho más eficiente crear 1 solicitud HTTP con 200 mensajes de 1 KB cada uno, con una sola carga útil de 200 KB. Si se usa correctamente, agrupar varios mensajes en una única solicitud es una manera excelente de optimizar los datos que se envían a Experience Platform.
Este documento proporciona un tutorial para enviar varios mensajes a Experience Platform dentro de una sola solicitud HTTP mediante la introducción de transmisión por secuencias.
Introducción
Este tutorial requiere una comprensión práctica de Adobe Experience Platform Data Ingestion. Antes de comenzar este tutorial, revise la siguiente documentación:
- Resumen de ingesta de datos: Cubre los conceptos principales de Experience Platform Data Ingestion, incluidos los métodos de ingesta y los conectores de datos.
- Información general sobre la ingesta de transmisión: El flujo de trabajo y los componentes básicos de la transmisión por secuencias, como las conexiones de transmisión por secuencias, los conjuntos de datos, XDM Individual Profile y XDM ExperienceEvent.
Este tutorial también requiere que haya completado el tutorial Autenticación en Adobe Experience Platform para poder realizar llamadas a las API Platform correctamente. Al completar el tutorial de autenticación, se proporciona el valor para el encabezado Autorización requerido por todas las llamadas de API en este tutorial. El encabezado se muestra en llamadas de ejemplo de la siguiente manera:
- Autorización: Portador
{ACCESS_TOKEN}
Todas las solicitudes del POST requieren un encabezado adicional:
- Content-Type: application/json
Creación de una conexión de flujo continuo
Primero debe crear una conexión de flujo continuo para poder iniciar la transmisión de datos a Experience Platform. Lea la guía crear una conexión de flujo continuo para aprender a crear una conexión de flujo continuo.
Después de registrar una conexión de flujo continuo, usted, como productor de datos, tendrá una URL única que se puede utilizar para transmitir datos a Platform.
Transmitir a un conjunto de datos
El siguiente ejemplo muestra cómo enviar varios mensajes a un conjunto de datos específico dentro de una única solicitud HTTP. Inserte la ID del conjunto de datos en el encabezado del mensaje para que ese mensaje se incorpore directamente en él.
Puede obtener el ID de un conjunto de datos existente mediante la interfaz de usuario de Platform o mediante una operación de listado en la API. La ID del conjunto de datos se puede encontrar en Experience Platform. Para ello, vaya a la pestaña Conjuntos de datos, haga clic en el conjunto de datos para el que desee la ID y copie la cadena del campo de ID del conjunto de datos en la pestaña Información. Consulte la descripción general del servicio de catálogo para obtener información sobre cómo recuperar conjuntos de datos mediante la API.
En lugar de utilizar un conjunto de datos existente, puede crear uno nuevo. Lea el tutorial Crear un conjunto de datos con API para obtener más información sobre cómo crear un conjunto de datos con API.
Formato de API
POST /collection/batch/{CONNECTION_ID}
{CONNECTION_ID}Solicitud
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Fernie Snow",
"quantity": 30,
"priceTotal": 7.8
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "gregdorcey@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "7af6adcc-dc9e-4692-b826-55d2abe68c11",
"timestamp": "2019-02-23T22:07:31Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Carmine Santiago",
"quantity": 10,
"priceTotal": 5.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "emilyong@example.com"
}
}
}
}
}
}
}
}
]
}'
Respuesta
Una respuesta correcta devuelve un estado HTTP 207 (varios estados). La revisión del cuerpo de respuesta proporciona más detalles sobre el éxito o el error de cada método ejecutado en la solicitud. Se devuelve una respuesta para cada elemento de la matriz de mensajes de solicitud. A continuación se muestra un ejemplo de una respuesta correcta sin errores de mensaje:
{
"inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
"batchId": "1565628583792:1485:153",
"receivedTimeMs": 1565628583854,
"responses": [
{
"xactionId": "1565628583792:1485:153:0"
},
{
"xactionId": "1565628583792:1485:153:1"
}
]
}
Para obtener más información sobre los códigos de estado, consulte la tabla códigos de respuesta en el apéndice de este tutorial.
Identificación de mensajes fallidos
En comparación con el envío de una solicitud con un solo mensaje, al enviar una solicitud HTTP con varios mensajes, hay factores adicionales que se deben tener en cuenta, como: cómo identificar cuándo se han producido errores al enviar datos, qué mensajes específicos no se han enviado y cómo se pueden recuperar y qué sucede con los datos que tienen éxito cuando fallan otros mensajes en la misma solicitud.
Antes de continuar con este tutorial, se recomienda revisar primero la guía recuperación de lotes con errores.
Enviar carga útil de solicitud con mensajes válidos y no válidos
El siguiente ejemplo muestra lo que sucede cuando el lote incluye mensajes válidos y no válidos.
La carga útil solicitada es una matriz de objetos JSON que representan el evento en el esquema XDM. Tenga en cuenta que deben cumplirse las siguientes condiciones para que la validación del mensaje se realice correctamente:
- El campo
imsOrgIddel encabezado del mensaje debe coincidir con la definición de entrada. Si la carga de la solicitud no incluye un campoimsOrgId, el Data Collection Core Service (DCCS) agregará el campo automáticamente. - El encabezado del mensaje debe hacer referencia a un esquema XDM existente creado en la interfaz de usuario de Platform.
- El campo
datasetIddebe hacer referencia a un conjunto de datos existente en Platform, y su esquema debe coincidir con el esquema proporcionado en el objetoheaderdentro de cada mensaje incluido en el cuerpo de la solicitud.
Formato de API
POST /collection/batch/{CONNECTION_ID}
{CONNECTION_ID}Solicitud
curl -X POST https://dcs.adobedc.net/collection/batch/{CONNECTION_ID} \
-H 'Content-Type: application/json' \
-d '{
"messages": [
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Tip Top Collection",
"quantity": 15,
"priceTotal": 9.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "rogerkanagawa@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "invalidIMSOrg@AdobeOrg",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Carmine Santiago",
"quantity": 10,
"priceTotal": 5.5
}
],
"commerce": {
"productViews": {
"value": 1
}
},
"_experience": {
"campaign": {
"message": {
"profileSnapshot": {
"workEmail": {
"address": "mohandeewar@example.com"
}
}
}
}
}
}
}
},
{
"header": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
"environment": {
"browserDetails": {
"userAgent": "Mozilla/5.0 (Windows NT 5.1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/29.0.1547.57 Safari/537.36 OPR/16.0.1196.62",
"acceptLanguage": "en-US",
"cookiesEnabled": true,
"javaScriptVersion": "1.6",
"javaEnabled": true
},
"colorDepth": 32,
"viewportHeight": 799,
"viewportWidth": 414
},
"productListItems": [
{
"SKU": "CC",
"name": "Tip Top Collection",
"quantity": 15,
"priceTotal": 9.5
}
],
"commerce": {
"productViews": {
"value": 1
}
}
}
}
},
{
"header": {
"msgType": "xdmEntityCreate",
"msgId": "79d2e715-f25f-4c36",
"xdmSchema": {
"name": "_xdm.context.experienceevent"
},
"imsOrgId": "{ORG_ID}",
"datasetId": "{DATASET_ID}",
"createdAt": 1526283801869
},
"body": {
"xdmMeta": {
"xdmSchema": {
"name": "_xdm.context.experienceevent"
}
},
"xdmEntity": {
"_id": "abc",
"dataSource": {
"_id": "http://abc.com/abc"
},
"timestamp": "2018-05-18T15:28:25Z",
"endUserIDs": {
"_vendor": {
"adobe": {
"experience": {
"mcId": {
"id": "http://abc.com/abc"
}
}
}
}
}
}
}
}
]
}'
Respuesta
La carga de respuesta incluye un estado para cada mensaje junto con un GUID en el xactionId que se puede utilizar para el seguimiento.
{
"inletId": "9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5",
"batchId": "1565638336649:1750:244",
"receivedTimeMs": 1565638336705,
"responses": [
{
"xactionId": "1565650704337:2124:92:3"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has an absent or wrong ims org in the header"
},
{
"statusCode": 400,
"message": "inletId: [9b0cb233972f3b0092992284c7353f5eead496218e8441a79b25e9421ea127f5] imsOrgId: [{ORG_ID}] Message has unknown xdm format"
}
]
}
La respuesta de ejemplo anterior muestra mensajes de error para la solicitud anterior. Al comparar esta respuesta con la respuesta válida anterior, puede observar que la solicitud resultó en un éxito parcial, con un mensaje que se ingirió correctamente y tres mensajes que resultaron en un error. Tenga en cuenta que ambas respuestas devuelven un código de estado "207". Para obtener más información sobre los códigos de estado, consulte la tabla códigos de respuesta en el apéndice de este tutorial.
El primer mensaje se envió correctamente a Platform y no se ve afectado por los resultados de los demás mensajes. Como resultado, al intentar reenviar los mensajes fallidos, no es necesario volver a incluir este mensaje.
Error en el segundo mensaje porque carecía de cuerpo de mensaje. La solicitud de colección espera que los elementos de mensaje tengan secciones de encabezado y cuerpo válidas. Añadir el siguiente código después del encabezado del segundo mensaje corregirá la solicitud, lo que permite que el segundo mensaje apruebe la validación:
"body": {
"xdmMeta": {
"schemaRef": {
"id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
"contentType": "application/vnd.adobe.xed-full+json;{SCHEMA_VERSION}"
}
},
"xdmEntity": {
"_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
"timestamp": "2019-02-23T22:07:01Z",
}
},
Error en el tercer mensaje debido a que se está utilizando un ID de organización no válido en el encabezado. La organización debe coincidir con el(la) {CONNECTION_ID} en el(la) que usted intenta publicar. Para determinar qué identificador de organización coincide con la conexión de flujo continuo que está utilizando, puede realizar una solicitud de GET inlet con Streaming Ingestion API. Consulte recuperación de una conexión de flujo continuo para ver un ejemplo de cómo recuperar las conexiones de flujo continuo creadas anteriormente.
Error en el cuarto mensaje porque no seguía el esquema XDM esperado. El xdmSchema incluido en el encabezado y el cuerpo de la solicitud no coinciden con el esquema XDM de {DATASET_ID}. La corrección del esquema en el encabezado y el cuerpo del mensaje le permite pasar la validación de DCCS y enviarlo correctamente a Platform. El cuerpo del mensaje también debe actualizarse para que coincida con el esquema XDM de {DATASET_ID} para que pase la validación de flujo continuo en Platform. Para obtener más información sobre lo que sucede con los mensajes que se transmiten correctamente a Platform, consulte la sección confirmar mensajes introducidos de este tutorial.
Recuperar mensajes fallidos de Platform
Los mensajes fallidos se identifican mediante un código de estado de error en la matriz de respuesta.
Los mensajes no válidos se recopilan y almacenan en un lote de "error" dentro del conjunto de datos especificado por {DATASET_ID}.
Lea la guía recuperación de lotes con errores para obtener más información sobre la recuperación de mensajes por lotes con errores.
Confirmar mensajes introducidos
Los mensajes que superen la validación de DCCS se transmitirán a Platform. En Platform, la validación de flujo prueba los mensajes por lotes antes de ingerirlos en Data Lake. El estado de los lotes, independientemente de si son correctos o no, aparece dentro del conjunto de datos especificado por {DATASET_ID}.
Puede ver el estado de los mensajes por lotes que se transmitieron correctamente a Platform mediante la interfaz de usuario del Experience Platform. Para ello, vaya a la pestaña Conjuntos de datos, haga clic en el conjunto de datos al que está transmitiendo y compruebe la pestaña Actividad de conjuntos de datos.
Los mensajes por lotes que pasan la validación de flujo continuo en Platform se incorporan en Data Lake. Los mensajes están disponibles para su análisis o exportación.
Pasos siguientes
Ahora que sabe cómo enviar varios mensajes en una sola solicitud y comprobar cuándo los mensajes se incorporan correctamente en el conjunto de datos de destino, puede empezar a transmitir sus propios datos a Platform. Para obtener información general sobre cómo consultar y recuperar datos ingeridos de Platform, consulte la guía Data Access.
Apéndice
Esta sección contiene información suplementaria para el tutorial.
Códigos de respuesta
La tabla siguiente muestra los códigos de estado devueltos por los mensajes de respuesta correctos y fallidos.