Show Menu
ARGOMENTI×

Guida alla risoluzione dei problemi del sistema XDM (Experience Data Model)

Questo documento contiene le risposte alle domande frequenti sul sistema Experience Data Model (XDM) e una guida alla risoluzione dei problemi per individuare gli errori più comuni. Per domande e risoluzione dei problemi relativi ad altri servizi in Adobe Experience Platform, consulta la guida alla risoluzione dei problemi per la piattaforma Experience.
Experience Data Model (XDM) è una specifica open-source che definisce schemi standardizzati per la gestione dell'esperienza cliente. La metodologia su cui è basata Experience Platform, XDM System , rende operativi gli schemi di Experience Data Model per l'utilizzo da parte dei servizi della piattaforma. Il Registro di schema fornisce un'interfaccia utente e un'API RESTful per accedere alla libreria ​Schema all'interno di Experience Platform. See the XDM documentation for more information.

Domande frequenti

Di seguito è riportato un elenco di risposte alle domande frequenti sul sistema XDM e sull'utilizzo dell'API del Registro di sistema dello schema.

Come si aggiungono i campi a uno schema?

È possibile aggiungere campi a uno schema utilizzando un mixin. Ciascun mixin è compatibile con una o più classi, consentendo l'utilizzo del mixin in qualsiasi schema che implementa una di queste classi compatibili. Adobe Experience Platform offre diversi mixin di settore con campi predefiniti, ma puoi aggiungere i tuoi campi a uno schema creando nuovi mixin tramite l'API o l'interfaccia utente.
Per informazioni dettagliate sulla creazione di nuovi mixin nell'API, consultate creare un documento mixin nella guida per gli sviluppatori di API del Registro di sistema dello schema. Se si utilizza l'interfaccia utente, vedere l'esercitazione Editor schema.

Quali sono gli usi migliori per i mixin rispetto ai tipi di dati?

Le miscele sono componenti che definiscono uno o più campi in uno schema. I mixin applicano la modalità di visualizzazione dei campi nella gerarchia dello schema, mostrando quindi la stessa struttura in ogni schema in cui sono inclusi. Le miscele sono compatibili solo con classi specifiche, identificate dal relativo meta:intendedToExtend attributo.
I tipi di dati possono anche fornire uno o più campi per uno schema. Tuttavia, a differenza dei mixin, i tipi di dati non sono vincolati a una determinata classe. Questo rende i tipi di dati un'opzione più flessibile per descrivere le strutture di dati comuni riutilizzabili tra più schemi con classi potenzialmente diverse.

Qual è l'ID univoco per uno schema?

Tutte le risorse del Registro di sistema dello schema (schemi, mixin, tipi di dati, classi) dispongono di un URI che funge da ID univoco a scopo di riferimento e di ricerca. Quando si visualizza uno schema nell'API, questo si trova negli attributi $id e meta:altId di livello principale.
Per ulteriori informazioni, vedere la sezione Identificazione dello schema nella guida per gli sviluppatori API del Registro di sistema dello schema.

Quando inizia uno schema per impedire l'interruzione delle modifiche?

È possibile apportare modifiche allo schema a condizione che non sia mai stato utilizzato nella creazione di un dataset o sia abilitato per l'uso nel profilo cliente in tempo reale. Una volta che uno schema è stato utilizzato nella creazione del set di dati o abilitato per l'uso con il profilo cliente in tempo reale, le regole di Evoluzione Principi di evoluzione dello schema schema vengono applicate in modo rigoroso 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, il cui intervallo potrebbe essere compreso tra -9007199254740992 e 9007199254740992. Ciò è dovuto a una limitazione del modo in cui le implementazioni JavaScript di JSON rappresentano numeri interi lunghi.
Per ulteriori informazioni sui tipi di campo, vedere la sezione Definizione dei tipi di campo XDM nella guida per gli sviluppatori API del Registro di sistema dello schema.

Come si definiscono le identità per lo schema?

In Experience Platform, le identità vengono utilizzate per identificare un oggetto (in genere una singola persona) indipendentemente dalle origini dei dati che vengono interpretate. Sono definiti negli schemi contrassegnando i campi chiave come "Identità". I campi comunemente utilizzati per l'identità includono indirizzo e-mail, numero di telefono, ID Experience Cloud (ECID) , ID CRM e altri campi ID univoci.
I campi possono essere contrassegnati come identità tramite l'API o l'interfaccia utente.

Definizione delle identità nell'API

Nell'API, le identità vengono stabilite creando descrittori di identità. I descrittori di identità indicano 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, riceverete uno stato HTTP 201 (Creato) e un oggetto di risposta contenente i dettagli del nuovo descrittore.
Per ulteriori dettagli sulla creazione di descrittori di identità nell'API, vedere il documento nella sezione descrittori nella guida per gli sviluppatori del Registro di sistema dello schema.

Definizione delle identità nell’interfaccia utente

Con lo schema aperto nell'Editor schema, fare clic sul campo nella sezione Struttura dell'editor che si desidera contrassegnare come identità. In Proprietà ​campo a destra, fare clic sulla casella di controllo Identità .
Per ulteriori dettagli sulla gestione delle identità nell'interfaccia utente, vedere la sezione sulla definizione dei campi di identità nell'esercitazione Editor di schema.

Lo schema deve avere un'identità primaria?

Le identità principali sono facoltative, poiché gli schemi possono avere 0 o 1 di essi. Tuttavia, uno schema deve avere un'identità primaria affinché lo schema sia abilitato per l'uso nel profilo cliente in tempo reale. Per ulteriori informazioni, vedere la sezione identità dell'esercitazione Editor di schema.

Come si attiva uno schema da utilizzare nel profilo cliente in tempo reale?

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

Abilitazione di uno schema esistente per il profilo tramite l'API

Eseguite una richiesta PATCH per aggiornare lo schema e aggiungere l' meta:immutableTags attributo come array contenente il valore "union". Se l'aggiornamento ha esito positivo, la risposta mostrerà lo schema aggiornato che ora contiene il tag unione.
Per ulteriori informazioni sull'utilizzo dell'API per abilitare uno schema da utilizzare nel profilo cliente in tempo reale, vedere il documento sindacati della guida per gli sviluppatori del Registro di schema.

Abilitazione di uno schema esistente per il profilo tramite l'interfaccia utente

In Experience Platform, fai clic su Schemi nella navigazione a sinistra, quindi seleziona il nome dello schema che desideri abilitare dall'elenco degli schemi. Quindi, sul lato destro dell'editor in Proprietà ​schema, fare clic su Profilo per attivarlo.
Per ulteriori informazioni, vedere la sezione sull' utilizzo in Real-time Customer Profile (Profilocliente in tempo reale) nell'esercitazione dell'Editor di schema.

Posso modificare direttamente uno schema di unione?

Gli schemi unione sono di sola lettura e vengono generati automaticamente dal sistema. Non possono essere modificati direttamente. Gli schemi unione vengono creati per una classe specifica quando viene aggiunto un tag "unione" allo schema che implementa tale classe.
Per ulteriori informazioni sulle unioni in XDM, vedere la sezione unioni nella guida per gli sviluppatori API del Registro di sistema dello schema.

Come si formatta il file di dati per inserire i dati nello 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 dataset. Per informazioni dettagliate sulle procedure ottimali per l'assimilazione dei file di dati, consultate la panoramica sull'assimilazione dei batch.

Errori e risoluzione dei problemi

Di seguito è riportato un elenco di messaggi di errore che possono verificarsi durante l'utilizzo dell'API del Registro di sistema dello schema.

Oggetto non trovato

{
    "type": "/placeholder/type/uri",
    "status": 404,
    "title": "NotFoundError",
    "detail": "Object https://ns.adobe.com/incorrectTenantId/schemas/ee067e31b08514d21e2b82577813409d 
      with version 1 not found"
}

Questo errore viene visualizzato quando il sistema non è in grado di trovare una risorsa specifica. La risorsa potrebbe essere stata eliminata oppure il percorso nella chiamata API non è valido. Prima di riprovare, verifica di aver immesso un percorso valido per la chiamata API. È possibile verificare di aver immesso l'ID corretto per la risorsa e che il percorso sia correttamente associato al contenitore appropriato (globale o tenant).
Per ulteriori informazioni sulla creazione di percorsi di ricerca nell'API, vedere le sezioni relative al contenitore e all'identificazione dello schema nella guida per gli sviluppatori del Registro di schema.

Il titolo deve essere univoco

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "Title must be unique. An object 
      https://ns.adobe.com/{TENANT_ID}/schemas/26f6833e55db1dd8308aa07a64f2042d 
      already exists with the same title."
}

Questo messaggio di errore viene visualizzato quando tentate 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 si tenta di creare un mixin con un titolo già utilizzato da uno schema, si verificherà questo errore.

I campi personalizzati devono utilizzare un campo di primo livello

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For custom fields, you must use a top level field named _{TENANT_ID}
       and all the other fields must be defined under it"
}

Questo messaggio di errore viene visualizzato quando tentate di creare un nuovo mixin con campi con nome non corretto. Le miscele definite dall'organizzazione IMS devono assegnare ai propri campi uno spazio dei nomi con un TENANT_ID per evitare conflitti con altre risorse del settore e del fornitore. Esempi dettagliati di strutture dati corrette per i mixin sono disponibili nel documento sulla creazione di una sezione mixin nella guida per gli sviluppatori di API del Registro di sistema dello schema.

Errori di profilo cliente in tempo reale

I messaggi di errore riportati di seguito sono associati alle operazioni di abilitazione degli schemi per il profilo cliente in tempo reale. Per ulteriori informazioni, consulta la sezione sindacati nella guida per gli sviluppatori API del Registro di sistema dello schema.

Per abilitare i set di dati del profilo, lo schema deve essere valido

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "To enable profile datasets the schema should be valid"
}

Questo messaggio di errore viene visualizzato quando si tenta di abilitare un dataset di profilo per uno schema che non è stato abilitato per il profilo cliente in tempo reale. Prima di abilitare il dataset, assicurarsi che lo schema contenga un tag di unione.

Deve essere presente un descrittore di identità di riferimento

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "For a schema to be able to participate in union, if any of its 
      property is associated with a xdm:descriptorOneToOne descriptor, there must 
      be a xdm:descriptorReferenceIdentity descriptor for that property"
}

Questo messaggio di errore viene visualizzato quando si tenta di abilitare uno schema per il profilo e una delle sue proprietà contiene un descrittore di relazione senza un descrittore di identità di riferimento. Aggiungete un descrittore di identità di riferimento al campo dello schema in questione per risolvere l'errore.

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

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "If both schemas from an already defined xdm:descriptorOneToOne 
      descriptor are promoted to union, and if there is a primary identity on one of 
      the schemas from the xdm:descriptorOneToOne descriptor, the 
      xdm:identityNamespace of the sourceSchema's descriptorReferenceIdentity and the 
      xdm:namespace field of the xdm:descriptorIdentity for the destinationSchema must 
      match"
}

Per abilitare gli schemi che contengono descrittori di relazione da utilizzare in Profile, lo spazio nomi del campo di origine e dello spazio dei nomi primario del campo di destinazione deve essere lo stesso. Questo messaggio di errore viene visualizzato quando si tenta di abilitare uno schema che contiene uno spazio nomi non corrispondente per il relativo descrittore di identità di riferimento. Per risolvere il problema, assicurarsi che il xdm:namespace valore del campo identità dello schema di destinazione corrisponda a quello della xdm:identityNamespace proprietà nel descrittore dell'identità di riferimento del campo di origine.
Per un elenco dei codici dei namespace di identità supportati, consultate la sezione sugli spazi dei nomi standard nella panoramica dello spazio dei nomi di identità.

Accetta errori di intestazione

La maggior parte delle richieste GET nell'API del Registro di sistema dello schema richiede un'intestazione Accetto per consentire al sistema di determinare come formattare la risposta. Di seguito è riportato un elenco di errori comuni associati all'intestazione Accetto. Per gli elenchi delle intestazioni Accetta compatibili per diverse richieste API, fare riferimento alle sezioni corrispondenti nella guida per gli sviluppatori del Registro di schema.

Il parametro di intestazione Accetta è obbligatorio

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Accept header parameter is required"
}

Questo messaggio di errore viene visualizzato quando manca un'intestazione Accetto da una richiesta API. Prima di riprovare, verificate che sia inclusa un'intestazione Accetto.

Supporto di accettazione sconosciuto

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept media supplied: xed+json"
}

Questo messaggio di errore viene visualizzato quando un'intestazione Accetto non è valida. Assicuratevi di aver immesso correttamente un'intestazione Accetto compatibile con la richiesta API che state tentando di eseguire prima di riprovare.

Formato Accetta sconosciuto disponibile

{
    "type": "/placeholder/type/uri",
    "status": 406,
    "title": "NotAcceptableError",
    "detail": "Unknown Accept format available "
}

Questo messaggio di errore viene visualizzato quando l'intestazione Accetto è stata fornita in modo non corretto durante la ricerca di un descrittore. Prima di riprovare, assicurarsi di aver immesso correttamente una delle intestazioni Accetta supportate per i descrittori .

La versione deve essere fornita nell'intestazione Accetto

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full-notext+json; version=1"
}

Questo messaggio di errore viene visualizzato quando un numero di versione non è stato incluso nell'intestazione Accetto. Alcuni elementi come gli schemi richiedono che venga specificata una versione quando si ricercano singole istanze. Un'intestazione Accetta contenente un numero di versione avrà un aspetto simile al seguente:
application/vnd.adobe.xed+json; version=1

Per un elenco delle intestazioni Accetto supportate, vedere la sezione Accetta intestazione nella guida per gli sviluppatori del Registro di sistema dello schema.

La versione non deve essere specificata nell'intestazione Accetto

{
    "type": "/placeholder/type/uri",
    "status": 400,
    "title": "BadRequestError",
    "detail": "version must not be supplied in the accept header. Example: 
      application/vnd.adobe.xed-full+json"
}

Se tenti di includere una versione nell’intestazione Accetto durante l’elencazione delle risorse (GET), riceverai questo errore. Le versioni sono necessarie solo quando si tenta di eseguire una richiesta di ricerca su una singola risorsa. Rimuovere la versione dall'intestazione Accetto per risolvere l'errore.