Ativar um conjunto de dados para atualizações de perfil usando APIs

Este tutorial aborda o processo de habilitação de um conjunto de dados com recursos de "substituição" para fazer atualizações nos dados do Perfil do cliente em tempo real. Isso inclui etapas para criar um novo conjunto de dados e configurar um conjunto de dados existente.

Introdução

Este tutorial requer uma compreensão funcional de vários serviços da Adobe Experience Platform envolvidos no gerenciamento de conjuntos de dados habilitados para perfis. Antes de iniciar este tutorial, reveja a documentação desses serviços Platform relacionados:

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

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:

Todas as solicitações que contêm uma carga (POST, PUT, PATCH) exigem um cabeçalho Content-Type adicional. O valor correto desse cabeçalho é mostrado nas solicitações de exemplo, quando necessário.

Todos os recursos em Experience Platform estão isolados em sandboxes virtuais específicas. Todas as solicitações para APIs Platform exigem um cabeçalho x-sandbox-name que especifique o nome da sandbox em que a operação ocorrerá. Para obter mais informações sobre sandboxes em Platform, consulte a documentação de visão geral da sandbox.

Criar um conjunto de dados habilitado para atualizações de perfil

Ao criar um novo conjunto de dados, você pode habilitá-lo para o Perfil e habilitar os recursos de atualização no momento da criação.

Para criar um conjunto de dados habilitado para Perfil e atualizações, use uma solicitação POST para o ponto de extremidade /dataSets.

Formato da API

POST /dataSets

Solicitação

Ao incluir unifiedIdentity e unifiedProfile em tags no corpo da solicitação, o conjunto de dados será habilitado para Profile após a criação. Na matriz unifiedProfile, adicionar isUpsert:true adicionará a capacidade do conjunto de dados de oferecer suporte a atualizações.

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

Resposta

Uma resposta bem-sucedida mostra uma matriz contendo a ID do conjunto de dados recém-criado na forma de "@/dataSets/{DATASET_ID}".

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Configurar um conjunto de dados existente configure-an-existing-dataset

As etapas a seguir abordam como configurar um conjunto de dados habilitado para perfil existente para a funcionalidade de atualização (substituição).

Verifique se o conjunto de dados está ativado para o Perfil

Usando a API Catalog, você pode inspecionar um conjunto de dados existente para determinar se ele está habilitado para uso em Real-Time Customer Profile. A chamada a seguir recupera os detalhes de um conjunto de dados por ID.

Formato da API

GET /dataSets/{DATASET_ID}

Solicitação

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

Resposta

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

Na propriedade tags, você pode ver que unifiedProfile está presente com o valor enabled:true. Portanto, Real-Time Customer Profile está habilitado para este conjunto de dados.

Desativar o conjunto de dados para o Perfil

Para configurar um conjunto de dados habilitado para atualizações, primeiro você deve desabilitar as marcas unifiedProfile e unifiedIdentity e depois reabilitá-las junto com a marca isUpsert. Isso é feito usando duas solicitações PATCH, uma para desativar e outra para reativar.

Formato da API

PATCH /dataSets/{DATASET_ID}

Solicitação

O corpo da primeira solicitação PATCH inclui um path para unifiedProfile e um path para unifiedIdentity, definindo o value para enabled:false para ambos os caminhos para desabilitar as marcas.

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

Resposta

Uma solicitação PATCH bem-sucedida retorna o Status HTTP 200 (OK) e uma matriz contendo a ID do conjunto de dados atualizado. Essa ID deve corresponder à enviada na solicitação PATCH. As marcas unifiedProfile e unifiedIdentity foram desabilitadas.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Ativar o conjunto de dados para Perfil e substituição enable-the-dataset

Um conjunto de dados existente pode ser ativado para Atualizações de perfil e atributo usando uma única solicitação de PATCH.

Formato da API

PATCH /dataSets/{DATASET_ID}

Solicitação

O corpo da solicitação inclui uma configuração de path a unifiedProfile de value para incluir as marcas enabled e isUpsert, ambas definidas como true, e uma configuração de path a unifiedIdentity de value para incluir a marca enabled definida como 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"
            ]
        }
      ]'

Resposta

Uma solicitação PATCH bem-sucedida retorna o Status HTTP 200 (OK) e uma matriz contendo a ID do conjunto de dados atualizado. Essa ID deve corresponder à enviada na solicitação PATCH. As marcas unifiedProfile e unifiedIdentity foram habilitadas e configuradas para atualizações de atributo.

[
    "@/dataSets/5b020a27e7040801dedbf46e"
]

Próximas etapas

O perfil e o conjunto de dados habilitado para substituição agora podem ser usados por fluxos de trabalho de assimilação em lote para fazer atualizações nos dados do perfil. Para saber mais sobre assimilação de dados na Adobe Experience Platform, comece lendo a visão geral da assimilação de dados.