DocumentazioneExperience PlatformGuida di Experience Data Model (XDM)

Appendice alla guida API del registro dello schema

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Argomenti:

Creato per:

  • Sviluppatore

Questo documento fornisce informazioni supplementari relative all'utilizzo dell'API Schema Registry.

Utilizzo dei parametri di query query

Schema Registry supporta l'utilizzo di parametri di query per la pagina e il filtro dei risultati quando si elencano le risorse.

NOTE
Quando si combinano più parametri di query, è necessario separarli con il simbolo di E commerciale (&).

Paging paging

I parametri di query più comuni per il paging includono:

Parametro
Descrizione
orderby
Ordinare i risultati per una proprietà specifica. Esempio: orderby=title ordinerà i risultati per titolo in ordine crescente (A-Z). L'aggiunta di un - prima del valore del parametro (orderby=-title) ordinerà gli elementi in base al titolo in ordine decrescente (Z-A).
limit
Se utilizzato insieme a un parametro orderby, limit limita il numero massimo di elementi da restituire per una determinata richiesta. Impossibile utilizzare questo parametro senza un parametro orderby.

Il parametro limit specifica un numero intero positivo (tra 0 e 500) come suggerimento per il numero massimo di elementi da restituire. Ad esempio, limit=5 restituisce solo cinque risorse nell'elenco. Tuttavia, questo valore non viene rispettato rigorosamente. La dimensione effettiva della risposta può essere minore o maggiore, in base alla necessità di fornire il funzionamento affidabile del parametro start, se fornito.
start
Se utilizzato insieme a un parametro orderby, start specifica da dove deve iniziare l'elenco di elementi sottoimpostato. Impossibile utilizzare questo parametro senza un parametro orderby. Questo valore può essere ottenuto dall'attributo _page.next di una risposta elenco e utilizzato per accedere alla pagina successiva dei risultati. Se il valore _page.next è null, non è disponibile alcuna pagina aggiuntiva.

Questo parametro viene in genere omesso per ottenere la prima pagina di risultati. Successivamente, start deve essere impostato sul valore massimo della proprietà di ordinamento primaria del campo orderby ricevuto nella pagina precedente. La risposta API restituisce quindi le voci che iniziano con quelle che hanno una proprietà di ordinamento primaria da orderby rigorosamente maggiore (per crescente) o minore (per decrescente) del valore specificato.

Ad esempio, se il parametro orderby è impostato su orderby=name,firstname, il parametro start conterrà un valore per la proprietà name. In questo caso, se desideri visualizzare le prossime 20 voci di una risorsa subito dopo il nome "Miller", utilizza: ?orderby=name,firstname&start=Miller&limit=20.

Filtro filtering

È possibile filtrare i risultati utilizzando il parametro property, utilizzato per applicare un operatore specifico a una determinata proprietà JSON nelle risorse recuperate. Gli operatori supportati includono:

Operatore
Descrizione
Esempio
==
Filtra in base al fatto che la proprietà sia uguale al valore specificato.
property=title==test
!=
Filtra in base al fatto che la proprietà non sia uguale al valore specificato.
property=title!=test
<
Filtra in base al fatto che la proprietà sia minore del valore specificato.
property=version<5
>
Filtra in base al fatto che la proprietà sia maggiore del valore specificato.
property=version>5
<=
Filtra in base al fatto che la proprietà sia minore o uguale al valore specificato.
property=version<=5
>=
Filtra in base al fatto che la proprietà sia maggiore o uguale al valore specificato.
property=version>=5
(Nessuno)
L'indicazione solo del nome della proprietà restituisce solo le voci in cui la proprietà esiste.
property=title
TIP
È possibile utilizzare il parametro property per filtrare i gruppi di campi dello schema in base alla classe compatibile. Ad esempio, property=meta:intendedToExtend==https://ns.adobe.com/xdm/context/profile restituisce solo i gruppi di campi compatibili con la classe XDM Individual Profile.

Modalità di compatibilità compatibility

Experience Data Model (XDM) è una specifica pubblicamente documentata, guidata da Adobe per migliorare l'interoperabilità, l'espressività e la potenza delle esperienze digitali. Adobe mantiene il codice sorgente e le definizioni XDM formali in un progetto open source su GitHub. Queste definizioni sono scritte in Notazione standard XDM, utilizzando JSON-LD (JavaScript Object Notation for Linked Data) e lo schema JSON come grammatica per la definizione degli schemi XDM.

Quando esamini le definizioni XDM formali nell’archivio pubblico, puoi notare che XDM standard è diverso da quello visualizzato in Adobe Experience Platform. Ciò che visualizzi in Experience Platform è chiamato Modalità di compatibilità e fornisce una semplice mappatura tra XDM standard e il modo in cui viene utilizzato in Platform.

Funzionamento della modalità di compatibilità

La modalità di compatibilità consente al modello XDM JSON-LD di funzionare con l’infrastruttura dati esistente alterando i valori all’interno di XDM standard mantenendo la stessa semantica. Utilizza una struttura JSON nidificata, che mostra gli schemi in un formato ad albero.

La differenza principale che noterai tra XDM standard e la modalità di compatibilità è la rimozione del prefisso "xdm:" per i nomi di campo.

Di seguito è riportato un confronto affiancato che mostra i campi relativi al compleanno (con gli attributi "description" rimossi) sia in XDM standard che in Modalità compatibilità. I campi Modalità di compatibilità includono un riferimento al campo XDM e al relativo tipo di dati negli attributi "meta:xdmField" e "meta:xdmType".

XDM standard
Modalità di compatibilità
{
  "xdm:bornDate": {
    "title": "Data di nascita",
    "type": "string",
    "format": "date"
  },
  "xdm:bornDayAndMonth": {
    "title": "Data di nascita",
    "type": "string",
    "pattern": "[0-1][0-9]-[0-9][0-9]"
  },
  "xdm:bornYear": {
    "title": "Anno di nascita",
    "type": "integer",
    "minimum": 1
    "maximum": 32767
  }
}


{
  "bornDate": {
    "title": "Data di nascita",
    "type": "string",
    "format": "date",
    "meta:xdmField": "xdm:bornDate",
    "meta:xdmType": "date"
  },
  "bornDayAndMonth": {
    "title": "Data di nascita",
    "type": "string",
    "pattern": "[0-1][0-9]-[0-9][0-9]",
    "meta:xdmField": "xdm:bornDayAndMonth",
    "meta:xdmType": "string"
  },
  "bornYear": {
    "title": "Anno di nascita",
    "type": "integer",
    "minimum": 1
    "maximum": 32767,
    "meta:xdmField": "xdm:bornYear",
    "meta:xdmType": "short"
  }
}

Perché è necessaria la modalità di compatibilità?

Adobe Experience Platform è progettato per lavorare con più soluzioni e servizi, ciascuno con le proprie sfide e limitazioni tecniche (ad esempio, il modo in cui alcune tecnologie gestiscono i caratteri speciali). Per superare queste limitazioni, è stata sviluppata la Modalità di compatibilità.

La maggior parte dei servizi Experience Platform, tra cui Catalog, Data Lake e Real-Time Customer Profile, utilizza Compatibility Mode al posto di XDM standard. Anche l'API Schema Registry utilizza Compatibility Mode e gli esempi in questo documento sono tutti visualizzati utilizzando Compatibility Mode.

È utile sapere che viene eseguita una mappatura tra XDM standard e il modo in cui è operazionalizzato in Experience Platform, ma non dovrebbe influire sull'utilizzo dei servizi Platform.

Il progetto open source è disponibile, ma quando si tratta di interagire con le risorse tramite Schema Registry, gli esempi di API in questo documento forniscono le best practice da conoscere e seguire.

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07