Evaluar y acceder a los resultados de los segmentos

Este documento proporciona un tutorial para evaluar los segmentos y acceder a los resultados de los mismos mediante el uso del Segmentation API.

Primeros pasos

Este tutorial requiere un conocimiento práctico de los distintos Adobe Experience Platform servicios que intervienen en la creación de segmentos de audiencia. Antes de comenzar este tutorial, consulte la documentación de los siguientes servicios:

  • Real-time Customer Profile:: Proporciona un perfil de cliente unificado en tiempo real basado en datos agregados de varias fuentes.
  • Adobe Experience Platform Segmentation Service:: Permite generar segmentos de audiencia a partir de Real-time Customer Profile datos.
  • Experience Data Model (XDM):: El marco estandarizado por el cual Platform organiza los datos de experiencia del cliente.
  • Simuladores: Experience Platform proporciona entornos limitados virtuales que dividen una sola Platform instancia en entornos virtuales independientes para ayudar a desarrollar y desarrollar aplicaciones de experiencia digital.

Encabezados requeridos

Este tutorial también requiere que haya completado el tutorial de autenticación para poder realizar correctamente llamadas a Platform las API. Al completar el tutorial de autenticación se proporcionan los valores para cada uno de los encabezados necesarios en todas las llamadas Experience Platform de API, 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. Las solicitudes a Platform las API 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 de Platform, consulte la documentación general delentorno limitado.

Todas las solicitudes de POST, PUT y PATCH requieren un encabezado adicional:

  • Content-Type: application/json

Evaluar un segmento

Una vez desarrollada, probada y guardada la definición del segmento, puede evaluar el segmento mediante una evaluación programada o una evaluación a petición.

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 en un momento específico, mientras que la evaluación a petición implica crear un trabajo de segmento para generar la audiencia inmediatamente. A continuación se describen los pasos para cada uno de ellos.

Si todavía no ha completado la creación de un segmento mediante el tutorial de la API de segmentación o ha creado una definición de segmento mediante el Generador de segmentos, hágalo antes de continuar con este tutorial.

Evaluación programada

Mediante una evaluación programada, su organización de IMS puede crear una programación recurrente para ejecutar automáticamente los trabajos de exportación.

NOTA

La evaluación programada puede habilitarse para entornos limitados con un máximo de cinco (5) directivas de combinación para XDM Individual Profile. Si su organización tiene más de cinco directivas de combinación para XDM Individual Profile dentro de un solo entorno de simulación de pruebas, no podrá usar la evaluación programada.

Crear una programación

Al realizar una solicitud de POST al extremo, puede crear una programación e incluir la hora específica en la que se debe activar la programación. /config/schedules

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 forma predeterminada, una programación se desactiva cuando se crea, a menos que la state propiedad se establezca active en el cuerpo de solicitud create (POST). Puede habilitar una programación (establecer la state en active /config/schedules ) realizando una solicitud de PATCH al extremo e incluyendo el ID de la programación en la ruta de acceso.

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

La temporización de programación se puede actualizar realizando una solicitud de PATCH al extremo e incluyendo el ID de la programación en la ruta de acceso. /config/schedules

Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de programaciones

Evaluación a petición

La evaluación a petición le permite crear un trabajo de segmento para generar un segmento de audiencia cuando lo necesite. A diferencia de la evaluación programada, esto solo sucederá cuando se solicite y no se repita.

Crear un trabajo de segmento

Un trabajo de segmento es un proceso asincrónico que crea un nuevo segmento de audiencia. Hace referencia a una definición de segmento, así como a cualquier directiva de combinación que controle la forma en que Real-time Customer Profile combina atributos superpuestos en los fragmentos de perfil. Cuando un trabajo de segmento se completa correctamente, puede recopilar información diversa sobre el segmento, como los errores que se hayan producido durante el procesamiento y el tamaño final de la audiencia.

Puede crear un nuevo trabajo de segmento realizando una solicitud de POST al /segment/jobs extremo en la Real-time Customer Profile API.

Encontrará información más detallada sobre el uso de este extremo en la guía de extremo de trabajos de segmentos

Buscar estado del trabajo del segmento

Puede usar el id para un trabajo de segmento específico para realizar una solicitud de búsqueda (GET) con el fin de realizar la vista del 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 segmentos

Interpretar resultados de segmentos

Cuando los trabajos de segmentos se ejecutan correctamente, el segmentMembership mapa se actualiza para cada perfil incluido en el segmento. segmentMembership también almacena todos los segmentos de audiencia preevaluados que se ingieren en Platform, lo que permite la integración con otras soluciones como Adobe Audience Manager.

El siguiente ejemplo muestra el aspecto del segmentMembership atributo para cada registro de perfil individual:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "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"
      }
    }
  }
}
Propiedad Descripción
lastQualificationTime Marca de hora cuando se hizo la afirmación de pertenencia a segmentos y el perfil entró o salió del segmento.
status El estado de la participación de segmentos como parte de la solicitud actual. Debe ser igual a uno de los siguientes valores conocidos:
  • existing:: La entidad sigue estando en el segmento.
  • realized:: La entidad está ingresando al segmento.
  • exited:: La entidad está saliendo del segmento.

Acceso a los resultados de los segmentos

Se puede acceder a los resultados de un trabajo de segmento 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.

Buscar un perfil

Si conoce el perfil específico al que desea acceder, puede hacerlo mediante la Real-time Customer Profile API. Los pasos completos para acceder a perfiles individuales están disponibles en Access Real-time Customer Perfil data mediante el tutorial de la API de Perfil.

Exportación de un segmento

Una vez completado correctamente un trabajo de segmentación (el valor del status atributo es "SUCCEEDED"), puede exportar la audiencia a un conjunto de datos en el que se pueda acceder a él y tomar medidas al respecto.

Se requieren los siguientes pasos para exportar la audiencia:

Creación de 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 se configure correctamente para garantizar que la exportación se realiza 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 se muestra a continuación). Para exportar un segmento, el conjunto de datos debe basarse en el XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Un esquema de unión es un esquema de sólo lectura generado por el sistema que agrega los campos de esquemas que comparten la misma clase, en este caso la clase de Perfil individual XDM. Para obtener más información sobre los esquemas de vista de uniones, consulte la sección Perfil de clientes en tiempo real de la guíapara desarrolladores de Esquema Registry.

Existen dos maneras de crear el conjunto de datos necesario:

  • Uso de API: Los pasos siguientes en este tutorial describen cómo crear un conjunto de datos que haga referencia al XDM Individual Profile Union Schema mediante la Catalog API.
  • Uso de la interfaz de usuario: Para utilizar la interfaz de usuario para crear un conjunto de datos que haga referencia al esquema de unión, siga los pasos del tutorial Adobe Experience Platform 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 con el paso para generar perfilesde audiencia.

Formato 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: {IMS_ORG}' \
  -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"
    },
    "fileDescription": {
        "persisted": true,
        "containerFormat": "parquet",
        "format": "parquet"
    }
}'
Propiedad Descripción
name Un nombre descriptivo para el conjunto de datos.
schemaRef.id ID de la vista de unión (esquema) con la que se asociará el conjunto de datos.
fileDescription.persisted Un valor booleano que cuando se establece en true, permite que el conjunto de datos persista en la vista de unión.

Respuesta

Una respuesta correcta devuelve una matriz que contiene la ID única de sólo lectura generada 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 miembros de audiencia

Una vez que tenga un conjunto de datos que mantenga la unión, puede crear un trabajo de exportación para que los miembros de la audiencia permanezcan en el conjunto de datos realizando una solicitud de POST al extremo en la /export/jobs Real-time Customer Profile API y proporcionando la ID del conjunto de datos y la información del segmento para los segmentos 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

Monitorear el progreso de exportación

Como proceso de trabajo de exportación, puede supervisar su estado realizando una solicitud de GET al /export/jobs extremo e incluyendo el id del trabajo de exportación en la ruta. El trabajo de exportación se completa una vez que el status campo devuelve el valor "SUCCEEDED".

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 dentro de la Data Lake en Experience Platform. A continuación, puede utilizar el Data Access API para acceder a los datos mediante el batchId vínculo asociado con la exportación. Según el tamaño del segmento, los datos pueden estar en fragmentos y el lote puede constar de varios archivos.

Para obtener instrucciones paso a paso sobre cómo utilizar la Data Access API para acceder y descargar archivos por lotes, siga el tutorial Acceso adatos.

También puede acceder a los datos de segmentos exportados correctamente mediante Adobe Experience Platform Query Service. Con la interfaz de usuario o la API RESTful, Query Service puede escribir, validar y ejecutar consultas en los datos dentro de la Data Lake.

Para obtener más información sobre cómo consulta de datos de audiencia, consulte la documentación de Query Service.

En esta página