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 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:

Encabezados obligatorios

Este tutorial también requiere que haya completado el tutorial de autenticación para realizar correctamente llamadas a las API de 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:

Todos los recursos de Experience Platform están aislados en zonas protegidas virtuales específicas. Las solicitudes a las API Platform requieren un encabezado que especifique el nombre de la zona protegida en la que se realizará la operación:

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

Evaluación de una definición de segmento evaluate-a-segment

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 scheduled-evaluation

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

Creación de una programación

Al realizar una solicitud de 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 solicitud de PATCH al extremo /config/schedules 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

El horario se puede actualizar realizando una solicitud del PATCH al extremo /config/schedules 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

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 solicitud de 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 a 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 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"
      }
    }
  }
}

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 export

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 create-dataset

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:

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"
    }
}'

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 generate-profiles

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 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 solicitud de 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.