Evaluación y acceso a resultados de definición de segmentos

Este documento proporciona un tutorial para evaluar definiciones de segmentos y acceder a estos resultados mediante la variable Segmentation API.

Primeros pasos

Este tutorial requiere una comprensión práctica de los distintos Adobe Experience Platform servicios implicados en la creación de audiencias. Antes de comenzar este tutorial, revise la documentación de los siguientes servicios:

Encabezados obligatorios

Este tutorial también requiere que haya completado el tutorial de autenticación para realizar llamadas correctamente a Platform API. Al completar el tutorial de autenticación, se proporcionan los valores para cada uno de los encabezados necesarios en todas las Experience Platform Llamadas de API, 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 aisladas para zonas protegidas virtuales específicas. Solicitudes a Platform Las API requieren un encabezado que especifique el nombre de la zona protegida en la que se realizará la operación:

  • x-sandbox-name: {SANDBOX_NAME}
NOTA

Para obtener más información sobre las zonas protegidas en Platform, consulte la documentación general de zona protegida.

Todas 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.

Evaluación programada (también conocida como "segmentación programada") permite crear una programación recurrente para ejecutar un trabajo de exportación a una hora específica, mientras que evaluación a la carta implica crear un trabajo de segmento para crear la audiencia inmediatamente. A continuación se describen los pasos de cada uno.

Si todavía no ha completado la Creación de una definición de segmento mediante la API de segmentación tutorial o creación de una definición de segmento utilizando 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.

NOTA

La evaluación programada se puede habilitar para zonas protegidas con un máximo de cinco (5) políticas de combinación para XDM Individual Profile. Si su organización tiene más de cinco políticas de combinación para XDM Individual Profile en un solo entorno de zona protegida, no podrá utilizar la evaluación programada.

Creación de una programación

Realizando una solicitud de POST a /config/schedules punto final, puede crear una programación e incluir la hora específica en la que se debe activar.

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

Habilitar una programación

De forma predeterminada, una programación está inactiva cuando se crea a menos que state La propiedad se establece en active en el cuerpo de la solicitud crear (POST). Puede activar una programación (establezca el state hasta active) realizando una solicitud de PATCH a /config/schedules e incluir el ID de la programación en la ruta.

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

Actualizar la hora de programación

El horario de programación se puede actualizar realizando una solicitud del PATCH al /config/schedules e incluir el ID de la programación en la ruta.

Encontrará información más detallada sobre el uso de este punto de conexión 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 el modo en que 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 segmentación realizando una solicitud de POST a /segment/jobs punto final en la Real-Time Customer Profile API.

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

Búsqueda del estado del trabajo del segmento

Puede usar el complemento id para que un trabajo de segmento específico realice una solicitud de consulta (GET) para ver el estado actual del trabajo.

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

Interpretar resultados del trabajo del segmento

Cuando los trabajos de segmentos se ejecutan correctamente, la variable segmentMembership el mapa se actualiza para cada perfil incluido en la definición del segmento. segmentMembership también almacena cualquier audiencia evaluada previamente que se incorpora en Platform, permitiendo la integración con otras soluciones como Adobe Audience Manager.

El siguiente ejemplo muestra lo que puede hacer el segmentMembership Este atributo tiene el siguiente aspecto 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"
      }
    }
  }
}
Propiedad Descripción
lastQualificationTime La marca de tiempo cuando se realizó la afirmación del abono del segmento y el perfil entró o salió de la definición del segmento.
status El 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.
NOTA

Cualquier pertenencia a segmento que esté en la variable exited estado durante más de 30 días, según el lastQualificationTime, estará sujeto 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 usando el complemento Real-Time Customer Profile API. Los pasos completos para acceder a perfiles individuales están disponibles en la Acceso a datos de perfil del cliente en tiempo real mediante la API de perfil tutorial.

Exportación de un segmento

Después de que un trabajo de segmentación se haya completado correctamente (el valor de status atributo 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

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 ejemplo de API que aparece a continuación). Para exportar una definición de segmento, el conjunto de datos debe basarse en la variable 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 Registro de esquemas.

Existen dos formas 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 a la variable XDM Individual Profile Union Schema uso del Catalog API.
  • Uso de la interfaz de usuario: Para usar la variable Adobe Experience Platform interfaz de usuario para crear un conjunto de datos que haga referencia al esquema de unión, siga los pasos en la Tutorial de IU y vuelva a este tutorial para continuar con los pasos para generación de perfiles de audiencia.

Si ya tiene un conjunto de datos compatible y conoce su ID, puede continuar directamente con el paso de generación de 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"
    }
}'
Propiedad Descripción
name Nombre descriptivo del conjunto de datos.
schemaRef.id El ID de la vista de unión (esquema) a la que se asociará el conjunto de datos.

Respuesta

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 solicitud del POST a /export/jobs punto final en la Real-Time Customer Profile y proporciona el ID del conjunto de datos y la información de definición del segmento para las definiciones de segmento que desea exportar.

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

Monitorización del progreso de exportación

Como procesa un trabajo de exportación, puede monitorizar su estado realizando una solicitud de GET a /export/jobs punto final e incluir el id del trabajo de exportación en la ruta. El trabajo de exportación se completa una vez que status devuelve el valor "SUCCEEDED".

Encontrará información más detallada sobre el uso de este punto de conexión 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 el Data Lake in Experience Platform. A continuación, puede utilizar la variable Data Access API para acceder a los datos utilizando 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 el complemento Data Access API para acceder y descargar archivos por lotes, siga las Tutorial de acceso a datos.

También puede acceder a los datos de definición de segmento exportados correctamente mediante Adobe Experience Platform Query Service. Uso de la interfaz de usuario o la API de RESTful, Query Service 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.

En esta página