Documentación Experience Platform Guía de catálogos y conjuntos de datos

Habilitar un conjunto de datos para actualizaciones de perfil mediante API

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Temas:
Catálogo

Creado para:

Desarrollador

Este tutorial cubre el proceso de activación de un conjunto de datos con funciones de "actualización" para realizar actualizaciones de los datos del perfil del cliente en tiempo real. Esto incluye pasos para crear un nuevo conjunto de datos y configurar uno existente.

NOTE

El flujo de trabajo descrito en este tutorial solo funciona para la ingesta por lotes. Para actualizaciones de ingesta de transmisión, consulte la guía sobre envío de actualizaciones parciales de fila al perfil del cliente en tiempo real mediante la preparación de datos.

Introducción

Este tutorial requiere una comprensión práctica de varios servicios de Adobe Experience Platform implicados en la administración de conjuntos de datos con perfil habilitado. Antes de comenzar este tutorial, revise la documentación de estos servicios relacionados de Platform:

Real-Time Customer Profile: proporciona un perfil de consumidor unificado y en tiempo real basado en los datos agregados de varias fuentes.
Catalog Service: una API RESTful que le permite crear conjuntos de datos y configurarlos para Real-Time Customer Profile y Identity Service.
Experience Data Model (XDM): El marco estandarizado mediante el cual Platform organiza los datos de experiencia del cliente.
Ingesta por lotes: La API de ingesta por lotes le permite ingerir datos en Experience Platform como archivos por lotes.

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

Lectura de llamadas de API de muestra

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

Recopilación de valores para los encabezados obligatorios

Para poder realizar llamadas a las API de 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 obligatorios en todas las llamadas de API de Experience Platform, como se muestra a continuación:

Authorization: Bearer {ACCESS_TOKEN}
x-api-key: {API_KEY}
x-gw-ims-org-id: {ORG_ID}

Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado Content-Type adicional. El valor correcto de este encabezado se muestra en las solicitudes de ejemplo cuando es necesario.

Todos los recursos de Experience Platform están aislados en zonas protegidas virtuales específicas. Todas las solicitudes a las API Platform requieren un encabezado x-sandbox-name que especifica el nombre de la zona protegida en la que se realizará la operación. Para obtener más información sobre las zonas protegidas en Platform, consulte la documentación de información general sobre las zonas protegidas.

Crear un conjunto de datos habilitado para actualizaciones de perfil

Al crear un nuevo conjunto de datos, puede habilitar ese conjunto de datos para Perfil y habilitar las funcionalidades de actualización en el momento de la creación.

NOTE

Para crear un nuevo conjunto de datos habilitado para perfiles, debe conocer el ID de un esquema XDM existente que esté habilitado para el perfil. Para obtener información sobre cómo buscar o crear un esquema habilitado para el perfil, vea el tutorial sobre creación de un esquema mediante la API de Registro de esquemas.

Para crear un conjunto de datos habilitado para Perfil y actualizaciones, use una solicitud del POST al extremo /dataSets.

Formato de API

POST /dataSets

Solicitud

Al incluir tanto unifiedIdentity como unifiedProfile en tags en el cuerpo de la solicitud, el conjunto de datos se habilitará para Profile tras la creación. Dentro de la matriz unifiedProfile, al agregar isUpsert:true se agregará la capacidad para que el conjunto de datos admita actualizaciones.

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": "Sample dataset",
        "description: "A sample dataset with a sample description.",
        "schemaRef": {
            "id": "https://ns.adobe.com/{TENANT_ID}/schemas/31670881463308a46f7d2cb09762715",
            "contentType": "application/vnd.adobe.xed-full-notext+json; version=1"
        },
        "tags": {
            "unifiedIdentity": [
                "enabled: true"
            ],
            "unifiedProfile": [
                "enabled: true",
                "isUpsert: true"
            ]
        }
      }'

Propiedad

Descripción

schemaRef.id

El identificador del esquema habilitado para Profile en el que se basará el conjunto de datos.

{TENANT_ID}

El área de nombres dentro de Schema Registry que contiene recursos que pertenecen a su organización. Consulte la sección TENANT_ID de la guía para desarrolladores de Schema Registry para obtener más información.

Respuesta

Una respuesta correcta muestra una matriz que contiene el ID del conjunto de datos recién creado en forma de "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configurar un conjunto de datos existente configure-an-existing-dataset

Los siguientes pasos tratan sobre cómo configurar un conjunto de datos con perfil habilitado para la funcionalidad de actualización (actualización).

NOTE

Para configurar un conjunto de datos con perfil habilitado para su actualización, primero debe deshabilitar el conjunto de datos para el perfil y, a continuación, volver a habilitarlo junto con la etiqueta isUpsert. Si el conjunto de datos existente no está habilitado para el perfil, puede continuar directamente con los pasos para habilitar el conjunto de datos para el perfil y actualizar. Si no está seguro, los siguientes pasos le muestran cómo comprobar si el conjunto de datos ya está habilitado.

Compruebe si el conjunto de datos está habilitado para el perfil

Con la API Catalog, puede inspeccionar un conjunto de datos existente para determinar si está habilitado para usarse en Real-Time Customer Profile. La siguiente llamada recupera los detalles de un conjunto de datos por ID.

Formato de API

GET /dataSets/{DATASET_ID}

Parámetro

Descripción

{DATASET_ID}

El ID del conjunto de datos que desea inspeccionar.

Solicitud

curl -X GET 'https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e' \
  -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}'

Respuesta

{
    "5b020a27e7040801dedbf46e": {
        "name": "{DATASET_NAME}",
        "imsOrg": "{ORG_ID}",
        "tags": {
            "adobe/pqs/table": [
                "unifiedprofileingestiontesteventsdataset"
            ],
            "unifiedIdentity": [
                "enabled:true"
            ],
            "unifiedProfile": [
                "enabled:true"
            ]
        },
        "version": "1.0.1",
        "created": 1536536917382,
        "updated": 1539793978215,
        "createdClient": "{CLIENT_CREATED}",
        "createdUser": "{CREATED_BY}",
        "updatedUser": "{CREATED_BY}",
        "viewId": "{VIEW_ID}",
        "files": "@/dataSetFiles?dataSetId=5b020a27e7040801dedbf46e",
        "schema": "{SCHEMA}",
        "schemaRef": {
            "id": "https://ns.adobe.com/xdm/context/experienceevent",
            "contentType": "application/vnd.adobe.xed+json"
        }
    }
}

En la propiedad tags, puede ver que unifiedProfile está presente con el valor enabled:true. Por lo tanto, Real-Time Customer Profile está habilitado para este conjunto de datos.

Deshabilitar el conjunto de datos para el perfil

Para configurar un conjunto de datos con perfil habilitado para las actualizaciones, primero debe deshabilitar las etiquetas unifiedProfile y unifiedIdentity y luego volver a habilitarlas junto con la etiqueta isUpsert. Esto se realiza mediante dos solicitudes de PATCH, una para deshabilitar y otra para volver a habilitar.

WARNING

Los datos introducidos en el conjunto de datos mientras está deshabilitado no se introducirán en el almacén de perfiles. Debe evitar la ingesta de datos en el conjunto de datos hasta que se haya vuelto a habilitar para el perfil.

Formato de API

PATCH /dataSets/{DATASET_ID}

Parámetro

Descripción

{DATASET_ID}

El ID del conjunto de datos que desea actualizar.

Solicitud

El primer cuerpo de solicitud de PATCH incluye un path para unifiedProfile y un path para unifiedIdentity, lo que establece value para enabled:false en ambas rutas de acceso para deshabilitar las etiquetas.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+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 '[
        {
            "op": "replace",
            "path": "/tags/unifiedProfile",
            "value": ["enabled:false"]
        },
        {
            "op": "replace",
            "path": "/tags/unifiedIdentity",
            "value": ["enabled:false"]
        }
      ]'

Respuesta

Una solicitud correcta del PATCH devuelve el estado HTTP 200 (OK) y una matriz que contiene el ID del conjunto de datos actualizado. Este ID debe coincidir con el enviado en la solicitud del PATCH. Ahora se han deshabilitado las etiquetas unifiedProfile y unifiedIdentity.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Habilitar el conjunto de datos para perfiles y actualizaciones enable-the-dataset

Se puede habilitar un conjunto de datos existente para las actualizaciones de perfiles y atributos mediante una sola solicitud de PATCH.

IMPORTANT

Al habilitar el conjunto de datos para el perfil, asegúrese de que el esquema con el que está asociado el conjunto de datos esté habilitado para el perfil also. Si el esquema no tiene habilitado el perfil, el conjunto de datos no aparecerá como habilitado para el perfil en la interfaz de usuario de Platform.

Formato de API

PATCH /dataSets/{DATASET_ID}

Parámetro

Descripción

{DATASET_ID}

El ID del conjunto de datos que desea actualizar.

Solicitud

El cuerpo de la solicitud incluye un path para unifiedProfile que establece value para incluir las etiquetas enabled y isUpsert, ambas establecidas en true, y un path para unifiedIdentity que establece value para incluir la etiqueta enabled establecida en true.

curl -X PATCH https://platform.adobe.io/data/foundation/catalog/dataSets/5b020a27e7040801dedbf46e \
  -H 'Content-Type:application/json-patch+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 '[
        {
            "op": "add",
            "path": "/tags/unifiedProfile",
            "value": [
                "enabled:true",
                "isUpsert:true"
            ]
        },
        {
            "op": "add",
            "path": "/tags/unifiedIdentity",
            "value": [
                "enabled:true"
            ]
        }
      ]'

Respuesta

Una solicitud correcta del PATCH devuelve el estado HTTP 200 (OK) y una matriz que contiene el ID del conjunto de datos actualizado. Este ID debe coincidir con el enviado en la solicitud del PATCH. La etiqueta unifiedProfile y la etiqueta unifiedIdentity se han habilitado y configurado para actualizaciones de atributos.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Pasos siguientes

Los flujos de trabajo de ingesta por lotes ahora pueden utilizar el perfil y el conjunto de datos habilitado para actualizar los datos del perfil. Para obtener más información acerca de la ingesta de datos en Adobe Experience Platform, comience por leer la descripción general de la ingesta de datos.

recommendation-more-help

c5c02be6-79a3-4a2f-b766-136bffe8b676