Adobe Experience Platform consente di creare segmenti che definiscono un gruppo di attributi o comportamenti specifici da un gruppo di profili. Una definizione di segmento è un oggetto che racchiude una query scritta in Profile Query Language (PQL). Questo oggetto è anche denominato predicato PQL. I predicati PQL definiscono le regole per il segmento in base alle condizioni relative a qualsiasi record o dati delle serie temporali forniti a Real-time Customer Profile. Per ulteriori informazioni sulla scrittura di query PQL, vedere la Guida PQL.
Questa guida fornisce informazioni utili per comprendere meglio le definizioni dei segmenti e include chiamate API di esempio per eseguire azioni di base tramite l'API.
Gli endpoint utilizzati in questa guida fanno parte dell'API Adobe Experience Platform Segmentation Service. Prima di continuare, controlla la guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente le chiamate all'API, comprese le intestazioni richieste e come leggere le chiamate API di esempio.
È possibile recuperare un elenco di tutte le definizioni di segmento per l'organizzazione IMS effettuando una richiesta di GET all'endpoint /segment/definitions
.
Formato API
L'endpoint /segment/definitions
supporta diversi parametri di query per facilitare il filtro dei risultati. Anche se questi parametri sono opzionali, il loro utilizzo è fortemente consigliato per ridurre i costi di sovraccarico. Effettuando una chiamata a questo endpoint senza parametri, verranno recuperate tutte le definizioni di segmento disponibili per l'organizzazione. È possibile includere più parametri, separati da e-mail (&
).
GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}
Parametri query
Parametro | Descrizione | Esempio |
---|---|---|
start |
Specifica l'offset iniziale per le definizioni di segmento restituite. | start=4 |
limit |
Specifica il numero di definizioni di segmento restituite per pagina. | limit=20 |
page |
Specifica da quale pagina partiranno i risultati delle definizioni dei segmenti. | page=5 |
sort |
Specifica per quale campo ordinare i risultati. È scritto nel seguente formato: [attributeName]:[desc|asc] . |
sort=updateTime:desc |
evaluationInfo.continuous.enabled |
Specifica se la definizione del segmento è abilitata per lo streaming. | evaluationInfo.continuous.enabled=true |
Richiesta
Nella richiesta seguente vengono recuperate le ultime due definizioni di segmento pubblicate all’interno dell’organizzazione IMS.
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions?limit=2 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con un elenco di definizioni di segmento per l’organizzazione IMS specificata come JSON.
{
"segments": [
{
"id": "3da8bad9-29fb-40e0-b39e-f80322e964de",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "segment",
"description": "",
"expression": {
"type": "PQL",
"format": "pql/json",
"value": "{PQL_EXPRESSION}"
},
"mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1573253640000,
"baselineTime": 1574327114,
"updateEpoch": 1575588309,
"updateTime": 1575588309000
},
{
"id": "ca763983-5572-4ea4-809c-b7dff7e0d79b",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 30,
"imsOrgId": "{IMS_ORG}",
"name": "test segment",
"description": "",
"expression": {
"type": "PQL",
"format": "pql/json",
"value": "{PQL_EXPRESSION}"
},
"mergePolicyId": "b83185bb-0bc6-489c-9363-0075eb30b4c8",
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 1561073779000,
"baselineTime": 1574327114,
"updateEpoch": 1574327114,
"updateTime": 1574327114000
}
],
"page": {
"totalCount": 2,
"totalPages": 1,
"sortField": "creationTime",
"sort": "desc",
"pageSize": 2,
"limit": 100
},
"link": {}
}
Puoi creare una nuova definizione di segmento effettuando una richiesta di POST all'endpoint /segment/definitions
.
Formato API
POST /segment/definitions
Richiesta
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
-d '{
"name": "People who ordered in the last 30 days",
"profileInstanceId": "ups",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"schema": {
"name": "_xdm.context.profile"
},
"payloadSchema": "string",
"ttlInDays": 60
}'
Proprietà | Descrizione |
---|---|
name |
Obbligatorio. Un nome univoco con cui fare riferimento al segmento. |
schema |
Obbligatorio. Schema associato alle entità nel segmento. È costituito da un campo id o name . |
expression |
Obbligatorio. Entità che contiene informazioni sui campi relativi alla definizione del segmento. |
expression.type |
Specifica il tipo di espressione. Attualmente, è supportato solo "PQL". |
expression.format |
Indica la struttura dell'espressione in valore. Attualmente è supportato il seguente formato:
|
expression.value |
Un'espressione conforme al tipo indicato in expression.format . |
description |
Descrizione leggibile della definizione. |
Un'espressione di definizione del segmento può anche fare riferimento a un attributo calcolato. Per ulteriori informazioni, fare riferimento alla guida all'endpoint API dell'attributo calcolato
La funzionalità dell'attributo calcolato è in alfa e non è disponibile per tutti gli utenti. La documentazione e le funzionalità sono soggette a modifiche.
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con i dettagli della nuova definizione del segmento creata.
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"profileInstanceId": "ups",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579292094,
"updateTime": 1579292094000
}
Proprietà | Descrizione |
---|---|
id |
ID generato dal sistema della nuova definizione del segmento creata. |
evaluationInfo |
Un oggetto generato dal sistema che indica il tipo di valutazione cui verrà sottoposta la definizione del segmento. Può essere batch, continuo (noto anche come streaming) o segmentazione sincrona. |
Puoi recuperare informazioni dettagliate su una definizione di segmento specifica effettuando una richiesta di GET all'endpoint /segment/definitions
e fornendo l'ID della definizione di segmento che desideri recuperare nel percorso della richiesta.
Formato API
GET /segment/definitions/{SEGMENT_ID}
Parametro | Descrizione |
---|---|
{SEGMENT_ID} |
Il valore id della definizione del segmento da recuperare. |
Richiesta
curl -X GET https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con informazioni dettagliate sulla definizione del segmento specificata.
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"profileInstanceId": "ups",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579292094,
"updateTime": 1579292094000
}
Proprietà | Descrizione |
---|---|
id |
ID di sola lettura generato dal sistema per la definizione del segmento. |
name |
Un nome univoco con cui fare riferimento al segmento. |
schema |
Schema associato alle entità nel segmento. È costituito da un campo id o name . |
expression |
Entità che contiene informazioni sui campi relativi alla definizione del segmento. |
expression.type |
Specifica il tipo di espressione. Attualmente, è supportato solo "PQL". |
expression.format |
Indica la struttura dell'espressione in valore. Attualmente è supportato il seguente formato:
|
expression.value |
Un'espressione conforme al tipo indicato in expression.format . |
description |
Una descrizione leggibile dell'espressione. |
evaluationInfo |
Un oggetto generato dal sistema che indica il tipo di valutazione, batch, continuo (noto anche come streaming) o sincrono cui verrà sottoposta la definizione del segmento. |
È possibile recuperare informazioni dettagliate su definizioni di segmenti multiple specificate effettuando una richiesta di POST all'endpoint /segment/definitions/bulk-get
e fornendo i valori id
delle definizioni di segmento nel corpo della richiesta.
Formato API
POST /segment/definitions/bulk-get
Richiesta
curl -X POST https://platform.adobe.io/data/core/ups/segment/definitions/bulk-get \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '{
"ids": [
{
"id": "54669488-03ab-4e0d-a694-37fe49e32be8"
},
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05"
}
]
}'
Risposta
Una risposta corretta restituisce lo stato HTTP 207 con le definizioni dei segmenti richieste.
{
"results": {
"54669488-03ab-4e0d-a694-37fe49e32be8": {
"id": "54669488-03ab-4e0d-a694-37fe49e32be8",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"profileInstanceId": "ups",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579292094,
"updateTime": 1579292094000
},
"4afe34ae-8c98-4513-8a1d-67ccaa54bc05": {
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"profileInstanceId": "ups",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "People who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"US\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579292094,
"updateTime": 1579292094000
}
}
}
Proprietà | Descrizione |
---|---|
id |
ID di sola lettura generato dal sistema per la definizione del segmento. |
name |
Un nome univoco con cui fare riferimento al segmento. |
schema |
Schema associato alle entità nel segmento. È costituito da un campo id o name . |
expression |
Entità che contiene informazioni sui campi relativi alla definizione del segmento. |
expression.type |
Specifica il tipo di espressione. Attualmente, è supportato solo "PQL". |
expression.format |
Indica la struttura dell'espressione in valore. Attualmente è supportato il seguente formato:
|
expression.value |
Un'espressione conforme al tipo indicato in expression.format . |
description |
Una descrizione leggibile dell'espressione. |
evaluationInfo |
Un oggetto generato dal sistema che indica il tipo di valutazione, batch, continuo (noto anche come streaming) o sincrono cui verrà sottoposta la definizione del segmento. |
Puoi richiedere di eliminare una definizione di segmento specifica effettuando una richiesta di DELETE all'endpoint /segment/definitions
e fornendo l'ID della definizione di segmento che desideri eliminare nel percorso della richiesta.
Formato API
DELETE /segment/definitions/{SEGMENT_ID}
Parametro | Descrizione |
---|---|
{SEGMENT_ID} |
Il valore id della definizione del segmento da eliminare. |
Richiesta
curl -X DELETE https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}'
Risposta
Una risposta corretta restituisce lo stato HTTP 200 senza messaggio.
Puoi aggiornare una definizione di segmento specifica effettuando una richiesta di PATCH all'endpoint /segment/definitions
e fornendo l'ID della definizione di segmento che desideri aggiornare nel percorso della richiesta.
Formato API
PATCH /segment/definitions/{SEGMENT_ID}
Parametro | Descrizione |
---|---|
{SEGMENT_ID} |
Il valore id della definizione del segmento da aggiornare. |
Richiesta
La seguente richiesta aggiornerà il paese dell'indirizzo di lavoro dagli Stati Uniti al Canada.
curl -X PATCH https://platform.adobe.io/data/core/ups/segment/definitions/4afe34ae-8c98-4513-8a1d-67ccaa54bc05 \
-H 'Authorization: Bearer {ACCESS_TOKEN}' \
-H 'Content-Type: application/json' \
-H 'x-gw-ims-org-id: {IMS_ORG}' \
-H 'x-api-key: {API_KEY}' \
-H 'x-sandbox-name: {SANDBOX_NAME}' \
-d '
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"name": "Updated people who ordered in the last 30 days",
"profileInstanceId": "ups",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"CA\""
},
"schema": {
"name": "_xdm.context.profile"
},
"payloadSchema": "string",
"ttlInDays": 60,
"creationTime": 0,
"updateTime": 0,
"updateEpoch": 0
}'
Risposta
Una risposta corretta restituisce lo stato HTTP 200 con i dettagli della nuova definizione di segmento aggiornata. Tenere presente che il paese dell'indirizzo di lavoro è stato aggiornato dagli Stati Uniti (USA) al Canada (CA).
{
"id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
"schema": {
"name": "_xdm.context.profile"
},
"ttlInDays": 60,
"profileInstanceId": "ups",
"imsOrgId": "{IMS_ORG}",
"sandbox": {
"sandboxId": "28e74200-e3de-11e9-8f5d-7f27416c5f0d",
"sandboxName": "prod",
"type": "production",
"default": true
},
"name": "Updated people who ordered in the last 30 days",
"description": "Last 30 days",
"expression": {
"type": "PQL",
"format": "pql/text",
"value": "workAddress.country = \"CA\""
},
"evaluationInfo": {
"batch": {
"enabled": true
},
"continuous": {
"enabled": false
},
"synchronous": {
"enabled": false
}
},
"dataGovernancePolicy": {
"excludeOptOut": true
},
"creationTime": 0,
"updateEpoch": 1579295340,
"updateTime": 1579295340000
}
Dopo aver letto questa guida è ora possibile comprendere meglio il funzionamento delle definizioni dei segmenti. Per ulteriori informazioni sulla creazione di un segmento, consultare l'esercitazione creating a segment tutorial.