Endpoint API per attributi calcolati
- Argomenti:
- Profili
Creato per:
- Utente
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
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:
Parametro query | Descrizione | Esempio |
---|---|---|
limit | Un parametro che specifica il numero massimo di elementi restituiti come parte della risposta. Il valore minimo di questo parametro è 1 e il valore massimo è 40. Se questo parametro non è incluso, per impostazione predefinita verranno restituiti 20 elementi. | limit=20 |
offset | Un parametro che specifica il numero di elementi da ignorare prima di restituire gli elementi. | offset=5 |
sortBy | Parametro che specifica l'ordine in cui vengono ordinati gli elementi restituiti. Le opzioni disponibili sono 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
| 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.
curl -X GET https://platform.adobe.io/data/core/ca/attributes?limit=3 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
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.
{
"_links": {
"last": {
"href": "/attributes?offset=3&limit=1"
},
"next": {
"href": "/attributes?offset=20&limit=20"
},
"prev": {
"href": "/attributes?offset=0&limit=20"
},
"self": {
"href": "/attributes?offset=0&limit=20"
}
},
"computedAttributes": [
{
"id": "2e3bf98c-5840-4eb5-98c9-fcd7bde82188",
"type": "ComputedAttribute",
"name": "multipleFilterClauses19",
"displayName": "Multiple Filter Clauses 19",
"description": "Multiple Filter Clauses 19",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)",
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "",
"createEpoch": 1671223530322,
"updateEpoch": 1673043640946,
"createdBy": "{USER_ID}"
},
{
"id": "d9fbbd3d-049a-4561-b826-adc162511950",
"type": "ComputedAttribute",
"name": "multipleFilterClauses20",
"displayName": "Multiple Filter Clauses 20",
"description": "Multiple Filter Clauses 20",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": true,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[eventType.equals(\"commerce.backofficeOrderPlaced\", false)].topN(timestamp, 1).map({\"timestamp\": timestamp, \"value\": producedBy}).head()"
},
"mergeFunction": {
"value": "MOST_RECENT"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "",
"createEpoch": 1671223586455,
"updateEpoch": 1671223586455,
"createdBy": "{USER_ID}"
},
{
"id": "afedff07-9d15-4385-b181-49708229d73b",
"type": "ComputedAttribute",
"name": "multipleFilterClauses18",
"displayName": "Multiple Filter Clauses 18",
"description": "Multiple Filter Clauses 18",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "e4f64b40-d8d9-11e9-a7ce-f3356ed0508b",
"sandboxName": "prod",
"type": "production",
"default": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)",
},
"mergeFunction": {
"value": "SUM"
},
"status": "PROCESSED",
"schema": {
"name": "_xdm.context.profile"
},
"duration": {
"count": 7,
"unit": "DAYS"
},
"lastEvaluationTs": "2023-08-27T00:14:55.028",
"createEpoch": 1671220358902,
"updateEpoch": 1671220358902,
"createdBy": "{USER_ID}"
}
],
"_page": {
"offset": 0,
"limit": 20,
"count": 3,
"totalCount": 3
}
}
_links
computedAttributes
_page
Creare un attributo calcolato
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
curl -X POST https://platform.adobe.io/data/core/ca/attributes \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-api-key: {API_KEY}'\
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)].sum(commerce.order.priceTotal)"
},
"keepCurrent": false,
"duration": {
"count": 4,
"unit": "DAYS"
},
"status": "DRAFT"
}'
name
displayName
.description
displayName
expression
expression.type
expression.format
pql/text
.expression.value
keepCurrent
false
.duration
duration.count
Numero che rappresenta la durata del periodo di lookback. I valori possibili dipendono dal valore del campo duration.unit
.
HOURS
: 1-24DAYS
: 1-7WEEKS
: 1-4MONTHS
: 1-6
duration.unit
HOURS
, DAYS
, WEEKS
e MONTHS
.status
DRAFT
e NEW
.Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni sull’attributo calcolato appena creato.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680070188696,
"updateEpoch": 1680070188696,
"createdBy": "{USER_ID}"
}
id
status
DRAFT
o NEW
.createEpoch
updateEpoch
createdBy
Recuperare un attributo calcolato specifico
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
curl -X GET 'https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631' \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni dettagliate sull’attributo calcolato specificato.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680070188696,
"updateEpoch": 1680070188696,
"createdBy": "{USER_ID}"
}
id
type
name
displayName
description
imsOrgId
sandbox
path
path
all'attributo calcolato.keepCurrent
expression
mergeFunction
SUM
, MIN
, MAX
e MOST_RECENT
.status
DRAFT
, NEW
, INITIALIZING
, PROCESSING
, PROCESSED
, FAILED
o DISABLED
.schema
_xdm.context.profile
.lastEvaluationTs
createEpoch
updateEpoch
createdBy
Eliminare un attributo calcolato specifico
È 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
curl -X DELETE https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 202 con i dettagli dell’attributo calcolato eliminato.
{
"id": "03ae581b-5f7b-48da-a9eb-4ef0daf4bc3c",
"type": "ComputedAttribute",
"name": "testdemopd2",
"displayName": "testdemopd2",
"description": "testdemopd2",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.shipping.shipDate occurs <= 1 days before now) and (timestamp occurs <= 1 days before now)].min(commerce.shipping.shipDate)"
},
"mergeFunction": {
"value": "MIN"
},
"status": "DRAFT",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1681365690928,
"updateEpoch": 1681365690928,
"createdBy": "{USER_ID}"
}
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
.
curl -X PATCH https://platform.adobe.io/data/core/ca/attributes/1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {ORG_ID}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"description": "Sample Description",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"status": "NEW"
}'
Risposta
In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con informazioni sull’attributo calcolato appena aggiornato.
{
"id": "1e8d0d77-b2bb-4b17-bbe6-2dbc08c1a631",
"type": "ComputedAttribute",
"name": "testing123",
"displayName": "Sample Display Name",
"description": "Sample Description",
"imsOrgId": "{ORG_ID}",
"sandbox": {
"sandboxId": "02dd69f0-da73-11e9-9ea1-af59ce7c24e8",
"sandboxName": "prod",
"type": "production",
"isDefault": true
},
"path": "{TENANT_ID}/ComputedAttributes",
"keepCurrent": false,
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "xEvent[(commerce.checkouts.value > 0.0 or commerce.purchases.value > 1.0 or commerce.order.priceTotal >= 10.0) and (timestamp occurs <= 7 days before now)].sum(commerce.order.priceTotal)"
},
"mergeFunction": {
"value": "SUM"
},
"status": "NEW",
"schema": {
"name": "_xdm.context.profile"
},
"lastEvaluationTs": "",
"createEpoch": 1680071726825,
"updateEpoch": 1680074429192,
"createdBy": "{USER_ID}"
}
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.