Med Adobe Experience Platform kan du skapa segment som definierar en grupp med specifika attribut eller beteenden från en grupp profiler. En segmentdefinition är ett objekt som kapslar in en fråga skriven i Profile Query Language (PQL). Det här objektet kallas även för ett PQL-predikat. PQL-predikat definierar reglerna för segmentet baserat på villkor som relaterar till data från poster eller tidsserier som du skickar till Real-time Customer Profile. Se PQL-guide om du vill ha mer information om hur du skriver PQL-frågor.
Den här handboken innehåller information som hjälper dig att förstå segmentdefinitioner bättre och innehåller exempel på API-anrop för att utföra grundläggande åtgärder med API:t.
Slutpunkterna som används i den här guiden är en del av Adobe Experience Platform Segmentation Service API. Läs igenom komma igång-guide för viktig information som du behöver känna till för att kunna anropa API:t, inklusive obligatoriska rubriker och hur du läser exempel-API-anrop.
Du kan hämta en lista över alla segmentdefinitioner för din IMS-organisation genom att göra en GET-förfrågan till /segment/definitions
slutpunkt.
API-format
The /segment/definitions
slutpunkten har stöd för flera frågeparametrar som hjälper dig att filtrera dina resultat. Även om dessa parametrar är valfria rekommenderar vi starkt att de används för att minska dyra overheadkostnader. Om du anropar den här slutpunkten utan parametrar hämtas alla segmentdefinitioner som är tillgängliga för organisationen. Flera parametrar kan inkluderas, avgränsade med et-tecken (&
).
GET /segment/definitions
GET /segment/definitions?{QUERY_PARAMETERS}
Frågeparametrar
Parameter | Beskrivning | Exempel |
---|---|---|
start |
Anger startförskjutningen för de returnerade segmentdefinitionerna. | start=4 |
limit |
Anger antalet segmentdefinitioner som returneras per sida. | limit=20 |
page |
Anger vilken sida som resultatet av segmentdefinitioner ska börja från. | page=5 |
sort |
Anger vilket fält som resultaten ska sorteras efter. Skrivs i följande format: `[attributeName]:[desc | asc]`. |
evaluationInfo.continuous.enabled |
Anger om segmentdefinitionen är direktuppspelningsaktiverad. | evaluationInfo.continuous.enabled=true |
Begäran
Följande begäran hämtar de två sista segmentdefinitionerna som publicerats i IMS-organisationen.
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}'
Svar
Ett lyckat svar returnerar HTTP-status 200 med en lista över segmentdefinitioner för den angivna IMS-organisationen som 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": {}
}
Du kan skapa en ny segmentdefinition genom att göra en POST-förfrågan till /segment/definitions
slutpunkt.
API-format
POST /segment/definitions
Begäran
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\""
},
"schema": {
"name": "_xdm.context.profile"
},
"payloadSchema": "string",
"ttlInDays": 60
}'
Egenskap | Beskrivning |
---|---|
name |
Obligatoriskt. Ett unikt namn som ska referera till segmentet. |
schema |
Obligatoriskt. Det schema som är associerat med entiteterna i segmentet. Består av antingen en id eller name fält. |
expression |
Obligatoriskt. En entitet som innehåller fältinformation om segmentdefinitionen. |
expression.type |
Anger uttryckstypen. För närvarande stöds bara PQL. |
expression.format |
Anger strukturen för uttrycket i värdet. Följande format stöds för närvarande:
|
expression.value |
Ett uttryck som överensstämmer med typen som anges i expression.format . |
description |
En läsbar beskrivning av definitionen. |
Ett segmentdefinitionsuttryck kan också referera till ett beräknat attribut. Mer information finns i API-slutpunktshandbok för beräknat attribut
Funktionen för beräknade attribut är alfavärden och är inte tillgänglig för alla användare. Dokumentationen och funktionaliteten kan komma att ändras.
Svar
Ett lyckat svar returnerar HTTP-status 200 med information om den segmentdefinition du nyss skapade.
{
"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
}
Egenskap | Beskrivning |
---|---|
id |
Ett systemgenererat ID för den segmentdefinition du nyss skapade. |
evaluationInfo |
Ett systemgenererat objekt som anger vilken typ av utvärdering som segmentdefinitionen ska genomgå. Den kan vara en grupp, kontinuerlig (kallas även direktuppspelning) eller synkron segmentering. |
Du kan hämta detaljerad information om en viss segmentdefinition genom att göra en GET-förfrågan till /segment/definitions
slutpunkt och ange ID:t för segmentdefinitionen som du vill hämta i sökvägen för begäran.
API-format
GET /segment/definitions/{SEGMENT_ID}
Parameter | Beskrivning |
---|---|
{SEGMENT_ID} |
The id värdet för segmentdefinitionen som du vill hämta. |
Begäran
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}'
Svar
Ett lyckat svar returnerar HTTP-status 200 med detaljerad information om den angivna segmentdefinitionen.
{
"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
}
Egenskap | Beskrivning |
---|---|
id |
Ett systemgenererat skrivskyddat ID för segmentdefinitionen. |
name |
Ett unikt namn som ska referera till segmentet. |
schema |
Det schema som är associerat med entiteterna i segmentet. Består av antingen en id eller name fält. |
expression |
En entitet som innehåller fältinformation om segmentdefinitionen. |
expression.type |
Anger uttryckstypen. För närvarande stöds bara PQL. |
expression.format |
Anger strukturen för uttrycket i värdet. Följande format stöds för närvarande:
|
expression.value |
Ett uttryck som överensstämmer med typen som anges i expression.format . |
description |
En läsbar beskrivning av definitionen. |
evaluationInfo |
Ett systemgenererat objekt som anger vilken typ av utvärdering, batch, kontinuerlig (kallas även direktuppspelning) eller synkron, segmentdefinitionen ska genomgå. |
Du kan hämta detaljerad information om flera angivna segmentdefinitioner genom att göra en POST-förfrågan till /segment/definitions/bulk-get
slutpunkt och tillhandahåller id
värden för segmentdefinitionerna i begärandetexten.
API-format
POST /segment/definitions/bulk-get
Begäran
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"
}
]
}'
Svar
Ett lyckat svar returnerar HTTP-status 207 med de begärda segmentdefinitionerna.
{
"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
}
}
}
Egenskap | Beskrivning |
---|---|
id |
Ett systemgenererat skrivskyddat ID för segmentdefinitionen. |
name |
Ett unikt namn som ska referera till segmentet. |
schema |
Det schema som är associerat med entiteterna i segmentet. Består av antingen en id eller name fält. |
expression |
En entitet som innehåller fältinformation om segmentdefinitionen. |
expression.type |
Anger uttryckstypen. För närvarande stöds bara PQL. |
expression.format |
Anger strukturen för uttrycket i värdet. Följande format stöds för närvarande:
|
expression.value |
Ett uttryck som överensstämmer med typen som anges i expression.format . |
description |
En läsbar beskrivning av definitionen. |
evaluationInfo |
Ett systemgenererat objekt som anger vilken typ av utvärdering, batch, kontinuerlig (kallas även direktuppspelning) eller synkron, segmentdefinitionen ska genomgå. |
Du kan begära att få ta bort en viss segmentdefinition genom att göra en DELETE-förfrågan till /segment/definitions
slutpunkt och ange ID:t för segmentdefinitionen som du vill ta bort i sökvägen för begäran.
Du kommer att not kan ta bort ett segment som används i en målaktivering.
API-format
DELETE /segment/definitions/{SEGMENT_ID}
Parameter | Beskrivning |
---|---|
{SEGMENT_ID} |
The id värdet för segmentdefinitionen som du vill ta bort. |
Begäran
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}'
Svar
Ett lyckat svar returnerar HTTP-status 200 utan något meddelande.
Du kan uppdatera en specifik segmentdefinition genom att göra en PATCH-begäran till /segment/definitions
slutpunkt och ange ID:t för segmentdefinitionen som du vill uppdatera i sökvägen för begäran.
API-format
PATCH /segment/definitions/{SEGMENT_ID}
Parameter | Beskrivning |
---|---|
{SEGMENT_ID} |
The id värdet för segmentdefinitionen som du vill uppdatera. |
Begäran
Följande begäran kommer att uppdatera arbetsadresslandet från USA till Kanada.
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
}'
Svar
Ett lyckat svar returnerar HTTP-status 200 med information om den nyligen uppdaterade segmentdefinitionen. Lägg märke till hur arbetsadresslandet har uppdaterats från USA (USA) till Kanada (CA).
{
"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
}
Du kan konvertera en segmentdefinition mellan pql/text
och pql/json
eller pql/json
till pql/text
genom att göra en POST-förfrågan till /segment/conversion
slutpunkt.
API-format
POST /segment/conversion
Begäran
Följande begäran ändrar segmentdefinitionens format från pql/text
till 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
}'
Svar
Ett lyckat svar returnerar HTTP-status 200 med information om din nyligen konverterade segmentdefinition.
{
"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\"}]}"
}
}
När du har läst den här guiden får du nu en bättre förståelse för hur segmentdefinitioner fungerar. Mer information om hur du skapar ett segment finns i skapa ett segment självstudiekurs.