Extremo de API de atributos calculados
Los atributos calculados son funciones que se utilizan para agregar datos de nivel de evento en atributos de nivel de perfil. Estas funciones se calculan automáticamente para que se puedan utilizar en la segmentación, activación y personalización. Esta guía incluye llamadas de API de ejemplo para realizar operaciones básicas de CRUD usando el extremo /attributes
.
Para obtener más información sobre los atributos calculados, comience por leer la descripción general de los atributos calculados.
Introducción
El extremo de API usado en esta guía es parte de la API del perfil del cliente en tiempo real.
Antes de continuar, revisa la Guía de introducción a la API de perfil para ver vínculos a la documentación recomendada, una guía para leer las llamadas de API de ejemplo que aparecen en este documento e información importante sobre los encabezados necesarios para realizar correctamente llamadas a cualquier API de Experience Platform.
Además, revise la documentación del siguiente servicio:
- Experience Data Model (XDM) System: El marco estandarizado mediante el cual Experience Platform organiza los datos de experiencia del cliente.
- Guía de introducción al Registro de esquemas: se proporciona información sobre su
{TENANT_ID}
, que aparece en las respuestas de esta guía.
- Guía de introducción al Registro de esquemas: se proporciona información sobre su
Recuperación de una lista de atributos calculados list
Puede recuperar una lista de todos los atributos calculados para su organización realizando una solicitud de GET al extremo /attributes
.
Formato de API
El extremo /attributes
admite varios parámetros de consulta para filtrar los resultados. Aunque estos parámetros son opcionales, se recomienda encarecidamente su uso para ayudar a reducir la costosa sobrecarga al enumerar recursos. Si realiza una llamada a este extremo sin parámetros, se recuperarán todos los atributos calculados disponibles para su organización. Se pueden incluir varios parámetros, separados por el símbolo et (&
).
GET /attributes
GET /attributes?{QUERY_PARAMETERS}
Los siguientes parámetros de consulta se pueden utilizar al recuperar una lista de atributos calculados:
limit
limit=20
offset
offset=5
sortBy
name
, status
, updateEpoch
y createEpoch
. También puede elegir si desea ordenar en orden ascendente o descendente si no incluye o incluye -
delante de la opción de ordenación. De forma predeterminada, los elementos se ordenarán por updateEpoch
en orden descendente.sortBy=name
property
Un parámetro que permite filtrar varios campos de atributos calculados. Entre las propiedades admitidas se incluyen name
, createEpoch
, mergeFunction.value
, updateEpoch
y status
. Las operaciones admitidas dependen de la propiedad enumerada.
name
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contiene()),NOT_CONTAINS
(=!contiene())createEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)mergeFunction.value
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contiene()),NOT_CONTAINS
(=!contiene())updateEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)status
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contiene()),NOT_CONTAINS
(=!contiene())
property=updateEpoch>=1683669114845
property=name!=testingrelease
property=status=contains(new,processing,disabled)
Solicitud
La siguiente solicitud recupera los tres últimos atributos calculados que se actualizaron en su organización.
code language-shell |
---|
|
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con una lista de los últimos 3 atributos calculados actualizados que pertenecen a su organización y a la zona protegida.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Propiedad | Descripción |
_links |
Objeto que contiene la información de paginación necesaria para tener acceso a la última página de resultados, a la siguiente página de resultados, a la página de resultados anterior o a la página de resultados actual. |
computedAttributes |
Matriz que contiene los atributos calculados en función de los parámetros de consulta. Encontrará más información sobre la matriz de atributos calculados en la sección recuperar un atributo calculado específico. |
_page |
Objeto que contiene metadatos sobre los resultados devueltos. Esto incluye información sobre el desplazamiento actual, el recuento de atributos calculados devueltos, el recuento total de atributos calculados, así como el límite de atributos calculados devueltos. |
Creación de un atributo calculado create
Para crear un atributo calculado, comience realizando una solicitud de POST al extremo /attributes
con un cuerpo de solicitud que contenga los detalles del atributo calculado que desea crear.
Formato de API
POST /attributes
Solicitud
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 | |
---|---|
Propiedad | Descripción |
name |
Nombre del campo de atributo calculado, como cadena. El nombre del atributo calculado solo puede estar compuesto por caracteres alfanuméricos sin espacios ni guiones bajos. Este valor debe ser único entre todos los atributos calculados. Como práctica recomendada, este nombre debe ser una versión camelCase de displayName . |
description |
Una descripción del atributo calculado. Esto resulta especialmente útil una vez que se han definido varios atributos calculados, ya que ayudará a otros usuarios de la organización a determinar el atributo calculado correcto que se debe utilizar. |
displayName |
El nombre para mostrar del atributo calculado. Este es el nombre que se mostrará al enumerar los atributos calculados en la interfaz de usuario de Adobe Experience Platform. |
expression |
Un objeto que representa la expresión de consulta del atributo calculado que intenta crear. |
expression.type |
Tipo de la expresión. Actualmente, solo se admite PQL. |
expression.format |
El formato de la expresión. Actualmente, solo se admite pql/text . |
expression.value |
El valor de la expresión. |
keepCurrent |
Un booleano que determina si el valor del atributo calculado se mantiene actualizado mediante una actualización rápida. Actualmente, este valor debe establecerse en false . |
duration |
Un objeto que representa el período retroactivo del atributo calculado. El periodo de retrospectiva representa hasta dónde se puede retroceder para calcular el atributo calculado. |
duration.count |
Un número que representa la duración del periodo de retroactividad. Los valores posibles dependen del valor del campo
|
duration.unit |
Cadena que representa la unidad de tiempo que se utilizará para el período retroactivo. Los valores posibles incluyen: HOURS , DAYS , WEEKS y MONTHS . |
status |
El estado del atributo calculado. Los valores posibles incluyen DRAFT y NEW . |
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con información sobre el atributo calculado recién creado.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Propiedad | Descripción |
id |
El ID generado por el sistema del atributo calculado recién creado. |
status |
El estado del atributo calculado. Puede ser DRAFT o NEW . |
createEpoch |
Hora a la que se creó el atributo calculado, en segundos. |
updateEpoch |
Hora a la que se actualizó por última vez el atributo calculado, en segundos. |
createdBy |
El ID del usuario que creó el atributo calculado. |
Recuperación de un atributo calculado específico get
Puede recuperar información detallada sobre un atributo calculado específico realizando una solicitud de GET al extremo /attributes
y proporcionando el identificador del atributo calculado que desea recuperar en la ruta de solicitud.
Formato de API
GET /attributes/{ATTRIBUTE_ID}
Solicitud
code language-shell |
---|
|
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con información detallada sobre el 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 | |
---|---|
Propiedad | Descripción |
id |
ID único, de solo lectura y generado por el sistema que se puede utilizar para hacer referencia al atributo calculado durante otras operaciones de la API. |
type |
Cadena que muestra que el objeto devuelto es un atributo calculado. |
name |
Nombre del atributo calculado. |
displayName |
El nombre para mostrar del atributo calculado. Este es el nombre que se mostrará al enumerar los atributos calculados en la interfaz de usuario de Adobe Experience Platform. |
description |
Una descripción del atributo calculado. Esto resulta especialmente útil una vez que se han definido varios atributos calculados, ya que ayudará a otros usuarios de la organización a determinar el atributo calculado correcto que se debe utilizar. |
imsOrgId |
El ID de la organización a la que pertenece el atributo calculado. |
sandbox |
El objeto de zona protegida contiene detalles de la zona protegida en la que se configuró el atributo calculado. Esta información se obtiene del encabezado de la zona protegida enviado en la solicitud. Para obtener más información, consulte la descripción general de las zonas protegidas. |
path |
El path al atributo calculado. |
keepCurrent |
Un booleano que determina si el valor del atributo calculado se mantiene actualizado mediante una actualización rápida. |
expression |
Un objeto que contiene la expresión del atributo calculado. |
mergeFunction |
Objeto que contiene la función de combinación para el atributo calculado. Este valor se basa en el parámetro de agregación correspondiente dentro de la expresión del atributo calculado. Los valores posibles incluyen SUM , MIN , MAX y MOST_RECENT . |
status |
El estado del atributo calculado. Puede ser uno de los siguientes valores: DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED o DISABLED . |
schema |
Un objeto que contiene información sobre el esquema en el que se evalúa la expresión. Actualmente, solo se admite _xdm.context.profile . |
lastEvaluationTs |
Una marca de tiempo que representa cuándo se evaluó por última vez el atributo calculado. |
createEpoch |
Hora a la que se creó el atributo calculado, en segundos. |
updateEpoch |
Hora a la que se actualizó por última vez el atributo calculado, en segundos. |
createdBy |
El ID del usuario que creó el atributo calculado. |
Eliminar un atributo calculado específico delete
Puede eliminar un atributo calculado específico realizando una solicitud de DELETE al extremo /attributes
y proporcionando el identificador del atributo calculado que desea eliminar en la ruta de solicitud.
DRAFT
). Este extremo no se puede usar para eliminar atributos calculados en ningún otro estado.Formato de API
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
del atributo calculado que desea eliminar.Solicitud
code language-shell |
---|
|
Respuesta
Una respuesta correcta devuelve el estado HTTP 202 con detalles del atributo calculado eliminado.
code language-json |
---|
|
Actualización de un atributo calculado específico
Puede actualizar un atributo calculado específico realizando una solicitud de PATCH al extremo /attributes
y proporcionando el identificador del atributo calculado que desea actualizar en la ruta de solicitud.
- Si el estado actual es
NEW
, el estado solo se puede cambiar aDISABLED
. - Si el estado actual es
DRAFT
, puede cambiar los valores de los campos siguientes:name
,description
,keepCurrent
,expression
yduration
. También puede cambiar el estado deDRAFT
aNEW
. Cualquier cambio en los campos generados por el sistema, comomergeFunction
opath
, devolverá un error. - Si el estado actual es
PROCESSING
oPROCESSED
, el estado solo se puede cambiar aDISABLED
.
Formato de API
PATCH /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
del atributo calculado que desea actualizar.Solicitud
La siguiente solicitud actualizará el estado del atributo calculado de DRAFT
a NEW
.
code language-shell |
---|
|
Respuesta
Una respuesta correcta devuelve el estado HTTP 200 con información sobre el atributo calculado recién actualizado.
code language-json |
---|
|
Pasos siguientes
Ahora que ha aprendido los conceptos básicos de los atributos calculados, está listo para empezar a definirlos para su organización. Para aprender a utilizar atributos calculados en la interfaz de usuario de Experience Platform, lea la guía de la interfaz de usuario de atributos calculados.