为自定义对象创建模式
Custom Objects API允许您创建基于蓝图的对象记录模式——是你自己设计的。模式定义了自定义对象的命名属性。模式不包含关于任何特定对象的信息。它只是描述信息。
您还可以在模式中定义验证规则，以维护对象记录的数据完整性。
自定义对象API中的模式基于JSON模式规范。有关更多信息，请参阅json schema.org上的以下资源:亚博电脑端
理解自定义对象API中的模式
模式是用于创建和验证某种类型的对象记录的模板。下面的例子是健身课程的一个可能的模式:
| 的名字 | 类型 | 要求 | 描述 |
|---|---|---|---|
| id | 字符串 | 是的 | 分配给健身类的唯一标识符 |
| 的名字 | 字符串 | 是的 | 健身班的友好公众名字 |
| 大小 | 数量 | 没有 | 允许参加课程的最大人数 |
模式由JSON对象中的关键字/值对组成。关键字中是否定义了模式属性JSON模式规范。自定义对象支持以下关键字:
- 标题
- 描述
- 属性
- 类型
- 项目
- 要求
的一部分定义模式创建对象类型自定义对象API。下面的示例展示了创建对象类型的JSON有效负载。
｛“数据”：｛“关键”：“fitness_class”，“模式”：｛“属性”：｛“id”：｛“类型”：“字符串”，“描述”："分配给健身类的唯一标识符"｝，“名称”：｛“类型”：“字符串”，“描述”：“健身课的友好公众名称”｝，“大小”：｛“类型”：“数量”，“描述”：“允许上这门课的最大人数”｝｝，“要求”：［“id”，“名称”］｝｝｝
这个例子使用了以下JSON Schema关键字:“属性”，“类型”，“描述”,“要求”．
定义自定义对象的属性
属性为自定义对象定义所需的任何属性JSON模式规范，但本节中描述的例外情况除外。
一个典型的属性定义由一个属性名和一个来自JSON Schema的带有“type”关键字的对象组成。
“模式”：｛“属性”：｛“exercise_room”：｛“类型”：“字符串”｝｝｝
模式属性名没有标准约定。使用snake_case或camelCase是常见的。名称出现在来自自定义对象API的HTTP响应的JSON体中，因此使用对将使用数据的应用程序有意义的名称。
对于自定义对象，属性适用以下命名规则:
- 名称不能以下划线(“_”)开头
- 不能使用星号(“*”)作为名称
- 不能使用以下转义字符:"\b"， "\f"， "\n"， "\r"， "\t"， "\u0007"， "\u0013"
在JSON模式中，对象的属性不局限于模式中的属性。然而，对于自定义对象，属性仅限于模式中的属性。如果自定义对象API接收到创建或更新具有不在模式中的属性的对象记录的请求，API将返回“422不可处理实体”状态。响应指定请求具有模式不允许的属性。如果您试图通过使用“additionalProperties”:真的在模式中，API返回一个400坏请求错误。
JSON模式支持在模式中完全不定义任何属性。然而，对于自定义对象，模式必须至少定义一个属性。
指定所需的属性
默认情况下，模式定义的所有属性都是可选的。对于自定义对象，您可能至少需要一个或多个必需属性。必需属性的一个典型示例是记录id或名称。
使用"required"关键字为一个对象指定一个或多个必需属性。关键字接受一个属性名数组。例子(强调):
“模式”：｛“属性”：｛“名称”：｛“类型”：“字符串”｝，“电子邮件”：｛“类型”：“字符串”｝，“地址”：｛“类型”：“字符串”｝｝，“要求”：［“名称”，“电子邮件”］｝
如果自定义对象API接收到一个创建记录的请求，但没有提供所需的属性，API将返回“422不可处理实体”状态。响应指定请求缺少一个属性。
验证属性的数据类型
在创建或更新该对象类型的记录时，可以在模式中使用“type”关键字来验证数据。API仅在为属性提供的值与声明的数据类型匹配时才创建或更新记录。
“模式”：｛“属性”：｛“num_locations”：｛“类型”：“数量”｝｝｝
例如，如果你为一个属性指定了一个期望数组的字符串，API将返回一个“422 Unprocessable Entity”状态。响应指定请求的属性与允许的类型不匹配。
“type”可以是以下类型之一:
- string - Unicode字符串
- 整数-一个整数
- 数字-任何数字类型，整数或浮点数
- 数组——一个有序的值列表
- 布尔-真或假
自定义对象不支持null和对象类型。
对于自定义对象，您只能为属性指定一种类型。在JSON Schema中，您可以通过指定一个受支持的类型数组来指定多个类型，例如"type": ["string"， "number"]．
如果你根本不想执行任何数据验证，就不要为属性指定类型:
“模式”：｛“属性”：｛“num_locations”：｛｝｝｝
在这种情况下，API将接受属性的任何数据类型。
例外:定义数组类型的属性时，必须包含项目元素，该元素定义数组中项的类型。项的类型可以是布尔值、整数、数字或字符串。
｛“类型”：“数组”，“项目”：｛“类型”：“数量”｝｝
验证字符串
您可以验证字符串是否太长或太短。您还可以根据正则表达式验证字符串，以确保它遵循特定的格式，例如电子邮件地址或电话号码的格式。
属性的类型必须声明为“字符串”。
要验证字符串的长度，使用"minLength"和"maxLength"关键字。例子:
“属性”：｛“exercise_room”：｛“类型”：“字符串”，“最小长度”：3.，“最大长度”：18｝｝
如果自定义对象API接收到创建或更新字符串太长或太短的记录的请求，API将返回“422不可处理实体”状态。响应指定字符串太长或太短。
要根据正则表达式验证字符串，请使用"pattern"关键字。例子:
“属性”：｛“phone_number”：｛“类型”：“字符串”，“模式”：“^ (\ [0 - 9]{3}\))?［0-9]{3}-[0-9]{4}$"｝｝
如果自定义对象API接收到一个创建或更新记录的请求，该记录的字符串与模式不匹配，API将返回“422不可处理实体”状态。响应指定正则表达式与输入字符串不匹配。
将属性限制为一组固定的值
您可能希望将属性值限制为一小组可能的值。例如，您可能希望“status”属性的值为“planned”、“started”或“done”之一。
使用“enum”关键字将属性的可能值限制为一组固定的值。
“状态”：｛“类型”：“字符串”，“枚举”：［“计划”，“开始”，“完成”］｝
如果自定义对象API接收到一个创建或更新记录的请求，该记录的值不是可能的值之一，API将返回“422不可处理实体”状态。响应指定在枚举中没有找到字符串。
将一个数字限制在一个值范围内
您可以使用“minimum”和“maximum”关键字为类型为number的属性指定可接受的值范围。在下面的示例中，属性的值可以是0到30之间的任何数字，包括。
“属性”：｛“num_weeks”：｛“类型”：“数量”，“最低”：0，“最大”：30.｝｝
要排除起始或结束范围值，请使用" exclusivminimum "或" exclusivmaximum "。
如果自定义对象API接收到一个创建或更新记录的请求，该数字超出了范围，API将返回“422不可处理实体”状态。响应指定数字低于所需的最小值或高于所需的最大值。
注释您的模式
您可以为可能使用或编辑该模式的其他人注释模式。注释还可以构成为自定义对象创建的开发人员文档的基础。
您可以使用以下关键字的任意组合来注释模式:
- 标题-简短描述
- 描述-关于数据用途的较长解释
没有一个关键字是必需的，并且该信息对验证数据没有影响。
例子:
“距离”：｛“类型”：“数量”，“标题”：“比赛距离”，“描述”：“自行车比赛距离(公里)”｝
任何人都可以得到这些信息检索对象类型自定义对象API。
请注意:自定义对象API目前不支持JSON模式中的“examples”关键字。