Criar um segmento usando a API do serviço de segmentação

Este documento fornece um tutorial para desenvolver, testar, visualizar e salvar uma definição de segmento usando o Adobe Experience Platform Segmentation Service API.

Para obter informações sobre como criar segmentos usando a interface do usuário, consulte a Guia do Construtor de segmentos.

Introdução

Este tutorial requer um entendimento prático dos vários Adobe Experience Platform serviços envolvidos na criação de segmentos de público-alvo. Antes de iniciar este tutorial, revise a documentação dos seguintes serviços:

Real-Time Customer Profile: fornece um perfil de consumidor 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 dos dados do Perfil do cliente em tempo real.
Experience Data Model (XDM): o quadro normalizado pelo qual Platform organiza os dados de experiência do cliente. Para melhor usar a segmentação, verifique se seus dados são assimilados como perfis e eventos de acordo com a práticas recomendadas para modelagem de dados.

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

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 cargas de solicitação formatadas corretamente. O exemplo de JSON retornado nas respostas da API também é fornecido. 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 Experience Platform guia de solução de problemas.

Coletar valores para cabeçalhos obrigatórios

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

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

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

x-sandbox-name: {SANDBOX_NAME}

OBSERVAÇÃO

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

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

Tipo de conteúdo: application/json

Desenvolver uma definição de segmento

A primeira etapa na segmentação é definir um segmento, representado em uma construção chamada de definição de segmento. Uma definição de segmento é um objeto que encapsula uma consulta gravada em Profile Query Language (PQL). Esse objeto também é chamado de predicado PQL. Os predicados de PQL definem as regras para o segmento com base nas condições relacionadas a qualquer registro ou dados de série de tempo fornecidos a Real-Time Customer Profile. Consulte a Guia de PQL para obter mais informações sobre como gravar consultas PQL.

Você pode criar uma nova definição de segmento fazendo uma solicitação POST para o /segment/definitions endpoint na variável Segmentation API. O exemplo a seguir descreve como formatar uma solicitação de definição, incluindo quais informações são necessárias para que um segmento seja definido com sucesso.

Para obter uma explicação detalhada sobre como definir um segmento, leia o guia do desenvolvedor de definição de segmento.

Estimar e visualizar um público

À medida que desenvolve a definição do segmento, é possível usar as ferramentas de estimativa e visualização no Real-Time Customer Profile para exibir informações de resumo para ajudar a garantir que você esteja isolando o público-alvo esperado. As estimativas fornecem informações estatísticas sobre uma definição de segmento, como o tamanho do público projetado e o intervalo de confiança. As visualizações fornecem listas paginadas de perfis qualificados para uma definição de segmento, permitindo comparar os resultados com o que você espera.

Ao estimar e visualizar seu público-alvo, você pode testar e otimizar seus predicados de PQL até que eles produzam um resultado desejado, em que possam ser usados em uma definição de segmento atualizada.

Há duas etapas necessárias para visualizar ou obter uma estimativa do seu segmento:

Criar um trabalho de visualização
Exibir estimativa ou visualização usar a ID do trabalho de visualização

Como as estimativas são geradas

As amostras de dados são usadas para avaliar segmentos e estimar o número de perfis qualificados. Novos dados são carregados na memória a cada manhã (entre 12AM-2AM PT, que é 7-9AM UTC) e todas as consultas de segmentação são estimadas usando os dados de amostra desse dia. Consequentemente, quaisquer novos campos adicionados ou dados adicionais coletados serão refletidos em estimativas no dia seguinte.

O tamanho da amostra depende do número geral de entidades no armazenamento de perfis. Esses tamanhos de amostra são representados na tabela a seguir:

Entidades na loja de perfis	Tamanho da amostra
Menos de 1 milhão	Conjunto de dados completo
1 a 20 milhões	1 milhão
Mais de 20 milhões	5% do total

As estimativas geralmente duram de 10 a 15 segundos, começando com uma estimativa aproximada e refinando à medida que mais registros são lidos.

Criar um trabalho de visualização

Você pode criar um novo trabalho de visualização fazendo uma solicitação POST para a /preview terminal.

Instruções detalhadas sobre como criar um trabalho de visualização podem ser encontradas na guia de visualizações e estimativas de endpoints.

Exibir uma estimativa ou visualização

Os processos de estimativa e pré-visualização são executados de forma assíncrona, pois consultas diferentes podem levar períodos diferentes para serem concluídas. Depois que um query for iniciado, você poderá usar chamadas de API para recuperar (GET) o estado atual da estimativa ou pré-visualização conforme avança.

Usar o Segmentation Service , você pode pesquisar o estado atual de um trabalho de visualização pela respectiva ID. Se o estado for "RESULT_READY", você poderá exibir os resultados. Para pesquisar o estado atual de um trabalho de visualização, leia a seção sobre recuperação de uma seção do trabalho de visualização no guia de endpoints de visualizações e estimativas. Para pesquisar o estado atual de um trabalho estimado, leia a seção sobre recuperação de um trabalho estimado no guia de endpoints de visualizações e estimativas.

Próximas etapas

Depois de desenvolver, testar e salvar a definição do segmento, é possível criar um trabalho de segmento para criar um público-alvo usando o Segmentation Service API. Veja o tutorial sobre avaliação e acesso aos resultados do segmento para obter etapas detalhadas sobre como fazer isso.