Definieren von XDM-Feldern in der Schema Registry-API

Alle Experience-Datenmodell (XDM)-Felder werden mithilfe der standardmäßigen JSON-Schema-Einschränkungen definiert, die für ihren Feldtyp gelten, mit zusätzlichen Einschränkungen für Feldnamen, die von Adobe Experience Platform erzwungen werden. Mit der Schema Registry-API können Sie benutzerdefinierte Felder in Ihren Schemata mithilfe von Formaten und optionalen Einschränkungen definieren. XDM-Feldtypen werden durch das Attribut auf Feldebene meta:xdmType verfügbar gemacht.

In diesem Handbuch wird die entsprechende Formatierung zum Definieren verschiedener Feldtypen beschrieben, einschließlich derjenigen mit optionalen Eigenschaften. Weitere Informationen zu optionalen Eigenschaften und typspezifischen Suchbegriffen finden Sie in der Dokumentation zum JSON-Schema.

Suchen Sie zunächst den gewünschten Feldtyp und verwenden Sie den bereitgestellten Beispiel-Code, um Ihre API-Anfrage zum Erstellen einer Feldergruppe oder Erstellen eines Datentyps zu erstellen.

String string

Zeichenfolge Felder werden durch type: string gekennzeichnet.

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

Sie können optional durch die folgenden zusätzlichen Eigenschaften einschränken, welche Arten von Werten für die Zeichenfolge eingegeben werden können:

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

URI uri

URI-Felder werden durch type: string gekennzeichnet, wobei die format-Eigenschaft auf uri gesetzt ist. Es werden keine anderen Eigenschaften akzeptiert.

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

enum enum

Enum-Felder müssen type: string verwenden, wobei die Enum-Werte selbst unter einem enum-Array bereitgestellt werden:

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

Optional können Sie für jeden Wert unter einer meta:enum-Eigenschaft kundenseitige Beschriftungen angeben, wobei jede Beschriftung unter enum mit einem entsprechenden Wert versehen wird.

"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"
  }
}

Sie können optional eine default-Eigenschaft bereitstellen, um den standardmäßigen enum anzugeben, den das Feld verwenden wird, wenn kein Wert angegeben wird.

"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"
}

Zahl number

Zahlenfelder werden durch type: number gekennzeichnet und haben keine anderen erforderlichen Eigenschaften.

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

Integer integer

Ganzzahl-Felder werden durch type: integer gekennzeichnet und haben keine anderen erforderlichen Felder.

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

Optional können Sie den Bereich der Ganzzahl einschränken, indem Sie der Definition minimum- und maximum hinzufügen. Einige andere numerische Typen, die von der Schema Builder-Benutzeroberfläche unterstützt werden, sind nur integer mit bestimmten minimum und maximum Einschränkungen, wie Long, Short und Byte.

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

Lang long

Das Äquivalent eines Long-Felds, das über die Schema Builder-Benutzeroberfläche erstellt wurde, ist ein integer Feldbestimmten minimum und maximum Werten (-9007199254740992 bzw. 9007199254740992).

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

kurz short

Das Äquivalent eines Short-Felds, das über die Schema Builder-Benutzeroberfläche erstellt wurde, ist ein integer Feldbestimmten minimum und maximum Werten (-32768 bzw. 32767).

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

Byte byte

Das Äquivalent eines Byte-Felds, das über die Schema Builder-Benutzeroberfläche erstellt wurde, ist ein integer Feldbestimmten minimum und maximum Werten (-128 bzw. 127).

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

Boolesch boolean

Boolesch Felder werden durch type: boolean gekennzeichnet.

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

Sie können optional einen default Wert angeben, den das Feld verwendet, wenn bei der Aufnahme kein expliziter Wert angegeben wird.

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

Datum date

Datum-Felder werden durch type: string und format: date gekennzeichnet. Sie können optional auch ein Array von examples bereitstellen, die in Fällen genutzt werden können, in denen Sie eine Beispiel-Datumszeichenfolge für Benutzer anzeigen möchten, die die Daten manuell eingeben.

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

DateTime date-time

DateTime-Felder werden durch type: string und format: date-time gekennzeichnet. Sie können optional auch ein Array von examples bereitstellen, die in Fällen genutzt werden können, in denen Sie eine Beispiel-Datums-/Uhrzeitzeichenfolge für Benutzer anzeigen möchten, die die Daten manuell eingeben.

"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

Array-Felder werden durch type: array und ein items-Objekt angegeben, das das Schema der Elemente definiert, die das Array akzeptiert.

Sie können Array-Elemente mithilfe von primitiven Typen definieren, z. B. ein Array von Zeichenfolgen:

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

Sie können die Array-Elemente auch auf der Grundlage eines vorhandenen Datentyps definieren, indem Sie über eine $ref-Eigenschaft auf die $id des Datentyps verweisen. Im Folgenden finden Sie ein Array von Zahlungsartikel-Objekten:

"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"
  }
}

Objekt object

Objekt-Felder werden durch type: object und ein properties-Objekt angegeben, das Untereigenschaften für das Schemafeld definiert.

Jedes unter properties definierte Unterfeld kann mit einem beliebigen primitiven type oder durch Verweis auf einen vorhandenen Datentyp über eine $ref-Eigenschaft definiert werden, die auf den $id des betreffenden Datentyps verweist:

"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"
    }
  }
}

Sie können auch das gesamte Objekt über definieren, indem Sie auf einen Datentyp verweisen, vorausgesetzt, der betreffende Datentyp selbst ist wie type: object definiert:

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

Landkarte map

Ein Zuordnungsfeld ist im Wesentlichen ein Feld vom Typ object mitnicht eingeschränkten Schlüsselsatz. Wie Objekte haben auch Karten einen type Wert von object, aber ihre meta:xdmType ist explizit auf map festgelegt.

Eine Zuordnung darf keine Eigenschaften definieren. Sie muss ein einzelnes additionalProperties definieren, um den Typ der in der Zuordnung enthaltenen Werte zu beschreiben (jede Zuordnung kann nur einen einzigen Datentyp enthalten). Der type muss entweder string oder integer sein.

Ein Zuordnungsfeld mit Werten vom Typ Zeichenfolge würde beispielsweise wie folgt definiert werden:

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

Im folgenden Abschnitt finden Sie weitere Details zum Erstellen benutzerdefinierter Zuordnungsfelder.

Erstellen benutzerdefinierter Zuordnungstypen custom-maps

Um „mapähnliche“ Daten in XDM effizient zu unterstützen, können -Objekte mit einem meta:xdmType versehen werden, der auf map gesetzt ist, um klarzustellen, dass ein -Objekt so verwaltet werden soll, als wäre der Schlüsselsatz nicht beschränkt. Daten, die in Zuordnungsfelder aufgenommen werden, müssen Zeichenfolgenschlüssel verwenden und nur Zeichenfolgen- oder Ganzzahlwerte (wie durch additionalProperties.type bestimmt).

XDM setzt die folgenden Einschränkungen für die Verwendung dieses Speicherhinweises:

Stellen Sie sicher, dass Sie Felder vom Typ Zuordnung nur verwenden, wenn dies unbedingt erforderlich ist, da sie die folgenden Leistungseinbußen aufweisen:

Die Benutzeroberfläche von Experience Platform weist auch Einschränkungen hinsichtlich der Extraktion der Schlüssel von Feldern vom Typ Zuordnung auf. Während sich Felder vom Typ „Objekt“ erweitern lassen, werden Zuordnungen stattdessen als einzelnes Feld angezeigt.

Nächste Schritte

In diesem Handbuch wurde beschrieben, wie Sie verschiedene Feldtypen in der API definieren. Weitere Informationen zur Formatierung von XDM-Feldtypen finden Sie im Handbuch zu Begrenzungen für XDM-Feldtypen.