Endpoint da API de atributos computados
Os atributos computados são funções usadas para agregar dados no nível do evento em atributos no nível do perfil. Essas funções são computadas automaticamente para que possam ser usadas na segmentação, ativação e personalização. Este guia inclui exemplos de chamadas de API para executar operações CRUD básicas usando o ponto de extremidade /attributes
.
Para saber mais sobre atributos computados, comece lendo a visão geral sobre atributos computados.
Introdução
O ponto de extremidade de API usado neste guia faz parte da API de perfil do cliente em tempo real.
Antes de continuar, consulte o Guia de Introdução à API de Perfil para obter links para a documentação recomendada, um guia para ler as chamadas de API de exemplo que aparecem neste documento e informações importantes sobre os cabeçalhos necessários para fazer chamadas com êxito para qualquer API de Experience Platform.
Além disso, consulte a documentação do seguinte serviço:
- Experience Data Model (XDM) System: a estrutura padronizada pela qual o Experience Platform organiza os dados de experiência do cliente.
- Guia de introdução ao Registro de Esquema: são fornecidas informações sobre o seu
{TENANT_ID}
, que aparece em respostas neste guia.
- Guia de introdução ao Registro de Esquema: são fornecidas informações sobre o seu
Recuperar uma lista de atributos computados list
Você pode recuperar uma lista de todos os atributos computados para sua organização fazendo uma solicitação GET para o ponto de extremidade /attributes
.
Formato da API
O ponto de extremidade /attributes
dá suporte a vários parâmetros de consulta para ajudar a filtrar os resultados. Embora esses parâmetros sejam opcionais, seu uso é altamente recomendado para ajudar a reduzir a sobrecarga cara ao listar recursos. Se você fizer uma chamada para esse endpoint sem parâmetros, todos os atributos computados disponíveis para sua organização serão recuperados. Vários parâmetros podem ser incluídos, separados por "E" comercial (&
).
GET /attributes
GET /attributes?{QUERY_PARAMETERS}
Os seguintes parâmetros de consulta podem ser usados ao recuperar uma lista de atributos computados:
limit
limit=20
offset
offset=5
sortBy
name
, status
, updateEpoch
e createEpoch
. Você também pode escolher se deseja classificar em ordem crescente ou decrescente, não incluindo ou incluindo um -
na frente da opção de classificação. Por padrão, os itens serão classificados por updateEpoch
em ordem decrescente.sortBy=name
property
Um parâmetro que permite filtrar em vários campos de atributo computados. As propriedades suportadas incluem name
, createEpoch
, mergeFunction.value
, updateEpoch
e status
. As operações compatíveis dependem da propriedade listada.
name
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contém()),NOT_CONTAINS
(=!contém())createEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)mergeFunction.value
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contém()),NOT_CONTAINS
(=!contém())updateEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)status
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contém()),NOT_CONTAINS
(=!contém())
property=updateEpoch>=1683669114845
property=name!=testingrelease
property=status=contains(new,processing,disabled)
Solicitação
A solicitação a seguir recupera os três últimos atributos calculados que foram atualizados em sua organização.
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com uma lista dos últimos 3 atributos calculados atualizados que pertencem à sua organização e sandbox.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propriedade | Descrição |
_links |
Um objeto que contém as informações de paginação necessárias para acessar a última página de resultados, a próxima página de resultados, a página anterior de resultados ou a página atual de resultados. |
computedAttributes |
Uma matriz que contém os atributos calculados com base nos parâmetros de consulta. Mais informações sobre a matriz de atributos computados podem ser encontradas na seção recuperar um atributo computado específico. |
_page |
Um objeto que contém metadados sobre os resultados retornados. Isso inclui informações sobre o deslocamento atual, a contagem de atributos computados retornados, a contagem total de atributos computados, bem como o limite de atributos computados retornados. |
Criar um atributo calculado create
Para criar um atributo computado, comece fazendo uma solicitação POST para o ponto de extremidade /attributes
com um corpo de solicitação contendo os detalhes do atributo computado que você deseja criar.
Formato da API
POST /attributes
Solicitação
code language-shell |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 | |
---|---|
Propriedade | Descrição |
name |
O nome do campo de atributo calculado, como uma string. O nome do atributo calculado só pode ser composto por caracteres alfanuméricos sem espaços ou sublinhados. Este valor deve ser exclusivo entre todos os atributos computados. Como prática recomendada, esse nome deve ser uma versão camelCase do displayName . |
description |
Uma descrição do atributo calculado. Isso é especialmente útil depois que vários atributos computados são definidos, pois ajudará outras pessoas em sua organização a determinar o atributo calculado correto a ser usado. |
displayName |
O nome de exibição do atributo calculado. Esse é o nome que será exibido ao listar os atributos calculados na interface do usuário do Adobe Experience Platform. |
expression |
Um objeto que representa a expressão de consulta do atributo calculado que você está tentando criar. |
expression.type |
O tipo da expressão. No momento, somente o PQL é compatível. |
expression.format |
O formato da expressão. Atualmente, somente pql/text é suportado. |
expression.value |
O valor da expressão. |
keepCurrent |
Um booleano que determina se o valor do atributo calculado é ou não mantido atualizado usando a atualização rápida. Atualmente, este valor deve ser definido como false . |
duration |
Um objeto que representa o período de pesquisa do atributo calculado. O período de pesquisa representa até que ponto a pesquisa anterior pode ser realizada para calcular o atributo calculado. |
duration.count |
Um número que representa a duração do período de pesquisa. Os valores possíveis dependem do valor do campo
|
duration.unit |
Uma string que representa a unidade de tempo que será usada para o período de pesquisa. Os valores possíveis incluem: HOURS , DAYS , WEEKS e MONTHS . |
status |
O status do atributo calculado. Os valores possíveis incluem DRAFT e NEW . |
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com informações sobre o atributo calculado recém-criado.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Propriedade | Descrição |
id |
A ID gerada pelo sistema do atributo computado recém-criado. |
status |
O status do atributo calculado. Pode ser DRAFT ou NEW . |
createEpoch |
A hora em que o atributo calculado foi criado, em segundos. |
updateEpoch |
A hora em que o atributo calculado foi atualizado pela última vez, em segundos. |
createdBy |
A ID do usuário que criou o atributo calculado. |
Recuperar um atributo calculado específico get
Você pode recuperar informações detalhadas sobre um atributo calculado específico fazendo uma solicitação GET para o ponto de extremidade /attributes
e fornecendo a ID do atributo calculado que você deseja recuperar no caminho da solicitação.
Formato da API
GET /attributes/{ATTRIBUTE_ID}
Solicitação
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com informações detalhadas sobre o atributo calculado especificado.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2 | |
---|---|
Propriedade | Descrição |
id |
Uma ID exclusiva, somente leitura, gerada pelo sistema que pode ser usada para fazer referência ao atributo calculado durante outras operações da API. |
type |
Uma string que mostra que o objeto retornado é um atributo calculado. |
name |
O nome do atributo calculado. |
displayName |
O nome de exibição do atributo calculado. Esse é o nome que será exibido ao listar os atributos calculados na interface do usuário do Adobe Experience Platform. |
description |
Uma descrição do atributo calculado. Isso é especialmente útil depois que vários atributos computados são definidos, pois ajudará outras pessoas em sua organização a determinar o atributo calculado correto a ser usado. |
imsOrgId |
A ID da organização à qual o atributo calculado pertence. |
sandbox |
O objeto de sandbox contém detalhes da sandbox na qual o atributo calculado foi configurado. Essas informações são retiradas do cabeçalho da sandbox enviado na solicitação. Para obter mais informações, consulte a visão geral das sandboxes. |
path |
O path para o atributo computado. |
keepCurrent |
Um booleano que determina se o valor do atributo calculado é ou não mantido atualizado usando a atualização rápida. |
expression |
Um objeto que contém a expressão do atributo computado. |
mergeFunction |
Um objeto que contém a função de mesclagem para o atributo calculado. Esse valor se baseia no parâmetro de agregação correspondente na expressão do atributo calculado. Os valores possíveis incluem SUM , MIN , MAX e MOST_RECENT . |
status |
O status do atributo calculado. Pode ser um dos seguintes valores: DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED ou DISABLED . |
schema |
Um objeto que contém informações sobre o esquema no qual a expressão é avaliada. Atualmente, somente _xdm.context.profile é suportado. |
lastEvaluationTs |
Um carimbo de data e hora que representa quando o atributo calculado foi avaliado pela última vez. |
createEpoch |
A hora em que o atributo calculado foi criado, em segundos. |
updateEpoch |
A hora em que o atributo calculado foi atualizado pela última vez, em segundos. |
createdBy |
A ID do usuário que criou o atributo calculado. |
Excluir um atributo calculado específico delete
Você pode excluir um atributo calculado específico fazendo uma solicitação DELETE para o ponto de extremidade /attributes
e fornecendo a ID do atributo calculado que você deseja excluir no caminho da solicitação.
DRAFT
). Este ponto de extremidade não pode ser usado para excluir atributos computados em qualquer outro estado.Formato da API
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
do atributo computado que você deseja excluir.Solicitação
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 202 com detalhes do atributo calculado excluído.
code language-json |
---|
|
Atualizar um atributo calculado específico
Você pode atualizar um atributo calculado específico fazendo uma solicitação PATCH para o ponto de extremidade /attributes
e fornecendo a ID do atributo calculado que você deseja atualizar no caminho da solicitação.
- Se o status atual for
NEW
, o status só poderá ser alterado paraDISABLED
. - Se o status atual for
DRAFT
, você poderá alterar os valores dos seguintes campos:name
,description
,keepCurrent
,expression
eduration
. Você também pode alterar a status deDRAFT
paraNEW
. Qualquer alteração em campos gerados pelo sistema, comomergeFunction
oupath
, retornará um erro. - Se o status atual for
PROCESSING
ouPROCESSED
, o status só poderá ser alterado paraDISABLED
.
Formato da API
PATCH /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
do atributo computado que você deseja atualizar.Solicitação
A solicitação a seguir atualizará o status do atributo computado de DRAFT
para NEW
.
code language-shell |
---|
|
Resposta
Uma resposta bem-sucedida retorna o status HTTP 200 com informações sobre o atributo calculado recém-atualizado.
code language-json |
---|
|
Próximas etapas
Agora que você aprendeu as noções básicas sobre atributos computados, você está pronto para começar a defini-los para sua organização. Para saber como usar atributos computados na interface do Experience Platform, leia o guia da interface do usuário de atributos computados.