Appendice della guida API del registro dello schema

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

Utilizzo dei parametri di query

Il Schema Registry supporta l’utilizzo di parametri di query per la pagina e filtrare i risultati durante l’elenco delle risorse.

NOTA

Quando si combinano più parametri di query, questi devono essere separati da e commerciali (&).

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). Se si aggiunge un - prima del valore del parametro (orderby=-title), gli elementi vengono ordinati per titolo in ordine decrescente (Z-A).
limit Se utilizzato insieme a un parametro orderby , limit limita il numero massimo di elementi che devono essere restituiti per una determinata richiesta. Questo parametro non può essere utilizzato senza un parametro orderby presente.

Il limit parametro specifica un numero intero positivo (tra 0 e 500) come ** hintas al numero massimo di elementi che devono essere restituiti. Ad esempio, limit=5 restituisce solo cinque risorse nell’elenco. Tuttavia, questo valore non è strettamente rispettato. La dimensione effettiva della risposta può essere inferiore 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 la posizione di inizio dell’elenco degli elementi impostato come secondario. Questo parametro non può essere utilizzato senza un parametro orderby presente. Questo valore può essere ottenuto dall'attributo _page.next di una risposta a elenco e utilizzato per accedere alla pagina successiva di risultati. Se il valore _page.next è null, non è disponibile alcuna pagina aggiuntiva.

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

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

Filtro

Puoi filtrare i risultati utilizzando il parametro property , utilizzato per applicare un operatore specifico a una determinata proprietà JSON all’interno delle risorse recuperate. Gli operatori supportati includono:

Operatore Descrizione Esempio
== Filtra in base al fatto che la proprietà sia uguale al valore fornito. property=title==test
!= Filtra in base al fatto che la proprietà non sia uguale al valore fornito. property=title!=test
< Filtra in base al fatto che la proprietà sia minore del valore specificato. property=version<5
> Filtra per determinare se la proprietà è maggiore del valore specificato. property=version>5
<= Filtra per specificare se la proprietà è minore o uguale al valore specificato. property=version<=5
>= Filtra per specificare se la proprietà è maggiore o uguale al valore specificato. property=version>=5
~ Filtra per stabilire se la proprietà corrisponde a un'espressione regolare specificata. property=title~test$
(Nessuna) Se si imposta solo il nome della proprietà, vengono restituite solo le voci in cui esiste la proprietà. property=title
SUGGERIMENTO

Puoi utilizzare il parametro property per filtrare i gruppi di campi dello schema in base alla relativa 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à

Experience Data Model (XDM) è una specifica documentata pubblicamente, spinta dall'Adobe per migliorare l'interoperabilità, l'espressività e il potere 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 e utilizzano JSON-LD (JavaScript Object Notation for Linked Data) e lo schema JSON come grammatica per la definizione degli schemi XDM.

Quando osservi 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 si chiama 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 di dati esistente modificando i valori all’interno di XDM standard mantenendo la stessa semantica. Utilizza una struttura JSON nidificata, visualizzando gli schemi in un formato simile a una struttura.

La differenza principale che noterai tra XDM standard e 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à 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:nascitaDate": {
    "title": "Data di nascita",
    "type": "string",
    "format": "date"
  },
  "xdm:nascitaDayAndMonth": {
    "title": "Data di nascita",
    "type": "string",
    "pattern": "[0-1][0-9]-[0-9][0-9]"
  },
  "xdm:nascitaYear": {
    "title": "Anno di nascita",
    "type": "integer",
    "minimo": 1
    "massimo": 32767
  }
}
  
{
  "data di nascita": {
    "title": "Data di nascita",
    "type": "string",
    "format": "date",
    "meta:xdmField": "xdm:nascitaDate",
    "meta:xdmType": "date"
  },
  "nascitaDayAndMonth": {
    "title": "Data di nascita",
    "type": "string",
    "pattern": "[0-1][0-9]-[0-9][0-9]",
    "meta:xdmField": "xdm:nascitaDayAndMonth",
    "meta:xdmType": "string"
  },
  "nataleYear": {
    "title": "Anno di nascita",
    "type": "integer",
    "minimo": 1
    "massimo": 32767,
    "meta:xdmField": "xdm:nascitaYear",
    "meta:xdmType": "short"
  }
}

Perché è necessaria la modalità di compatibilità?

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

La maggior parte dei servizi Experience Platform, inclusi Catalog, Data Lake e Real-time Customer Profile utilizza Compatibility Mode al posto di XDM standard. L’ API Schema Registry utilizza anche Compatibility Mode e gli esempi contenuti in questo documento vengono visualizzati utilizzando Compatibility Mode.

Vale la pena sapere che una mappatura avviene tra XDM standard e il modo in cui viene operazionale in Experience Platform, ma non dovrebbe influenzare l'utilizzo dei servizi Platform.

Il progetto open source è a tua disposizione, 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.

In questa pagina