Transmisión de datos de series temporales mediante API de ingesta de transmisión

Este tutorial le ayudará a empezar a utilizar las API de ingesta de transmisión, que forman parte de las API Data Ingestion Service de Adobe Experience Platform.

Primeros pasos

Este tutorial requiere conocimientos prácticos de varios servicios de Adobe Experience Platform. Antes de comenzar este tutorial, consulte la documentación de los siguientes servicios:

  • Experience Data Model (XDM): El marco estandarizado mediante el cual se Platform organizan los datos de experiencia.
  • Real-time Customer Profile: Proporciona un perfil unificado y de cliente en tiempo real basado en datos agregados de varias fuentes.
  • Guía para desarrolladores de Schema Registry: Una guía completa que cubre cada uno de los extremos disponibles de la Schema Registry API y cómo realizar llamadas a ellos. Esto incluye conocer su {TENANT_ID}, que aparece en las llamadas a lo largo de este tutorial, así como saber cómo crear esquemas, que se utilizan para crear un conjunto de datos para la ingesta.

Además, este tutorial requiere que ya haya creado una conexión de flujo continuo. Para obtener más información sobre la creación de una conexión de flujo continuo, lea el tutorial de creación de una conexión de flujo continuo.

Las secciones siguientes proporcionan información adicional que deberá conocer para realizar llamadas correctamente a las API de ingesta de transmisión.

Leer llamadas de API de ejemplo

Esta guía proporciona ejemplos de llamadas a la API para demostrar cómo dar formato a las solicitudes. Estas incluyen rutas de acceso, encabezados necesarios y cargas de solicitud con el formato correcto. También se proporciona el JSON de muestra devuelto en las respuestas de API. Para obtener información sobre las convenciones utilizadas en la documentación para las llamadas de API de ejemplo, consulte la sección sobre cómo leer llamadas de API de ejemplo en la guía de solución de problemas Experience Platform.

Recopilar valores para encabezados necesarios

Para realizar llamadas a las API Platform, primero debe completar el tutorial de autenticación. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados necesarios en todas las llamadas a la API Experience Platform, como se muestra a continuación:

  • Autorización: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

Todos los recursos de Experience Platform están aislados en entornos limitados virtuales específicos. Todas las solicitudes a las API Platform requieren un encabezado que especifique el nombre del simulador para pruebas en el que se realizará la operación:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Para obtener más información sobre los entornos limitados en Platform, consulte la documentación general del entorno limitado.

Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado adicional:

  • Content-Type: application/json

Componer un esquema basado en la clase XDM ExperienceEvent

Para crear un conjunto de datos, primero debe crear un nuevo esquema que implemente la clase XDM ExperienceEvent. Para obtener más información sobre cómo crear esquemas, lea la guía para desarrolladores de la API del Registro de Esquemas.

Formato de API

POST /schemaregistry/tenant/schemas

Solicitud

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/schemas
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "type": "object",
    "title": "{SCHEMA_NAME}",
    "description": "{SCHEMA_DESCRIPTION}",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce"
        },
        {  
         "$ref":"https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
        }
    ],
    "meta:immutableTags": [
        "union"
    ]
}'
Propiedad Descripción
title El nombre que desea utilizar para el esquema. Este nombre debe ser único.
description Una descripción significativa del esquema que está creando.
meta:immutableTags En este ejemplo, la etiqueta union se utiliza para mantener los datos en Real-time Customer Profile.

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 con detalles del esquema recién creado.

{
    "$id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "meta:altId": "_{TENANT_ID}.schemas.{SCHEMA_ID}",
    "meta:resourceType": "schemas",
    "version": "{SCHEMA_VERSION}",
    "type": "object",
    "title": "{SCHEMA_NAME}",
    "description": "{SCHEMA_DESCRIPTION}",
    "allOf": [
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/xdm/context/experienceevent-commerce",
            "type": "object",
            "meta:xdmType": "object"
        },
        {
            "$ref": "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
            "type": "object",
            "meta:xdmType": "object"
        }
    ],
    "refs": [
        "https://ns.adobe.com/xdm/context/experienceevent-commerce",
        "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details",
        "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
        "https://ns.adobe.com/xdm/context/experienceevent"
    ],
    "imsOrg": "{IMS_ORG}",
    "meta:immutableTags": [
        "union"
    ],
    "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
    "required": [
        "@id",
        "xdm:timestamp"
    ],
    "meta:abstract": false,
    "meta:extensible": false,
    "meta:extends": [
        "https://ns.adobe.com/xdm/context/experienceevent",
        "https://ns.adobe.com/xdm/data/time-series",
        "https://ns.adobe.com/xdm/context/identitymap",
        "https://ns.adobe.com/xdm/context/experienceevent-environment-details",
        "https://ns.adobe.com/xdm/context/experienceevent-commerce",
        "https://ns.adobe.com/experience/campaign/experienceevent-profile-work-details"
    ],
    "meta:containerId": "tenant",
    "imsOrg": "{IMS_ORG}",
    "meta:xdmType": "object",
    "meta:class": "https://ns.adobe.com/xdm/context/experienceevent",
    "meta:registryMetadata": {
        "repo:createDate": 1551229957987,
        "repo:lastModifiedDate": 1551229957987,
        "xdm:createdClientId": "{CLIENT_ID}",
        "xdm:repositoryCreatedBy": "{CREATED_BY}"
    },
    "meta:tenantNamespace": "{NAMESPACE}"
}
Propiedad Descripción
{TENANT_ID} Este ID se utiliza para garantizar que los recursos que crea tengan un espacio de nombres adecuado y estén contenidos dentro de su organización de IMS. Para obtener más información sobre el ID del inquilino, lea la guía del registro de esquema.

Tenga en cuenta los atributos $id, así como los version, ya que ambos se utilizarán al crear su conjunto de datos.

Definir un descriptor de identidad principal para el esquema

A continuación, añada un descriptor de identidad al esquema creado anteriormente, utilizando el atributo de dirección de correo electrónico de trabajo como identificador principal. Al hacerlo, se producirán dos cambios:

  1. La dirección de correo electrónico de trabajo se convertirá en un campo obligatorio. Esto significa que los mensajes enviados sin este campo no se validan correctamente y no se incorporan.

  2. Real-time Customer Profile utilizará la dirección de correo electrónico de trabajo como identificador para ayudar a unir más información sobre ese individuo.

Solicitud

curl -X POST https://platform.adobe.io/data/foundation/schemaregistry/tenant/descriptors \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "@type":"xdm:descriptorIdentity",
    "xdm:sourceProperty":"/_experience/campaign/message/profileSnapshot/workEmail/address",
    "xdm:property":"xdm:code",
    "xdm:isPrimary":true,
    "xdm:namespace":"Email",
    "xdm:sourceSchema":"{SCHEMA_REF_ID}",
    "xdm:sourceVersion":1
}
Propiedad Descripción
{SCHEMA_REF_ID} El $id que recibió anteriormente al componer el esquema. Debería tener un aspecto similar al siguiente: "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}"
NOTA

​Códigos de área de nombres de identidad

Asegúrese de que los códigos sean válidos: el ejemplo anterior utiliza "correo electrónico", que es un área de nombres de identidad estándar. En las preguntas frecuentes sobre el servicio de identidad se pueden encontrar otros espacios de nombres de identidad estándar utilizados con más frecuencia.

Si desea crear un área de nombres personalizada, siga los pasos descritos en la descripción general del área de nombres de identidad.

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 con información sobre el área de nombres de identidad principal recién creada para el esquema.

{
    "xdm:property": "xdm:code",
    "xdm:sourceSchema": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
    "xdm:namespace": "Email",
    "@type": "xdm:descriptorIdentity",
    "xdm:sourceVersion": 1,
    "xdm:isPrimary": true,
    "xdm:sourceProperty": "/_experience/campaign/message/profileSnapshot/workEmail/address",
    "@id": "ec31c09e0906561861be5a71fcd964e29ebe7923b8eb0d1e",
    "meta:containerId": "tenant",
    "version": "1",
    "imsOrg": "{IMS_ORG}"
}

Crear un conjunto de datos para datos de series temporales

Una vez que haya creado el esquema, deberá crear un conjunto de datos para introducir los datos de registro.

NOTA

Este conjunto de datos se habilitará para Real-time Customer Profile y Identity estableciendo las etiquetas adecuadas.

Formato de API

POST /catalog/dataSets

Solicitud

curl -X POST https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "name": "{DATASET_NAME}",
    "description": "{DATASET_DESCRIPTION}",
    "schemaRef": {
        "id": "{SCHEMA_REF_ID}",
        "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
    },
    "fileDescription": {
        "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    },
    "tags": {
        "unifiedIdentity": ["enabled:true"],
        "unifiedProfile": ["enabled:true"]
    }
}'

Respuesta

Una respuesta correcta devuelve el estado HTTP 201 y una matriz que contiene el ID del conjunto de datos recién creado con el formato @/dataSets/{DATASET_ID}.

[
    "@/dataSets/5e72608b10f6e318ad2dee0f"
]

Ingesta de datos de series temporales en la conexión de flujo continuo

Con el conjunto de datos y la conexión de flujo continuo en su lugar, puede ingerir registros JSON con formato XDM para introducir datos de series temporales en Platform.

Formato de API

POST /collection/{CONNECTION_ID}?synchronousValidation=true
Parámetro Descripción
{CONNECTION_ID} El valor id de la conexión de flujo continuo recién creada.
synchronousValidation Un parámetro de consulta opcional diseñado para fines de desarrollo. Si se establece en true, se puede utilizar para comentarios inmediatos a fin de determinar si la solicitud se ha enviado correctamente. De forma predeterminada, este valor se establece en false.

Solicitud

La ingesta de datos de series temporales en una conexión de flujo continuo se puede realizar con o sin el nombre de origen.

La solicitud de ejemplo siguiente incorpora datos de series temporales con un nombre de origen ausente en Platform. Si en los datos falta el nombre del origen, se agregará el ID de origen de la definición de conexión de flujo continuo.

IMPORTANTE

Debe generar su propio xdmEntity._id y xdmEntity.timestamp. Una buena forma de generar un ID es utilizar la función UUID en la preparación de datos. Puede encontrar más información sobre la función UUID en la Guía de funciones de preparación de datos. El atributo xdmEntity._id representa un identificador único para el propio registro, no un ID único de la persona o dispositivo cuyo registro es. El ID de persona o dispositivo es específico en cualquier atributo asignado como persona o identificador de dispositivo del esquema.

Tanto xdmEntity._id como xdmEntity.timestamp son los únicos campos obligatorios para los datos de series temporales. Además, la siguiente llamada de API no requiere encabezados de autenticación.

curl -X POST https://dcs.adobedc.net/collection/{CONNECTION_ID}?synchronousValidation=true \
  -H "Content-Type: application/json" \
  -d '{
    "header": {
        "schemaRef": {
            "id": "{SCHEMA_REF_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "datasetId": "{DATASET_ID}"
    },
    "body": {
        "xdmMeta": {
            "schemaRef": {
                "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
                "contentType": "application/vnd.adobe.xed-full+json;version={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": "janedoe@example.com"
                            }
                        }
                    }
                }
            }
        }
    }
}'

Si desea incluir un nombre de origen, el siguiente ejemplo muestra cómo lo incluiría.

    "header": {
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/{SCHEMA_ID}",
            "contentType": "application/vnd.adobe.xed-full+json;version={SCHEMA_VERSION}"
        },
        "imsOrgId": "{IMS_ORG}",
        "datasetId": "{DATASET_ID}",
        "source": {
            "name": "Sample source name"
        }
    }

Respuesta

Una respuesta correcta devuelve el estado HTTP 200 con detalles del Profile recién transmitido.

{
    "inletId": "{CONNECTION_ID}",
    "xactionId": "1584479347507:2153:240",
    "receivedTimeMs": 1584479347507,
    "synchronousValidation": {
        "status": "pass"
    }
}
Propiedad Descripción
{CONNECTION_ID} El ID de la conexión de flujo continuo creada anteriormente.
xactionId Identificador único generado en el servidor para el registro que acaba de enviar. Este ID ayuda a Adobe a rastrear el ciclo vital de este registro a través de varios sistemas y con depuración.
receivedTimeMs: Marca de tiempo (época en milisegundos) que muestra la hora a la que se recibió la solicitud.
synchronousValidation.status Dado que se ha agregado el parámetro de consulta synchronousValidation=true, este valor aparecerá. Si la validación se ha realizado correctamente, el estado será pass.

Recuperar los datos de series temporales recién introducidos

Para validar los registros introducidos anteriormente, puede utilizar Profile Access API para recuperar los datos de la serie temporal. Esto se puede hacer utilizando una solicitud GET al extremo /access/entities y utilizando parámetros de consulta opcionales. Se pueden usar varios parámetros, separados por el símbolo &."

NOTA

Si el ID de la directiva de combinación no está definido y schema.name o relatedSchema.name es _xdm.context.profile, Profile Access recuperará todas las identidades relacionadas.

Formato de API

GET /access/entities
GET /access/entities?{QUERY_PARAMETERS}
GET /access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email
Parámetro Descripción
schema.name Requerido. Nombre del esquema al que se accede.
relatedSchema.name Requerido. Dado que accede a un _xdm.context.experienceevent, este valor especifica el esquema de la entidad de perfil con el que están relacionados los eventos de series temporales.
relatedEntityId El ID de la entidad relacionada. Si se proporciona, también debe proporcionar el área de nombres de la entidad.
relatedEntityIdNS El espacio de nombres del ID que está intentando recuperar.

Solicitud

curl -X GET \
  https://platform-stage.adobe.io/data/core/ups/access/entities?schema.name=_xdm.context.experienceevent&relatedSchema.name=_xdm.context.profile&relatedEntityId=janedoe@example.com&relatedEntityIdNS=email \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "x-api-key: {API_KEY}" \
  -H "x-gw-ims-org-id: {IMS_ORG}" \
  -H "x-sandbox-name: {SANDBOX_NAME}"

Respuesta

Una respuesta correcta devuelve el estado HTTP 200 con detalles de las entidades solicitadas. Como puede ver, estos son los mismos datos de series temporales que se incorporaron anteriormente.

{
    "_page": {
        "orderby": "timestamp",
        "start": "9af5adcc-db9c-4692-b826-65d3abe68c22",
        "count": 1,
        "next": ""
    },
    "children": [
        {
            "relatedEntityId": "BVrqzwVv7o2p3naHvnsWpqZXv3KJgA",
            "entityId": "9af5adcc-db9c-4692-b826-65d3abe68c22",
            "timestamp": 1582495621000,
            "entity": {
                "environment": {
                    "browserDetails": {
                        "javaScriptVersion": "1.6",
                        "cookiesEnabled": true,
                        "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",
                        "javaEnabled": true
                    },
                    "colorDepth": 32,
                    "viewportHeight": 799,
                    "viewportWidth": 414
                },
                "_id": "9af5adcc-db9c-4692-b826-65d3abe68c22",
                "commerce": {
                    "productViews": {
                        "value": 1
                    }
                },
                "productListItems": [
                    {
                        "name": "Fernie Snow",
                        "quantity": 30,
                        "SKU": "CC",
                        "priceTotal": 7.8
                    }
                ],
                "_experience": {
                    "campaign": {
                        "message": {
                            "profileSnapshot": {
                                "workEmail": {
                                    "address": "janedoe@example.com"
                                }
                            }
                        }
                    }
                },
                "timestamp": "2020-02-23T22:07:01Z"
            },
            "lastModifiedAt": "2020-03-18T18:51:19Z"
        }
    ],
    "_links": {
        "next": {
            "href": ""
        }
    }
}

Pasos siguientes

Al leer este documento, ahora puede comprender cómo introducir datos de registro en Platform mediante conexiones de flujo continuo. Puede intentar realizar más llamadas con valores diferentes y recuperar los valores actualizados. Además, puede empezar a monitorizar los datos introducidos a través de la interfaz de usuario Platform. Para obtener más información, consulte la guía monitorización de la ingesta de datos.

Para obtener más información sobre la ingesta de transmisión en general, lea la descripción general de la ingesta de transmisión.

En esta página

Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free
Adobe Summit Banner

A virtual event April 27-28.

Expand your skills and get inspired.

Register for free