Définition des champs XDM dans l’API Schema Registry

Tous les champs de modèle de données d’expérience (XDM) sont définis à l’aide de la norme Schéma JSON contraintes qui s’appliquent à leur type de champ, avec des contraintes supplémentaires pour les noms de champ qui sont appliqués par Adobe Experience Platform. L’API Schema Registry vous permet de définir des champs personnalisés dans vos schémas à l’aide de formats et de contraintes facultatives. Les types de champ XDM sont exposés par l’attribut field-level, meta:xdmType.

REMARQUE

meta:xdmType est une valeur générée par le système. Par conséquent, vous n’êtes pas obligé d’ajouter cette propriété au fichier JSON de votre champ lors de l’utilisation de l’API (sauf lorsque création de types de mappage personnalisés). La bonne pratique consiste à utiliser des types de schémas JSON (tels que string et integer) 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 différents types de champs, y compris ceux avec 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 des schémas JSON.

Pour commencer, recherchez le type de champ souhaité et utilisez l’exemple de code fourni pour créer votre requête API pour création d’un groupe de champs ou création d’un type de données.

Type XDM Propriétés facultatives Exemple
String
  • pattern
  • minLength
  • maxLength
"sampleField": {
            "type": "string",
            "pattern": "^[A-Z]{2}$",
            "maxLength": 2
}
URI
"sampleField": {
          "type": "string",
          "format": "uri"
}
Enum
  • default
  • meta:enum
Les valeurs d’énumération contraintes sont fournies sous la variable enum , tandis que des étiquettes facultatives destinées aux clients pour chaque valeur peuvent être fournies sous meta:enum:
"sampleField": {
          "type": "string",
          "enum": [
              "value1",
              "value2",
              "value3"
          ],
          "meta:enum": {
              "value1": "Value 1",
              "value2": "Value 2",
              "value3": "Value 3"
          },
          "default": "value1"
}

Notez que la variable meta:enum la valeur est not déclarer une énumération ou piloter toute validation de données par elle-même. Dans la plupart des cas, les chaînes fournies sous meta:enum sont également fournis sous enum pour s’assurer que les données sont limitées. Cependant, il existe certains cas d’utilisation où meta:enum est fourni sans qu’un enum tableau. Voir le tutoriel sur définition des valeurs proposées pour plus d’informations.
Number
"sampleField": {
          "type": "number"
}
Long
"sampleField": {
          "type": "integer",
          "minimum": -9007199254740992,
          "maximum": 9007199254740992
}
Integer
"sampleField": {
          "type": "integer",
          "minimum": -2147483648,
          "maximum": 2147483648
}
Court
"sampleField": {
          "type": "integer",
          "minimum": -32768,
          "maximum": 32768
}
Byte
"sampleField": {
          "type": "entier",
          "minimum": -128,
          "maximum": 128
  }
Booléen
  • default
"sampleField": {
          "type": "boolean",
          "default": false
}
Date
"sampleField": {
          "type": "string",
          "format": "date",
          "examples": ["2004-10-23"]
}
DateTime
"sampleField": { "type": "string", "format": "date-time", "examples" : ["2004-10-23T12:00:00-06:00"] }
Array Tableau de types scalaires de base (par exemple, chaînes) :
"sampleField": {
          "type": "array",
          "items": {
            "type": "string"
  }
}
Un tableau d’objets défini par un autre schéma :
"sampleField": { "type": "array", "items" : { "$ref": "https://ns.adobe.com/xdm/data/paymentitem" } }
Object Le type de chaque sous-champ défini sous properties peut être défini à l’aide de n’importe quel type scalaire :
"sampleField": {
          "type": "object",
          "properties": {
            "field1": {
              "type": "string"
            },
            "field2": {
              "type": "number"
    }
  }
}
Les champs de type objet peuvent être définis en référençant la variable $id d’un type de données :
"sampleField": { "type": "object", "$ref" : "https://ns.adobe.com/xdm/common/phoneinteraction" }
Map Un champ de type map est essentiellement un champ de type objet avec un ensemble non limité de clés. Comme les objets, les cartes ont une type valeur de object, mais leur meta:xdmType est explicitement défini sur map.

Une carte must not définissez les propriétés. It must définir une seule additionalProperties schéma pour décrire le type de valeurs contenues dans le mappage (chaque mappage ne peut contenir qu’un seul type de données). Le type doit être définie sur string ou integer.

Un champ map avec des valeurs de type chaîne :
"sampleField": { "type": "object", "meta:xdmType" : "map", "additionalProperties":{ "type": "string" } }
Consultez la section ci-dessous pour plus d’informations sur la création de types de mappage personnalisés dans XDM.

Création de types de mappage personnalisés

Afin de prendre en charge efficacement les données "de type carte" dans XDM, les objets peuvent être annotés avec un meta:xdmType défini sur map pour indiquer clairement qu’un objet doit être géré comme si l’ensemble de clés n’était pas contraint. Les données ingérées dans les champs de mappage doivent utiliser des clés de chaîne et uniquement des valeurs string ou integer (telles que déterminées par additionalProperties.type).

XDM impose les restrictions suivantes à l’utilisation de cet indice de stockage :

  • Les types de carte DOIVENT être de type object.
  • Les types de carte NE DOIVENT PAS avoir de propriétés définies (en d’autres termes, ils définissent des objets "vides").
  • Les types de carte DOIVENT inclure un additionalProperties.type qui décrit les valeurs qui peuvent être placées dans le mappage, soit string ou integer.

Assurez-vous que vous utilisez uniquement des champs de type map lorsque cela est absolument nécessaire, car ils présentent les inconvénients suivants en termes de performances :

  • Le temps de réponse de Adobe Experience Platform Query Service passe de trois secondes à dix secondes pour 100 millions d’enregistrements.
  • Les cartes doivent comporter moins de 16 clés, sinon elles risquent d’être détériorées.

L’interface utilisateur de Platform présente également des limites quant à la manière dont elle peut extraire les clés des champs de type map. Bien que les champs de type objet puissent être développés, les mappages s’affichent sous la forme d’un champ unique.

Étapes suivantes

Ce guide explique comment définir différents types de champ dans l’API. Pour plus d’informations sur la mise en forme des types de champ XDM, consultez le guide sur Contraintes de type de champ XDM.

Sur cette page