Felsökningsguide för XDM-system

Det här dokumentet innehåller svar på vanliga frågor om Experience Data Model (XDM) och XDM-system i Adobe Experience Platform, inklusive en felsökningsguide för vanliga fel. För frågor och felsökning som rör andra plattformstjänster, se felsökningsguiden för Experience Platform.

Experience Data Model (XDM) är en öppen källkodsspecifikation som definierar standardiserade scheman för kundupplevelsehantering. Metoden som Experience Platform byggs på, XDM System, opererar Experience Data Model scheman som ska användas av Platform-tjänster. Schema Registry innehåller ett användargränssnitt och ett RESTful-API för åtkomst till Schema Library i Experience Platform. Mer information finns i XDM-dokumentationen.

Vanliga frågor och svar

Nedan följer en lista med svar på vanliga frågor om XDM-system och användning av Schema Registry-API:t.

Hur lägger jag till fält i ett schema?

Du kan lägga till fält i ett schema med hjälp av en schemafältgrupp. Varje fältgrupp är kompatibel med en eller flera klasser, vilket gör att fältgruppen kan användas i alla scheman som implementerar en av dessa kompatibla klasser. Adobe Experience Platform tillhandahåller flera branschfältgrupper med sina egna fördefinierade fält, men du kan lägga till egna fält i ett schema genom att skapa anpassade fältgrupper med API:t eller användargränssnittet.

Mer information om hur du skapar fältgrupper i Schema Registry API finns i guiden för fältgruppsslutpunkter. Om du använder användargränssnittet kan du läsa självstudiekursen för schemaredigeraren.

Vilket är det bästa användningsområdet för fältgrupper jämfört med datatyper?

Fältgrupper är komponenter som definierar ett eller flera fält i ett schema. Fältgrupper styr hur deras fält visas i schemats hierarki och visar därför samma struktur i varje schema som de ingår i. Fältgrupper är bara kompatibla med specifika klasser, vilket identifieras av deras meta:intendedToExtend-attribut.

Datatyper kan även innehålla ett eller flera fält för ett schema. Till skillnad från fältgrupper är datatyperna dock inte begränsade till en viss klass. Detta gör datatyper till ett mer flexibelt alternativ för att beskriva vanliga datastrukturer som kan återanvändas i flera scheman med potentiellt olika klasser.

Vilket unikt ID har ett schema?

Alla Schema Registry-resurser (scheman, fältgrupper, datatyper, klasser) har en URI som fungerar som ett unikt ID för referens- och sökningsändamål. När du visar ett schema i API:t finns det i attributen $id och meta:altId på den översta nivån.

Mer information finns i avsnittet resursidentifiering i API-handboken för Schema Registry.

När börjar ett schema förhindra att ändringar bryts?

Du kan göra ändringar i ett schema så länge det aldrig har använts för att skapa en datauppsättning eller aktiverats för användning i Real-Time Customer Profile. När ett schema har använts när datauppsättningar skapades eller aktiverats för användning med Real-Time Customer Profile, kommer reglerna för schemautveckling att tillämpas strikt av systemet.

Vilken är den maximala storleken för en lång fälttyp?

En lång fälttyp är ett heltal med en maximal storlek på 53 (+1) bitar, vilket ger den ett möjligt intervall mellan -9007199254740992 och 900719925474092. Detta beror på en begränsning av hur JavaScript implementeringar av JSON representerar långa heltal.

Mer information om fälttyper finns i dokumentet om XDM-fälttypsbegränsningar.

Hur definierar jag identiteter för mitt schema?

I Experience Platform används identiteter för att identifiera ett ämne (vanligtvis en enskild person) oavsett vilka datakällor som tolkas. De definieras i scheman genom att nyckelfält markeras som"Identitet". Vanliga fält för identitet är e-postadress, telefonnummer, Experience Cloud ID (ECID), CRM-ID och andra unika ID-fält.

Fält kan markeras som identiteter med antingen API:t eller användargränssnittet.

Definiera identiteter i API:t

I API:t etableras identiteter genom att skapa identitetsbeskrivningar. Identitetsbeskrivare signalerar att en viss egenskap för ett schema är en unik identifierare.

Identitetsbeskrivare skapas av en POST-begäran till slutpunkten /descriptors. Om det lyckas får du ett HTTP Status 201 (Skapad) och ett svarsobjekt med information om den nya beskrivningen.

Mer information om hur du skapar identitetsbeskrivningar i API:t finns i dokumentet om avsnittet beskrivningar i Schema Registry-utvecklarhandboken.

Definiera identiteter i användargränssnittet

Med schemat öppet i Schemaredigeraren markerar du det fält i Structure-delen av redigeraren som du vill markera som en identitet. Markera kryssrutan Identity under Field Properties till höger.

Mer information om hur du hanterar identiteter i användargränssnittet finns i avsnittet Definiera identitetsfält i schemaredigerarens självstudiekurs.

Behöver mitt schema en primär identitet?

Primära identiteter är valfria eftersom scheman kan ha antingen noll eller en av dem. Ett schema måste dock ha en primär identitet för att schemat ska kunna aktiveras för användning i Real-Time Customer Profile. Mer information finns i avsnittet identity i schemaredigerarens självstudiekurs.

Hur aktiverar jag ett schema för användning i Real-Time Customer Profile?

Scheman har aktiverats för användning i Real-Time Customer Profile genom att en "union"-tagg läggs till i schemats meta:immutableTags-attribut. Du kan aktivera ett schema för användning med Profile med API:t eller användargränssnittet.

Aktiverar ett befintligt schema för Profile med API:t

Gör en PATCH-begäran om att uppdatera schemat och lägga till attributet meta:immutableTags som en matris som innehåller värdet "union". Om uppdateringen lyckas visas det uppdaterade schemat som nu innehåller unionstaggen.

Mer information om hur du använder API:t för att aktivera ett schema för användning i Real-Time Customer Profile finns i dokumentet union i Schema Registry-utvecklarhandboken.

Aktiverar ett befintligt schema för Profile med användargränssnittet

I Experience Platform väljer du Schemas i den vänstra navigeringen och väljer namnet på schemat som du vill aktivera i listan med scheman. Sedan väljer du Profile till höger om redigeraren under Schema Properties för att aktivera den.

Mer information finns i avsnittet Använd i kundprofil för realtid i självstudiekursen Schema Editor.

Kan jag redigera ett unionsschema direkt?

Unionsscheman är skrivskyddade och genereras automatiskt av systemet. De kan inte redigeras direkt. Unionsscheman skapas för en viss klass när en"union"-tagg läggs till i schemat som implementerar den klassen.

Mer information om fackföreningar i XDM finns i avsnittet fackföreningar i API-handboken för Schema Registry.

Hur ska jag formatera min datafil för att importera data till mitt schema?

Experience Platform accepterar datafiler i antingen Parquet- eller JSON-format. Innehållet i dessa filer måste överensstämma med det schema som datauppsättningen refererar till. Mer information om de bästa sätten att mata in datafiler finns i översikten över gruppinmatning.

Fel och felsökning

Nedan följer en lista över felmeddelanden som du kan stöta på när du arbetar med API:t Schema Registry.

Resursen hittades inte

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1010-404",
    "title": "Resource not found",
    "status": 404,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found.",
        "sub-errors": []
    },
    "detail": "The requested class resource https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 with version 1 is not found."
}

Det här felet visas när systemet inte kan hitta en viss resurs. Resursen kan ha tagits bort eller så är sökvägen i API-anropet ogiltig. Kontrollera att du har angett en giltig sökväg för API-anropet innan du försöker igen. Du kanske vill kontrollera att du har angett rätt ID för resursen och att sökvägen har rätt namn tillsammans med rätt behållare (global eller klientorganisation).

Mer information om hur du skapar sökvägar i API:t finns i avsnitten container och resource identifier i utvecklarhandboken för Schema Registry.

Titeln är inte unik

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1521-400",
    "title": "Title not unique",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title",
        "sub-errors": []
    },
    "detail": "Object titles must be unique. An object https://ns.adobe.com/{TENANT_ID}/classes/11447bb484d4599d2cd9b0aseefff78b463cbbde1527f498 already exists with the same title"
}

Det här felmeddelandet visas när du försöker skapa en resurs med en titel som redan används av en annan resurs. Titlar måste vara unika för alla resurstyper. Om du till exempel försöker skapa en fältgrupp med en titel som redan används av ett schema, visas det här felet.

Valideringsfel för namnområde

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1021-400",
    "title": "Namespace validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}.",
        "sub-errors": []
    },
    "detail": "A custom field is defined under an invalid namespace. All custom fields must be defined under a top-level field named {TENANT_ID}."
}

Det här felmeddelandet visas när du försöker skapa en resurs med felaktigt namngivna fält eller lägga till felaktigt namngivna fält i en befintlig resurs.

Resurser som definieras av din organisation måste namnge sina fält under ditt innehavar-ID för att undvika konflikter med andra bransch- och leverantörsresurser. När du skapar ett schema med standardfältgrupper måste alla anpassade fält som du lägger till i strukturen för dessa fältgrupper också namnges under ditt klient-ID.

Detaljerade exempel på lämpliga datastrukturer för XDM-resurser finns i API-handboken för schematabellen:

Ogiltigt accepteringshuvud

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1006-400",
    "title": "Accept header invalid",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json",
        "sub-errors": []
    },
    "detail": "The supplied Accept header is not valid: application/vnd.adobe.xed+json;version=1 - A valid Accept value should look like application/vnd.adobe.{xed|xdm}+json"
}

GET-begäranden i API:t Schema Registry kräver en Accept-rubrik för att systemet ska kunna avgöra hur svaret ska formateras. Det här felet inträffar när en obligatorisk Accept-rubrik är ogiltig eller saknas.

Beroende på vilken slutpunkt du använder anger egenskapen detailed-message hur en giltig Accept-rubrik ska se ut för ett lyckat svar. Kontrollera att du har angett ett Accept-huvud som är korrekt kompatibelt med den API-begäran som du försöker göra innan du försöker igen.

En lista över kompatibla Accept-huvuden för olika API-begäranden finns i motsvarande avsnitt i Utvecklarhandboken för schemaregister.

Real-Time Customer Profile fel

Följande felmeddelanden är associerade med åtgärder som ingår i aktiveringen av scheman för Real-Time Customer Profile. Mer information finns i avsnittet Fackföreningar i API-handboken för Schema Registry.

Det måste finnas en beskrivning av en referensidentitet

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1526-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union.",
        "sub-errors": []
    },
    "detail": "If a schema contains properties that are associated with an xdm:descriptorOneToOne descriptor, those properties must also have a xdm:descriptorReferenceIdentity descriptor for that schema to participate in a union."
}

Det här felmeddelandet visas när du försöker aktivera ett schema för Profile och en av dess egenskaper innehåller en relationsbeskrivare utan någon referensidentitetsbeskrivare. Lös det här felet genom att lägga till en beskrivare för referens-ID i schemafältet i fråga.

Namnutrymmena för referensbeskrivningsfältet och målschemat måste matcha

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1527-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field.",
        "sub-errors": []
    },
    "detail": "If both schemas from an existing xdm:descriptorOneToOne descriptor are promoted to union, and one of those schemas contains a primary identity, the xdm:identityNamespace of the source schema's descriptorReferenceIdentity field must match the xdm:namespace field of destination schema's xdm:descriptorIdentity field."
}

Om du vill aktivera scheman som innehåller relationsbeskrivningar för användning i Profile måste källfältets namnutrymme och det primära namnområdet för referensfältet vara samma. Det här felmeddelandet visas när du försöker aktivera ett schema som innehåller ett omatchat namnutrymme för dess referensidentitetsbeskrivning.

Kontrollera att värdet xdm:namespace för referensschemats identitetsfält matchar värdet för egenskapen xdm:identityNamespace i källfältets beskrivare för referens-ID för att lösa problemet.

En lista med standardkoder för identitetsnamnutrymmen finns i avsnittet standardnamnutrymmen i översikten över identitetsnamnutrymmen.

Schemat måste innehålla en identityMap eller primär identitet

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1528-400",
    "title": "Union descriptor validation error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "To participate in a union, a schema must include an identityMap fieldgroup or a primary identity descriptor.",
        "sub-errors": []
    },
    "detail": "To participate in a union, a schema must include an identityMap fieldgroup or a primary identity descriptor."
}

Innan du aktiverar ett schema för profilen måste du skapa en primär identitetsbeskrivning för schemat, eller inkludera ett identitetsmappningsfält som ska fungera vid den primära identiteten i stället.

Det går inte att sammanfoga inkompatibla datatyper

{
    "type": "http://ns.adobe.com/aep/errors/XDM-1413-400",
    "title": "Merge Schema Error",
    "status": 400,
    "report": {
        "registryRequestId": "a15996b5-5133-4cec-9bf7-7d1207904ae3",
        "timestamp": "06-01-2021 04:11:06",
        "detailed-message": "Cannot merge incompatible data types. The path /person/name has already been defined in schema (id=0238be93d3e7a06aec5e0655955901ec) using a different data type. Types: string, object",
        "sub-errors": []
    },
    "detail": "Cannot merge incompatible data types. The path /person/name has already been defined in schema (id=0238be93d3e7a06aec5e0655955901ec) using a different data type. Types: string, object"
}

Alla profilaktiverade scheman som tillhör samma klass måste kunna sammanfogas för att det ska gå att skapa ett unionsschema för den klassen. Det här felet uppstår när du försöker lägga till ett fält i ett schema vars sökväg delas av ett annat profilaktiverat schema och datatypen skiljer sig från den ursprungliga. Eftersom scheman båda är profilaktiverade och innehåller samma fältsökväg, försöker profilen sammanfoga dessa två fält till ett när man skapar unionsschemat. Eftersom olika datatyper inte kan sammanfogas skulle detta betraktas som en sammanslagningskonflikt och är inte tillåtet.

Du löser problemet genom att välja ett annat namn för fältet eller kapsla det under ett unikt namngivet objekt för att undvika sammanslagningskonflikter med andra profilaktiverade scheman under samma klass med liknande fält.