Guida alla risoluzione dei problemi del sistema XDM

Questo documento contiene le risposte alle domande più frequenti su Experience Data Model (XDM) e sul sistema XDM in Adobe Experience Platform, inclusa una guida alla risoluzione dei problemi relativi agli errori più comuni. Per domande e risoluzione dei problemi relativi ad altri servizi Platform, consulta la guida alla risoluzione dei problemi di Experience Platform.

Experience Data Model (XDM) è una specifica open-source che definisce schemi standardizzati per la gestione della customer experience. La metodologia su cui viene generato Experience Platform, il sistema XDM, rende operativi Experience Data Model schemi per l'utilizzo da parte dei servizi Platform. Schema Registry fornisce un'interfaccia utente e un'API RESTful per accedere a Schema Library entro Experience Platform. Per ulteriori informazioni, consulta la documentazione XDM.

Domande frequenti

Di seguito è riportato un elenco di risposte alle domande più frequenti sul sistema XDM e sull'utilizzo dell'API Schema Registry.

Come si aggiungono campi a uno schema?

È possibile aggiungere campi a uno schema utilizzando un gruppo di campi schema. Ogni gruppo di campi è compatibile con una o più classi, consentendo l'utilizzo del gruppo di campi in qualsiasi schema che implementa una di queste classi compatibili. Sebbene Adobe Experience Platform fornisca a diversi gruppi di campi del settore i propri campi predefiniti, è possibile aggiungere campi personalizzati a uno schema creando gruppi di campi personalizzati utilizzando l’API o l’interfaccia utente.

Per informazioni dettagliate sulla creazione di gruppi di campi nell'API Schema Registry, consulta la guida dell'endpoint del gruppo di campi. Se utilizzi l'interfaccia utente, consulta l'esercitazione sull'editor di schemi.

Quali sono gli utilizzi migliori per i gruppi di campi rispetto ai tipi di dati?

I gruppi di campi sono componenti che definiscono uno o più campi in uno schema. I gruppi di campi impongono il modo in cui i loro campi vengono visualizzati nella gerarchia dello schema e pertanto presentano la stessa struttura in ogni schema in cui sono inclusi. I gruppi di campi sono compatibili solo con classi specifiche, identificate dal relativo attributo meta:intendedToExtend.

I tipi di dati possono anche fornire uno o più campi per uno schema. Tuttavia, a differenza dei gruppi di campi, i tipi di dati non sono vincolati a una particolare classe. Questo rende i tipi di dati un’opzione più flessibile per descrivere strutture di dati comuni riutilizzabili in più schemi con classi potenzialmente diverse.

Qual è l’ID univoco di uno schema?

Tutte le risorse Schema Registry (schemi, gruppi di campi, tipi di dati, classi) hanno un URI che funge da ID univoco a scopo di riferimento e ricerca. Quando si visualizza uno schema nell'API, è possibile trovarlo negli attributi principali $id e meta:altId.

Per ulteriori informazioni, vedere la sezione identificazione risorsa nella guida dell'API Schema Registry.

Quando uno schema inizia a impedire l’interruzione delle modifiche?

È possibile apportare modifiche che causano interruzioni a uno schema se non è mai stato utilizzato nella creazione di un set di dati o abilitato per l'utilizzo in Real-Time Customer Profile. Una volta che uno schema è stato utilizzato nella creazione di set di dati o abilitato per l'utilizzo con Real-Time Customer Profile, le regole di Schema Evolution vengono rigorosamente applicate dal sistema.

Qual è la dimensione massima di un tipo di campo lungo?

Un tipo di campo lungo è un numero intero con una dimensione massima di 53 (+1) bit, che può essere compreso tra -9007199254740992 e 9007199254740992. Ciò è dovuto a una limitazione del modo in cui le implementazioni JavaScript di JSON rappresentano i numeri interi lunghi.

Per ulteriori informazioni sui tipi di campo, consulta il documento sui vincoli per i tipi di campo XDM.

Come posso definire le identità per il mio schema?

In Experience Platform, le identità vengono utilizzate per identificare un soggetto (in genere una singola persona) indipendentemente dalle origini dei dati interpretate. Vengono definiti negli schemi contrassegnando i campi chiave come "Identità". I campi comunemente utilizzati per l'identità includono l'indirizzo e-mail, il numero di telefono, Experience Cloud ID (ECID), l'ID del sistema di gestione delle relazioni con i clienti e altri campi ID univoci.

I campi possono essere contrassegnati come identità utilizzando l’API o l’interfaccia utente di.

Definizione delle identità nell’API

Nell’API, le identità vengono stabilite creando i descrittori di identità. I descrittori di identità segnalano che una particolare proprietà per uno schema è un identificatore univoco.

I descrittori di identità vengono creati da una richiesta POST all’endpoint /descriptors. In caso di esito positivo, riceverai un oggetto HTTP Status 201 (Creato) e un oggetto di risposta contenente i dettagli del nuovo descrittore.

Per ulteriori dettagli sulla creazione di descrittori di identità nell'API, consulta il documento sulla sezione descriptors nella guida per gli sviluppatori di Schema Registry.

Definizione delle identità nell’interfaccia utente

Con lo schema aperto nell'Editor schemi, seleziona il campo nella sezione Struttura dell'editor che desideri contrassegnare come identità. In Proprietà campo sul lato destro, selezionare la casella di controllo Identità.

Per ulteriori dettagli sulla gestione delle identità nell'interfaccia utente, vedere la sezione relativa alla definizione dei campi di identità nell'esercitazione sull'editor di schema.

Il mio schema richiede un’identità primaria?

Le identità primarie sono facoltative, poiché gli schemi possono avere zero o uno di essi. Tuttavia, uno schema deve avere un'identità primaria per poter essere abilitato per l'utilizzo in Real-Time Customer Profile. Per ulteriori informazioni, consulta la sezione identity dell'esercitazione sull'editor di schema.

Come si abilita uno schema da utilizzare in Real-Time Customer Profile?

Gli schemi sono abilitati per l'utilizzo in Real-Time Customer Profile tramite l'aggiunta di un tag "union" nell'attributo meta:immutableTags dello schema. L'abilitazione di uno schema per l'utilizzo con Profile può essere eseguita utilizzando l'API o l'interfaccia utente.

Abilitazione di uno schema esistente per Profile tramite l'API

Effettuare una richiesta PATCH per aggiornare lo schema e aggiungere l'attributo meta:immutableTags come array contenente il valore "union". Se l’aggiornamento ha esito positivo, la risposta mostrerà lo schema aggiornato che ora contiene il tag di unione.

Per ulteriori informazioni sull'utilizzo dell'API per abilitare uno schema da utilizzare in Real-Time Customer Profile, vedere il documento unions della Guida per gli sviluppatori di Schema Registry.

Abilitazione di uno schema esistente per Profile tramite l'interfaccia utente

In Experience Platform, selezionare Schemi nell'area di navigazione a sinistra e selezionare il nome dello schema che si desidera abilitare dall'elenco degli schemi. Quindi, sul lato destro dell'editor in Proprietà schema, seleziona Profilo per attivarlo.

Per ulteriori informazioni, vedere la sezione sull'utilizzo in Real-Time Customer Profile nell'esercitazione Schema Editor.

Posso modificare direttamente uno schema di unione?

Gli schemi di unione sono di sola lettura e vengono generati automaticamente dal sistema. Non possono essere modificati direttamente. Gli schemi di unione vengono creati per una classe specifica quando un tag "union" viene aggiunto allo schema che implementa tale classe.

Per ulteriori informazioni sulle unioni in XDM, consulta la sezione unioni nella guida dell'API Schema Registry.

Come posso formattare il file di dati per acquisire i dati nel mio schema?

Experience Platform accetta file di dati in formato Parquet o JSON. Il contenuto di questi file deve essere conforme allo schema a cui fa riferimento il set di dati. Per informazioni dettagliate sulle best practice per l'acquisizione dei file di dati, consulta la panoramica sull'acquisizione batch.

Errori e risoluzione problemi

Di seguito è riportato un elenco di messaggi di errore che è possibile visualizzare durante l'utilizzo dell'API Schema Registry.

Risorsa non trovata

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

Questo errore viene visualizzato quando il sistema non è riuscito a trovare una particolare risorsa. È possibile che la risorsa sia stata eliminata o che il percorso nella chiamata API non sia valido. Prima di riprovare, assicurati di aver inserito un percorso valido per la chiamata API. Puoi verificare di aver immesso l’ID corretto per la risorsa e che il percorso abbia un namespace corretto con il contenitore appropriato (globale o tenant).

Per ulteriori informazioni sulla costruzione dei percorsi di ricerca nell'API, vedere le sezioni container e resource identifier nella guida per gli sviluppatori Schema Registry.

Titolo non univoco

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

Questo messaggio di errore viene visualizzato quando si tenta di creare una risorsa con un titolo già utilizzato da un’altra risorsa. I titoli devono essere univoci per tutti i tipi di risorse. Ad esempio, se tenti di creare un gruppo di campi con un titolo già utilizzato da uno schema, riceverai questo errore.

Errore di convalida dello spazio dei nomi

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

Questo messaggio di errore viene visualizzato quando si tenta di creare una risorsa con campi con spazio dei nomi errato o di aggiungere campi con spazio dei nomi errato a una risorsa esistente.

Le risorse definite dall’organizzazione devono assegnare uno spazio dei nomi ai relativi campi sotto l’ID tenant, al fine di evitare conflitti con altre risorse del settore e del fornitore. Quando crei uno schema utilizzando gruppi di campi standard, anche tutti i campi personalizzati aggiunti all’interno della struttura di tali gruppi di campi devono avere lo spazio dei nomi sotto l’ID tenant.

Esempi dettagliati delle strutture di dati corrette per le risorse XDM sono disponibili nella guida dell’API del registro dello schema:

Intestazione Accept non valida

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

Le richieste GET nell'API Schema Registry richiedono un'intestazione Accept per poter determinare come formattare la risposta. Questo errore si verifica quando un'intestazione Accept richiesta non è valida o è mancante.

A seconda dell'endpoint utilizzato, la proprietà detailed-message indica l'aspetto di un'intestazione Accept valida per una risposta corretta. Verificare di aver immesso correttamente un'intestazione Accept compatibile con la richiesta API che si sta tentando di eseguire prima di riprovare.

Per gli elenchi di intestazioni compatibili di Accept per diverse richieste API, fare riferimento alle sezioni corrispondenti nella Guida per gli sviluppatori del registro dello schema.

Real-Time Customer Profile errori

I seguenti messaggi di errore sono associati alle operazioni necessarie per abilitare gli schemi per Real-Time Customer Profile. Per ulteriori informazioni, consulta la sezione unions nella guida dell'API Schema Registry.

Deve essere presente un descrittore di identità di riferimento

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

Questo messaggio di errore viene visualizzato quando si tenta di abilitare uno schema per Profile e una delle relative proprietà contiene un descrittore di relazione senza un descrittore di identità di riferimento. Per risolvere l’errore, aggiungi un descrittore di identità di riferimento al campo dello schema in questione.

Gli spazi dei nomi del campo del descrittore dell’identità di riferimento e dello schema di destinazione devono corrispondere

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

Per abilitare gli schemi che contengono descrittori di relazione da utilizzare in Profile, lo spazio dei nomi del campo di origine e lo spazio dei nomi primario del campo di riferimento devono essere uguali. Questo messaggio di errore viene visualizzato quando si tenta di abilitare uno schema che contiene uno spazio dei nomi senza corrispondenza per il relativo descrittore di identità di riferimento.

Per risolvere il problema, verificare che il valore xdm:namespace del campo di identità dello schema di riferimento corrisponda a quello della proprietà xdm:identityNamespace nel descrittore di identità di riferimento del campo di origine.

Per un elenco dei codici dello spazio dei nomi di identità standard, vedere la sezione relativa agli spazi dei nomi standard nella panoramica dello spazio dei nomi delle identità.

Lo schema deve includere un identityMap o un’identità primaria

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

Prima di abilitare uno schema per il profilo, devi creare un descrittore di identità primaria per lo schema oppure includere un campo di mappa identità per agire sull'identità primaria.

Impossibile unire tipi di dati non compatibili

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

Tutti gli schemi abilitati per il profilo appartenenti alla stessa classe devono essere in grado di unirsi per creare lo schema di unione per tale classe. Questo errore viene visualizzato quando si tenta di aggiungere un campo a uno schema il cui percorso è condiviso da un altro schema abilitato per il profilo e il tipo di dati è diverso da quello originale. Poiché gli schemi sono entrambi abilitati per il profilo e contengono lo stesso percorso di campo, Profile tenterà di unire questi due campi in uno durante la costruzione dello schema di unione. Poiché non è possibile unire diversi tipi di dati, questo viene considerato un conflitto di unione e non è consentito.

Per risolvere il problema, scegli un nome diverso per il campo o nidificalo in un oggetto con spazio dei nomi univoco al fine di evitare conflitti di unione con altri schemi abilitati per i profili nella stessa classe con campi simili.