Avaliar e acessar resultados de definição de segmento
Este documento fornece um tutorial para avaliar as definições de segmento e acessar esses resultados usando o Segmentation API.
Introdução
Este tutorial requer um entendimento prático dos vários Adobe Experience Platform serviços envolvidos na criação de públicos. Antes de iniciar este tutorial, revise 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 públicos-alvo a partir do Real-Time Customer Profile dados.
- Experience Data Model (XDM): a estrutura padronizada pela qual a 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.
- Sandboxes: Experience Platform O fornece sandboxes virtuais que particionam uma única Platform 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 a tutorial de autenticação para fazer chamadas com êxito para o Platform APIs. 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:
- 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. 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}
Todas as solicitações de POST, PUT e PATCH exigem um cabeçalho adicional:
- Tipo de conteúdo: application/json
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.
Avaliação programada (também conhecida como "segmentação programada") permite criar uma programação recorrente para executar um trabalho de exportação em um horário específico, enquanto 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 você ainda não tiver concluído a criar uma definição de segmento usando a API de segmentação tutorial ou criou uma definição de segmento usando 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 /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 como usar este endpoint podem ser encontradas na guia de endpoint de agendamentos
Ativar um agendamento
Por padrão, um agendamento fica inativo quando criado, a menos que state
propriedade está definida como active
no corpo da solicitação create (POST). Você pode habilitar um agendamento (defina o state
para active
) fazendo um pedido PATCH ao /config/schedules
e incluindo a ID do agendamento no caminho.
Informações mais detalhadas sobre como usar este endpoint podem ser encontradas na guia de endpoint de agendamentos
Atualizar o horário agendado
O cronograma pode ser atualizado fazendo uma solicitação PATCH para o /config/schedules
e incluindo a ID do agendamento no caminho.
Informações mais detalhadas sobre como usar este endpoint podem ser encontradas na guia de endpoint 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 quaisquer políticas de mesclagem que controlam como Real-Time Customer Profile O 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 /segment/jobs
endpoint na variável Real-Time Customer Profile API.
Informações mais detalhadas sobre como usar este endpoint podem ser encontradas na manual de endpoint de trabalhos de segmento
Pesquisar status do trabalho do segmento
Você pode usar o id
para um job de segmento específico, execute uma solicitação de pesquisa (GET) para exibir o status atual do job.
Informações mais detalhadas sobre como usar este endpoint podem ser encontradas na manual de endpoint de trabalhos de segmento
Interpretar resultados do trabalho do segmento
Quando os trabalhos de segmento são executados com sucesso, a variável segmentMembership
O mapa é atualizado para cada perfil incluído na definição do segmento. segmentMembership
O também armazena quaisquer públicos-alvo pré-avaliados que são assimilados na Platform, permitindo a integração com outras soluções, como Adobe Audience Manager.
O exemplo a seguir mostra o que segmentMembership
O atributo é semelhante a 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"
}
}
}
}
lastQualificationTime
status
O status de participação da definição de segmento como parte da solicitação atual. Deve ser igual a um dos seguintes valores conhecidos:
realized
: a entidade se qualifica para a definição do segmento.exited
: a entidade está saindo da definição do segmento.
exited
por mais de 30 dias, com base na lastQualificationTime
, estará sujeita a exclusão.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 o Real-Time Customer Profile API. As etapas completas para acessar perfis individuais estão disponíveis na Acessar dados do Perfil do cliente em tempo real usando a API do perfil tutorial.
Exportar um segmento export
Depois que um trabalho de segmentação é concluído com sucesso (o valor da variável status
atributo é "SUCCEEDED"), você pode exportar seu público-alvo para um conjunto de dados em que ele possa ser acessado e aplicado.
As seguintes etapas são necessárias para exportar seu público-alvo:
- Criar um conjunto de dados de destino : crie o conjunto de dados para conter membros do público-alvo.
- Gerar perfis de público-alvo no conjunto de dados - Preencha o conjunto de dados com Perfis individuais XDM com base nos resultados de um trabalho de segmento.
- Monitorar o progresso da exportação - Verifique o progresso atual do processo de exportação.
- Ler dados do público - Recupere os Perfis individuais XDM resultantes que representam os membros do 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 na variável 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 esquema.
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 o Catalog API.
- Uso da interface do usuário: Para usar o Adobe Experience Platform para criar um conjunto de dados que faça referência ao esquema de união, siga as etapas da seção Tutorial de interface do usuário e retorne a este tutorial para prosseguir com as etapas para geração de perfis de público.
Se você já tiver um conjunto de dados compatível e souber sua ID, poderá prosseguir diretamente para a etapa para geração de perfis de público.
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"
}
}'
name
schemaRef.id
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 /export/jobs
endpoint na variável 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 como usar este endpoint podem ser encontradas na guia de endpoint 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 ao /export/jobs
e incluindo o id
do trabalho de exportação no caminho. O trabalho de exportação é concluído depois que a variável status
O campo retorna o valor "SUCCEEDED".
Informações mais detalhadas sobre como usar este endpoint podem ser encontradas na guia de endpoint de trabalhos de exportação
Próximas etapas
Após a exportação ser concluída com êxito, os dados estarão disponíveis na Data Lake in Experience Platform. Em seguida, você pode usar o Data Access API para acessar os dados usando o batchId
associada à 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 o Data Access para acessar e baixar arquivos em lote, siga as Tutorial de acesso a dados.
Você também pode acessar dados de definição de segmento exportados com sucesso usando Adobe Experience Platform Query Service. Usando a IU ou a API RESTful, 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.