Slutpunkt för segmentdefinitioner

Med Adobe Experience Platform kan du skapa segmentdefinitioner 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). Segmentdefinitioner används på profiler för att skapa målgrupper. Det här objektet (segmentdefinitionen) kallas också för ett PQL-predikat. PQL-predikat definierar reglerna för segmentdefinitionen baserat på villkor som relaterar till data från poster eller tidsserier som du skickar till Real-Time Customer Profile. Se PQL-guide för 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.

Komma igång

Slutpunkterna som används i den här guiden är en del av Adobe Experience Platform Segmentation Service API. Innan du fortsätter bör du granska 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.

Hämta en lista med segmentdefinitioner list

Du kan hämta en lista över alla segmentdefinitioner för din 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 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 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": {}
}

Skapa en ny segmentdefinition create

Du kan skapa en ny segmentdefinition genom att göra en POST-förfrågan till /segment/definitions slutpunkt.

IMPORTANT
Segmentdefinitioner skapade med API inte kan redigeras med segmentbyggaren.

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\""
        },
        "evaluationInfo": {
            "batch": {
                "enabled": true
            },
            "continuous": {
                "enabled": false
            },
            "synchronous": {
                "enabled": false
            }
        },
        "schema": {
            "name": "_xdm.context.profile"
        },
        "payloadSchema": "string",
        "ttlInDays": 60
    }'
Egenskap
Beskrivning
name
Ett unikt namn som ska referera till segmentdefinitionen.
description
(Valfritt.) En beskrivning av segmentdefinitionen som du skapar.
evaluationInfo
(Valfritt.) Den typ av segmentdefinition som du skapar. Om du vill skapa ett gruppsegment anger du evaluationInfo.batch.enabled att vara sant. Om du vill skapa ett direktuppspelningssegment anger du evaluationInfo.continuous.enabled att vara sant. Om du vill skapa ett kantsegment anger du evaluationInfo.synchronous.enabled att vara sant. Om den lämnas tom skapas segmentdefinitionen som batch segment.
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:

  • pql/text: En textbeteckning för en segmentdefinition enligt den publicerade PQL-grammatiken. Till exempel: workAddress.stateProvince = homeAddress.stateProvince.
expression.value
Ett uttryck som överensstämmer med typen som anges i expression.format.

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 objekt som anger vilken typ av utvärdering som segmentdefinitionen ska genomgå. Det kan vara gruppsegmentering, direktuppspelning (kallas även kontinuerlig) eller kantsegmentering (kallas även synkron).

Hämta en specifik segmentdefinition get

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 segmentdefinitionen.
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:

  • pql/text: En textbeteckning för en segmentdefinition enligt den publicerade PQL-grammatiken. Till exempel: workAddress.stateProvince = homeAddress.stateProvince.
expression.value
Ett uttryck som överensstämmer med typen som anges i expression.format.
description
En läsbar beskrivning av definitionen.
evaluationInfo
Ett objekt som anger vilken typ av utvärdering, batch, direktuppspelning (kallas även kontinuerlig) eller kant (kallas även synkron), kommer segmentdefinitionen att genomgå.

Hämta segmentdefinitioner gruppvis bulk-get

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 segmentdefinitionen.
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:

  • pql/text: En textbeteckning för en segmentdefinition enligt den publicerade PQL-grammatiken. Till exempel: workAddress.stateProvince = homeAddress.stateProvince.
expression.value
Ett uttryck som överensstämmer med typen som anges i expression.format.
description
En läsbar beskrivning av definitionen.
evaluationInfo
Ett objekt som anger vilken typ av utvärdering, batch, direktuppspelning (kallas även kontinuerlig) eller kant (kallas även synkron), kommer segmentdefinitionen att genomgå.

Ta bort en specifik segmentdefinition delete

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.

NOTE
En segmentdefinition som används i en målaktivering inte tas bort.

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.

Uppdatera en specifik segmentdefinition

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
}

Konvertera segmentdefinition

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ästa steg

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älvstudie.

recommendation-more-help
770bc05d-534a-48a7-9f07-017ec1e14871