Utvärdera och få tillgång till segmentdefinitionsresultat

Senaste uppdatering: 2023-11-14
  • Ämnen:
  • Segments
    Visa mer om det här ämnet
  • Skapat för:
  • Developer
    User
    Admin
    Leader

Det här dokumentet innehåller en självstudiekurs för att utvärdera segmentdefinitioner och få tillgång till dessa resultat med Segmentation API.

Komma igång

Den här självstudiekursen kräver en fungerande förståelse för de olika Adobe Experience Platform tjänster som används för att skapa målgrupper. Innan du börjar med den här självstudiekursen bör du läsa dokumentationen för följande tjänster:

  • Real-Time Customer Profile: Tillhandahåller en enhetlig kundprofil i realtid baserad på aggregerade data från flera källor.
  • Adobe Experience Platform Segmentation Service: Används för att bygga målgrupper utifrån Real-Time Customer Profile data.
  • Experience Data Model (XDM): Det standardiserade ramverk som Platform använder för att organisera kundupplevelsedata. För att utnyttja segmenteringen på bästa sätt bör du se till att dina data är inmatade som profiler och händelser enligt bästa praxis för datamodellering.
  • Sandlådor: Experience Platform innehåller virtuella sandlådor som partitionerar en enda Platform till separata virtuella miljöer för att utveckla och utveckla applikationer för digitala upplevelser.

Obligatoriska rubriker

Den här självstudiekursen kräver även att du har slutfört självstudiekurs om autentisering för att kunna ringa Platform API. När du är klar med självstudiekursen för autentisering visas värdena för var och en av de obligatoriska rubrikerna i alla Experience Platform API-anrop enligt nedan:

  • Behörighet: Bearer {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Alla resurser i Experience Platform isoleras till specifika virtuella sandlådor. Begäranden till Platform API:er kräver en rubrik som anger namnet på sandlådan som åtgärden ska utföras i:

  • x-sandbox-name: {SANDBOX_NAME}
OBSERVERA

Mer information om sandlådor i Platform, se översiktsdokumentation för sandlåda.

Alla förfrågningar från POST, PUT och PATCH kräver ytterligare en rubrik:

  • Content-Type: application/json

Utvärdera en segmentdefinition

När du har utvecklat, testat och sparat din segmentdefinition kan du sedan utvärdera segmentdefinitionen genom en schemalagd utvärdering eller on-demand-utvärdering.

Schemalagd utvärdering (kallas även"schemalagd segmentering") kan du skapa ett återkommande schema för att köra ett exportjobb vid en viss tidpunkt, medan on-demand-utvärdering innebär att skapa ett segmentjobb för att omedelbart bygga upp målgruppen. Stegen för varje steg beskrivs nedan.

Om du ännu inte har slutfört skapa en segmentdefinition med segmenterings-API självstudiekurs eller skapa en segmentdefinition med Segment Buildergör du det innan du fortsätter med kursen.

Schemalagd utvärdering

Med schemalagd utvärdering kan din organisation skapa ett återkommande schema för att automatiskt köra exportjobb.

OBSERVERA

Schemalagd utvärdering kan aktiveras för sandlådor med högst fem (5) sammanfogningsprinciper för XDM Individual Profile. Om din organisation har fler än fem samkörningspolicyer för XDM Individual Profile i en enda sandlådemiljö kommer du inte att kunna använda schemalagd utvärdering.

Skapa ett schema

Genom att göra en POST-förfrågan till /config/schedules kan du skapa ett schema och inkludera den specifika tidpunkt då schemat ska utlösas.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktshandbok för scheman

Aktivera ett schema

Som standard är ett schema inaktivt när det skapas såvida inte state egenskapen är inställd på active i texten för skapandebegäran (POST). Du kan aktivera ett schema (ange state till active) genom att göra en begäran från PATCH till /config/schedules slutpunkten och inklusive ID för schemat i sökvägen.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktshandbok för scheman

Uppdatera schematiden

Tidsplaneringen kan uppdateras genom att PATCH begär /config/schedules slutpunkten och inklusive ID för schemat i sökvägen.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktshandbok för scheman

On-demand-utvärdering

Med On-demand-utvärdering kan ni skapa ett segmentjobb för att generera en målgrupp när ni behöver det. Till skillnad från schemalagd utvärdering kommer detta endast att ske när det begärs och inte är återkommande.

Skapa ett segmentjobb

Ett segmentjobb är en asynkron process som skapar ett målgruppssegment på begäran. Det refererar till en segmentdefinition samt eventuella sammanfogningsprinciper som styr hur Real-Time Customer Profile sammanfogar överlappande attribut i dina profilfragment. När ett segmentjobb har slutförts kan du samla in olika information om segmentdefinitionen, t.ex. eventuella fel som kan ha inträffat under bearbetningen och målgruppens slutliga storlek. Ett segmentjobb måste köras varje gång du vill uppdatera målgruppen som är kvalificerad för segmentdefinitionen.

Du kan skapa ett nytt segmentjobb genom att göra en POST-förfrågan till /segment/jobs slutpunkt i Real-Time Customer Profile API.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktsguide för segmentjobb

Sök efter jobbstatus för segment

Du kan använda id för ett specifikt segmentjobb att utföra en sökbegäran (GET) för att visa jobbets aktuella status.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktsguide för segmentjobb

Tolka segmentjobbresultat

När segmentjobben har körts segmentMembership kartan uppdateras för varje profil som ingår i segmentdefinitionen. segmentMembership lagrar även alla förutvärderade målgrupper som hämtas in till Platform, vilket möjliggör integrering med andra lösningar som Adobe Audience Manager.

I följande exempel visas vad segmentMembership för varje enskild profilpost ser attributet ut så här:

{
  "segmentMembership": {
    "UPS": {
      "04a81716-43d6-4e7a-a49c-f1d8b3129ba9": {
        "timestamp": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      },
      "53cba6b2-a23b-454a-8069-fc41308f1c0f": {
        "lastQualificationTime": "2018-04-26T15:52:25+00:00",
        "status": "realized"
      }
    },
    "Email": {
      "abcd@adobe.com": {
        "lastQualificationTime": "2017-09-26T15:52:25+00:00",
        "status": "exited"
      }
    }
  }
}
Egenskap Beskrivning
lastQualificationTime Tidsstämpeln när kontrollen av segmentmedlemskap gjordes och profilen angavs eller avslutades i segmentdefinitionen.
status Segmentdefinitionens deltagarstatus som en del av den aktuella begäran. Måste vara lika med ett av följande kända värden:
  • realized: Entiteten kvalificerar sig för segmentdefinitionen.
  • exited: Entiteten avslutar segmentdefinitionen.
OBSERVERA

Alla segmentmedlemskap som finns i exited status i mer än 30 dagar, baserat på lastQualificationTime, kan tas bort.

Åtkomst till segmentjobbresultat

Resultatet av ett segmentjobb kan nås på ett av två sätt: du kan komma åt enskilda profiler eller exportera en hel publik till en datauppsättning.

I följande avsnitt beskrivs dessa alternativ mer ingående.

Söka efter en profil

Om du vet vilken profil du vill använda kan du göra det med Real-Time Customer Profile API. De fullständiga stegen för att komma åt enskilda profiler finns i Få åtkomst till kundprofildata i realtid med profils-API självstudie.

Exportera ett segment

När ett segmenteringsjobb har slutförts (värdet på status -attributet är "SUCCEEDED") kan du exportera målgruppen till en datauppsättning där den kan nås och hanteras.

Följande steg krävs för att exportera målgruppen:

Skapa en måldatauppsättning

När du exporterar en målgrupp måste du först skapa en måldatauppsättning. Det är viktigt att datauppsättningen är korrekt konfigurerad för att exporten ska lyckas.

Ett av de viktigaste övervägandena är schemat som datauppsättningen baseras på (schemaRef.id i API-exempelbegäran nedan). För att kunna exportera en segmentdefinition måste datauppsättningen baseras på XDM Individual Profile Union Schema (https://ns.adobe.com/xdm/context/profile__union). Ett unionsschema är ett systemgenererat, skrivskyddat schema som samlar in fält i scheman som delar samma klass, i det här fallet klassen XDM Individual Profile. Mer information om unionens vyscheman finns i Avsnittet Kundprofil i realtid i utvecklarhandboken för schemaregistret.

Det finns två sätt att skapa den nödvändiga datauppsättningen:

  • Använda API: Stegen som följer i den här självstudiekursen visar hur du skapar en datauppsättning som refererar till XDM Individual Profile Union Schema med Catalog API.
  • Använda gränssnittet: Använd Adobe Experience Platform om du vill skapa en datauppsättning som refererar till unionsschemat följer du stegen i Självstudiekurs om användargränssnitt och sedan återgå till den här självstudiekursen för att fortsätta med stegen för generera målgruppsprofiler.

Om du redan har en kompatibel datauppsättning och känner till dess ID kan du fortsätta direkt till steget för generera målgruppsprofiler.

API-format

POST /dataSets

Begäran

Följande begäran skapar en ny datauppsättning med konfigurationsparametrar i nyttolasten.

curl -X POST \
  https://platform.adobe.io/data/foundation/catalog/dataSets \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {ORG_ID}' \
  -H 'x-sandbox-name: {SANDBOX_NAME}' \
  -d '{
    "name": "Segment Export",
    "schemaRef": {
        "id": "https://ns.adobe.com/xdm/context/profile__union",
        "contentType": "application/vnd.adobe.xed+json;version=1"
    }
}'
Egenskap Beskrivning
name Ett beskrivande namn för datauppsättningen.
schemaRef.id ID:t för den unionsvy (schema) som datauppsättningen ska kopplas till.

Svar

Ett lyckat svar returnerar en array som innehåller det skrivskyddade, systemgenererade unika ID:t för den nya datauppsättningen. Ett korrekt konfigurerat datauppsättnings-ID krävs för att målgruppsmedlemmar ska kunna exporteras.

[
  "@/datasets/5b020a27e7040801dedba61b"
]

Generera profiler för målgruppsmedlemmar

När du har en enhetlig datauppsättning kan du skapa ett exportjobb som behåller målgruppsmedlemmarna i datauppsättningen genom att göra en POST till /export/jobs slutpunkt i Real-Time Customer Profile API och ange datauppsättnings-ID och segmentdefinitionsinformation för de segmentdefinitioner som du vill exportera.

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktsguide för exportjobb

Övervaka exportförlopp

Som en exportjobbsprocess kan du övervaka dess status genom att göra en GET-förfrågan till /export/jobs slutpunkt och inklusive id av exportjobbet i sökvägen. Exportjobbet är klart när status returnerar värdet "SUCCEEDED".

Mer detaljerad information om hur du använder den här slutpunkten finns i slutpunktsguide för exportjobb

Nästa steg

När exporten är klar är dina data tillgängliga i Data Lake in Experience Platform. Du kan sedan använda Data Access API för att få åtkomst till data med batchId som är associerad med exporten. Beroende på segmentdefinitionens storlek kan data vara i segment och gruppen kan bestå av flera filer.

Stegvisa instruktioner om hur du använder Data Access API för att få tillgång till och ladda ned batchfiler, följ Dataåtkomst, genomgång.

Du kan också komma åt exporterade segmentdefinitionsdata med Adobe Experience Platform Query Service. Använda gränssnittet eller RESTful API, Query Service kan du skriva, validera och köra frågor på data i Data Lake.

Mer information om hur man hämtar information finns i dokumentationen om Query Service.

På denna sida