Endpoint di definizioni segmento

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 incapsula 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 di serie temporali forniti Real-Time Customer Profile. Consulta la Guida di PQL per ulteriori informazioni sulla scrittura di query PQL.

Questa guida fornisce informazioni utili per comprendere meglio le definizioni dei segmenti e include esempi di chiamate API per eseguire azioni di base utilizzando l’API.

Introduzione

Gli endpoint utilizzati in questa guida fanno parte del Adobe Experience Platform Segmentation Service API. Prima di continuare, controlla guida introduttiva per informazioni importanti che devi conoscere per effettuare correttamente chiamate all’API, incluse le intestazioni richieste e la lettura di esempi di chiamate API.

Recuperare un elenco di definizioni di segmenti

Per recuperare un elenco di tutte le definizioni di segmenti per la tua organizzazione IMS, invia una richiesta GET al /segment/definitions endpoint.

Formato API

Il /segment/definitions 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 generali. Effettuando una chiamata a questo endpoint senza parametri, verranno recuperate tutte le definizioni di segmento disponibili per la tua organizzazione. È possibile includere più parametri, separati da e commerciali (&).

GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}

Parametri query

Parametro Descrizione Esempio
start Specifica l'offset iniziale per le definizioni dei segmenti restituite. start=4
limit Specifica il numero di definizioni di segmenti restituite per pagina. limit=20
page Specifica da quale pagina inizieranno i risultati delle definizioni dei segmenti. page=5
sort Specifica il campo in base al quale ordinare i risultati. è scritto nel seguente formato: `[attributeName]:[desc asc]`.
evaluationInfo.continuous.enabled Specifica se la definizione del segmento è abilitata per lo streaming. evaluationInfo.continuous.enabled=true

Richiesta

La seguente richiesta recupererà le ultime due definizioni di segmenti pubblicate nell’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: {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 di definizioni di segmenti per l’organizzazione IMS specificata come JSON.

{
    "segments": [
        {
            "id": "3da8bad9-29fb-40e0-b39e-f80322e964de",
            "schema": {
                "name": "_xdm.context.profile"
            },
            "ttlInDays": 30,
            "imsOrgId": "{ORG_ID}",
            "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": "{ORG_ID}",
            "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": {}
}

Creare una nuova definizione di segmento

Per creare una nuova definizione di segmento, devi effettuare una richiesta POST al /segment/definitions endpoint.

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: {ORG_ID}' \
 -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\""
        },
        "evaluationInfo": {
            "batch": {
                "enabled": true
            },
            "continuous": {
                "enabled": false
            },
            "synchronous": {
                "enabled": false
            }
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string",
        "ttlInDays": 60
    }'
Proprietà Descrizione
name Obbligatorio. Nome univoco con cui fare riferimento al segmento.
description Una descrizione della definizione del segmento che stai creando.
evaluationInfo Il tipo di segmento che stai creando. Se desideri creare un segmento batch, imposta evaluationInfo.batch.enabled per essere vero. Se desideri creare un segmento di streaming, imposta evaluationInfo.continuous.enabled per essere vero. Se desiderate creare un segmento di spigolo, impostate evaluationInfo.synchronous.enabled per essere vero. Se lasciato vuoto, il segmento verrà creato come batch segmento.
schema Obbligatorio. Lo schema associato alle entità nel segmento. È costituito da un id o name campo.
expression Obbligatorio. Un’entità che contiene informazioni sui campi relative 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:
  • pql/text: rappresentazione testuale di una definizione di segmento, in base alla grammatica PQL pubblicata. Ad esempio, workAddress.stateProvince = homeAddress.stateProvince.
expression.value Espressione conforme al tipo indicato in expression.format.
description Una descrizione leggibile della definizione.
NOTA

Un’espressione di definizione del segmento può anche fare riferimento a un attributo calcolato. Per ulteriori informazioni, consulta guida dell’endpoint API per attributi calcolati

La funzionalità degli attributi calcolati è in formato alfa e non è disponibile per tutti gli utenti. La documentazione e le funzionalità sono soggette a modifiche.

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli della definizione del segmento appena creata.

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "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 definizione del segmento appena creata.
evaluationInfo Oggetto che indica il tipo di valutazione a cui verrà sottoposta la definizione del segmento. Può essere in batch, in streaming (o continua) o in segmentazione Edge (o sincrona).

Recuperare una definizione di segmento specifica

Per recuperare informazioni dettagliate su una definizione di segmento specifica, effettua una richiesta GET al /segment/definitions e fornendo l’ID della definizione del segmento da recuperare nel percorso della richiesta.

Formato API

GET /segment/definitions/{SEGMENT_ID}
Parametro Descrizione
{SEGMENT_ID} Il id valore della definizione del segmento che desideri 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: {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 sulla definizione del segmento specificata.

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "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 della definizione del segmento.
name Nome univoco con cui fare riferimento al segmento.
schema Lo schema associato alle entità nel segmento. È costituito da un id o name campo.
expression Un’entità che contiene informazioni sui campi relative 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:
  • pql/text: rappresentazione testuale di una definizione di segmento, in base alla grammatica PQL pubblicata. Ad esempio, workAddress.stateProvince = homeAddress.stateProvince.
expression.value Espressione conforme al tipo indicato in expression.format.
description Una descrizione leggibile della definizione.
evaluationInfo Oggetto che indica il tipo di valutazione, batch, streaming (noto anche come continuo) o edge (noto anche come sincrono) a cui verrà sottoposta la definizione del segmento.

Definizioni di segmenti di recupero in blocco

Per recuperare informazioni dettagliate su più definizioni di segmenti specificate, effettua una richiesta POST al /segment/definitions/bulk-get endpoint e fornitura di id valori delle definizioni dei segmenti 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: {ORG_ID}' \
  -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

In caso di esito positivo, la risposta 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": "{ORG_ID}",
            "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": "{ORG_ID}",
            "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 della definizione del segmento.
name Nome univoco con cui fare riferimento al segmento.
schema Lo schema associato alle entità nel segmento. È costituito da un id o name campo.
expression Un’entità che contiene informazioni sui campi relative 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:
  • pql/text: rappresentazione testuale di una definizione di segmento, in base alla grammatica PQL pubblicata. Ad esempio, workAddress.stateProvince = homeAddress.stateProvince.
expression.value Espressione conforme al tipo indicato in expression.format.
description Una descrizione leggibile della definizione.
evaluationInfo Oggetto che indica il tipo di valutazione, batch, streaming (noto anche come continuo) o edge (noto anche come sincrono) a cui verrà sottoposta la definizione del segmento.

Eliminare una definizione di segmento specifica

Per richiedere l’eliminazione di una definizione di segmento specifica, effettua una richiesta DELETE al /segment/definitions e fornendo l’ID della definizione del segmento da eliminare nel percorso della richiesta.

NOTA

Lo farai non essere in grado di eliminare un segmento utilizzato in un’attivazione di destinazione.

Formato API

DELETE /segment/definitions/{SEGMENT_ID}
Parametro Descrizione
{SEGMENT_ID} Il id valore della definizione del segmento che desideri 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: {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 senza messaggio.

Aggiornare una definizione di segmento specifica

Per aggiornare una definizione di segmento specifica, devi eseguire una richiesta PATCH al /segment/definitions e fornendo l’ID della definizione del segmento da aggiornare nel percorso della richiesta.

Formato API

PATCH /segment/definitions/{SEGMENT_ID}
Parametro Descrizione
{SEGMENT_ID} Il id valore della definizione del segmento da aggiornare.

Richiesta

La richiesta seguente aggiorna 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: {ORG_ID}' \
 -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

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli della definizione del segmento appena aggiornata. Nota come il paese dell'indirizzo del luogo di lavoro è stato aggiornato da Stati Uniti (Stati Uniti) a Canada (Italia).

{
    "id": "4afe34ae-8c98-4513-8a1d-67ccaa54bc05",
    "schema": {
        "name": "_xdm.context.profile"
    },
    "ttlInDays": 60,
    "profileInstanceId": "ups",
    "imsOrgId": "{ORG_ID}",
    "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
}

Converti definizione segmento

Puoi convertire una definizione di segmento tra pql/text e pql/json o pql/json a pql/text facendo una richiesta POST al /segment/conversion endpoint.

Formato API

POST /segment/conversion

Richiesta

La richiesta seguente modificherà il formato della definizione del segmento da pql/text a pql/json.

curl -X POST https://platform.adobe.io/data/core/ups/segment/conversion \
 -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 '{
        "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
    }'

Risposta

In caso di esito positivo, la risposta restituisce lo stato HTTP 200 con i dettagli della definizione del segmento appena convertito.

{
    "ttlInDays": 60,
    "imsOrgId": "6A29340459CA8D350A49413A@AdobeOrg",
    "sandbox": {
        "sandboxId": "ff0f6870-c46d-11e9-8ca3-036939a64204",
        "sandboxName": "prod",
        "type": "production",
        "default": true
    },
    "description": "Last 30 days",
    "expression": {
        "type": "PQL",
        "format": "pql/json",
        "value": "{\"nodeType\":\"fnApply\",\"fnName\":\"=\",\"params\":[{\"nodeType\":\"fieldLookup\",\"fieldName\":\"country\",\"object\":{\"nodeType\":\"fieldLookup\",\"fieldName\":\"workAddress\",\"object\":{\"nodeType\":\"parameterReference\",\"position\":1}}},{\"nodeType\":\"literal\",\"literalType\":\"String\",\"value\":\"US\"}]}"
    }
}

Passaggi successivi

Dopo aver letto questa guida hai acquisito una migliore comprensione del funzionamento delle definizioni dei segmenti. Per ulteriori informazioni sulla creazione di un segmento, leggi la sezione creazione di un segmento esercitazione.

In questa pagina