Vincoli del tipo di campo XDM

Negli schemi Experience Data Model (XDM), il tipo di campo limita il tipo di dati che può contenere il campo. Questo documento fornisce una panoramica di ogni tipo di campo di base, inclusi gli altri formati di serializzazione a cui possono essere mappati e come definire i propri tipi di campo nell’API per applicare vincoli diversi.

Introduzione

Prima di utilizzare questa guida, controlla le nozioni di base sulla composizione dello schema per un'introduzione agli schemi, alle classi e ai mixin XDM.

Se prevedi di definire i tuoi tipi di campo nell'API, ti consigliamo vivamente di iniziare con la Guida per gli sviluppatori del Registro di sistema dello schema per scoprire come creare mixin e tipi di dati in cui includere i campi personalizzati. Se utilizzi l’interfaccia utente di Experience Platform per creare gli schemi, consulta la guida Definizione dei campi nell’interfaccia utente per scoprire come implementare i vincoli sui campi definiti all’interno di mixin personalizzati e tipi di dati.

Struttura di base ed esempi

XDM è basato su uno schema JSON e pertanto i campi XDM ereditano una sintassi simile quando ne definiscono il tipo. Per comprendere in che modo diversi tipi di campi sono rappresentati nello schema JSON, è utile indicare i vincoli di base di ciascun tipo.

NOTA

Per ulteriori informazioni sullo schema JSON e sulle altre tecnologie sottostanti nelle API di Platform, consulta la Guida ai fondamentali dell’API .

La tabella seguente illustra il modo in cui ogni tipo XDM viene rappresentato nello schema JSON, insieme a un valore di esempio conforme al tipo:

Tipo XDM	Schema JSON	Esempio
String	{"type": "string"}	`"Platinum"`
Doppio	{"type": "number"}	`12925.49`
Long	{ "type": "integer", "massimo": 9007199254740991, "minimo": -9007199254740991 }	`1478108935`
Integer	{ "type": "integer", "massimo": 2147483648, "minimo": -2147483648 }	`24906290`
Short	{ "type": "integer", "massimo": 32768, "minimo": -32768 }	`15781`
Byte	{ "type": "integer", "massimo": 128, "minimo": -128 }	`90`
Date*	{ "type": "string", "format": "date" }	`"2019-05-15"`
DateTime*	{ "type": "string", "format": "data-ora" }	`"2019-05-15T20:20:39+00:00"`
Boolean	{"type": "string"}	`true`

*Tutte le stringhe in formato data devono essere conformi allo standard ISO 8601 (RFC 3339, sezione 5.6).

Mappatura di tipi XDM su altri formati

Le sezioni seguenti descrivono come ogni tipo XDM viene mappato su altri formati di serializzazione comuni:

Parquet, SQL Spark e Java
Scala, .NET e CosmosDB
MongoDB, Aerospike e Protobuf 2

IMPORTANTE

Tra i tipi XDM standard elencati nelle tabelle seguenti, è incluso anche il tipo Map . Le mappe vengono utilizzate negli schemi standard quando i dati sono rappresentati come chiavi che corrispondono a determinati valori, o quando le chiavi non possono essere ragionevolmente incluse in uno schema statico e devono essere trattate come valori di dati.

I campi di tipo mappa sono riservati per l’utilizzo dello schema del settore e del fornitore e non possono quindi essere utilizzati nelle risorse personalizzate definite dall’utente. L’inclusione del tipo di mappa nelle tabelle seguenti ha lo scopo di aiutarti a determinare come mappare i dati esistenti su XDM se sono attualmente memorizzati in uno dei formati elencati di seguito.

Parquet, SQL Spark e Java

Tipo XDM	Parquet	SQL Spark	Java
String	Tipo: `BYTE_ARRAY` Annotazione: `UTF8`	`StringType`	`java.lang.String`
Double	Tipo: `DOUBLE`	`LongType`	`java.lang.Double`
Long	Tipo: `INT64`	`LongType`	`java.lang.Long`
Integer	Tipo: `INT32` Annotazione: `INT_32`	`IntegerType`	`java.lang.Integer`
Short	Tipo: `INT32` Annotazione: `INT_16`	`ShortType`	`java.lang.Short`
Byte	Tipo: `INT32` Annotazione: `INT_8`	`ByteType`	`java.lang.Short`
Date	Tipo: `INT32` Annotazione: `DATE`	`DateType`	`java.util.Date`
DateTime	Tipo: `INT64` Annotazione: `TIMESTAMP_MILLIS`	`TimestampType`	`java.util.Date`
Boolean	Tipo: `BOOLEAN`	`BooleanType`	`java.lang.Boolean`
Map	`MAP`-gruppo annotato(`<key-type>` deve essere `STRING`)	`MapType` (`keyType` deve essere `StringType`)	`java.util.Map`

Scala, .NET e CosmosDB

Tipo XDM	Scala	.NET	CosmosDB
String	`String`	`System.String`	`String`
Double	`Double`	`System.Double`	`Number`
Long	`Long`	`System.Int64`	`Number`
Integer	`Int`	`System.Int32`	`Number`
Short	`Short`	`System.Int16`	`Number`
Byte	`Byte`	`System.SByte`	`Number`
Date	`java.util.Date`	`System.DateTime`	`String`
DateTime	`java.util.Date`	`System.DateTime`	`String`
Boolean	`Boolean`	`System.Boolean`	`Boolean`
Map	`Map`	(N/D)	`object`

MongoDB, Aerospike e Protobuf 2

Tipo XDM	MongoDB	Aerospik	Protobuf 2
String	`string`	`String`	`string`
Double	`double`	`Double`	`double`
Long	`long`	`Integer`	`int64`
Integer	`int`	`Integer`	`int32`
Short	`int`	`Integer`	`int32`
Byte	`int`	`Integer`	`int32`
Date	`date`	`Integer` (millisecondi Unix)	`int64` (millisecondi Unix)
DateTime	`timestamp`	`Integer` (millisecondi Unix)	`int64` (millisecondi Unix)
Boolean	`bool`	`Integer` (0/1 binario)	`bool`
Map	`object`	`map`	`map<key_type, value_type>`

Definizione dei tipi di campi XDM nell’API

Tutti i campi XDM sono definiti utilizzando i vincoli standard JSON Schema applicabili al tipo di campo, con vincoli aggiuntivi per i nomi di campo applicati da Experience Platform. L’API del Registro di sistema dello schema consente di definire ulteriori tipi di campi utilizzando i formati e i vincoli facoltativi. I tipi di campo XDM sono esposti dall’attributo a livello di campo meta:xdmType.

NOTA

meta:xdmType è un valore generato dal sistema e pertanto non è necessario aggiungere questa proprietà al JSON per il campo quando si utilizza l’API. Si consiglia di utilizzare i tipi di schema JSON (ad esempio string e integer) con i vincoli minimi/massimi appropriati, come definito nella tabella seguente.

La tabella seguente delinea la formattazione appropriata per definire diversi tipi di campi, compresi quelli con proprietà facoltative. Ulteriori informazioni sulle proprietà facoltative e sulle parole chiave specifiche per tipo sono disponibili tramite la documentazione dello schema JSON.

Per iniziare, trova il tipo di campo desiderato e utilizza il codice di esempio fornito per generare la richiesta API per creare un mixin o creare un tipo di dati.

Tipo XDM	Proprietà facoltative	Esempio
String	`pattern` `minLength` `maxLength`	"sampleField": { "type": "string", "pattern": "^[A-Z]{2}$", "maxLength": 2 }
URI		"sampleField": { "type": "string", "format": "uri" }
Enum	`default` `meta:enum`	I valori enum vincolati vengono forniti sotto la matrice `enum`, mentre le etichette facoltative rivolte al cliente per ciascun valore possono essere fornite sotto `meta:enum`: "sampleField": { "type": "string", "enum": [ "value1", "value2", "value3" ], "meta:enum": { "value1": "Valore 1", "value2": "Valore 2", "value3": "Valore 3" }, "default": "value1" }
Number		"sampleField": { "type": "number" }
Long		"sampleField": { "type": "integer", "minimo": -9007199254740992, "massimo": 9007199254740992 }
Integer		"sampleField": { "type": "integer", "minimo": -2147483648, "massimo": 2147483648 }
Short		"sampleField": { "type": "integer", "minimo": -32768, "massimo": 32768 }
Byte		"sampleField": { "type": "integer", "minimo": -128, "massimo": 128 }
Boolean	`default`	"sampleField": { "type": "booleano", "default": false }
Date		"sampleField": { "type": "string", "format": "date", "esempi": ["2004-10-23"] }
DateTime		"sampleField": { "type": "string", "format": "data-ora", "esempi": ["2004-10-23T12:00:00-06:00"] }
Array		Matrice di tipi scalari di base (ad esempio stringhe): "sampleField": { "type": "array", "items": { "type": "string" } } Array di oggetti definiti da un altro schema: "sampleField": { "type": "array", "items": { "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } }
Object		L'attributo `type` di ciascun sottocampo definito in `properties` può essere definito utilizzando qualsiasi tipo di scala: "sampleField": { "type": "oggetto", "properties": { "field1": { "type": "string" }, "field2": { "type": "number" } } } I campi di tipo oggetto possono essere definiti facendo riferimento a `$id` di un tipo di dati: "sampleField": { "type": "oggetto", "$ref": "https://ns.adobe.com/xdm/common/phoneinteraction" }
Map		Una mappa non deve definire proprietà. Per descrivere il tipo di valori contenuti nella mappa, deve definire un singolo schema `additionalProperties` (ogni mappa può contenere solo un singolo tipo di dati). I valori possono essere qualsiasi attributo XDM valido `type` o un riferimento a un altro schema utilizzando un attributo `$ref`. Un campo mappa con valori di tipo stringa: "sampleField": { "type": "oggetto", "additionalProperties":{ "type": "string" } } Campo mappa con array di stringhe per valori: "sampleField": { "type": "oggetto", "additionalProperties":{ "type": "array", "items": { "type": "string" } } } Campo mappa che fa riferimento a un altro tipo di dati: "sampleField": { "type": "oggetto", "additionalProperties":{ "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } }