在架构注册表API中定义XDM字段

所有Experience Data Model (XDM)字段均使用适用于其字段类型的标准JSON架构约束进行定义,并对Adobe Experience Platform强制实施的字段名称使用其他约束。 架构注册表API允许您通过使用格式和可选约束来定义架构中的自定义字段。 XDM字段类型由字段级别属性meta:xdmType公开。

NOTE
meta:xdmType是系统生成的值,因此使用API时不需要将此属性添加到字段的JSON中(除非在创建自定义映射类型时)。 最佳实践是将JSON架构类型(如stringinteger)与下表定义的相应最小/最大约束一起使用。

本指南概述了用于定义不同字段类型的相应格式,包括那些具有可选属性的字段类型。 有关可选属性和特定类型关键字的详细信息,请参阅JSON架构文档

若要开始,请查找所需的字段类型并使用提供的示例代码为创建字段组创建数据类型生成API请求。

字符串 string

String字段由type: string指示。

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

您可以选择通过以下附加属性来限制可为字符串输入的值的类型:

  • pattern:约束所依据的正则表达式模式。
  • minLength:字符串的最小长度。
  • maxLength:字符串的最大长度。
"sampleField": {
  "title": "Sample String Field",
  "description": "An example string field with added constraints.",
  "type": "string",
  "pattern": "^[A-Z]{2}$",
  "maxLength": 2
}

URI uri

URI字段由type: string指示,其中format属性设置为uri。 不接受其他属性。

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

枚举 enum

枚举字段必须使用type: string,枚举值本身在enum数组下提供:

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

您可以选择为meta:enum属性下的每个值提供面向客户的标签,每个标签都与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"
  }
}
NOTE
meta:enum值​ ​自行声明枚举或驱动任何数据验证。 在大多数情况下,在meta:enum下提供的字符串也在enum下提供,以确保数据受约束。 但是,在某些情况下,提供meta:enum时没有相应的enum数组。 有关详细信息,请参阅有关定义建议值的教程。

您可以选择提供default属性,以指示如果未提供值,字段将使用的默认enum值。

"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
如果未提供default值,并且枚举字段设置为required,则任何缺少此字段的接受值的记录将在摄取时验证失败。

数字 number

数字字段由type: number指示,没有其他必需属性。

"sampleField": {
  "title": "Sample Number Field",
  "description": "An example number field.",
  "type": "number"
}
NOTE
number类型用于任何数字类型,可以是整数或浮点数,而integer类型专门用于整数数字。 有关每种类型的用例的更多信息,请参阅有关数字类型🔗的JSON架构文档。

整数 integer

整数字段由type: integer指示,没有其他必填字段。

"sampleField": {
  "title": "Sample Integer Field",
  "description": "An example integer field.",
  "type": "integer"
}
NOTE
虽然integer类型专门引用整数值,但number类型用于任何数值类型,可以是整数或浮点数。 有关每种类型的用例的更多信息,请参阅有关数字类型🔗的JSON架构文档。

您可以选择通过将minimummaximum属性添加到定义来约束整数的范围。 架构生成器UI支持的几个其他数字类型只是具有特定minimummaximum约束的integer类型,如LongShortByte

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

long

通过架构生成器UI创建的Long字段的等效项是integer类型字段,具有特定minimummaximum值(分别为-90071992547409929007199254740992)。

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

short

通过架构生成器UI创建的Short字段的等效项是integer类型字段,具有特定minimummaximum值(分别为-3276832768)。

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

字节 byte

通过架构生成器UI创建的字节字段的等效项是integer类型字段,具有特定minimummaximum值(分别为-128128)。

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

布尔值 boolean

Boolean字段由type: boolean指示。

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

您可以选择提供一个default值,如果没有在摄取期间提供显式值,则字段将使用该值。

"sampleField": {
  "title": "Sample Boolean Field",
  "description": "An example boolean field with a default value.",
  "type": "boolean",
  "default": false
}
IMPORTANT
如果未提供default值,并且布尔字段设置为required,则任何缺少此字段的接受值的记录将在摄取时验证失败。

日期 date

日期字段由type: stringformat: date指示。 此外,您还可以选择提供一个examples数组,以便在需要为用户手动输入数据显示样本日期字符串时使用该数组。

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

日期时间 date-time

日期时间字段由type: stringformat: date-time指示。 您还可以选择提供一个examples数组,以便在要显示手动输入数据的用户的日期时间字符串示例的情况下使用。

"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字段由type: arrayitems对象表示,该对象定义了该数组将接受的项的架构。

您可以使用原始类型(如字符串数组)定义数组项:

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

您还可以通过$ref属性引用数据类型的$id,根据现有数据类型定义数组项。 以下是付款项对象的数组:

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

对象 object

对象字段由type: object和定义架构字段的子属性的properties对象表示。

properties下定义的每个子字段可以使用任何基元type定义,也可以通过指向相关数据类型的$id$ref属性引用现有数据类型来定义:

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

您也可以通过引用数据类型来定义整个对象,前提是相关数据类型本身定义为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"
}

地图 map

映射字段本质上是具有无约束键集的object类型字段。 与对象类似,映射的type值为object,但其meta:xdmType显式设置为map

映射​ 不得 ​定义任何属性。 它​ 必须 ​定义单个additionalProperties架构以描述映射中包含的值类型(每个映射只能包含单个数据类型)。 type值必须为stringinteger

例如,带有字符串类型值的映射字段的定义如下所示:

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

有关创建自定义映射字段的更多详细信息,请参阅以下部分。

创建自定义映射类型 custom-maps

为了在XDM中有效地支持“类似映射”的数据,可以使用设置为mapmeta:xdmType对对象进行注释,以明确表示应像键集不受约束那样管理对象。 摄取到映射字段的数据必须使用字符串键,并且只能使用字符串或整数值(由additionalProperties.type决定)。

XDM对使用此存储提示设置了以下限制:

  • 映射类型必须是object类型。
  • 映射类型不能定义属性(换句话说,它们定义“空”对象)。
  • 映射类型必须包含描述可以放置在映射中的值的additionalProperties.type字段,即stringinteger

确保仅在绝对必要时使用映射类型字段,因为它们存在以下性能缺陷:

Platform用户界面在如何提取映射类型字段的键方面也存在限制。 虽然对象类型字段可以展开,但映射显示为一个字段。

后续步骤

本指南介绍了如何在API中定义不同的字段类型。 有关XDM字段类型的格式化的详细信息,请参阅XDM字段类型约束指南。

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