Show Menu
SUJETS×

Annexe

Ce document fournit des informations supplémentaires sur l'utilisation de l'API de registre de Schémas.

Mode de compatibilité

Le modèle de données d’expérience (XDM) est une spécification publiquement documentée, pilotée par Adobe pour améliorer l’interopérabilité, l’expressivité et la puissance des expériences numériques. Adobe conserve le code source et les définitions XDM formelles dans un projet open source sur GitHub . Ces définitions sont écrites en Notation standard XDM, en utilisant JSON-LD (Notation d’objet JavaScript pour les données liées) et le Schéma JSON comme grammaire pour la définition de schémas XDM.
Lorsque vous consultez des définitions XDM formelles dans le référentiel public, vous pouvez constater que XDM standard diffère de ce que vous voyez dans Adobe Experience Platform. Ce que vous voyez dans la plate-forme d’expérience s’appelle le mode de compatibilité, et il fournit une mise en correspondance simple entre XDM standard et la façon dont il est utilisé dans la plate-forme.

Fonctionnement du mode de compatibilité

Le mode de compatibilité permet au modèle JSON-LD XDM de fonctionner avec l’infrastructure de données existante en modifiant les valeurs dans XDM standard tout en conservant la sémantique la même. Il utilise une structure JSON imbriquée, affichant les schémas sous forme d’arborescence.
La principale différence que vous remarquerez entre XDM standard et le mode de compatibilité est la suppression du préfixe "xdm:" pour les noms de champs.
Vous trouverez ci-dessous une comparaison côte à côte montrant les champs liés à l’anniversaire (avec la suppression des attributs "description") en mode XDM standard et en mode de compatibilité. Notez que les champs Mode de compatibilité incluent une référence au champ XDM et à son type de données dans les attributs "meta:xdmField" et "meta:xdmType".
XDM standard Mode de compatibilité
        { "xdm:bornDate": { "title" : "Date de naissance", "type" : "string", "format" : "date", }, "xdm:bornDayAndMonth" : { "title" : "Date de naissance", "type" : "string", "pattern" : "[0-1][0-9]-[0-9][0-9]", }, "xdm:bornYear" : { "title" : "Année de naissance", "type" : "integer", "minimum" : 1, "maximum" : 32767 }
      

        { "bornDate" : { "title" : "Date de naissance", "type" : "string", "format" : "date", "meta:xdmField" : "xdm:bornDate", "meta:xdmType" : "date" }, "bornDayAndMonth": { "title" : "Date de naissance", "type" : "string", "pattern" : "[0-1][0-9]-[0-9][0-9]", "meta:xdmField" : "xdm:bornDayAndMonth", "meta:xdmType" : "string" }, "bornYear" : { "title" : "Année de naissance", "type" : "integer", "minimum" : 1, "maximum" : 32767, "meta:xdmField" : "xdm:bornYear", "meta:xdmType" : "short" }
      

Pourquoi le mode de compatibilité est-il nécessaire ?

Adobe Experience Platform est conçu pour fonctionner avec plusieurs solutions et services, chacun avec ses propres défis et limitations techniques (par exemple, la manière dont certaines technologies gèrent des caractères spéciaux). Afin de surmonter ces limitations, le mode de compatibilité a été développé.
La plupart des services Experience Platform, y compris Catalog, Data Lake et le Profil client en temps réel, utilisent le mode de compatibilité plutôt que le mode XDM standard. L'API Schéma Registry utilise également le mode de compatibilité, et les exemples de ce document sont tous affichés à l'aide du mode de compatibilité.
Il est intéressant de savoir qu’un mappage a lieu entre XDM standard et la façon dont il est opérationnel dans Experience Platform, mais il ne devrait pas affecter votre utilisation des services de la plate-forme.
Le projet open source est à votre disposition, mais lorsqu'il s'agit d'interagir avec des ressources via le Registre des Schémas, les exemples d'API de ce document fournissent les meilleures pratiques que vous devez connaître et suivre.

Définition des types de champs XDM dans l'API

Les schémas XDM sont définis à l’aide des normes de Schéma JSON et des types de champs de base, avec des contraintes supplémentaires pour les noms de champs appliqués par Experience Platform. XDM vous permet de définir d'autres types de champs en utilisant des formats et des contraintes facultatives. Les types de champ XDM sont exposés par l'attribut de niveau champ meta:xdmType .
meta:xdmType est une valeur générée par le système. Par conséquent, vous n’êtes pas tenu d’ajouter cette propriété au fichier JSON pour votre champ. Il est recommandé d’utiliser des types de Schéma JSON (chaînes et entiers, par exemple) avec les contraintes min/max appropriées, telles que définies dans le tableau ci-dessous.
Le tableau suivant décrit la mise en forme appropriée pour définir les types de champs scalaires et les types de champs plus spécifiques à l’aide des propriétés facultatives. Pour plus d’informations sur les propriétés facultatives et les mots-clés spécifiques au type, consultez la documentation du Schéma JSON.
Pour commencer, recherchez le type de champ souhaité et utilisez l’exemple de code fourni pour générer votre requête d’API.
Type souhaité (meta:xdmType) JSON (Schéma JSON) Exemple de code
chaîne type : Propriétés stringOptional :
  • pattern
  • minLength
  • maxLength
        "sampleField" : { "type" : "string", "pattern" : "^[A-Z]{2}$", "maxLength": 2 }
      

uri (xdmType:string) type : Format de chaîne : uri
        "sampleField" : { "type" : "string", "format" : "uri" }
      

enum (xdmType: string) type : stringOptional, propriété :
  • default
Spécifiez des libellés d’option destinés aux clients à l’aide de "meta:enum" :
        "sampleField" : { "type" : "string", "enum" : [ "value1", "value2", "value3" ], "meta:enum" : { "value1": "Value 1", "value2" : "Value 2", "value3" : "Value 3" }, "default": "value1" }
      

nombre type : nombre minimum : ±2,23 × 10^308 maximum : ±1,80 × 10^308
        "sampleField" : { "type" : "number" }
      

long type : nombre maximal : 2^53+1 minimum : -2^53+1
        "sampleField" : { "type" : "integer", "minimum" : -9007199254740992, "maximum" : 9007199254740992 }
      

int type : maximal : 2^31 minimum : -2^31
        "sampleField" : { "type" : "integer", "minimum" : -2147483648, "maximum" : 2147483648 }
      

short type : nombre maximal : 2^15 minimum : -2^15
        "sampleField" : { "type" : "integer", "minimum" : -32768, "maximum" : 32768 }
      

byte type : nombre maximal : 2^7 minimum : -2^7
        "sampleField" : { "type" : "integer", "minimum" : -128, "maximum" : 128 }
      

booléen type : boolean {true, false}Propriété facultative :
  • default
        "sampleField" : { "type" : "boolean", "default" : false }
      

date type : Format de chaîne : date
        "sampleField" : { "type" : "string", "format" : "date", "exemples" : ["2004-10-23"] }
      

Date définie par la RFC 3339, section 5.6 , où "date complète" = date-année complète "-" date-mois "-" date-mday (AAAA-MM-JJ)
date-heure type : Format de chaîne : date-heure
        "sampleField" : { "type" : "string", "format" : "date-heure", "exemples" : ["2004-10-23T12:00:00-06:00"] }
      

Date-Heure telle que définie par la RFC 3339, section 5.6 , où "date-time" = "T" à temps plein à date complète: (AAAA-MM-JJ'T'HH:MM:SS.SSSSX)
tableau type : tableau items.type peut être défini à l’aide de n’importe quel type scalaire :
        "sampleField" : { "type" : "array", "items" : { "type" : "string" } }
      

Tableau d'objets définis par un autre schéma :
        "sampleField" : { "type" : "array", "items" : { "$ref": "id" } }
      

Où "id" correspond à {id} du schéma de référence.
objet type : objet du média.{field}.type peut être défini à l'aide de n'importe quel type scalaire :
        "sampleField" : { "type" : "object", "properties" : { "field1" : { "type" : "string" }, "field2" : { "type" : "number" } } }
      

Champ de type "objet" défini par un schéma de référence :
        "sampleField" : { "type" : "object", "$ref" : "id" }
      

Où "id" correspond à {id} du schéma de référence.
map type : objectNote : L'utilisation du type de données "map" est réservée à l'utilisation du schéma du secteur industriel et du fournisseur et n'est pas disponible pour l'utilisation dans les champs définis par le client. Elle est utilisée dans les schémas standard lorsque les données sont représentées sous la forme de clés qui correspondent à une valeur ou lorsque les clés ne peuvent pas raisonnablement être incluses dans un schéma statique et doivent être traitées comme des valeurs de données. Un 'map' NE DOIT PAS définir de propriétés. Il DOIT définir un schéma "additionalProperties" unique pour décrire le type de valeurs contenues dans la "map". Un "mappage" dans XDM ne peut contenir qu'un seul type de données. Les valeurs peuvent être n'importe quelle définition de schéma XDM valide, y compris un tableau ou un objet, ou comme référence à un autre schéma (via $ref). Champ de correspondance avec des valeurs de type "string" :
        "sampleField" : { "type" : "object", "additionalProperties":{ "type": "string" } }
      

Mapper un champ dont les valeurs sont un tableau de chaînes :
        "sampleField" : { "type" : "object", "additionalProperties":{ "type": "array", "items" : { "type" : "string" } } }
      

Champ de mappage qui référence un autre schéma :
        "sampleField" : { "type" : "object", "additionalProperties":{ "$ref": "id" } }
      

Où "id" correspond à {id} du schéma de référence.

Mappage de types XDM à d’autres formats

Le tableau ci-dessous décrit le mappage entre "meta:xdmType" et d’autres formats de sérialisation.
Type
XDM (meta:xdmType)
JSON
(Schéma JSON)
Parquet
(type/annotation)
Spark SQL
Java
Scala
.NET
CosmosDB
MongoDB
Aérospike
Protocole 2
chaîne
type:string
BYTE_ARRAY/UTF8
StringType
java.lang.String
Chaîne
System.String
Chaîne
chaîne
Chaîne
chaîne
nombre
type:number
DOUBLE
DoubleType
java.lang.Double
Double
System.Double
Nombre
double
Double
double
long
type:
integermaximum:253+1
INT64
LongType
java.lang.Long
Long
System.Int64
Nombre
long
Entier
int64
int
type:
integermaximum:231
INT32/INT_32
IntegerType
java.lang.Integer
Int
System.Int32
Nombre
int
Entier
int32
short
type:
integermaximum:215
INT32/INT_16
ShortType
java.lang.Short
Court
System.Int16
Nombre
int
Entier
int32
byte
type:
integermaximum:27
INT32/INT_8
ByteType
java.lang.Short
Octet
System.SByte
Nombre
int
Entier
int32
booléen
type:boolean
BOOLÉEN
BooleanType
java.lang.Boolean
Booléen
System.Boolean
Booléen
bool
Entier
Entier
date
type:format
de chaîne:date
(RFC 3339, section 5.6)
INT32/DATE
DateType
java.util.Date
java.util.Date
System.DateTime
Chaîne
date
Entier
(unix millis)
int64
(unix millis)
date-heure
type:format
de chaîne:date-time
(RFC 3339, section 5.6)
INT64/TIMESTAMP_MILLIS
TimestampType
java.util.Date
java.util.Date
System.DateTime
Chaîne
timestamp
Entier
(unix millis)
int64
(unix millis)
map
objet
MAP groupe
annoté < key_type> DOIT être de type STRING
< value_type> type de valeurs de mappage
MapType
"keyType" DOIT être StringType
"valueType" est un type de valeurs de mappage.
java.util.Map
Carte
---
objet
objet
map
map< key_type, value_type>