Definieren von XDM-Feldern in der Schema Registry-API

Alle Experience-Datenmodell (XDM)-Felder werden mit den 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 Schemas definieren, indem Sie Formate und optionale Einschränkungen verwenden. XDM-Feldtypen werden durch das Attribut auf Feldebene, meta:xdmType, verfügbar gemacht.

NOTE
meta:xdmType ist ein vom System generierter Wert. Daher müssen Sie diese Eigenschaft nicht zum JSON für Ihr Feld hinzufügen, wenn Sie die API verwenden (außer beim Erstellen benutzerdefinierter Zuordnungstypen ).Es empfiehlt sich, JSON-Schematypen (z. B. string und integer) mit den entsprechenden Min-/Max-Einschränkungen zu verwenden, wie in der folgenden Tabelle definiert.

In diesem Handbuch wird die geeignete 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 Beispielcode, der zum Erstellen Ihrer API-Anfrage für das Erstellen einer Feldergruppe oder Erstellen eines Datentyps bereitgestellt wird.

String string

String -Felder sind durch type: string gekennzeichnet.

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

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

  • pattern: Ein Regex-Muster, durch das eingeschränkt werden soll.
  • minLength: Eine Mindestlänge für die Zeichenfolge.
  • maxLength: Eine maximale Länge für die Zeichenfolge.
"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 Eigenschaft format 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"
  ]
}

Sie können optional für jeden Wert unter einer meta:enum -Eigenschaft kundenorientierte Beschriftungen angeben, wobei jede Beschriftung einem entsprechenden Wert unter enum zugeordnet 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"
  }
}
NOTE
Der meta:enum -Wert deklariert nicht eine Auflistung oder führt eine Datenvalidierung allein durch. In den meisten Fällen werden unter meta:enum bereitgestellte Zeichenfolgen auch unter enum bereitgestellt, um sicherzustellen, dass die Daten eingeschränkt sind. Es gibt jedoch einige Anwendungsfälle, in denen meta:enum ohne ein entsprechendes enum -Array bereitgestellt wird. Weitere Informationen finden Sie im Tutorial zum Definieren der vorgeschlagenen Werte 🔗 .

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

"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"
}
IMPORTANT
Wenn kein default -Wert angegeben wird und das Enum-Feld auf required gesetzt ist, schlägt die Überprüfung bei der Aufnahme eines Datensatzes fehl, wenn für dieses Feld ein anerkannter Wert fehlt.

Nummer number

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

"sampleField": {
  "title": "Sample Number Field",
  "description": "An example number field.",
  "type": "number"
}
NOTE
number-Typen werden für jeden numerischen Typ verwendet, entweder Ganzzahlen oder Gleitkommazahlen, während integer Typen speziell für ganzzahlige Zahlen verwendet werden. Weitere Informationen zu den Anwendungsfällen für jeden Typ finden Sie in der Dokumentation zum JSON-Schema für numerische Typen .

Integer integer

Integer -Felder sind durch type: integer gekennzeichnet und haben keine anderen erforderlichen Felder.

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field.",
  "type": "integer"
}
NOTE
Während integer-Typen sich speziell auf ganzzahlige Zahlen beziehen, werden number Typen für alle numerischen Typen verwendet, entweder Ganzzahlen oder Gleitkommazahlen. Weitere Informationen zu den Anwendungsfällen für jeden Typ finden Sie in der Dokumentation zum JSON-Schema für numerische Typen .

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

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

Long long

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

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

short short

Das Äquivalent eines Short -Felds, das über die Schema Builder-Benutzeroberfläche erstellt wird, ist ein Feld vom Typ integer mit bestimmten minimum - und maximum -Werten (-32768 bzw. 32768 ).

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

Byte byte

Das Äquivalent eines Byte -Felds, das über die Schema Builder-Benutzeroberfläche erstellt wird, ist ein Feld vom Typ integer mit bestimmten minimum - und maximum -Werten (-128 bzw. 128).

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

Boolean boolean

Die Felder Boolesch sind 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 während 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
}
IMPORTANT
Wenn kein default -Wert angegeben wird und das boolesche Feld auf required gesetzt ist, schlägt die Überprüfung bei der Aufnahme für jeden Datensatz fehl, für den ein anerkannter Wert für dieses Feld fehlt.

Datum date

Die Felder Datum sind durch type: string und format: date gekennzeichnet. Sie können optional auch ein Array von examples angeben, das verwendet werden soll, wenn Sie eine Beispieldatumszeichenfolge 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

Die Felder DateTime sind durch type: string und format: date-time gekennzeichnet. Sie können optional auch ein Array von "examples"bereitstellen, das verwendet werden kann, wenn Sie eine Beispiel-Datum-Uhrzeit-Zeichenfolge 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 Primitive-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 Grundlage eines vorhandenen Datentyps definieren, indem Sie über eine $ref -Eigenschaft auf das $id des Datentyps verweisen. Im Folgenden finden Sie ein Array von Zahlungselement -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.

Das unter properties definierte Unterfeld kann mit einem beliebigen Primitive type oder durch Referenzierung eines vorhandenen Datentyps über eine $ref -Eigenschaft definiert werden, die auf das $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 definieren, indem Sie auf einen Datentyp verweisen, vorausgesetzt, der betreffende Datentyp ist selbst als 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 objectmit einem nicht beschränkten Satz von Schlüsseln. Wie Objekte haben Karten den Wert type von object, ihre meta:xdmType sind jedoch explizit auf map eingestellt.

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

Ein Zuordnungsfeld mit Zeichenfolgenwerten würde beispielsweise wie folgt definiert:

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

Weitere Informationen zum Erstellen von benutzerdefinierten Zuordnungsfeldern finden Sie im folgenden Abschnitt.

Erstellen benutzerdefinierter Zuordnungstypen custom-maps

Um "map-like"-Daten in XDM effizient zu unterstützen, können Objekte mit einer "meta:xdmType"-Einstellung auf "map"kommentiert werden, um deutlich zu machen, 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 und nur String- oder Ganzzahlwerte verwenden (wie durch additionalProperties.type bestimmt).

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

  • Zuordnungstypen MÜSSEN vom Typ object sein.
  • Für Zuordnungstypen dürfen KEINE Eigenschaften definiert sein (d. h. sie definieren "leere"Objekte).
  • Zuordnungstypen MÜSSEN ein additionalProperties.type -Feld enthalten, das die Werte beschreibt, die auf der Zuordnung platziert werden können, entweder string oder integer.

Stellen Sie sicher, dass Sie nur Felder vom Typ Zuordnung verwenden, wenn dies unbedingt erforderlich ist, da sie die folgenden Leistungsbeeinträchtigungen aufweisen:

  • Die Antwortzeit von Adobe Experience Platform Query Service wird für 100 Millionen Datensätze von drei Sekunden auf zehn Sekunden reduziert.
  • Karten mit weniger als 16 Schlüsseln müssen vorhanden sein. Andernfalls besteht die Gefahr einer weiteren Verschlechterung.

Die Benutzeroberfläche von Platform weist außerdem Einschränkungen hinsichtlich der Art und Weise auf, wie die Schlüssel von Feldern vom Typ Zuordnung extrahiert werden können. Während Objekttypen erweitert werden können, werden Zuordnungen stattdessen als ein einzelnes Feld angezeigt.

Nächste Schritte

In diesem Handbuch wurde die Definition verschiedener Feldtypen in der API beschrieben. Weitere Informationen zur Formatierung von XDM-Feldtypen finden Sie im Handbuch zu XDM-Feldtypbegrenzungen.

recommendation-more-help
62e9ffd9-1c74-4cef-8f47-0d00af32fc07