Impor a conformidade de uso de dados para uma definição de segmento usando APIs

Este tutorial aborda as etapas para impor a conformidade do uso de dados para definições de segmento usando APIs.

Introdução

Este tutorial requer entendimento prático dos seguintes componentes do Adobe Experience Platform:

As seções a seguir fornecem informações adicionais que você precisará saber para fazer chamadas com êxito para as APIs do Platform.

Leitura de chamadas de API de amostra

Este tutorial fornece exemplos de chamadas de API para demonstrar como formatar suas solicitações. Isso inclui caminhos, cabeçalhos necessários e conteúdos de solicitação formatados corretamente. Também fornece exemplos de JSON retornado nas respostas da API. Para obter informações sobre as convenções usadas na documentação para chamadas de API de exemplo, consulte a seção sobre como ler chamadas de API de exemplo no guia de solução de problemas Experience Platform.

Coletar valores para cabeçalhos necessários

Para fazer chamadas para APIs do Platform, primeiro complete o tutorial de autenticação. Concluir o tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API da Experience Platform, conforme mostrado abaixo:

Todos os recursos em Experience Platform estão isolados em sandboxes virtuais específicas. Todas as solicitações para Platform APIs exigem um cabeçalho que especifique o nome da sandbox em que a operação ocorrerá:

Todas as solicitações que contêm um conteúdo (POST, PUT, PATCH) exigem um cabeçalho adicional:

Pesquisar uma política de mesclagem para uma definição de segmento merge-policy

Esse fluxo de trabalho começa acessando uma definição de segmento conhecida. As definições de segmento habilitadas para uso em Real-Time Customer Profile contêm uma ID de política de mesclagem na definição de segmento. Essa política de mesclagem contém informações sobre quais conjuntos de dados devem ser incluídos na definição do segmento, que por sua vez contém quaisquer rótulos de uso de dados aplicáveis.

Usando a API Segmentation, você pode pesquisar uma definição de segmento por sua ID para encontrar a política de mesclagem associada.

Formato da API

GET /segment/definitions/{SEGMENT_DEFINITION_ID}

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna os detalhes da definição de 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
  }
}

Localizar os conjuntos de dados de origem na política de mesclagem datasets

As políticas de mesclagem contêm informações sobre os conjuntos de dados de origem, que por sua vez contêm rótulos de uso de dados. Você pode pesquisar os detalhes de uma política de mesclagem fornecendo a ID da política de mesclagem em uma solicitação GET para a API Profile. Mais informações sobre políticas de mesclagem podem ser encontradas no manual do ponto de extremidade de políticas de mesclagem.

Formato da API

GET /config/mergePolicies/{MERGE_POLICY_ID}

Solicitação

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

Resposta

Uma resposta bem-sucedida retorna os detalhes da política de mesclagem.

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

Avaliar conjuntos de dados para violações de política

Depois de obter as IDs dos conjuntos de dados de origem da política de mesclagem, você poderá usar a API do Serviço de política para avaliar esses conjuntos de dados em relação a ações de marketing específicas para verificar violações da política de uso de dados.

Para avaliar os conjuntos de dados, você deve fornecer o nome da ação de marketing no caminho de uma solicitação POST, além de fornecer as IDs do conjunto de dados no corpo da solicitação, como mostrado no exemplo abaixo.

Formato da API

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

Solicitação

A solicitação a seguir testa a ação de marketing exportToThirdParty em relação aos conjuntos de dados obtidos na etapa anterior. A carga da solicitação é uma matriz que contém as IDs de cada conjunto de dados.

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

Resposta

Uma resposta bem-sucedida retorna o URI da ação de marketing, os rótulos de uso de dados coletados dos conjuntos de dados fornecidos e uma lista de quaisquer políticas de uso de dados que foram violadas como resultado do teste da ação com esses rótulos. Neste exemplo, a política "Exportar dados para terceiros" é mostrada na matriz violatedPolicies, indicando que a ação de marketing acionou uma violação de política.

{
  "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"
    }
  ]
}

Usando os dados retornados na resposta da API, você pode configurar protocolos no aplicativo de experiência para aplicar adequadamente as violações de política quando elas ocorrerem.

Filtrar campos de dados

Se a definição de segmento não passar na avaliação, você poderá ajustar os dados incluídos na definição de segmento por meio de um dos dois métodos descritos abaixo.

Atualizar a política de mesclagem da definição do segmento

Atualizar a política de mesclagem de uma definição de segmento ajustará os conjuntos de dados e campos que serão incluídos quando o trabalho do segmento for executado. Consulte a seção sobre atualização de uma política de mesclagem existente no tutorial de política de mesclagem de APIs para obter mais informações.

Restringir campos de dados específicos ao exportar a definição de segmento

Ao exportar uma definição de segmento para um conjunto de dados usando a API Segmentation, você pode filtrar os dados incluídos na exportação usando o parâmetro fields. Quaisquer campos de dados adicionados a esse parâmetro serão incluídos na exportação, enquanto todos os outros campos de dados serão excluídos.

Considere uma definição de segmento que tenha campos de dados chamados "A", "B" e "C". Se você deseja exportar apenas o campo "C", o parâmetro fields conterá apenas o campo "C". Ao fazer isso, os campos "A" e "B" seriam excluídos ao exportar a definição do segmento.

Consulte a seção sobre exportação de uma definição de segmento no tutorial de segmentação para obter mais informações.

Próximas etapas

Ao seguir este tutorial, você pesquisou os rótulos de uso de dados associados a uma definição de segmento e os testou quanto a violações de política em relação a ações de marketing específicas. Para obter mais informações sobre a Governança de dados no Experience Platform, leia a visão geral da Governança de dados.