API-slutpunkt för beräknade attribut

IMPORTANT
Åtkomsten till API:t är begränsad. Kontakta Adobe Support om du vill veta hur du får åtkomst till API:t för beräknade attribut.

Beräknade attribut är funktioner som används för att samla data på händelsenivå i attribut på profilnivå. Funktionerna beräknas automatiskt så att de kan användas för segmentering, aktivering och personalisering. Den här guiden innehåller exempel på API-anrop för att utföra grundläggande CRUD-åtgärder med slutpunkten /attributes.

Om du vill veta mer om beräknade attribut börjar du med att läsa översikten beräknade attribut.

Komma igång

API-slutpunkten som används i den här guiden ingår i Real-Time Customer Profile API.

Innan du fortsätter bör du gå igenom guiden Komma igång-start för profil-API för att få länkar till rekommenderad dokumentation, en guide till hur du läser exempelanrop till API:er som visas i det här dokumentet samt viktig information om vilka huvuden som krävs för att kunna ringa anrop till valfritt Experience Platform-API.

Läs även dokumentationen för följande tjänst:

Hämta en lista med beräknade attribut list

Du kan hämta en lista över alla beräknade attribut för din organisation genom att göra en GET-förfrågan till slutpunkten /attributes.

API-format

Slutpunkten /attributes har stöd för flera frågeparametrar som kan hjälpa dig att filtrera dina resultat. Även om dessa parametrar är valfria rekommenderar vi starkt att de används för att minska dyra overheadkostnader när du listar resurser. Om du anropar den här slutpunkten utan parametrar hämtas alla beräknade attribut som är tillgängliga för din organisation. Flera parametrar kan inkluderas, avgränsade med et-tecken (&).

GET /attributes
GET /attributes?{QUERY_PARAMETERS}

Följande frågeparametrar kan användas när en lista med beräknade attribut hämtas:

Frågeparameter
Beskrivning
Exempel
limit
En parameter som anger det maximala antalet objekt som returneras som en del av svaret. Det minsta värdet för den här parametern är 1 och det högsta värdet är 40. Om den här parametern inte ingår returneras som standard 20 objekt.
limit=20
offset
En parameter som anger antalet objekt som ska hoppas över innan objekten returneras.
offset=5
sortBy
En parameter som anger i vilken ordning de returnerade objekten sorteras. De tillgängliga alternativen är name, status, updateEpoch och createEpoch. Du kan också välja om du vill sortera i stigande eller fallande ordning genom att inte ta med eller ta med - framför sorteringsalternativet. Som standard sorteras objekten efter updateEpoch i fallande ordning.
sortBy=name
property

En parameter som gör att du kan filtrera på olika beräknade attributfält. Egenskaper som stöds är name, createEpoch, mergeFunction.value, updateEpoch och status. Vilka åtgärder som stöds beror på vilken egenskap som visas.

  • name: EQUAL (=), NOT_EQUAL (!=), CONTAINS (=contains()), NOT_CONTAINS (=!contains())
  • createEpoch: GREATER_THAN_OR_EQUALS (<=), LESS_THAN_OR_EQUALS (>=)
  • mergeFunction.value: EQUAL (=), NOT_EQUAL (!=), CONTAINS (=contains()), NOT_CONTAINS (=!contains())
  • updateEpoch: GREATER_THAN_OR_EQUALS (<=), LESS_THAN_OR_EQUALS (>=)
  • status: EQUAL (=), NOT_EQUAL (!=), CONTAINS (=contains()), NOT_CONTAINS (=!contains())
property=updateEpoch>=1683669114845
property=name!=testingrelease
property=status=contains(new,processing,disabled)

Begäran

Följande begäran hämtar de tre senaste beräknade attributen som uppdaterades i din organisation.

En exempelbegäran om att hämta en lista med beräknade attribut.
code language-shell
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}'

Svar

Ett lyckat svar returnerar HTTP-status 200 med en lista över de tre senaste uppdaterade beräknade attributen som tillhör din organisation och sandlåda.

Ett exempelsvar för att hämta en lista med beräknade attribut.
code language-json
{
    "_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
    }
}
table 0-row-2 1-row-2 2-row-2 3-row-2
Egenskap Beskrivning
_links Ett objekt som innehåller den sidnumreringsinformation som krävs för att komma åt den sista resultatsidan, nästa resultatsida, föregående resultatsida eller den aktuella resultatsidan.
computedAttributes En array som innehåller de beräknade attributen baserat på dina frågeparametrar. Mer information om den beräknade attributarrayen finns i hämtningen av ett visst beräknat attributavsnitt.
_page Ett objekt som innehåller metadata om de returnerade resultaten. Detta inkluderar information om aktuell förskjutning, antalet returnerade beräknade attribut, det totala antalet beräknade attribut samt gränsen för returnerade beräknade attribut.

Skapa ett beräknat attribut create

Om du vill skapa ett beräknat attribut börjar du med att göra en POST-förfrågan till slutpunkten /attributes med en begärandebrödtext som innehåller information om det beräknade attributet som du vill skapa.

API-format

POST /attributes

Begäran

En exempelbegäran om att skapa ett nytt beräknat attribut.
code language-shell
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"
      }'
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2
Egenskap Beskrivning
name Namnet på det beräknade attributfältet, som en sträng. Namnet på det beräknade attributet får endast bestå av alfanumeriska tecken utan mellanslag eller understreck. Värdet måste vara unikt bland alla beräknade attribut. Det här namnet bör vara en cameraCase-version av displayName.
description En beskrivning av det beräknade attributet. Detta är särskilt användbart när flera beräknade attribut har definierats, eftersom det kommer att hjälpa andra inom organisationen att fastställa rätt beräknat attribut att använda.
displayName Det beräknade attributets visningsnamn. Det här namnet visas när du anger dina beräknade attribut i Adobe Experience Platform-gränssnittet.
expression Ett objekt som representerar frågeuttrycket för det beräknade attribut som du försöker skapa.
expression.type Uttryckets typ. För närvarande stöds endast PQL.
expression.format Uttryckets format. För närvarande stöds bara pql/text.
expression.value Uttryckets värde.
keepCurrent Ett booleskt värde som avgör om det beräknade attributets värde uppdateras eller inte med hjälp av snabb uppdatering. För närvarande bör det här värdet anges till false.
duration Ett objekt som representerar uppslagsperioden för det beräknade attributet. Uppslagsperioden representerar hur långt tillbaka som kan slås tillbaka för att beräkna det beräknade attributet.
duration.count

Ett tal som representerar längden för uppslagsperioden. Möjliga värden beror på värdet för fältet duration.unit.

  • HOURS: 1-24
  • DAYS: 1-7
  • WEEKS: 1-4
  • MONTHS: 1-6
duration.unit En sträng som representerar den tidsenhet som ska användas för uppslagsperioden. Möjliga värden är: HOURS, DAYS, WEEKS och MONTHS.
status Status för beräknat attribut. Möjliga värden är DRAFT och NEW.

Svar

Ett lyckat svar returnerar HTTP-status 200 med information om det nya beräknade attributet.

Ett samplingssvar när ett nytt beräknat attribut skapas.
code language-json
{
    "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}"
}
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2
Egenskap Beskrivning
id Det systemgenererade ID:t för det nya beräknade attributet.
status Det beräknade attributets status. Detta kan antingen vara DRAFT eller NEW.
createEpoch Tiden då det beräknade attributet skapades, i sekunder.
updateEpoch Den tidpunkt då det beräknade attributet senast uppdaterades, i sekunder.
createdBy ID för den användare som skapade det beräknade attributet.

Hämta ett specifikt beräknat attribut get

Du kan hämta detaljerad information om ett specifikt beräknat attribut genom att göra en GET-förfrågan till slutpunkten /attributes och ange ID:t för det beräknade attribut som du vill hämta i sökvägen till begäran.

API-format

GET /attributes/{ATTRIBUTE_ID}

Begäran

En exempelbegäran om att hämta ett specifikt beräknat attribut.
code language-shell
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}'

Svar

Ett lyckat svar returnerar HTTP-status 200 med detaljerad information om det angivna beräknade attributet.

Ett samplingssvar när ett visst beräknat attribut hämtas.
code language-json
{
    "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}"
}
table 0-row-2 1-row-2 2-row-2 3-row-2 4-row-2 5-row-2 6-row-2 7-row-2 8-row-2 9-row-2 10-row-2 11-row-2 12-row-2 13-row-2 14-row-2 15-row-2 16-row-2 17-row-2
Egenskap Beskrivning
id Ett unikt, skrivskyddat, systemgenererat ID som kan användas för att referera till det beräknade attributet under andra API-åtgärder.
type En sträng som visar att det returnerade objektet är ett beräknat attribut.
name Namnet på det beräknade attributet.
displayName Det beräknade attributets visningsnamn. Det här namnet visas när du anger dina beräknade attribut i Adobe Experience Platform-gränssnittet.
description En beskrivning av det beräknade attributet. Detta är särskilt användbart när flera beräknade attribut har definierats, eftersom det kommer att hjälpa andra inom organisationen att fastställa rätt beräknat attribut att använda.
imsOrgId ID:t för organisationen som det beräknade attributet tillhör.
sandbox Sandlådeobjektet innehåller information om den sandlåda som det beräknade attributet konfigurerades i. Den här informationen hämtas från sandlådehuvudet som skickas i begäran. Mer information finns i översikten över sandlådor.
path path till beräknat attribut.
keepCurrent Ett booleskt värde som avgör om det beräknade attributets värde uppdateras eller inte med hjälp av snabb uppdatering.
expression Ett objekt som innehåller attributets uttryck.
mergeFunction Ett objekt som innehåller kopplingsfunktionen för det beräknade attributet. Det här värdet baseras på motsvarande aggregeringsparameter i det beräknade attributets uttryck. Möjliga värden är SUM, MIN, MAX och MOST_RECENT.
status Det beräknade attributets status. Detta kan vara något av följande värden: DRAFT, NEW, INITIALIZING, PROCESSING, PROCESSED, FAILED eller DISABLED.
schema Ett objekt som innehåller information om schemat där uttrycket utvärderas i. För närvarande stöds bara _xdm.context.profile.
lastEvaluationTs En tidsstämpel som representerar när det beräknade attributet senast utvärderades.
createEpoch Tiden då det beräknade attributet skapades, i sekunder.
updateEpoch Den tidpunkt då det beräknade attributet senast uppdaterades, i sekunder.
createdBy ID för den användare som skapade det beräknade attributet.

Ta bort ett visst beräknat attribut delete

Du kan ta bort ett specifikt beräknat attribut genom att göra en DELETE-begäran till /attributes-slutpunkten och ange ID:t för det beräknade attribut som du vill ta bort i sökvägen till begäran.

IMPORTANT
Borttagningsbegäran kan bara användas för att ta bort beräknade attribut med statusen draft (DRAFT). Slutpunkten kan inte användas för att ta bort beräknade attribut i något annat läge.

API-format

DELETE /attributes/{ATTRIBUTE_ID}
Parameter
Beskrivning
{ATTRIBUTE_ID}
Värdet id för det beräknade attributet som du vill ta bort.

Begäran

En exempelbegäran om att ta bort ett beräknat attribut.
code language-shell
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}'

Svar

Ett lyckat svar returnerar HTTP-status 202 med information om det borttagna beräknade attributet.

Ett exempelsvar när ett beräknat attribut tas bort.
code language-json
{
    "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}"
}

Uppdatera ett specifikt beräknat attribut

Du kan uppdatera ett specifikt beräknat attribut genom att göra en PATCH-begäran till slutpunkten /attributes och ange ID:t för det beräknade attribut som du vill uppdatera i sökvägen till begäran.

IMPORTANT
När du uppdaterar ett beräknat attribut kan endast följande fält uppdateras:
  • Om den aktuella statusen är NEW kan statusen bara ändras till DISABLED.
  • Om den aktuella statusen är DRAFT kan du ändra värdena för följande fält: name, description, keepCurrent, expression och duration. Du kan också ändra status från DRAFT till NEW. Ändringar i systemgenererade fält, som mergeFunction eller path, returnerar ett fel.
  • Om den aktuella statusen är antingen PROCESSING eller PROCESSED kan statusen bara ändras till DISABLED.

API-format

PATCH /attributes/{ATTRIBUTE_ID}
Parameter
Beskrivning
{ATTRIBUTE_ID}
Värdet id för det beräknade attribut som du vill uppdatera.

Begäran

Följande begäran uppdaterar statusen för det beräknade attributet från DRAFT till NEW.

En exempelbegäran om att uppdatera ett beräknat attribut.
code language-shell
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"
 }'

Svar

Ett lyckat svar returnerar HTTP-status 200 med information om ditt nyligen uppdaterade beräknade attribut.

Ett exempelsvar när ett beräknat attribut uppdateras.
code language-json
{
    "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}"
}

Nästa steg

Nu när du har lärt dig grunderna i beräknade attribut kan du börja definiera dem för din organisation. Om du vill lära dig hur du använder beräknade attribut i användargränssnittet för Experience Platform kan du läsa användargränssnittshandboken för beräknade attribut.

recommendation-more-help
54550d5b-f1a1-4065-a394-eb0f23a2c38b