Definire i campi XDM nell’API del registro dello schema

Tutti i campi Experience Data Model (XDM) sono definiti utilizzando i vincoli standard JSON Schema che si applicano al relativo tipo di campo, con vincoli aggiuntivi per i nomi di campo applicati da Adobe Experience Platform. L’API Schema Registry consente di definire campi personalizzati negli schemi tramite l’utilizzo di formati e vincoli facoltativi. I tipi di campo XDM sono esposti dall'attributo a livello di campo, meta:xdmType.

Questa guida descrive la formattazione appropriata per definire diversi tipi di campi, inclusi quelli con proprietà facoltative. Ulteriori informazioni sulle proprietà facoltative e sulle parole chiave specifiche per il tipo sono disponibili nella documentazione sullo schema JSON.

Per iniziare, individua il tipo di campo desiderato e utilizza il codice di esempio fornito per generare la richiesta API per la creazione di un gruppo di campi o la creazione di un tipo di dati.

Stringa string

I campi String sono indicati da type: string.

"sampleField": {
  "title": "Sample String Field",
  "description": "An example string field.",
  "type": "string"
}

Facoltativamente, puoi vincolare i tipi di valori che possono essere immessi per la stringa attraverso le seguenti proprietà aggiuntive:

"sampleField": {
  "title": "Sample String Field",
  "description": "An example string field with added constraints.",
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "maxLength": 2
}

URI uri

I campi URI sono indicati da type: string con la proprietà format impostata su uri. Non sono accettate altre proprietà.

"sampleField": {
  "title": "Sample URI Field",
  "description": "An example URI field.",
  "type": "string",
  "format": "uri"
}

Enum enum

I campi Enum devono utilizzare type: string, con i valori enum forniti sotto una matrice enum:

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ]
}

Facoltativamente, è possibile fornire etichette rivolte al cliente per ogni valore sotto una proprietà meta:enum, con ogni etichetta digitata su un valore corrispondente in enum.

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field with customer-facing labels.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ],
  "meta:enum": {
      "value1": "Value 1",
      "value2": "Value 2",
      "value3": "Value 3"
  }
}

Facoltativamente, è possibile fornire una proprietà default per indicare il valore enum predefinito che verrà utilizzato dal campo se non viene fornito alcun valore.

"sampleField": {
  "title": "Sample Enum Field",
  "description": "An example enum field with customer-facing labels and a default value.",
  "type": "string",
  "enum": [
      "value1",
      "value2",
      "value3"
  ],
  "meta:enum": {
      "value1": "Value 1",
      "value2": "Value 2",
      "value3": "Value 3"
  },
  "default": "value1"
}

Numero number

I campi numerici sono indicati da type: number e non hanno altre proprietà obbligatorie.

"sampleField": {
  "title": "Sample Number Field",
  "description": "An example number field.",
  "type": "number"
}

Numero intero integer

I campi Integer sono indicati da type: integer e non contengono altri campi obbligatori.

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field.",
  "type": "integer"
}

Facoltativamente, è possibile vincolare l'intervallo del numero intero aggiungendo minimum e maximum proprietà alla definizione. Diversi altri tipi numerici supportati dall'interfaccia utente di Schema Builder sono solo integer tipi con vincoli minimum e maximum specifici, ad esempio Long, Short e Byte.

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field with added constraints.",
  "type": "integer",
  "minimum": 1,
  "maximum": 100
}

Lungo long

L'equivalente di un campo Long creato tramite l'interfaccia utente di Schema Builder è un campo di tipo integer con valori minimum e maximum specifici (-9007199254740992 e 9007199254740992, rispettivamente).

"sampleField": {
  "title": "Sample Long Field",
  "description": "An example long field.",
  "type": "integer",
  "minimum": -9007199254740992,
  "maximum": 9007199254740992
}

Breve short

L'equivalente di un campo Short creato tramite l'interfaccia utente di Schema Builder è un campo di tipo integer con valori minimum e maximum specifici (-32768 e 32768, rispettivamente).

"sampleField": {
  "title": "Sample Short Field",
  "description": "An example short field.",
  "type": "integer",
  "minimum": -32768,
  "maximum": 32768
}

Byte byte

L'equivalente di un campo Byte creato tramite l'interfaccia utente di Schema Builder è un campo di tipo integer con valori minimum e maximum specifici (-128 e 128, rispettivamente).

"sampleField": {
  "title": "Sample Byte Field",
  "description": "An example byte field.",
  "type": "integer",
  "minimum": -128,
  "maximum": 128
}

Booleano boolean

I campi Boolean sono indicati da type: boolean.

"sampleField": {
  "title": "Sample Boolean Field",
  "description": "An example boolean field.",
  "type": "boolean"
}

Facoltativamente, puoi fornire un valore default che il campo utilizzerà quando non viene fornito alcun valore esplicito durante l'acquisizione.

"sampleField": {
  "title": "Sample Boolean Field",
  "description": "An example boolean field with a default value.",
  "type": "boolean",
  "default": false
}

Data date

I campi Date sono indicati da type: string e format: date. Facoltativamente, puoi anche fornire un array di examples da sfruttare nei casi in cui desideri visualizzare una stringa di data di esempio per gli utenti che immettono manualmente i dati.

"sampleField": {
  "title": "Sample Date Field",
  "description": "An example date field with an example array item.",
  "type": "string",
  "format": "date",
  "examples": ["2004-10-23"]
}

DataOra date-time

I campi DateTime sono indicati da type: string e format: date-time. Facoltativamente, puoi anche fornire un array di examples da sfruttare nei casi in cui desideri visualizzare una stringa di esempio datetime per gli utenti che immettono manualmente i dati.

"sampleField": {
  "title": "Sample Datetime Field",
  "description": "An example datetime field with an example array item.",
  "type": "string",
  "format": "date-time",
  "examples": ["2004-10-23T12:00:00-06:00"]
}

Array array

I campi Array sono indicati da type: array e da un oggetto items che definisce lo schema degli elementi che l'array accetterà.

Puoi definire gli elementi array utilizzando tipi primitivi, ad esempio una matrice di stringhe:

"sampleField": {
  "title": "Sample Array Field",
  "description": "An example array field using a primitive type.",
  "type": "array",
  "items": {
    "type": "string"
  }
}

È inoltre possibile definire gli elementi array in base a un tipo di dati esistente facendo riferimento a $id del tipo di dati tramite una proprietà $ref. Di seguito è riportata una matrice di oggetti elemento di pagamento:

"sampleField": {
  "title": "Sample Array Field",
  "description": "An example array field using a data type reference.",
  "type": "array",
  "items": {
    "$ref": "https://ns.adobe.com/xdm/data/paymentitem"
  }
}

Oggetto object

I campi Object sono indicati da type: object e da un oggetto properties che definisce sottoproprietà per il campo schema.

Ogni sottocampo definito in properties può essere definito utilizzando qualsiasi elemento di base type o facendo riferimento a un tipo di dati esistente tramite una proprietà $ref che punta a $id del tipo di dati in questione:

"sampleField": {
  "title": "Sample Object Field",
  "description": "An example object field.",
  "type": "object",
  "properties": {
    "field1": {
      "type": "string"
    },
    "field2": {
      "$ref": "https://ns.adobe.com/xdm/common/measure"
    }
  }
}

È inoltre possibile definire l'intero oggetto tramite facendo riferimento a un tipo di dati, a condizione che il tipo di dati in questione sia esso stesso definito come type: object:

"sampleField": {
  "title": "Sample Object Field",
  "description": "An example object field using a data type reference.",
  "$ref": "https://ns.adobe.com/xdm/common/phoneinteraction"
}

Mappa map

Un campo mappa è essenzialmente un campo di tipo object con un set di chiavi non vincolato. Come gli oggetti, le mappe hanno un valore type di object, ma il loro meta:xdmType è impostato in modo esplicito su map.

Una mappa non deve definire proprietà. deve definire un singolo schema additionalProperties per descrivere il tipo di valori contenuti nella mappa (ogni mappa può contenere solo un singolo tipo di dati). Il valore type deve essere string o integer.

Ad esempio, un campo mappa con valori di tipo stringa sarebbe definito come segue:

"sampleField": {
  "title": "Sample Map Field",
  "description": "An example map field.",
  "type": "object",
  "meta:xdmType": "map",
  "additionalProperties": {
    "type": "string"
  }
}

Per ulteriori dettagli sulla creazione di campi mappa personalizzati, consulta la sezione seguente.

Creazione di tipi di mappe personalizzati custom-maps

Per supportare in modo efficiente i dati di tipo mappa in XDM, agli oggetti può essere aggiunta un'annotazione con meta:xdmType impostato su map per chiarire che un oggetto deve essere gestito come se il set di chiavi non fosse vincolato. I dati acquisiti nei campi mappa devono utilizzare chiavi stringa e solo valori stringa o interi (come determinato da additionalProperties.type).

XDM pone le seguenti restrizioni sull’utilizzo di questo hint di archiviazione:

Assicurati di utilizzare campi di tipo mappa solo quando assolutamente necessario, in quanto presentano i seguenti svantaggi in termini di prestazioni:

Anche l’interfaccia utente di Platform presenta limitazioni su come estrarre le chiavi dei campi di tipo mappa. Mentre i campi di tipo oggetto possono essere espansi, le mappe vengono visualizzate come un singolo campo.

Passaggi successivi

Questa guida illustra come definire diversi tipi di campi nell’API. Per ulteriori informazioni sulla formattazione dei tipi di campo XDM, consulta la guida sui vincoli per i tipi di campo XDM.