Aplicar el cumplimiento del uso de datos para una definición de segmento mediante API

Este tutorial cubre los pasos para aplicar el cumplimiento del uso de datos para definiciones de segmentos mediante API.

Introducción

Este tutorial requiere una comprensión práctica de los siguientes componentes de Adobe Experience Platform:

Las secciones siguientes proporcionan información adicional que necesitará 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:

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

Todas las solicitudes que contienen una carga útil (POST, PUT, PATCH) requieren un encabezado adicional:

Búsqueda de una política de combinación para una definición de segmento merge-policy

Este flujo de trabajo comienza accediendo a una definición de segmento conocida. Las definiciones de segmento habilitadas para usarse en Real-Time Customer Profile contienen un identificador de política de combinación dentro de su definición de segmento. Esta política de combinación contiene información sobre qué conjuntos de datos se van a incluir en la definición del segmento, que a su vez contienen cualquier etiqueta de uso de datos aplicable.

Con la API Segmentation, puede buscar una definición de segmento por su ID para encontrar su política de combinación asociada.

Formato de API

GET /segment/definitions/{SEGMENT_DEFINITION_ID}

Solicitud

curl -X GET \
  https://platform.adobe.io/data/core/ups/segment/definitions/24379cae-726a-4987-b7b9-79c32cddb5c1 \
  -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

Una respuesta correcta devuelve los detalles de la definición del segmento.

{
    "id": "24379cae-726a-4987-b7b9-79c32cddb5c1",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "imsOrgId": "{ORG_ID}",
    "name": "Cart abandons in CA",
    "description": "",
    "expression": {
        "type": "PQL",
        "format": "pql/text",
        "value": "homeAddress.countryISO = 'US'"
    },
    "mergePolicyId": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "evaluationInfo": {
        "batch": {
            "enabled": true
        },
        "continuous": {
            "enabled": false
        },
        "synchronous": {
            "enabled": false
        }
    },
    "creationTime": 1556094486000,
    "updateEpoch": 1556094486000,
    "updateTime": 1556094486000
  }
}

Buscar los conjuntos de datos de origen de la política de combinación datasets

Las políticas de combinación contienen información sobre sus conjuntos de datos de origen, que a su vez contienen etiquetas de uso de datos. Puede buscar los detalles de una política de combinación proporcionando el ID de la política de combinación en una solicitud de GET a la API Profile. Encontrará más información sobre las políticas de combinación en la guía de extremo de políticas de combinación.

Formato de API

GET /config/mergePolicies/{MERGE_POLICY_ID}

Solicitud

curl -X GET \
  https://platform.adobe.io/data/core/ups/config/mergePolicies/2b43d78d-0ad4-4c1e-ac2d-574c09b01119 \
  -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

Una respuesta correcta devuelve los detalles de la política de combinación.

{
    "id": "2b43d78d-0ad4-4c1e-ac2d-574c09b01119",
    "imsOrgId": "{ORG_ID}",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "version": 1,
    "identityGraph": {
        "type": "none"
    },
    "attributeMerge": {
        "type":"dataSetPrecedence",
        "data": {
            "order": ["5b95b155419ec801e6eee780", "5b7c86968f7b6501e21ba9df"]
        }
    },
    "default": false,
    "updateEpoch": 1551127597
}

Evaluar conjuntos de datos para infracciones de directivas

Una vez que haya obtenido los ID de los conjuntos de datos de origen de la política de combinación, puede usar la API del servicio de políticas para evaluar esos conjuntos de datos con respecto a acciones de marketing específicas a fin de comprobar violaciones de la política de uso de datos.

Para evaluar los conjuntos de datos, debe proporcionar el nombre de la acción de marketing en la ruta de una solicitud de POST, a la vez que proporciona los ID de conjuntos de datos dentro del cuerpo de la solicitud, como se muestra en el ejemplo siguiente.

Formato de API

POST /marketingActions/core/{MARKETING_ACTION_NAME}/constraints
POST /marketingActions/custom/{MARKETING_ACTION_NAME}/constraints

Solicitud

La siguiente solicitud prueba la acción de marketing exportToThirdParty con los conjuntos de datos obtenidos en el paso anterior. La carga útil solicitada es una matriz que contiene los ID de cada conjunto de datos.

curl -X POST \
  https://platform.adobe.io/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty/constraints
  -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}' \
  -H 'Content-Type: application/json' \
  -d '[
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780"
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df"
    }
  ]'

Respuesta

Una respuesta correcta devuelve el URI de la acción de marketing, las etiquetas de uso de datos recopiladas de los conjuntos de datos proporcionados y una lista de cualquier política de uso de datos que se haya violado como resultado de la prueba de la acción contra esas etiquetas. En este ejemplo, la directiva "Exportar datos a terceros" se muestra en la matriz violatedPolicies, lo que indica que la acción de marketing desencadenó una infracción de directiva.

{
  "timestamp": 1556324277895,
  "clientId": "{CLIENT_ID}",
  "userId": "{USER_ID}",
  "imsOrg": "{ORG_ID}",
  "marketingActionRef": "https://platform.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty",
  "duleLabels": [
    "C1",
    "C2",
    "C4",
    "C5"
  ],
  "discoveredLabels": [
    {
      "entityType": "dataSet",
      "entityId": "5b95b155419ec801e6eee780",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C2",
            ],
            "path": "/properties/_customer"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/geoUnit"
          },
          {
            "labels": [
              "C1"
            ],
            "path": "/properties/identityMap"
          }
        ]
      }
    },
    {
      "entityType": "dataSet",
      "entityId": "5b7c86968f7b6501e21ba9df",
      "dataSetLabels": {
        "connection": {
          "labels": []
        },
        "dataSet": {
          "labels": [
            "C5"
          ]
        },
        "fields": [
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/createdByBatchID"
          },
          {
            "labels": [
              "C5"
            ],
            "path": "/properties/faxPhone"
          }
        ]
      }
    }
  ],
  "violatedPolicies": [
    {
      "name": "Export Data to Third Party",
      "status": "ENABLED",
      "marketingActionRefs": [
        "https://platform-stage.adobe.io:443/data/foundation/dulepolicy/marketingActions/custom/exportToThirdParty"
      ],
      "description": "Conditions under which data cannot be exported to a third party",
      "deny": {
        "operator": "OR",
        "operands": [
          {
            "label": "C1"
          },
          {
            "operator": "AND",
            "operands": [
              {
                "label": "C3"
              },
              {
                "label": "C7"
              }
            ]
          }
        ]
      },
      "imsOrg": "{ORG_ID}",
      "created": 1565651746693,
      "createdClient": "{CREATED_CLIENT}",
      "createdUser": "{CREATED_USER",
      "updated": 1565723012139,
      "updatedClient": "{UPDATED_CLIENT}",
      "updatedUser": "{UPDATED_USER}",
      "_links": {
        "self": {
          "href": "https://platform-stage.adobe.io/data/foundation/dulepolicy/policies/custom/5d51f322e553c814e67af1a3"
        }
      },
      "id": "5d51f322e553c814e67af1a3"
    }
  ]
}

Con los datos devueltos en la respuesta de API, puede configurar protocolos en su aplicación de experiencia para aplicar correctamente infracciones de directivas cuando se producen.

Filtrar campos de datos

Si la definición del segmento no supera la evaluación, puede ajustar los datos incluidos en la definición del segmento mediante uno de los dos métodos descritos a continuación.

Actualizar la política de combinación de la definición del segmento

Al actualizar la política de combinación de una definición de segmento, se ajustarán los conjuntos de datos y los campos que se incluirán cuando se ejecute el trabajo de segmentación. Consulte la sección sobre actualización de una política de combinación existente en el tutorial de la política de combinación de API para obtener más información.

Restringir campos de datos específicos al exportar la definición del segmento

Al exportar una definición de segmento a un conjunto de datos mediante la API Segmentation, puede filtrar los datos que se incluyen en la exportación mediante el parámetro fields. Cualquier campo de datos añadido a este parámetro se incluirá en la exportación, mientras que el resto de campos de datos se excluirán.

Imagine una definición de segmento que tenga campos de datos llamados "A", "B" y "C". Si solo desea exportar el campo "C", el parámetro fields contendría el campo "C" solamente. Al hacerlo, los campos "A" y "B" se excluirían al exportar la definición del segmento.

Consulte la sección sobre exportación de una definición de segmento en el tutorial de segmentación para obtener más información.

Pasos siguientes

Al seguir este tutorial, ha buscado las etiquetas de uso de datos asociadas a una definición de segmento y las ha probado para detectar infracciones de directivas en acciones de marketing específicas. Para obtener más información sobre la administración de datos en Experience Platform, lea la descripción general de Administración de datos.