Evaluación y acceso a resultados de definición de segmentos
Creado para:
- Usuario
Este documento proporciona un tutorial para evaluar definiciones de segmentos y acceder a estos resultados mediante Segmentation API.
Introducción
Este tutorial requiere una comprensión práctica de los distintos servicios de Adobe Experience Platform implicados en la creación de audiencias. Antes de comenzar este tutorial, revise la documentación de los siguientes servicios:
- Real-Time Customer Profile: proporciona un perfil de cliente unificado en tiempo real en función de los datos agregados de varias fuentes.
- Adobe Experience Platform Segmentation Service: permite crear audiencias a partir de los datos de Real-Time Customer Profile.
- Experience Data Model (XDM): el marco estandarizado mediante el cual Platform organiza los datos de experiencia del cliente. Para utilizar la segmentación de la mejor manera posible, asegúrate de que tus datos se incorporen como perfiles y eventos según las prácticas recomendadas para el modelado de datos.
- Zonas protegidas: Experience Platform proporciona zonas protegidas virtuales que dividen una sola instancia de Experience Platform en entornos virtuales independientes para ayudar a desarrollar y evolucionar aplicaciones de experiencia digital.
Encabezados obligatorios
Este tutorial también requiere que haya completado el tutorial de autenticación para realizar correctamente llamadas a las API de Experience Platform. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados obligatorios en todas las llamadas de API de Experience Platform, como se muestra a continuación:
- Autorización: Portador
{ACCESS_TOKEN} - x-api-key:
{API_KEY} - x-gw-ims-org-id:
{ORG_ID}
Todos los recursos de Experience Platform están aislados en zonas protegidas virtuales específicas. Las solicitudes a las API Experience Platform requieren un encabezado que especifique el nombre de la zona protegida en la que se realizará la operación:
- x-sandbox-name:
{SANDBOX_NAME}
NOTETodas las solicitudes de POST, PUT y PATCH requieren un encabezado adicional:
- Content-Type: application/json
Evaluación de una definición de segmento
Una vez que haya desarrollado, probado y guardado la definición del segmento, puede evaluarla mediante la evaluación programada o la evaluación bajo demanda.
La evaluación programada (también conocida como "segmentación programada") le permite crear una programación recurrente para ejecutar un trabajo de exportación a una hora específica, mientras que la evaluación bajo demanda implica la creación de un trabajo de segmento para generar la audiencia inmediatamente. A continuación se describen los pasos de cada uno.
Si todavía no ha completado el tutorial crear una definición de segmento con la API de segmentación o ha creado una definición de segmento con Generador de segmentos, hágalo antes de continuar con este tutorial.
Evaluación programada
Mediante la evaluación programada, su organización puede crear una programación recurrente para ejecutar automáticamente los trabajos de exportación.
NOTECreación de una programación
Al realizar una petición POST al extremo /config/schedules, puede crear una programación e incluir la hora específica en que se debe activar la programación.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de programaciones
Habilitar una programación
De manera predeterminada, una programación está inactiva cuando se crea a menos que la propiedad state se establezca en active en el cuerpo de la solicitud de creación (POST). Puede habilitar una programación (establecer state en active) realizando una petición PATCH al extremo /config/schedules e incluyendo el ID de la programación en la ruta.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de programaciones
Actualizar la hora de programación
El tiempo de programación se puede actualizar realizando una petición PATCH al extremo /config/schedules e incluyendo el ID de la programación en la ruta.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de programaciones
Evaluación a la carta
La evaluación bajo demanda le permite crear un trabajo de segmentación para generar una audiencia siempre que lo necesite. A diferencia de la evaluación programada, esto solo ocurrirá cuando se solicite y no sea recurrente.
Creación de un trabajo de segmentación
Un trabajo de segmentación es un proceso asincrónico que crea un segmento de audiencia bajo demanda. Hace referencia a una definición de segmento, así como a cualquier política de combinación que controle cómo Real-Time Customer Profile combina atributos superpuestos en los fragmentos de perfil. Cuando un trabajo de segmentación se completa correctamente, puede recopilar información diversa acerca de la definición del segmento, como los errores que se hayan podido producir durante el procesamiento y el tamaño final de la audiencia. Se debe ejecutar un trabajo de segmento cada vez que desee actualizar la audiencia a la que se clasifica actualmente la definición del segmento.
Puede crear un nuevo trabajo de segmento realizando una petición POST al extremo /segment/jobs en la API Real-Time Customer Profile.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de trabajos de segmentación
Búsqueda del estado del trabajo del segmento
Puede utilizar id para un trabajo de segmento específico con el fin de realizar una solicitud de búsqueda (GET) y ver el estado actual del trabajo.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de trabajos de segmentación
Interpretar resultados del trabajo del segmento
Cuando se ejecutan correctamente los trabajos del segmento, el mapa segmentMembership se actualiza para cada perfil incluido en la definición del segmento. segmentMembership también almacena cualquier audiencia preevaluada que se haya introducido en Experience Platform, lo que permite la integración con otras soluciones como Adobe Audience Manager.
El ejemplo siguiente muestra el aspecto del atributo segmentMembership para cada registro de perfil individual:
{
"segmentMembership": {
"UPS": {
"04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
"timestamp": "2018-04-26T15:52:25+00:00",
"status": "realized"
},
"53cba6b2-a23b-454a-8069-fc41308f1c0f": {
"lastQualificationTime": "2018-04-26T15:52:25+00:00",
"status": "realized"
}
},
"Email": {
"abcd@adobe.com": {
"lastQualificationTime": "2017-09-26T15:52:25+00:00",
"status": "exited"
}
}
}
}
lastQualificationTimestatusEl estado de participación de la definición del segmento como parte de la solicitud actual. Debe ser igual a uno de los siguientes valores conocidos:
realized: la entidad cumple los requisitos para la definición del segmento.exited: la entidad está saliendo de la definición del segmento.
NOTEexited durante más de 30 días, según el lastQualificationTime, estará sujeta a eliminación.Acceder a resultados de trabajo de segmentos
Se puede acceder a los resultados de un trabajo de segmentación de una de las dos maneras siguientes: puede acceder a perfiles individuales o exportar una audiencia completa a un conjunto de datos.
Las siguientes secciones describen estas opciones con más detalle.
Búsqueda de un perfil
Si conoce el perfil específico al que desea acceder, puede hacerlo mediante la API Real-Time Customer Profile. Los pasos completos para acceder a perfiles individuales están disponibles en el tutorial Acceder a los datos del perfil del cliente en tiempo real mediante la API de perfil.
Exportación de un segmento
Una vez que un trabajo de segmentación se haya completado correctamente (el valor del atributo status es "SUCCEEDED"), puede exportar la audiencia a un conjunto de datos al que se pueda acceder y sobre el que se pueda actuar.
Se requieren los siguientes pasos para exportar la audiencia:
- Crear un conjunto de datos de destinatario: cree el conjunto de datos para albergar miembros de audiencia.
- Generar perfiles de audiencia en el conjunto de datos: rellene el conjunto de datos con perfiles individuales XDM en función de los resultados de un trabajo de segmentación.
- Supervisar progreso de exportación - Compruebe el progreso actual del proceso de exportación.
- Leer datos de audiencia - Recupere los perfiles individuales XDM resultantes que representan a los miembros de su audiencia.
Crear un conjunto de datos de destinatario
Al exportar una audiencia, primero se debe crear un conjunto de datos de destinatario. Es importante que el conjunto de datos esté configurado correctamente para garantizar que la exportación se realice correctamente.
Una de las consideraciones clave es el esquema en el que se basa el conjunto de datos (schemaRef.id en la solicitud de muestra de API que aparece a continuación). Para exportar una definición de segmento, el conjunto de datos debe basarse en XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Un esquema de unión es un esquema de solo lectura generado por el sistema que agrega los campos de esquemas que comparten la misma clase, en este caso la clase XDM Individual Profile. Para obtener más información sobre los esquemas de vista de unión, consulte la sección Perfil del cliente en tiempo real de la guía para desarrolladores de Schema Registry.
Existen dos formas de crear el conjunto de datos necesario:
- Usar API: Los pasos que siguen en este tutorial describen cómo crear un conjunto de datos que hace referencia a XDM Individual Profile Union Schema mediante la API Catalog.
- Uso de la interfaz de usuario: Para usar la interfaz de usuario de Adobe Experience Platform para crear un conjunto de datos que haga referencia al esquema de unión, siga los pasos del tutorial de la interfaz de usuario y, a continuación, vuelva a este tutorial para continuar con los pasos para generar perfiles de audiencia.
Si ya tiene un conjunto de datos compatible y conoce su ID, puede continuar directamente al paso para generar perfiles de audiencia.
Formato de API
POST /dataSets
Solicitud
La siguiente solicitud crea un nuevo conjunto de datos, que proporciona parámetros de configuración en la carga útil.
curl -X POST \
https://platform.adobe.io/data/foundation/catalog/dataSets \
-H 'Content-Type: application/json' \
-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}' \
-d '{
"name": "Segment Export",
"schemaRef": {
"id": "https://ns.adobe.com/xdm/context/profile__union",
"contentType": "application/vnd.adobe.xed+json;version=1"
}
}'
nameschemaRef.idRespuesta
Una respuesta correcta devuelve una matriz que contiene el ID único de solo lectura generado por el sistema del conjunto de datos recién creado. Se requiere un ID de conjunto de datos configurado correctamente para exportar correctamente los miembros de la audiencia.
[
"@/datasets/5b020a27e7040801dedba61b"
]
Generar perfiles para los miembros de la audiencia
Una vez que tenga un conjunto de datos que persiste en la unión, puede crear un trabajo de exportación para mantener los miembros de la audiencia en el conjunto de datos realizando una petición POST al extremo /export/jobs en la API Real-Time Customer Profile y proporcionando la información del ID del conjunto de datos y la definición del segmento para las definiciones de segmento que desea exportar.
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de trabajos de exportación
Monitorización del progreso de exportación
Como procesos de trabajo de exportación, puede supervisar su estado realizando una petición GET al extremo /export/jobs e incluyendo id del trabajo de exportación en la ruta. El trabajo de exportación se ha completado una vez que el campo status devuelve el valor "CORRECTO".
Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de trabajos de exportación
Pasos siguientes
Una vez que la exportación se haya completado correctamente, los datos estarán disponibles en Data Lake en Experience Platform. A continuación, puede usar Data Access API para obtener acceso a los datos mediante el batchId asociado con la exportación. Según el tamaño de la definición del segmento, los datos pueden estar en fragmentos y el lote puede constar de varios archivos.
Para obtener instrucciones paso a paso acerca de cómo usar la API Data Access para obtener acceso y descargar archivos por lotes, siga el tutorial de acceso a datos.
También puede tener acceso a los datos de definición de segmento exportados correctamente usando Adobe Experience Platform Query Service. Al usar la interfaz de usuario o la API RESTful, Query Service le permite escribir, validar y ejecutar consultas sobre datos dentro de Data Lake.
Para obtener más información sobre cómo consultar datos de audiencia, consulte la documentación sobre Query Service.