Handleiding voor probleemoplossing voor XDM-systemen

Dit document bevat antwoorden op veelgestelde vragen over Experience Data Model (XDM) en XDM System in Adobe Experience Platform, waaronder een gids voor probleemoplossing voor algemene fouten. Voor vragen en het oplossen van problemen met betrekking tot andere diensten van het Platform, gelieve te verwijzen naar de gids van het oplossen van problemenprobleem van de Experience Platform.

Experience Data Model (XDM) is een open-bronspecificatie die gestandaardiseerde schema's voor het beheer van de klantenervaring bepaalt. De methodologie waarop Experience Platform wordt gebouwd, XDM Systeem, exploiteert Experience Data Model schema's voor gebruik door Platform diensten. De Schema Registry biedt een gebruikersinterface en een RESTful-API voor toegang tot de Schema Library within Experience Platform -API. Zie de documentatie XDMvoor meer informatie.

Veelgestelde vragen

Hieronder volgt een lijst met antwoorden op veelgestelde vragen over XDM System en het gebruik van de Schema Registry API.

Basisbeginselen van schema

In deze sectie vindt u antwoorden op fundamentele vragen over schemastructuur, veldgebruik en identificatie in het XDM-systeem.

Hoe voeg ik velden toe aan een schema?

U kunt velden aan een schema toevoegen met een schemaveldgroep. Elke veldgroep is compatibel met een of meer klassen, zodat de veldgroep kan worden gebruikt in elk schema dat een van die compatibele klassen implementeert. Hoewel Adobe Experience Platform verschillende industrieveldgroepen hun eigen vooraf gedefinieerde velden biedt, kunt u uw eigen velden aan een schema toevoegen door aangepaste veldgroepen te maken met behulp van de API of de gebruikersinterface.

Voor details bij het creëren van gebiedsgroepen in Schema Registry API, zie de gids van het het eindpunt van de gebiedsgroep. Als u UI gebruikt, zie het leerprogramma van de Redacteur van het Schema.

Wat zijn de beste toepassingen voor veldgroepen versus gegevenstypen?

de groepen van het Gebiedzijn componenten die één of meerdere gebieden in een schema bepalen. Veldgroepen dwingen af hoe hun velden worden weergegeven in de hiërarchie van het schema en tonen daarom in elk schema dezelfde structuur aan waarin ze zijn opgenomen. Veldgroepen zijn alleen compatibel met specifieke klassen, zoals bepaald door het kenmerk meta:intendedToExtend ervan.

de types van Gegevenskunnen één of meerdere gebieden voor een schema ook verstrekken. In tegenstelling tot veldgroepen worden gegevenstypen echter niet beperkt tot een bepaalde klasse. Dit maakt gegevenstypes een flexibelere optie om gemeenschappelijke gegevensstructuren te beschrijven die over veelvoudige schema's met potentieel verschillende klassen herbruikbaar zijn.

Wat is unieke identiteitskaart voor een schema?

Alle Schema Registry -bronnen (schema's, veldgroepen, gegevenstypen, klassen) hebben een URI die fungeert als unieke id voor referentie- en opzoekdoeleinden. Wanneer u een schema in de API weergeeft, vindt u dit in de kenmerken $id en meta:altId op hoofdniveau.

Voor meer informatie, zie de middelidentificatiesectie in de Schema Registry API gids.

Wat is de maximumgrootte van een lang gebiedstype?

Een lang veldtype is een geheel getal met een maximale grootte van 53(+1) bits, waardoor het een mogelijk bereik heeft tussen -9007199254740992 en 900719925474092. Dit is te wijten aan een beperking van de manier waarop JavaScript-implementaties van JSON lange gehele getallen vertegenwoordigen.

Voor meer informatie over gebiedstypes, zie het document op XDM gebied typegrenzen.

Wat is meta:AltId?

meta:altId is een unieke id voor een schema. meta:altId verstrekt gemakkelijk om identiteitskaart voor gebruik in API vraag van verwijzingen te voorzien. Met deze id vermijdt u dat deze telkens moet worden gecodeerd/gedecodeerd als deze wordt gebruikt, net als bij de JSON URI-indeling.

Wat zijn de gebruiksbeperkingen voor een gegevenstype van een kaart?

XDM plaatst de volgende beperkingen op het gebruik van dit gegevenstype:

Zie de gebruiksbeperkingen voor kaartvoorwerpenvoor meer details.

Schema Identity Management

Deze sectie bevat antwoorden op veelgestelde vragen over het definiëren en beheren van identiteiten binnen uw schema's.

Hoe definieer ik identiteiten voor mijn schema?

In Experience Platform worden identiteiten gebruikt om een onderwerp (doorgaans een individuele persoon) te identificeren, ongeacht de bronnen van gegevens die worden geïnterpreteerd. Ze worden in schema's gedefinieerd door de sleutelvelden als "Identiteit" te markeren. Veelgebruikte gebieden voor identiteit omvatten e-mailadres, telefoonaantal, Experience Cloud ID (ECID), identiteitskaart van CRM, en andere unieke gebieden van identiteitskaart

Velden kunnen als id's worden gemarkeerd met de API of de gebruikersinterface.

Identiteiten definiëren in de API

In de API worden identiteiten vastgesteld door identiteitsbeschrijvers te maken. Identiteitsbeschrijvers geven aan dat een bepaalde eigenschap voor een schema een unieke id is.

De beschrijvers van de identiteit worden gecreeerd door een verzoek van de POST aan het /descriptors eindpunt. Als dit lukt, ontvangt u een HTTP Status 201 (Gemaakt) en een reactieobject met de details van de nieuwe descriptor.

Voor meer details bij het creëren van identiteitsbeschrijvers in API, zie het document op beschrijverssectie in de Schema Registry ontwikkelaarsgids.

Identiteiten definiëren in de gebruikersinterface

Open het schema in de Schema-editor en selecteer het veld in de sectie Structure van de editor dat u als identiteit wilt markeren. Selecteer onder Field Properties aan de rechterkant het selectievakje Identity .

Voor meer details bij het beheren van identiteiten in UI, zie de sectie over het bepalen van identiteitsgebiedensectie in het leerprogramma van de Redacteur van het Schema.

Heeft mijn schema een primaire identiteit nodig?

Primaire identiteiten zijn optioneel, omdat schema's ofwel nul ofwel één ervan kunnen hebben. Een schema moet echter een primaire identiteit hebben voordat het schema kan worden ingeschakeld voor gebruik in Real-Time Customer Profile . Zie de identiteitsectie van het leerprogramma van de Redacteur van het Schema voor meer informatie.

Schema profiel inschakelen

Deze sectie verstrekt begeleiding bij het toelaten van schema's voor gebruik met het Profiel van de Klant in real time.

Hoe kan ik een schema inschakelen voor gebruik in Real-Time Customer Profile?

Schema's kunnen in Real-Time Customer Profile worden gebruikt door een tag "union" toe te voegen binnen het kenmerk meta:immutableTags van het schema. U kunt een schema inschakelen voor gebruik met Profile via de API of de gebruikersinterface.

Een bestaand schema voor Profile inschakelen met de API

Voer een PATCH-verzoek in om het schema bij te werken en het kenmerk meta:immutableTags toe te voegen als een array met de waarde "union". Als de update succesvol is, zal de reactie het bijgewerkte schema tonen dat nu de verenigingsmarkering bevat.

Voor meer informatie bij het gebruiken van API om een schema voor gebruik in Real-Time Customer Profile toe te laten, zie het vakbondendocument van de Schema Registry ontwikkelaarsgids.

Bezig met inschakelen van een bestaand schema voor Profile via de gebruikersinterface

Selecteer Schemas in Experience Platform in de linkernavigatie en selecteer in de lijst met schema's de naam van het schema dat u wilt inschakelen. Selecteer vervolgens aan de rechterkant van de editor onder Schema Properties de optie Profile om deze in of uit te schakelen.

Voor meer informatie, zie de sectie over gebruik in het Profiel van de Klant in real timein het Schema Editor leerprogramma.

Wanneer Adobe Analytics-gegevens als bron worden geïmporteerd, wordt het automatisch gemaakte schema ingeschakeld voor Profiel?

Het schema wordt niet automatisch toegelaten voor het Profiel van de Klant in real time. U moet uitdrukkelijk de dataset voor Profiel toelaten dat wordt gebaseerd op welk schema voor Profiel wordt toegelaten. Zie de documentatie om de stappen en vereisten te leren nodig om een dataset voor gebruik in het Profiel van de Klant in real timetoe te laten.

Kan ik profiel-toegelaten schema's schrappen?

U kunt geen schema schrappen nadat het voor het Profiel van de Klant in real time is toegelaten. Als een schema eenmaal is ingeschakeld voor Profiel, kan het niet worden uitgeschakeld of verwijderd en kunnen velden niet uit het schema worden verwijderd. Daarom is het essentieel om de schemaconfiguratie zorgvuldig te plannen en te verifiëren alvorens het voor Profiel toe te laten. U kunt een profiel-Toegelaten dataset echter schrappen. Hier vindt u informatie: https://experienceleague.adobe.com/nl/docs/experience-platform/catalog/datasets/user-guide#delete-a-profile-enabled-dataset

Wijziging en beperkingen van het schema

Deze sectie verstrekt verduidelijkingen over de regels van de schemawijziging en de preventie van het breken van veranderingen.

Wanneer begint een schema het breken van veranderingen te verhinderen?

Er kunnen verbluffende wijzigingen in een schema worden aangebracht zolang het schema nog nooit is gebruikt bij het maken van een gegevensset of is ingeschakeld voor gebruik in Real-Time Customer Profile . Zodra een schema in datasetverwezenlijking of toegelaten voor gebruik met Real-Time Customer Profile is gebruikt, worden de regels van Evolutie van het Schemastrikt afgedwongen door het systeem.

Kan ik een samenvoegingsschema direct uitgeven?

Unieschema's zijn alleen-lezen en worden automatisch gegenereerd door het systeem. Ze kunnen niet rechtstreeks worden bewerkt. Unieschema's worden voor een specifieke klasse gemaakt wanneer een tag union wordt toegevoegd aan een schema dat die klasse implementeert.

Voor meer informatie over unies in XDM, zie de vakbondensectie in de Schema Registry API gids.

Hoe moet ik mijn gegevensbestand formatteren om gegevens in mijn schema in te voeren?

Experience Platform accepteert gegevensbestanden in Parquet - of JSON-indeling. De inhoud van deze dossiers moet met het schema in overeenstemming zijn dat door de dataset van verwijzingen wordt voorzien. Voor details over beste praktijken voor datafile ingestie, zie het overzicht van partijingestitie.

Hoe kan ik een schema in een read-only schema omzetten?

U kunt een schema momenteel niet omzetten in alleen-lezen.

Fouten en problemen oplossen

Hieronder volgt een lijst met foutberichten die kunnen optreden wanneer u werkt met de API van Schema Registry .

Bron niet gevonden

{
    "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."
}

Deze fout wordt weergegeven wanneer het systeem een bepaalde bron niet kan vinden. De bron kan zijn verwijderd of het pad in de API-aanroep is ongeldig. Controleer of u een geldig pad voor uw API-aanroep hebt ingevoerd voordat u het opnieuw probeert. U kunt willen controleren dat u correcte identiteitskaart voor het middel bent ingegaan, en dat de weg behoorlijk genoemd met de aangewezen container (globaal of huurder) is.

Voor meer informatie bij het construeren van raadplegingswegen in API, zie de containeren middelidentificatiesecties in de Schema Registry ontwikkelaarsgids.

Titel is niet uniek

{
    "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"
}

Dit foutbericht wordt weergegeven wanneer u een bron probeert te maken met een titel die al door een andere bron wordt gebruikt. Titels moeten uniek zijn voor alle typen bronnen. Als u bijvoorbeeld een veldgroep probeert te maken met een titel die al wordt gebruikt door een schema, ontvangt u deze fout.

Validatiefout naamruimte

{
    "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}."
}

Dit foutbericht wordt weergegeven wanneer u een bron probeert te maken met velden met een onjuiste naam of wanneer u onjuist benoemde velden toevoegt aan een bestaande bron.

De middelen die door uw organisatie worden bepaald moeten hun gebieden onder uw huurdersidentiteitskaart namespace om conflicten met andere industrie en verkopersmiddelen te vermijden. Wanneer het bouwen van een schema gebruikend standaardgebiedsgroepen, om het even welke douanevelden die u binnen de structuur van die gebiedsgroepen toevoegt moeten ook namespaced onder uw huurdersidentiteitskaart zijn.

Gedetailleerde voorbeelden van juiste gegevensstructuren voor XDM-bronnen vindt u in de handleiding Schema Registry API:

Koptekst accepteren is ongeldig

{
    "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"
}

Voor GET-aanvragen in de Schema Registry API is een Accept -header vereist, zodat het systeem kan bepalen hoe de reactie moet worden opgemaakt. Deze fout treedt op wanneer een vereiste Accept -koptekst ongeldig is of ontbreekt.

Afhankelijk van het eindpunt dat u gebruikt, geeft de eigenschap detailed-message aan hoe een geldige Accept -header eruit moet zien voor een geslaagde reactie. Controleer of u een Accept -header correct hebt ingevoerd die compatibel is met de API-aanvraag die u wilt uitvoeren voordat u het opnieuw probeert.

Voor lijsten van compatibele Accepteer kopballen voor verschillende API verzoeken, gelieve naar hun overeenkomstige secties in de de ontwikkelaarsgids van de Registratie van het Schemate verwijzen.

Real-Time Customer Profile fouten

De volgende foutberichten zijn gekoppeld aan bewerkingen die van invloed zijn op het inschakelen van schema's voor Real-Time Customer Profile . Zie de vakbondensectie in de Schema Registry API gids voor meer informatie.

Er moet een identiteitsbeschrijving voor verwijzingen zijn

{
    "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."
}

Dit foutbericht wordt weergegeven wanneer u een schema voor Profile probeert in te schakelen en een van de eigenschappen een relatiebeschrijving zonder een verwijzings-id-descriptor bevat. Voeg een beschrijver van de verwijzingsIdentiteit aan het schemagebied in kwestie toe om deze fout op te lossen.

De naamruimten van het beschrijvingsveld voor de referentie-id en het doelschema moeten overeenkomen

{
    "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 schema's in te schakelen die relatiebeschrijvers voor gebruik in Profile bevatten, moeten de naamruimte van het bronveld en de primaire naamruimte van het verwijzingsveld gelijk zijn. Dit foutbericht wordt weergegeven wanneer u een schema wilt inschakelen dat een naamruimte zonder overeenkomst bevat voor de verwijzingsidentiteitsbeschrijving.

Zorg ervoor dat de xdm:namespace -waarde van het identiteitsveld van het referentieschema overeenkomt met die van de xdm:identityNamespace -eigenschap in het identiteitsbeschrijvingsbestand van het bronveld om dit probleem op te lossen.

Voor een lijst van standaardidentiteitsnamespacecodes, zie de sectie op standaard namespacesin het overzicht van identiteitsnaamruimte.

Het schema moet een identityMap of primaire identiteit bevatten

{
    "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."
}

Alvorens een schema voor Profiel toe te laten, moet u eerst een primaire identiteitsbeschrijvervoor het schema creëren, of een gebied van de identiteitskaart omvatten om bij de primaire identiteit in plaats daarvan te handelen.

Kan incompatibele gegevenstypen niet samenvoegen

{
    "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"
}

Alle profiel-toegelaten schema's die tot de zelfde klasse behoren moeten samen kunnen samenvoegen om het verenigingsschema voor die klasse te construeren. Deze fout verschijnt wanneer u een gebied aan een schema probeert toe te voegen de waarvan weg door een ander profiel-toegelaten schema wordt gedeeld en het gegevenstype verschillend is dan origineel. Aangezien de schema's zowel profiel-toegelaten zijn als het zelfde gebiedspad bevatten, zou het Profiel proberen om deze twee gebieden in één samen te voegen wanneer het construeren van het verenigingsschema. Omdat verschillende gegevenstypen niet samen kunnen worden samengevoegd, wordt dit beschouwd als een samenvoegconflict en is dit niet toegestaan.

U lost het probleem op door een andere naam voor het veld te kiezen of het onder een uniek, naamloos object te nesten om samenvoegconflicten met andere, voor profiel geschikte schema's onder dezelfde klasse met vergelijkbare velden te voorkomen.