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 /attributes
endpoint.
Per ulteriori informazioni sugli attributi calcolati, consulta la sezione panoramica degli attributi calcolati.
Introduzione
L’endpoint API utilizzato in questa guida fa parte del API Profilo cliente in tempo reale.
Prima di continuare, controlla Guida introduttiva all’API del profilo per collegamenti alla documentazione consigliata, una guida per la lettura delle chiamate API di esempio visualizzate in questo documento e informazioni importanti sulle intestazioni richieste necessarie per effettuare correttamente le chiamate a qualsiasi API di Experienci Platform.
Inoltre, consulta la documentazione del seguente servizio:
- Experience Data Model (XDM) System: framework standardizzato per l’organizzazione dei dati sull’esperienza del cliente in Experience Platform.
- Guida introduttiva al Registro di schema: informazioni su
{TENANT_ID}
, che viene visualizzato nelle risposte di questa guida.
- Guida introduttiva al Registro di schema: informazioni su
Recuperare un elenco di attributi calcolati list
Per recuperare un elenco di tutti gli attributi calcolati per la tua organizzazione, devi effettuare una richiesta GET al /attributes
endpoint.
Formato API
Il /attributes
l’endpoint supporta diversi parametri di query per aiutare a 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
. Puoi anche scegliere se ordinare in ordine crescente o decrescente non includendo o includendo un -
davanti all’opzione di ordinamento. Per impostazione predefinita, gli elementi vengono ordinati per updateEpoch
in ordine decrescente.sortBy=name
property
Parametro che consente di filtrare in base a vari campi attributo calcolati. Le proprietà supportate includono 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 recupera una sezione attributo calcolato specifica. |
_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, inizia effettuando una richiesta POST al /attributes
endpoint con un corpo della richiesta contenente i dettagli dell’attributo calcolato che desideri 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 camelCase del 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, solo pql/text è supportato. |
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
|
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, effettua una richiesta GET al /attributes
e fornendo l’ID dell’attributo calcolato che desideri 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, vedere panoramica sulle sandbox. |
path |
Il 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 includono SUM , MIN , MAX , e MOST_RECENT . |
status |
Stato dell'attributo calcolato. Può corrispondere a uno dei seguenti valori: DRAFT , NEW , INITIALIZING , PROCESSING , PROCESSED , FAILED , o DISABLED . |
schema |
Oggetto che contiene informazioni sullo schema in cui viene valutata l’espressione. Attualmente, solo _xdm.context.profile è supportato. |
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
Per eliminare un attributo calcolato specifico, devi eseguire una richiesta DELETE al /attributes
e fornendo l’ID dell’attributo calcolato che desideri eliminare nel percorso della richiesta.
DRAFT
). Questo endpoint non può per eliminare gli attributi calcolati in qualsiasi altro stato.Formato API
DELETE /attributes/{ATTRIBUTE_ID}
{ATTRIBUTE_ID}
id
valore dell’attributo calcolato che desideri 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 al /attributes
e fornendo l’ID dell’attributo calcolato che desideri 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
. Puoi anche 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
valore dell’attributo calcolato che desideri aggiornare.Richiesta
La richiesta seguente aggiorna 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 su come utilizzare gli attributi calcolati nell’interfaccia utente di Experienci Platform, leggi guida dell’interfaccia utente per attributi calcolati.