Avaliar e acessar os resultados do segmento

Este documento fornece um tutorial para avaliar segmentos e acessar resultados de segmentos usando o Segmentation API.

Introdução

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

  • Real-time Customer Profile: Fornece um perfil de cliente unificado em tempo real com base em dados agregados de várias fontes.
  • Adobe Experience Platform Segmentation Service: Permite criar segmentos de público-alvo a partir de Real-time Customer Profile dados.
  • Experience Data Model (XDM): A estrutura padronizada pela qual a Platform organiza os dados de experiência do cliente.
  • Sandboxes: Experience Platform O fornece sandboxes virtuais que particionam uma única Platform instância em ambientes virtuais separados para ajudar a desenvolver aplicativos de experiência digital.

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 APIs Platform. A conclusão do tutorial de autenticação fornece os valores para cada um dos cabeçalhos necessários em todas as chamadas de API Experience Platform, conforme mostrado abaixo:

  • Autorização: Portador {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {IMS_ORG}

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

  • x-sandbox-name: {SANDBOX_NAME}
OBSERVAÇÃO

Para obter mais informações sobre sandboxes em Platform, consulte a documentação de visão geral da sandbox.

Todas as solicitações de POST, PUT e PATCH exigem um cabeçalho adicional:

  • Tipo de conteúdo: application/json

Avaliar um segmento

Depois de desenvolver, testar e salvar a definição de segmento, você pode avaliar o segmento por meio de avaliação programada ou sob demanda.

A avaliação agendada (também conhecida como "segmentação agendada") permite criar uma programação 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-alvo imediatamente. As etapas para cada um são descritas abaixo.

Se ainda não tiver concluído o criar um segmento usando o tutorial da API de segmentação ou criado uma definição de segmento usando Construtor de segmentos, faça isso antes de prosseguir com este tutorial.

Avaliação agendada

Por meio da avaliação agendada, a Organização IMS pode criar um agendamento recorrente para executar automaticamente tarefas de exportação.

OBSERVAÇÃO

A avaliação agendada pode ser ativada para sandboxes com no máximo cinco (5) políticas de mesclagem para XDM Individual Profile. Se sua organização tiver mais de cinco políticas de mesclagem para XDM Individual Profile em um único ambiente de sandbox, você não poderá usar a avaliação agendada.

Criar um agendamento

Ao fazer uma solicitação de POST para o endpoint /config/schedules, é possível criar um agendamento e incluir o horário específico em que o agendamento deve ser acionado.

Informações mais detalhadas sobre o uso desse endpoint podem ser encontradas no guia de endpoint de agendamentos

Habilitar 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 de criação (POST). Você pode habilitar um agendamento (defina state como active) fazendo uma solicitação de PATCH para o endpoint /config/schedules e incluindo a ID do agendamento no caminho.

Informações mais detalhadas sobre o uso desse endpoint podem ser encontradas no guia de endpoint de agendamentos

Atualizar a hora da programação

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

Informações mais detalhadas sobre o uso desse endpoint podem ser encontradas no guia de endpoint de agendamentos

Avaliação por demanda

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

Criar um trabalho de segmento

Um trabalho de segmento é um processo assíncrono que cria um novo segmento de público-alvo. Ele faz referência a uma definição de segmento, bem como a quaisquer políticas de mesclagem que controlam como Real-time Customer Profile mescla atributos sobrepostos nos fragmentos de perfil. Quando um trabalho de segmento é concluído com êxito, você pode coletar várias informações sobre o segmento, como erros que possam ter ocorrido durante o processamento e o tamanho final do público-alvo.

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

Informações mais detalhadas sobre o uso desse ponto de extremidade podem ser encontradas no guia do ponto de extremidade de tarefas do segmento

Pesquisar o 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) para visualizar o status atual do trabalho.

Informações mais detalhadas sobre o uso desse ponto de extremidade podem ser encontradas no guia do ponto de extremidade de tarefas do segmento

Interpretar os resultados do segmento

Quando as tarefas de segmento são executadas com êxito, o mapa segmentMembership é atualizado para cada perfil incluído no segmento. segmentMembership O também armazena todos os segmentos de público-alvo pré-avaliados que são assimilados no Platform, permitindo a integração com outras soluções como o Adobe Audience Manager.

O exemplo a seguir mostra como o atributo segmentMembership se parece para cada registro de perfil individual:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "existing"
      },
      "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"
      }
    }
  }
}
Propriedade Descrição
lastQualificationTime O carimbo de data e hora quando a asserção de associação de segmento foi feita e o perfil entrou ou saiu do segmento.
status O status da participação do segmento como parte da solicitação atual. Deve ser igual a um dos seguintes valores conhecidos:
  • existing: A entidade continua a estar no segmento.
  • realized: A entidade está inserindo o segmento.
  • exited: A entidade está saindo do segmento.

Acessar resultados 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, poderá fazer isso usando a API Real-time Customer Profile. As etapas completas para acessar perfis individuais estão disponíveis no tutorial do Acessar Perfil do cliente em tempo real usando a API de perfil .

Exportar um segmento

Após concluir com êxito um trabalho de segmentação (o valor do atributo status é "SUCCEEDED"), você pode exportar o público para um conjunto de dados, onde ele pode ser acessado e tratado.

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

Criar um conjunto de dados de destino

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 é baseado (schemaRef.id na solicitação de amostra de API abaixo). Para exportar um segmento, o conjunto de dados deve ser baseado no XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Um schema de união é um schema gerado pelo sistema e somente leitura que agrega os campos de esquemas que compartilham a mesma classe, neste caso, que é a classe de Perfil individual XDM. Para obter mais informações sobre schemas de exibição de união, consulte a seção Real-time Customer Profile do Schema Registry developer guide.

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

  • Uso de APIs: as etapas a seguir neste tutorial descrevem como criar um conjunto de dados que faça referência ao XDM Individual Profile Union Schema usando a Catalog API.
  • Uso da interface do usuário: para usar a interface do Adobe Experience Platform usuário para criar um conjunto de dados que faça referência ao schema de união, siga as etapas no tutorial da interface do usuário e retorne a este tutorial para prosseguir com as etapas para a geração de perfis de público-alvo.

Se você já tiver um conjunto de dados compatível e souber sua ID, poderá prosseguir 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 no payload.

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: {IMS_ORG}' \
  -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"
    },
    "fileDescription": {
        "persisted": true
    }
}'
Propriedade Descrição
name Um nome descritivo para o conjunto de dados.
schemaRef.id A ID da exibição de união (schema) à qual o conjunto de dados será associado.
fileDescription.persisted Um valor booleano que, quando definido como true, permite que o conjunto de dados persista na exibição de união.

Resposta

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

[
  "@/datasets/5b020a27e7040801dedba61b"
] 

Gerar perfis para membros do público-alvo

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

Informações mais detalhadas sobre o uso desse endpoint podem ser encontradas no guia do endpoint de tarefas de exportação

Monitorar progresso da exportação

Como um trabalho de exportação processa, você pode monitorar seu status fazendo uma solicitação de GET para o endpoint /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 desse endpoint podem ser encontradas no guia do endpoint de tarefas de exportação

Próximas etapas

Depois que a exportação for concluída com êxito, seus dados estarão disponíveis no Data Lake em Experience Platform. Em seguida, você pode usar o Data Access API para acessar os dados usando o batchId associado à exportação. Dependendo do tamanho 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 Data Access para acessar e baixar arquivos em lote, siga o tutorial de Acesso a Dados.

Você também pode acessar dados de segmentos exportados com êxito usando Adobe Experience Platform Query Service. Usando a interface do usuário ou a API RESTful, Query Service permite gravar, validar e executar consultas em dados dentro do Data Lake.

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

Nesta página