Endpoint API per attributi calcolati
Gli attributi calcolati sono funzioni utilizzate per aggregare i dati a livello di evento negli attributi a livello di profilo. Queste funzioni vengono calcolate automaticamente in modo che possano essere utilizzate in segmentazione, attivazione e personalizzazione. Questa guida include esempi di chiamate API per eseguire operazioni CRUD di base utilizzando l'endpoint /attributes
.
Per ulteriori informazioni sugli attributi calcolati, leggere la panoramica sugli attributi calcolati.
Introduzione
L'endpoint API utilizzato in questa guida fa parte dell'API del profilo cliente in tempo reale.
Prima di continuare, consulta la Guida introduttiva all'API del profilo per i collegamenti alla documentazione consigliata, una guida alla lettura delle chiamate API di esempio visualizzate in questo documento e informazioni importanti sulle intestazioni necessarie per effettuare correttamente le chiamate a qualsiasi API di Experience Platform.
Inoltre, consulta la documentazione del seguente servizio:
- Experience Data Model (XDM) System: framework standardizzato tramite il quale Experience Platform organizza i dati sull'esperienza del cliente.
- Guida introduttiva al registro degli schemi: vengono fornite informazioni su
{TENANT_ID}
, visualizzate nelle risposte in questa guida.
- Guida introduttiva al registro degli schemi: vengono fornite informazioni su
Recuperare un elenco di attributi calcolati list
Per recuperare un elenco di tutti gli attributi calcolati per l'organizzazione, eseguire una richiesta GET all'endpoint /attributes
.
Formato API
L'endpoint /attributes
supporta diversi parametri di query per filtrare i risultati. Anche se questi parametri sono facoltativi, si consiglia vivamente di utilizzarli per ridurre i costi comuni quando si elencano le risorse. Se effettui una chiamata a questo endpoint senza parametri, verranno recuperati tutti gli attributi calcolati disponibili per la tua organizzazione. È possibile includere più parametri, separati da e commerciali (&
).
GET /attributes
GET /attributes?{QUERY_PARAMETERS}
I seguenti parametri di query possono essere utilizzati per recuperare un elenco di attributi calcolati:
limit
limit=20
offset
offset=5
sortBy
name
, status
, updateEpoch
e createEpoch
. È inoltre possibile scegliere se ordinare in ordine crescente o decrescente non includendo o includendo -
prima dell'opzione di ordinamento. Per impostazione predefinita, gli elementi verranno ordinati per updateEpoch
in ordine decrescente.sortBy=name
property
Parametro che consente di filtrare in base a vari campi attributo calcolati. Le proprietà supportate sono name
, createEpoch
, mergeFunction.value
, updateEpoch
e status
. Le operazioni supportate dipendono dalla proprietà elencata.
name
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains(),NOT_CONTAINS
(=!contains())createEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)mergeFunction.value
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains(),NOT_CONTAINS
(=!contains())updateEpoch
:GREATER_THAN_OR_EQUALS
(<=),LESS_THAN_OR_EQUALS
(>=)status
:EQUAL
(=),NOT_EQUAL
(!=),CONTAINS
(=contains(),NOT_CONTAINS
(=!contains())
property=updateEpoch>=1683669114845
property=name!=testingrelease
property=status=contains(new,processing,disabled)
Richiesta
La richiesta seguente recupera gli ultimi tre attributi calcolati che sono stati aggiornati nell’organizzazione.
code language-shell |
---|
|
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con un elenco degli ultimi 3 attributi calcolati aggiornati che appartengono alla tua organizzazione e alla sandbox.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 | |
---|---|
Proprietà | Descrizione |
_links |
Oggetto contenente le informazioni sull'impaginazione necessarie per accedere all'ultima pagina dei risultati, alla pagina successiva dei risultati, alla pagina precedente dei risultati o alla pagina corrente dei risultati. |
computedAttributes |
Matrice che contiene gli attributi calcolati in base ai parametri di query. Ulteriori informazioni sull'array degli attributi calcolati sono disponibili nella sezione recuperare un attributo calcolato specifico. |
_page |
Oggetto contenente metadati sui risultati restituiti. Ciò include informazioni sull'offset corrente, il conteggio degli attributi calcolati restituiti, il conteggio totale degli attributi calcolati e il limite degli attributi calcolati restituiti. |
Creare un attributo calcolato create
Per creare un attributo calcolato, iniziare effettuando una richiesta POST all'endpoint /attributes
con un corpo della richiesta contenente i dettagli dell'attributo calcolato che si desidera creare.
Formato API
POST /attributes
Richiesta
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 | |
---|---|
Proprietà | Descrizione |
name |
Nome del campo attributo calcolato sotto forma di stringa. Il nome dell'attributo calcolato può essere composto solo da caratteri alfanumerici senza spazi o trattini bassi. Questo valore deve essere univoco tra tutti gli attributi calcolati. Come best practice, questo nome deve essere una versione di camelCase di displayName . |
description |
Descrizione dell'attributo calcolato. Questa funzione è particolarmente utile quando sono stati definiti più attributi calcolati, in quanto consente ad altri utenti all’interno dell’organizzazione di determinare l’attributo calcolato corretto da utilizzare. |
displayName |
Nome visualizzato dell'attributo calcolato. Questo è il nome che verrà visualizzato quando vengono elencati gli attributi calcolati nell’interfaccia utente di Adobe Experience Platform. |
expression |
Oggetto che rappresenta l’espressione di query dell’attributo calcolato che stai tentando di creare. |
expression.type |
Tipo dell'espressione. Attualmente, è supportato solo PQL. |
expression.format |
Il formato dell’espressione. Attualmente, è supportato solo pql/text . |
expression.value |
Il valore dell’espressione. |
keepCurrent |
Valore booleano che determina se il valore dell’attributo calcolato viene mantenuto aggiornato tramite l’aggiornamento rapido. Attualmente, questo valore deve essere impostato su false . |
duration |
Oggetto che rappresenta il periodo di lookback per l’attributo calcolato. Il periodo di lookback rappresenta il periodo di tempo trascorso il quale è possibile risalire per calcolare l’attributo calcolato. |
duration.count |
Numero che rappresenta la durata del periodo di lookback. I valori possibili dipendono dal valore del campo
|
duration.unit |
Stringa che rappresenta l’unità di tempo che verrà utilizzata per il periodo di lookback. I valori possibili includono: HOURS , DAYS , WEEKS e MONTHS . |
status |
Stato dell'attributo calcolato. I valori possibili includono DRAFT e NEW . |
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni sull’attributo calcolato appena creato.
code language-json |
---|
|
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 | |
---|---|
Proprietà | Descrizione |
id |
ID generato dal sistema dell’attributo calcolato appena creato. |
status |
Stato dell'attributo calcolato. Può essere DRAFT o NEW . |
createEpoch |
L’ora di creazione dell’attributo calcolato in secondi. |
updateEpoch |
Ora dell'ultimo aggiornamento dell'attributo calcolato, in secondi. |
createdBy |
ID dell’utente che ha creato l’attributo calcolato. |
Recuperare un attributo calcolato specifico get
Per recuperare informazioni dettagliate su un attributo calcolato specifico, eseguire una richiesta GET all'endpoint /attributes
e fornire l'ID dell'attributo calcolato che si desidera recuperare nel percorso della richiesta.
Formato API
GET /attributes/{ATTRIBUTE_ID}
Richiesta
code language-shell |
---|
|
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni dettagliate sull’attributo calcolato specificato.
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 | |
---|---|
Proprietà | Descrizione |
id |
ID univoco generato dal sistema e di sola lettura, che può essere utilizzato per fare riferimento all’attributo calcolato durante altre operazioni API. |
type |
Stringa che indica che l'oggetto restituito è un attributo calcolato. |
name |
Nome dell'attributo calcolato. |
displayName |
Nome visualizzato dell'attributo calcolato. Questo è il nome che verrà visualizzato quando vengono elencati gli attributi calcolati nell’interfaccia utente di Adobe Experience Platform. |
description |
Descrizione dell'attributo calcolato. Questa funzione è particolarmente utile quando sono stati definiti più attributi calcolati, in quanto consente ad altri utenti all’interno dell’organizzazione di determinare l’attributo calcolato corretto da utilizzare. |
imsOrgId |
ID dell’organizzazione a cui appartiene l’attributo calcolato. |
sandbox |
L’oggetto sandbox contiene i dettagli della sandbox in cui è stato configurato l’attributo calcolato. Queste informazioni sono tratte dall’intestazione sandbox inviata nella richiesta. Per ulteriori informazioni, consulta la panoramica delle sandbox. |
path |
path all'attributo calcolato. |
keepCurrent |
Valore booleano che determina se il valore dell’attributo calcolato viene mantenuto aggiornato tramite l’aggiornamento rapido. |
expression |
Oggetto contenente l'espressione dell'attributo calcolato. |
mergeFunction |
Oggetto contenente la funzione di unione per l’attributo calcolato. Questo valore è basato sul parametro di aggregazione corrispondente all'interno dell'espressione dell'attributo calcolato. I valori possibili sono SUM , MIN , MAX e MOST_RECENT . |
status |
Stato dell'attributo calcolato. Può essere uno dei valori seguenti: DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED o DISABLED . |
schema |
Oggetto che contiene informazioni sullo schema in cui viene valutata l’espressione. Attualmente, è supportato solo _xdm.context.profile . |
lastEvaluationTs |
Timestamp che rappresenta l’ultima valutazione dell’attributo calcolato. |
createEpoch |
L’ora di creazione dell’attributo calcolato in secondi. |
updateEpoch |
Ora dell'ultimo aggiornamento dell'attributo calcolato, in secondi. |
createdBy |
ID dell’utente che ha creato l’attributo calcolato. |
Eliminare un attributo calcolato specifico delete
È possibile eliminare un attributo calcolato specifico effettuando una richiesta DELETE all'endpoint /attributes
e fornendo l'ID dell'attributo calcolato che si desidera eliminare nel percorso della richiesta.
DRAFT
). Questo endpoint non può essere utilizzato per eliminare attributi calcolati in qualsiasi altro stato.Formato API
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
dell'attributo calcolato che si desidera eliminare.Richiesta
code language-shell |
---|
|
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 202 con i dettagli dell’attributo calcolato eliminato.
code language-json |
---|
|
Aggiornare un attributo calcolato specifico
È possibile aggiornare un attributo calcolato specifico effettuando una richiesta PATCH all'endpoint /attributes
e fornendo l'ID dell'attributo calcolato che si desidera aggiornare nel percorso della richiesta.
- Se lo stato corrente è
NEW
, lo stato può essere modificato solo inDISABLED
. - Se lo stato corrente è
DRAFT
, è possibile modificare i valori dei campi seguenti:name
,description
,keepCurrent
,expression
eduration
. È inoltre possibile modificare lo stato daDRAFT
aNEW
. Qualsiasi modifica ai campi generati dal sistema, ad esempiomergeFunction
opath
, restituirà un errore. - Se lo stato corrente è
PROCESSING
oPROCESSED
, lo stato può essere modificato solo inDISABLED
.
Formato API
PATCH /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
dell'attributo calcolato che si desidera aggiornare.Richiesta
La richiesta seguente aggiornerà lo stato dell'attributo calcolato da DRAFT
a NEW
.
code language-shell |
---|
|
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni sull’attributo calcolato appena aggiornato.
code language-json |
---|
|
Passaggi successivi
Ora che hai imparato le nozioni di base sugli attributi calcolati, puoi iniziare a definirli per la tua organizzazione. Per informazioni sull'utilizzo degli attributi calcolati nell'interfaccia utente di Experience Platform, leggere la guida dell'interfaccia utente degli attributi calcolati.