Avaliar e acessar resultados de definição de segmento

Este documento fornece um tutorial para avaliar definições de segmento e acessar esses resultados usando o Segmentation API.

Introdução

Este tutorial requer uma compreensão funcional dos vários serviços do Adobe Experience Platform envolvidos na criação de públicos-alvo. Antes de iniciar este tutorial, revise a documentação dos seguintes serviços:

Cabeçalhos obrigatórios

Este tutorial também requer que você tenha concluído o tutorial de autenticação para fazer chamadas com êxito para as APIs Platform. 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. 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 de POST, PUT e PATCH exigem um cabeçalho adicional:

Avaliar uma definição de segmento evaluate-a-segment

Depois de desenvolver, testar e salvar a definição do segmento, é possível avaliá-la por meio da avaliação programada ou por meio da avaliação sob demanda.

A avaliação agendada (também conhecida como 'segmentação agendada') permite criar um agendamento recorrente para executar um trabalho de exportação em um horário específico, enquanto a avaliação sob demanda envolve a criação de um trabalho de segmento para criar o público imediatamente. As etapas para cada um são descritas abaixo.

Se você ainda não concluiu o tutorial criar uma definição de segmento usando a API de segmentação ou criou uma definição de segmento usando o Construtor de segmentos, faça isso antes de prosseguir com este tutorial.

Avaliação programada scheduled-evaluation

Por meio da avaliação programada, sua organização pode criar uma programação recorrente para executar trabalhos de exportação automaticamente.

Criar um agendamento

Ao fazer uma solicitação POST para o ponto de extremidade /config/schedules, você pode criar um agendamento e incluir a hora específica em que o agendamento deve ser acionado.

Informações mais detalhadas sobre o uso deste ponto de extremidade podem ser encontradas no manual do ponto de extremidade de agendamentos

Ativar um agendamento

Por padrão, um agendamento fica inativo quando criado, a menos que a propriedade state esteja definida como active no corpo da solicitação create (POST). Você pode habilitar um agendamento (definir state como active) fazendo uma solicitação PATCH para o ponto de extremidade /config/schedules e incluindo a ID do agendamento no caminho.

Informações mais detalhadas sobre o uso deste ponto de extremidade podem ser encontradas no manual do ponto de extremidade de agendamentos

Atualizar o horário agendado

O cronograma pode ser atualizado fazendo uma solicitação PATCH para o ponto de extremidade /config/schedules e incluindo a ID do cronograma no caminho.

Informações mais detalhadas sobre o uso deste ponto de extremidade podem ser encontradas no manual do ponto de extremidade de agendamentos

Avaliação sob demanda

A avaliação sob demanda permite criar um trabalho de segmento para gerar um público-alvo sempre que você precisar. Ao contrário da avaliação agendada, isso ocorrerá somente quando solicitado e não é recorrente.

Criar um trabalho de segmento

Um trabalho de segmento é um processo assíncrono que cria um segmento de público-alvo sob demanda. Ele faz referência a uma definição de segmento, bem como a qualquer política de mesclagem que controle como o Real-Time Customer Profile mescla atributos sobrepostos nos fragmentos de perfil. Quando um trabalho de segmento é concluído com sucesso, você pode coletar várias informações sobre a definição do segmento, como erros que possam ter ocorrido durante o processamento e o tamanho máximo do seu público-alvo. Um trabalho de segmento precisa ser executado sempre que você quiser atualizar o público-alvo que a definição de segmento qualifica atualmente.

Você pode criar um novo trabalho de segmento fazendo uma solicitação POST para o ponto de extremidade /segment/jobs na API Real-Time Customer Profile.

Informações mais detalhadas sobre como usar este ponto de extremidade podem ser encontradas no manual do ponto de extremidade de trabalhos do segmento

Pesquisar status do trabalho do segmento

Você pode usar o id para um trabalho de segmento específico para executar uma solicitação de pesquisa (GET) a fim de visualizar o status atual do trabalho.

Informações mais detalhadas sobre como usar este ponto de extremidade podem ser encontradas no manual do ponto de extremidade de trabalhos do segmento

Interpretar resultados do trabalho do segmento

Quando trabalhos de segmento são executados com êxito, o mapa segmentMembership é atualizado para cada perfil incluído na definição do segmento. O segmentMembership também armazena quaisquer públicos pré-avaliados que sejam assimilados no Platform, permitindo a integração com outras soluções, como o Adobe Audience Manager.

O exemplo a seguir mostra a aparência do 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"
      }
    }
  }
}

Acessar resultados de trabalho do segmento

Os resultados de um trabalho de segmento podem ser acessados de uma das duas formas a seguir: você pode acessar perfis individuais ou exportar um público-alvo inteiro para um conjunto de dados.

As seções a seguir descrevem essas opções com mais detalhes.

Pesquisar um perfil

Se você souber o perfil específico que gostaria de acessar, é possível fazer isso usando a API Real-Time Customer Profile. As etapas completas para acessar perfis individuais estão disponíveis no tutorial Acessar dados de perfil do cliente em tempo real usando a API de perfil.

Exportar um segmento export

Depois que um trabalho de segmentação for concluído com êxito (o valor do atributo status é "SUCCEEDED"), você poderá exportar seu público-alvo para um conjunto de dados onde ele possa ser acessado e reagido.

As seguintes etapas são necessárias para exportar seu público-alvo:

Criar um conjunto de dados de destino create-dataset

Ao exportar um público-alvo, um conjunto de dados de destino deve ser criado primeiro. É importante que o conjunto de dados seja configurado corretamente para garantir que a exportação seja bem-sucedida.

Uma das principais considerações é o esquema no qual o conjunto de dados se baseia (schemaRef.id na solicitação de amostra de API abaixo). Para exportar uma definição de segmento, o conjunto de dados deve ser baseado em XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Um esquema de união é um esquema somente leitura gerado pelo sistema que agrega os campos de esquemas que compartilham a mesma classe, neste caso, a classe Perfil individual XDM. Para obter mais informações sobre esquemas de visualização de união, consulte a seção Perfil do cliente em tempo real do guia do desenvolvedor do Registro de esquemas.

Há duas maneiras de criar o conjunto de dados necessário:

Se você já tiver um conjunto de dados compatível e souber sua ID, prossiga diretamente para a etapa para gerar perfis de público-alvo.

Formato da API

POST /dataSets

Solicitação

A solicitação a seguir cria um novo conjunto de dados, fornecendo parâmetros de configuração na carga.

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

Resposta

Uma resposta bem-sucedida retorna uma matriz que contém a ID exclusiva gerada pelo sistema somente leitura do conjunto de dados recém-criado. Uma ID de conjunto de dados configurada corretamente é necessária para exportar membros do público-alvo com êxito.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Gerar perfis para membros do público generate-profiles

Depois de ter um conjunto de dados persistente em união, você pode criar um trabalho de exportação para persistir os membros do público-alvo para o conjunto de dados fazendo uma solicitação POST para o ponto de extremidade /export/jobs na API Real-Time Customer Profile e fornecendo a ID do conjunto de dados e as informações de definição de segmento para as definições de segmento que você deseja exportar.

Informações mais detalhadas sobre o uso deste ponto de extremidade podem ser encontradas no manual do ponto de extremidade de trabalhos de exportação

Monitorar o progresso da exportação

Como um processo de trabalho de exportação, é possível monitorar seu status fazendo uma solicitação GET para o ponto de extremidade /export/jobs e incluindo o id do trabalho de exportação no caminho. O trabalho de exportação é concluído assim que o campo status retorna o valor "SUCCEEDED".

Informações mais detalhadas sobre o uso deste ponto de extremidade podem ser encontradas no manual do ponto de extremidade de trabalhos de exportação

Próximas etapas

Após a exportação ser concluída com êxito, seus dados ficarão disponíveis no Data Lake em Experience Platform. Você pode então usar o Data Access API para acessar os dados usando o batchId associado à exportação. Dependendo do tamanho da definição do segmento, os dados podem estar em partes e o lote pode consistir em vários arquivos.

Para obter instruções passo a passo sobre como usar a API do Data Access para acessar e baixar arquivos em lotes, siga o tutorial sobre Acesso a Dados.

Você também pode acessar dados de definição de segmento exportados com êxito usando o Adobe Experience Platform Query Service. Usando a interface ou a API RESTful, o Query Service permite gravar, validar e executar consultas em dados no Data Lake.

Para obter mais informações sobre como consultar dados de público, consulte a documentação em Query Service.