DocumentaçãoGuia do desenvolvedor do Target

Adobe Target Bulk Profile Update API

Last update: Wed Sep 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Criado para:

  • Desenvolvedor

O Adobe Target Bulk Profile Update API permite atualizar perfis de usuário para vários visitantes de um site em massa usando um arquivo em lote.

Usando o Bulk Profile Update API, você pode enviar convenientemente dados detalhados do perfil do visitante na forma de parâmetros do perfil para muitos usuários para Target a partir de qualquer fonte externa. Fontes externas podem incluir os sistemas de CRM (Customer Relationship Management, gerenciamento de relacionamento com o cliente) ou POS (Point of Sale, ponto de venda), que normalmente não estão disponíveis em uma página da Web.

Versão
Exemplo de URL
Recursos
v1
http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/profile/batchUpdate
Suporte somente para atualização de perfil em massa.
v2
http://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate
  • Caso não seja encontrado, criar perfil.
  • Atualização de status por linha.
NOTE
A versão 2 (v2) de Bulk Profile Update API é a versão atual. No entanto, Target ainda oferece suporte à versão 1 (v1).

Benefícios da API de atualização do perfil em massa

  • Nenhum limite sobre o número de atributos de perfil.
  • Os atributos de perfil enviados pelo site podem ser atualizados por meio da API e do oposto.

Avisos

  • O tamanho do arquivo em lote deve ser menor que 50 MB. Além disso, o número total de linhas não deve ultrapassar 500.000 por carregamento.
  • As atualizações geralmente ocorrem em menos de uma hora, mas podem levar até 24 horas para serem refletidas.
  • Não há limite para o número ou as linhas que você pode fazer upload por um período de 24 horas em lotes subsequentes. No entanto, o processo de ingestão pode ter o fluxo controlado em horário comercial, para garantir que outros processos sejam executados com eficiência.
  • As chamadas de atualização em lote v2 consecutivas sem chamadas da mbox entre as mesmas thirdPartyIds substituindo as propriedades atualizadas na primeira chamada de atualização em lote.
  • Adobe não garante que 100% dos dados do perfil de lote sejam incorporados e retidos no Target e, portanto, estejam disponíveis para uso no direcionamento. No design atual, há a possibilidade de uma pequena porcentagem de dados (até 0,1% de grandes lotes de produção) não ser integrada ou retida.

Arquivo em lote

Para atualizar os dados do perfil em massa, crie um arquivo em lote. O arquivo de lote é um arquivo de texto com valores separados por vírgulas semelhante ao seguinte arquivo de amostra.

\ batch=pcId,param1,param2,param3,param4\ 123,value1\ 124,value1,value4\ 125,value2\ 126,value1,value2,value3,value4\

NOTE
O parâmetro batch= é obrigatório e deve ser especificado no início do arquivo.

Você faz referência a este arquivo na chamada de POST para Target servidores para processar o arquivo. Ao criar o arquivo de lote, considere o seguinte:

  • A primeira linha do arquivo deve especificar cabeçalhos de coluna.
  • O primeiro cabeçalho deve ser um pcId ou thirdPartyId. Não há suporte para Marketing Cloud visitor ID. pcId é um visitorID gerado por Target. thirdPartyId é uma ID especificada pelo aplicativo cliente, que é passada para Target através de uma chamada de mbox como mbox3rdPartyId. Deve ser chamado aqui de thirdPartyId.
  • Os parâmetros e valores especificados no arquivo de lote devem ser codificados por URL usando UTF-8 por motivos de segurança. Os parâmetros e valores podem ser encaminhados para outros nós de borda para processamento por meio de solicitações HTTP.
  • Os parâmetros devem estar somente no formato paramName. Os parâmetros são exibidos em Target como profile.paramName.
  • Se você estiver usando Bulk Profile Update API v2, não precisará especificar todos os valores de parâmetro para cada pcId. Perfis são criados para qualquer pcId ou mbox3rdPartyId que não seja encontrado em Target. Se você estiver usando a v1, os perfis não serão criados para pcIds ou mbox3rdPartyIds ausentes.
  • O tamanho do arquivo em lote deve ser menor que 50 MB. Além disso, o número total de linhas não deve exceder 500 mil. Esse limite garante que os servidores não sejam inundados com muitas solicitações.
  • Você pode enviar vários arquivos. No entanto, a soma total das linhas de todos os arquivos enviados em um dia não deve exceder um milhão para cada cliente.
  • Não há restrição quanto ao número de atributos que você pode fazer upload. No entanto, o tamanho total dos dados do perfil externo, que incluem Atributos do cliente, API do perfil, parâmetros de perfil na mbox e saída do script de perfil, não deve exceder 64 KB.
  • Os parâmetros e valores diferenciam maiúsculas de minúsculas.

solicitação POST do HTTP

Faça uma solicitação HTTP POST para Target servidores de borda para processar o arquivo. Este é um exemplo de solicitação HTTP POST para o arquivo batch.txt usando o comando curl:

\ curl -X POST --data-binary @BATCH.TXT http\://CLIENTCODE.tt.omtrdc.net/m2/CLIENTCODE/v2/profile/batchUpdate\

Em que:

BATCH.TXT é o nome do arquivo. CLIENTCODE é o código de cliente Target.

Se você não souber seu código de cliente, na interface de usuário do Target, clique em Administration > Implementation. O código de cliente é mostrado na seção Account Details.

Inspect a resposta

A API de perfis retorna o status de envio do lote para processamento, juntamente com um link em "batchStatus" para um URL diferente que mostra o status geral do trabalho em lote específico.

Exemplo de resposta da API

O código a seguir recortado é um exemplo de uma resposta da API de perfis:

<response>
    <success>true</success>
    <batchStatus>http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383</batchStatus>
    <message>Batch submitted for processing</message>
</response>

Se houver um erro, a resposta conterá success=false e uma mensagem detalhada para o erro.

Resposta de status de lote padrão

Uma resposta padrão bem-sucedida quando o link da URL batchStatus acima é clicado é semelhante à seguinte:

<response><batchId>demo4-1701473848678-13029383</batchId><status>complete</status><batchSize>1</batchSize></response>

Os valores esperados para os campos de status são:

Status
Detalhes
complete
A solicitação de atualização do lote de perfis foi concluída com êxito.
incomplete
A solicitação de atualização do lote de perfis ainda está sendo processada e não foi concluída.
stuck
A solicitação de atualização do lote de perfis está paralisada e não pôde ser concluída.

Resposta detalhada do URL de status do lote

Uma resposta mais detalhada pode ser obtida ao passar um parâmetro showDetails=true para a url batchStatus acima.

Por exemplo:

http://mboxedge45.tt.omtrdc.net/m2/demo/profile/batchStatus?batchId=demo-1701473848678-13029383&showDetails=true

Resposta detalhada

<response>
    <batchId>demo4-1701473848678-13029383</batchId>
    <status>complete</status>
    <batchSize>1</batchSize>
    <consumedCount>1</consumedCount>
    <successfulUpdates>1</successfulUpdates>
    <profilesNotFound>0</profilesNotFound>
    <failedUpdates>0</failedUpdates>
</response>
recommendation-more-help
6906415f-169c-422b-89d3-7118e147c4e3