本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 数据模型 数据模型表示系统中数据的组织层次结构。此外，它还支持整个设备实现之间的 end-to-end通信。对于托管集成，使用了两种数据模型。托管集成数据模型和物质数据模型的 AWS 实现。它们有相似之处，但也有细微的差异，将在以下主题中概述。 对于第三方设备，这两种数据模型都用于最终用户、托管集成和第三方云提供商之间的通信。要转换来自两个数据模型的设备命令和设备事件之类的消息，需要利用 Cloud-to-Cloud连接器功能。 **Topics** + [托管集成数据模型](managedintegrations-data-model.md) + [AWS 物质数据模型的实现](matter-data-model.md) + [数据模型架构](data-model-schemas.md) # 托管集成数据模型 托管集成数据模型管理最终用户与托管集成之间的所有通信。 **设备层次结构** `endpoint`和`capability`数据元素用于描述托管集成数据模型中的设备。 **`endpoint`** `endpoint`表示该功能提供的逻辑接口或服务。 ``` { "endpointId": { "type":"string" }, "capabilities": Capability[] } ``` **`Capability`** `capability`代表设备功能。 ``` { "$id": "string", // Schema identifier (e.g. /schema-versions/capability/matter.OnOff@1.4) "name": "string", // Human readable name "version": "string", // e.g. 1.0 "properties": Property[], "actions": Action[], "events": Event[] } ``` 对于`capability`数据元素，有三个项目构成该项目：`property``action`、和`event`。它们可用于与设备交互和监控。 + **属性**：设备保持的状态，例如可调光灯的当前亮度等级属性。 + ``` { "name": // Property Name is outside of Property Entity "value": Value, // value represented in any type e.g. 4, "A", [] "lastChangedAt": Timestamp // ISO 8601 Timestamp upto milliseconds yyyy-MM-ddTHH:mm:ss.ssssssZ "mutable": boolean, "retrievable": boolean, "reportable": boolean } ``` + **操作**：可以执行的任务，例如在门锁上锁门。操作可能会产生响应和结果。 + ``` { "name": { "$ref": "/schema-versions/definition/aws.name@1.0" }, //required "parameters": Map, "responseCode": HTTPResponseCode, "errors": { "code": "string", "message": "string" } } ``` + **事件**：本质上是过去状态转换的记录。虽然事件`property`代表当前的状态，但却是过去的日记，包括单调递增的计数器、时间戳和优先级。它们支持捕获状态转换，以及无法轻易实现的数据建模`property`。 + ``` { "name": { "$ref": "/schema-versions/definition/aws.name@1.0" }, //required "parameters": Map } ``` # AWS 物质数据模型的实现 Matter 数据模型的 AWS 实施管理托管集成与第三方云提供商之间的所有通信。 有关更多信息，请参阅 M [atter 数据模型：开发者资源](https://csa-iot.org/resources/developer-resources/page/2/?dr_keywords&dr_solution%5B0%5D=935&dr_lang=1019)。 **设备层次结构** 有两个数据元素用于描述设备：`endpoint`和`cluster`。 **`endpoint`** `endpoint`表示该功能提供的逻辑接口或服务。 ``` { "id": { "type":"string"}, "clusters": Cluster[] } ``` **`cluster`** `cluster`代表设备功能。 ``` { "id": "hexadecimalString", "revision": "string" // optional "attributes": AttributeMap, "commands": CommandMap, "events": EventMap } ``` 对于`cluster`数据元素，有三个项目构成该项目：`attribute``command`、和`event`。它们可用于与设备交互和监控。 + **属性**：设备保持的状态，例如可调光灯的当前亮度等级属性。 + ``` { "id" (hexadecimalString): (JsonNode) value } ``` + **命令**：可以执行的任务，例如在门锁上锁门。命令可能会生成响应和结果。 + ``` "id": { "fieldId": "fieldValue", ... "responseCode": HTTPResponseCode, "errors": { "code": "string", "message": "string" } } ``` + **事件**：本质上是过去状态转换的记录。虽然事件`attributes`代表当前的状态，但却是过去的日记，包括单调递增的计数器、时间戳和优先级。它们支持捕获状态转换，以及无法轻易实现的数据建模`attributes`。 + ``` "id": { "fieldId": "fieldValue", ... } ``` # 数据模型架构 托管集成支持两种架构类型：*功能*和*类型定义*。如果要创建自定义数据模型，则使用 JSON 架构文档来定义任一类型的架构。每个架构文档的字符数限制为 50,000。 ## 能力架构 *功能*是代表端点内特定功能的基本构建块。借助功能，您可以使用属性、操作和事件对设备状态和行为进行建模。*属性*使您可以灵活地使用任何声明性数据类型对设备的状态属性进行建模。*操作*和*事件*对设备的行为进行建模，包括设备可以执行的命令和可以报告的信号。 下图显示了能力架构的高级结构。 ``` Capability | |-- Action |-- Event |-- Property ``` 操作 表示与设备功能的交互的实体。例如，按铃或查看谁在门口。 事件 代表来自设备功能的事件的实体。设备可以发送事件以报告事件、警报或来自传感器（例如敲门声）的活动。 属性 代表设备状态下特定属性的实体。例如，钟声响起或门廊灯亮起 每项功能都包括一个唯一的命名空间标识符、版本信息及其用途描述。架构文档使用语义版本控制来保持向后兼容性，同时启用新功能。 有关更多信息，请参阅 [能力定义架构](schema-for-capability-definitions.md)。 ## 类型定义架构 类型定义是一种声明性的结构化数据类型，可实现可重用性和可组合性。它定义了应如何格式化和限制信息。使用类型定义在 IoT 解决方案中创建标准化数据格式。 每个类型定义包括： + 唯一的命名空间标识符 + 标题 + 描述 + 定义数据格式和约束条件的属性 类型可以是简单的基元，例如具有定义限制的整数或字符串，也可以是复杂的结构，例如枚举或具有多个字段的自定义对象。类型定义使用 JSON 架构语法来指定约束，包括最小值和最大值、字符串长度以及允许的模式。 有关更多信息，请参阅 [类型定义架构](schema-for-type-definitions.md)。 # 能力定义架构 一项功能是使用声明性的 JSON 文档记录的，该文档为该功能在系统中的运行方式提供了明确的协议。 对于权能，必备元素为`$id``name`、`extrinsicId`、，`extrinsicVersion`并且至少在以下一个部分中包含一个元素： + `properties` + `actions` + `events` 权能中的可选元素是`$ref``title`、`description`、`version`、`$defs`和`extrinsicProperties`。有关权能，`$ref`必须参阅`aws.capability`。 以下各节详细介绍了用于能力定义的架构。 ## \$1id（必填） \$1id 元素标识架构定义。它必须遵循以下结构： + 从 `/schema-versions/` URI 前缀开始 + 包括`capability`架构类型 + 使用正斜杠 (`/`) 作为 URI 路径分隔符 + 包括架构标识，片段之间用句点分隔 (`.`) + 使用`@`字符分隔架构 ID 和版本 + 以 semver 版本结尾，使用句点 (`.`) 分隔版本片段 架构标识必须以长度为 3-12 个字符的根命名空间开头，然后是可选的子命名空间和名称。 semver 版本包括主要版本（最多 3 位数）、次要版本（最多 3 位数）和可选的补丁版本（最多 4 位数）。 **注意** 您不能使用保留的命名空间或 `aws` `matter` **Example 示例 \$1id** ``` /schema-version/capability/aws.Recording@1.0 ``` ## \$1ref 该`$ref`元素引用系统中的现有能力。它遵循与`$id`元素相同的约束。 **注意** 类型定义或功能必须与`$ref`文件中提供的值相同。 **Example 示例 \$1ref** ``` /schema-version/definition/aws.capability@1.0 ``` ## 姓名（必填） 名称元素是一个字符串，表示架构文档中的实体名称。它通常包含缩写，必须遵循以下规则： + 仅包含字母数字字符、句点 (.)、正斜杠 (/)、连字符 (-) 和空格 + 以字母开头 + 最多 64 个字符 Amazon Web Services 控制台用户界面和文档中使用名称元素。 **Example 示例名称** ``` Door Lock On/Off Wi-Fi Network Management PM2.5 Concentration Measurement RTCSessionController Energy EVSE ``` ## 删除实例快照 标题元素是架构文档所代表的实体的描述性字符串。它可以包含任何字符，可在文档中使用。能力标题的最大长度为 256 个字符。 **Example 标题示例** ``` Real-time Communication (RTC) Session Controller Energy EVSE Capability ``` ## description 该`description`元素详细解释了架构文档所代表的实体。它可以包含任何字符，可在文档中使用。能力描述的最大长度为 2048 个字符 **Example 示例描述** ``` Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management. ``` ## version `version` 元素是可选的。它是一个表示架构文档版本的字符串。它具有以下限制： + 使用 semver 格式，以下版本片段用`.`（句点）分隔。 + `MAJOR`版本，最多 3 位数 + `MINOR`版本，最多 3 位数 + `PATCH`版本（可选），最多 4 位数 + 长度可以介于 3 到 12 个字符之间。 **Example 示例版本** ``` 1.0 ``` ``` 1.12 ``` ``` 1.4.1 ``` ### 使用功能版本 权能是一个不可变的版本化实体。任何更改都将创建新版本。系统使用 MAJOR.MINOR.PATCH 格式的语义版本控制，其中： + 更改向后不兼容的 API 时，主要版本会增加 + 以向后兼容的方式添加功能时，次要版本会增加 + 在功能中添加一些不起作用的次要添加时，补丁版本会增加。 源自 Matter 集群的功能基于 1.4 版，预计每个 Matter 版本都将导入到系统中。由于 Matter 版本同时消耗 semver 的主要和次要级别，因此托管集成只能使用 PATCH 版本。 在为 Matter 添加补丁版本时，请务必考虑到 Matter 使用顺序修订版。所有 PATCH 版本都必须符合 Matter 规范中记录的修订版，并且必须向后兼容。 要修复任何向后不兼容的问题，您必须与连接标准联盟 (CSA) 合作解决规范中的问题并发布新的修订版。 AWS-托管功能的初始版本为。`1.0`有了这些，就可以使用所有三个级别的版本。 ## 外部版本（必填） 这是一个字符串，表示在 AWS IoT 系统之外管理的版本。对于 Matter 能力，`extrinsicVersion`映射到 `revision` 它以字符串化的整数值表示，长度可以是 1 到 10 位数字。 **Example 示例版本** ``` 7 ``` ``` 1567 ``` ## extrinsiCid（必填） 该`extrinsicId`元素表示在 Amazon Web Services 物联网系统之外管理的标识符。对于 Matter 能力 `clusterId``attributeId`，`commandId`它会根据上下文映射到`fieldId`、、、或。`eventId` `extrinsicId`可以是字符串化的十进制整数（1-10 位数），也可以是字符串化的十六进制整数（0x 或 0X 前缀，后面是 1-8 个十六进制数字）。 **注意** 对于 AWS，供应商 ID (VID) 为 0x1577，对于 Matter，则为 0。系统确保自定义架构不会使用这些 VIDs 为功能保留的内容。 **Example 示例 extinSICID** ``` 0018 0x001A 0x15771002 ``` ## \$1defs 该`$defs`部分是子架构的映射，在 JSON 架构允许的情况下，可以在架构文档中引用这些子架构。在此地图中，键用于本地参考定义，值提供了 JSON 架构。 **注意** 系统仅强制要求该映射`$defs`是有效的映射，并且每个子架构都是有效的 JSON 架构。不强制执行其他规则。 使用定义时，请遵循以下限制： + 在定义名称中仅使用 URI 友好字符 + 确保每个值都是一个有效的子架构 + 包括符合架构文档大小限制的任意数量的子架构 ## 外在特性 该`extrinsicProperties`元素包含一组在外部系统中定义但保留在数据模型中的属性。对于 Matter 功能，它映射到 ZCL 集群、属性、命令或事件中不同的未建模或部分建模的元素。 外在属性必须遵循以下限制： + 属性名称必须是字母数字，不含空格或特殊字符 + 属性值可以是任何 JSON 架构值 + 最多 20 处房产 该系统支持多种功能`extrinsicProperties`，包括`access`、`apiMaturity`、`cli``cliFunctionName`、和其他。这些属性便于 ACL 进行数据模型转换 AWS （反之亦然）。 **注意** 功能的`action`、`event`、和`struct`字段元素支持外部属性`property`，但不支持能力或集群本身。 # 系统支持的外部属性 系统会跟踪以下未建模或部分建模的集群、属性、命令或事件属性，就像转换到 ZCL 或从 ZCL 转换`extrinsicProperties`期间一样： `access` 每个访问对象都包含以下内容： + `op`-操作建模为`enum`，其值为：`read``write`、或 `invoke` + `privilege`-特权建模为`enum`，其值为：`view``proxy_view`、`operate`、`manage`、或 `administer` + `role`-代表操作员角色的无界字符串 `apiMaturity` 代表成熟度水平的无界纯字符串。在 ZCL 中将其建模为，`enum`其值为：`stable`、`provisional``internal`、或 `deprecated` `side` 以枚举形式建模，其值为：`either``server`、和 `client` 布尔属性 以下属性是布尔标志： + `isFabricScoped` + `isFabricSensitive` + `mustUseAtomicWrite` + `mustUseTimedInvoke` 字符串属性 以下属性表示为无界字符串： + `cli` + `cliFunctionName` + `functionName` + `group` + `introducedIn` + `manufacturerCode` + `noDefaultImplementation` + `presentIf` + `priority` + `removedIn` + `reportableChange` + `reportMinInterval` + `reportMaxInterval` + `restriction` + `storage` ### 转型注意事项 对于 ZCL 变换`extrinsicProperties`，无需处理即可存储在地图中。使用发现功能的自定义架构不会进行 ZCL 转换。但是，如果您计划将来为自定义架构实现 ZCL 转换，则必须对所有无界纯字符串类型进行建模，`extrinsicProperties`并定义诸如枚举、模式（正则表达式）和长度之类的约束。这种准备工作可确保在转换过程中正确处理这些特性。 相比之下，对于连接器的 AWS 转换，`extrinsicProperties`则根本不包括在内，因为连接器格式中不需要这些细节。 ## 属性 属性表示该功能的设备管理状态。每个状态都被定义为一个键值对，其中键描述状态的名称，值描述状态的定义。 使用属性时，请遵循以下限制： + 在属性名称中仅使用字母数字字符，不得使用空格或特殊字符 + 包括符合架构文档大小限制的任意数量的属性 ### 使用属性 功能中的属性是一个基本元素，它代表由托管集成提供支持的设备的特定状态。它代表设备的当前状态或配置。通过标准化这些属性的定义和结构，智能家居系统可确保来自不同制造商的设备能够进行有效通信，从而创造无缝且可互操作的体验。 对于能力属性，必填元素为`extrinsicId`和`value`。能力属性中的可选元素是`description``retrievable`、`mutable`、`reportable`和`extrinsicProperties`。 #### 值 一种无界结构，允许生成器设置任何符合 JSON 架构的约束来定义此属性的数据类型。 定义值时，请遵循以下约束： + 对于简单类型，请使用`type`和任何其他原生 JSON 架构约束，例如或 `maxLength` `maximum` + 对于复合类型，请使用`oneOf``allOf`、或`anyOf`。系统不支持该`not`关键字 + 要引用任何全局类型，请`$ref`使用有效的可发现引用 + 为了获得空性，请遵循 OpenAPI 类型架构定义，为可空属性提供布尔标志（`true`如果允许的值为 null） 示例： ``` { "$ref": "/schema-versions/definition/matter.uint16@1.4", "nullable": true, "maximum": 4096 } ``` #### 可检索 描述状态是否可读的布尔值。 状态的可读性方面将推迟到设备对功能的实现。设备决定给定状态是否可读。目前尚不支持在能力报告中报告状态的这一方面，因此不支持在系统内强制执行。 示例：`true` 或 `false` #### Mutable 描述状态是否可写的布尔值。 状态的可写性方面被推迟到设备对功能的实现。设备决定给定状态是否可写。目前尚不支持在能力报告中报告状态的这一方面，因此不支持在系统内强制执行。 示例：`true` 或 `false` #### 可报告 一个布尔值，用于描述状态发生变化时设备是否报告状态。 状态的可报告性方面将推迟到设备对功能的实现。设备决定给定状态是否可报告。目前尚不支持在能力报告中报告状态的这一方面，因此不支持在系统内强制执行。 示例：`true` 或 `false` ## 操作 操作是遵循请求-响应模型的架构管理操作。每个操作都代表一个设备实现的操作。 在实施操作时，请遵循以下限制： + 在操作数组中仅包含唯一的动作 + 包括符合架构文档大小限制的任意数量的操作 ### 使用操作 操作是与托管集成系统中的设备功能进行交互和控制的标准化方式。它代表可在设备上执行的特定命令或操作，并采用结构化格式，用于对任何必要的请求或响应参数进行建模。这些操作是用户意图和设备操作之间的桥梁，可实现对不同类型的智能设备进行一致而可靠的控制。 对于操作，必填元素为`name`和`extrinsicId`。可选元素是`description``extrinsicProperties`、`request`和`response`。 ### 描述 描述的最大长度限制为 1536 个字符。 ### 请求 请求部分是可选的，如果没有请求参数，则可以省略。如果省略，则系统支持仅使用名称发送没有任何有效载荷的请求`Action`。这用于简单的操作，例如打开或关闭灯。 复杂的动作需要额外的参数。例如，直播摄像机镜头的请求可能包含有关要使用的流媒体协议或是否将直播发送到特定显示设备的参数。 对于操作请求，必填元素为`parameters`。可选元素是`description``extrinsicId`、和`extrinsicProperties`。 #### 请求描述 描述采用与第 3.5 节相同的格式，最大长度为 2048 个字符。 ### 响应 在托管集成中，对于通过 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API 发送的任何操作请求，该请求都会到达设备并期望得到异步响应。操作响应定义了该响应的结构。 对于操作请求，必填元素为`parameters`。可选元素是`name``description`、`extrinsicId`、`extrinsicProperties`、`errors`和`responseCode`。 #### 响应描述 描述采用与相同的格式[description](#capability-schema-description)，最大长度为 2048 个字符。 #### 响应名称 该名称的格式与以下内容相同[姓名（必填）](#capability-schema-name)，但有以下额外细节： + 响应的常规名称是通过附加`Response`到操作名称得出的。 + 如果要使用其他名称，则可以在此`name`元素中提供该名称。如果响应中提供了 a`name`，则此值的优先级高于常规名称。 #### 错误 如果在处理请求时出现错误，则在响应中提供的唯一消息的无限数组。 约束： + 消息项声明为 JSON 对象，其中包含以下字段： + `code`: 包含字母数字字符和`_`（下划线）的字符串，长度介于 1 到 64 个字符之间 + `message`: 一个无界限的字符串值 **Example 错误消息示例** ``` "errors": [ { "code": "AD_001", "message": "Unable to receive signal from the sensor. Please check connection with the sensor." } ] ``` #### 响应代码 显示请求处理方式的整数代码。我们建议设备代码返回使用 HTTP 服务器响应状态码规范的代码，以实现系统内部的一致性。 约束：一个介于 100 到 599 之间的整数值。 ### 请求或响应参数 参数部分定义为名称和子架构对的映射。如果可以容纳在架构文档中，则可以在请求参数中定义任意数量的参数。 参数名称只能包含字母数字字符。不允许使用空格或任何其他字符。 #### 参数字段 a 中的必填元素`parameter`是`extrinsicId`和`value`。可选元素为`description`和`extrinsicProperties`。 描述元素的格式与相同[description](#capability-schema-description)，最大长度为 1024 个字符。 ### `extrinsicId`并`extrinsicProperties`覆盖 `extrinsicId`和`extrinsicProperties`的格式与[extrinsiCid（必填）](#capability-schema-extrinsicId)和相同[外在特性](#capability-schema-extrinsicProperties)，但有以下额外细节： + 如果在请求或响应中提供了，`extrinsicId`则该值的优先级高于在操作级别提供的值。系统必须`extrinsicId`先使用 request/response 关卡，如果缺少则使用操作关卡 `extrinsicId` + 如果`extrinsicProperties`在请求或响应中提供，则这些属性的优先级高于在操作级别提供的 va 值。系统必须采取操作级别`extrinsicProperties`并替换该级别提供的键值对 request/response `extrinsicProperties` **Example extrinsicID 和 extrinsicProperties** ``` { "name": "ToggleWithEffect", "extrinsicId": "0x0001", "extrinsicProperties": { "apiMaturity": "provisional", "introducedIn": "1.2" }, "request": { "extrinsicProperties": { "apiMaturity": "stable", "manufacturerCode": "XYZ" }, "parameters": { ... } }, "response": { "extrinsicProperties": { "noDefaultImplementation": true }, "parameters": { { ... } } } ``` 在上面的示例中，操作请求的有效值为： ``` # effective request "name": "ToggleWithEffect", "extrinsicId": "0x0001", "extrinsicProperties": { "apiMaturity": "stable", "introducedIn": "1.2" "manufacturerCode": "XYZ" }, "parameters": { ... } # effective response "name": "ToggleWithEffectResponse", "extrinsicId": "0x0001", "extrinsicProperties": { "apiMaturity": "provisional", "introducedIn": "1.2" "noDefaultImplementation": true }, "parameters": { ... } ``` ### 内置动作 对于所有功能，您可以使用关键字`ReadState`和执行自定义操作`UpdateState`。这两个操作关键字将作用于数据模型中定义的功能属性。 ReadState 向发送命令`managedThing`以读取其状态属性的值。`ReadState`用作强制更新设备状态的一种方式。 UpdateState 发送命令以更新某些属性。 在以下情况下，强制设备状态同步可能很有用： 1. 设备处于离线状态一段时间，未发出任何事件。 1. 该设备刚刚配置完毕，尚未在云中维护任何状态。 1. 设备状态与设备的实际状态不同步。 #### ReadState 例子 使用 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API 检查灯是开还是关： ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "aws.OnOff", "name": "On/Off", "version": "1", "actions": [ { "name": "ReadState", "parameters": { "propertiesToRead": [ "OnOff" ] } } ] } ] } ] } ``` 读取该`matter.OnOff`功能的所有状态属性： ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "aws.OnOff", "name": "On/Off", "version": "1", "actions": [ { "name": "ReadState", "parameters": { "propertiesToRead": [ "*" ] // Use the wildcard operator to read ALL state properties for a capability } } ] } ] } ] } ``` #### UpdateState 示例 使用 [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API 更改`OnTime`为灯光： ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "matter.OnOff", "name": "On/Off", "version": "1", "actions": [ { "name": "UpdateState", "parameters": { "OnTime": 5 } } ] } ] } ] } ``` ## 事件 事件是由设备实现的架构管理的单向信号。 根据以下限制实现事件： + 在事件数组中仅包含唯一的事件 + 包括符合架构文档大小限制的任意数量的事件 # 托管集成系统中的事件 ### 处理 事件 事件是一种主动了解设备或其周围环境变化的标准化方式。它表示设备将发送到云端的建模事件，以提供有关在设备上修改或在其环境中感知到的内容的信息。由于这些事件是建模的，因此客户可以在控制流中使用它们来对特定事件以及其中提供的详细信息做出反应。 对于事件，必填元素为`name`和`extrinsicId`。可选元素是`description``extrinsicProperties`、和`request`。 ### 描述 描述采用与中所述相同的格式[description](schema-for-capability-definitions.md#capability-schema-description)，最大长度为 512 个字符。 ### 请求 该`request`部分是可选的，如果没有请求参数，则可以省略。如果省略，则系统支持设备仅使用事件名称发送没有任何有效负载的事件请求。这用于简单的事件，例如泵上的传感器故障，或者烟雾或一氧化碳警报器上的警报被静音。 复杂的动作需要额外的参数。例如，直播摄像机镜头的请求可能包含有关要使用的流媒体协议或是否将直播发送到特定显示设备的参数。 对于活动请求，必填元素为`parameters`。没有可选元素。 ### 响应 目前不支持事件响应。 # 类型定义架构 以下各节详细介绍了用于类型定义的架构。 ## \$1id \$1id 元素标识架构定义。它必须遵循以下结构： + 从 `/schema-versions/` URI 前缀开始 + 包括`definition`架构类型 + 使用正斜杠 (`/`) 作为 URI 路径分隔符 + 包括架构标识，片段之间用句点分隔 (`.`) + 使用`@`字符分隔架构 ID 和版本 + 以 semver 版本结尾，使用句点 (`.`) 分隔版本片段 架构标识必须以长度为 3-12 个字符的根命名空间开头，然后是可选的子命名空间和名称。 semver 版本包括主要版本（最多 3 位数）、次要版本（最多 3 位数）和可选的补丁版本（最多 4 位数）。 **注意** 您不能使用保留的命名空间或 `aws` `matter` **Example 示例 \$1id** ``` /schema-version/capability/aws.Recording@1.0 ``` ## \$1ref \$1ref `` 元素引用系统中现有的类型定义。它遵循与`$id`元素相同的约束。 **注意** 类型定义或功能必须与`$ref`文件中提供的值相同。 **Example 示例 \$1ref** ``` /schema-version/definition/aws.capability@1.0 ``` ## 名称 名称元素是一个字符串，表示架构文档中的实体名称。它通常包含缩写，必须遵循以下规则： + 仅包含字母数字字符、句点 (.)、正斜杠 (/)、连字符 (-) 和空格 + 以字母开头 + 最多 192 个字符 Amazon Web Services 控制台用户界面和文档中使用名称元素。 **Example 示例名称** ``` Door Lock On/Off Wi-Fi Network Management PM2.5 Concentration Measurement RTCSessionController Energy EVSE ``` ## 删除实例快照 标题元素是架构文档所代表的实体的描述性字符串。它可以包含任何字符，可在文档中使用。 **Example 标题示例** ``` Real-time Communication (RTC) Session Controller Energy EVSE Capability ``` ## description 该`description`元素详细解释了架构文档所代表的实体。它可以包含任何字符，可在文档中使用。 **Example 示例描述** ``` Electric Vehicle Supply Equipment (EVSE) is equipment used to charge an Electric Vehicle (EV) or Plug-In Hybrid Electric Vehicle. This capability provides an interface to the functionality of Electric Vehicle Supply Equipment (EVSE) management. ``` ## extrinsiCID 该`extrinsicId`元素表示在 Amazon Web Services 物联网系统之外管理的标识符。对于 Matter 能力，它会映射到`clusterId``attributeId``commandId``eventId`、、`fieldId`、或，具体取决于上下文。 `extrinsicId`可以是字符串化的十进制整数（1-10 位数），也可以是字符串化的十六进制整数（0x 或 0X 前缀，后面是 1-8 个十六进制数字）。 **注意** 对于 AWS，供应商 ID (VID) 为 0x1577，对于 Matter，则为 0。系统确保自定义架构不会使用这些 VIDs 为功能保留的内容。 **Example 示例 extinSICID** ``` 0018 0x001A 0x15771002 ``` ## 外在特性 该`extrinsicProperties`元素包含一组在外部系统中定义但保留在数据模型中的属性。对于 Matter 功能，它映射到 ZCL 集群、属性、命令或事件中不同的未建模或部分建模的元素。 外在属性必须遵循以下限制： + 属性名称必须是字母数字，不含空格或特殊字符 + 属性值可以是任何 JSON 架构值 + 最多 20 处房产 该系统支持多种功能`extrinsicProperties`，包括`access`、`apiMaturity`、`cli``cliFunctionName`、和其他。这些属性便于 ACL 进行数据模型转换 AWS （反之亦然）。 **注意** 功能的`action`、`event`、和`struct`字段元素支持外部属性`property`，但不支持能力或集群本身。 # 系统支持的外部属性 系统会跟踪以下未建模或部分建模的集群、属性、命令或事件属性，就像转换到 ZCL 或从 ZCL 转换`extrinsicProperties`期间一样： `access` 每个访问对象都包含以下内容： + `op`-操作建模为`enum`，其值为：`read``write`、或 `invoke` + `privilege`-特权建模为`enum`，其值为：`view``proxy_view`、`operate`、`manage`、或 `administer` + `role`-代表操作员角色的无界字符串 `apiMaturity` 代表成熟度水平的无界纯字符串。在 ZCL 中将其建模为，`enum`其值为：`stable`、`provisional``internal`、或 `deprecated` `side` 以枚举形式建模，其值为：`either``server`、和 `client` 布尔属性 以下属性是布尔标志： + `isFabricScoped` + `isFabricSensitive` + `mustUseAtomicWrite` + `mustUseTimedInvoke` 字符串属性 以下属性表示为无界字符串： + `cli` + `cliFunctionName` + `functionName` + `group` + `introducedIn` + `manufacturerCode` + `noDefaultImplementation` + `presentIf` + `priority` + `removedIn` + `reportableChange` + `reportMinInterval` + `reportMaxInterval` + `restriction` + `storage` ### 转型注意事项 对于 ZCL 变换`extrinsicProperties`，无需处理即可存储在地图中。使用发现功能的自定义架构不会进行 ZCL 转换。但是，如果您计划将来为自定义架构实现 ZCL 转换，则必须对所有无界纯字符串类型进行建模，`extrinsicProperties`并定义诸如枚举、模式（正则表达式）和长度之类的约束。这种准备工作可确保在转换过程中正确处理这些特性。 相比之下，对于连接器的 AWS 转换，`extrinsicProperties`则根本不包括在内，因为连接器格式中不需要这些细节。 # 在能力架构文档中构建和使用类型定义 架构中的所有元素都解析为类型定义。这些类型定义要么是*原始类型定义*（例如布尔值、字符串、数字），要么是*命名空间类型定义*（为方便起见，根据原始类型定义构建的类型定义）。 定义自定义架构时，可以使用原始定义和命名空间类型定义。 **Contents** + [原始类型定义](#primitive-type-definitions) + [布尔运算](#boolean-types) + [整数类型支持](#integers-support) + [数字](#numbers) + [字符串](#strings) + [null](#nulls) + [数组](#arrays) + [对象](#objects) + [命名空间类型定义](#namespaced-type-definitions) + [`matter` 类型](#matter-types) + [`aws` 类型](#aws-types) + [位图类型定义](#bitmap-type-definition) + [枚举类型定义](#enum-type-definition) ## 原始类型定义 原始类型定义是托管集成中定义的所有类型定义的基石。所有命名空间定义，包括自定义类型定义，都通过`$ref`关键字或关键字解析为原始类型定义。`type` 使用关键字可以为空所有原始类型，并且可以使用`nullable`关键字来标识所有原始类型。`type` ### 布尔运算 布尔类型支持默认值。 示例定义： ``` { "type" : "boolean", "default" : "false", "nullable" : true } ``` ### 整数类型支持 整数类型支持以下内容： + `default` 值 + `maximum` 值 + `minimum` 值 + `exclusiveMaximum` 值 + `exclusiveMinimum` 值 + `multipleOf` 值 如果`x`正在验证该值，则以下条件必须为真： + `x` ≥ `minimum` + `x` > `exclusiveMinimum` + `x` < `exclusiveMaximum` **注意** 小数部分为零的数字被视为整数，但不接受浮点数。 ``` 1.0 // Schema-Compliant 3.1415926 // NOT Schema-Compliant ``` 虽然您可以同时指定`minimum`和 `exclusiveMinimum` /或同时指定`maximum`和`exclusiveMaximum`，但我们不建议同时使用两者。 示例定义： ``` { "type" : "integer", "default" : 2, "nullable" : true, "maximum" : 10, "minimum" : 0, "multipleOf": 2 } ``` 替代定义： ``` { "type" : "integer", "default" : 2, "nullable" : true, "exclusiveMaximum" : 11, "exclusiveMinimum" : -1, "multipleOf": 2 } ``` ### 数字 将数字类型用于任何数值类型，包括整数和浮点数。 数字类型支持以下内容： + `default` 值 + `maximum` 值 + `minimum` 值 + `exclusiveMaximum` 值 + `exclusiveMinimum` 值 + `multipleOf`价值观。倍数可以是浮点数。 如果`x`正在验证该值，则以下条件必须为真： + `x` ≥ `minimum` + `x` > `exclusiveMinimum` + `x` < `exclusiveMaximum` 虽然您可以同时指定`minimum`和 `exclusiveMinimum` /或同时指定`maximum`和`exclusiveMaximum`，但我们不建议同时使用两者。 示例定义： ``` { "type" : "number", "default" : 0.4, "nullable" : true, "maximum" : 10.2, "minimum" : 0.2, "multipleOf": 0.2 } ``` 替代定义： ``` { "type" : "number", "default" : 0.4, "nullable" : true, "exclusiveMaximum" : 10.2, "exclusiveMinimum" : 0.2, "multipleOf": 0.2 } ``` ### 字符串 字符串类型支持以下内容： + `default` 值 + 长度约束（必须是非负数），包括`maxLength`和`minLength`值 + `pattern`正则表达式的值 定义正则表达式时，如果该表达式与字符串中的任意位置匹配，则该字符串有效。例如，正则表达式`p`匹配任何包含 p 的字符串，例如 “apple”，而不仅仅是字符串 “p”。为清楚起见，我们建议在正则表达式周围加上`^...$`（例如，`^p$`），除非您有具体的理由不这样做。 示例定义： ``` { "type" : "string", "default" : "defaultString", "nullable" : true, "maxLength": 10, "minLength": 1, "pattern" : "^([0-9a-fA-F]{2})+$" } ``` ### null Null 类型仅接受单个值：`null`。 示例定义： ``` { "type": "null" } ``` ### 数组 数组类型支持以下内容： + `default`— 将用作默认值的列表。 + `items`— 对所有数组元素施加的 JSON 类型定义。 + 长度限制（必须为非负数） + `minItems` + `maxItems` + `pattern`正则表达式的值 + `uniqueItems`— 一个布尔值，表示数组中的元素是否需要唯一 + `prefixItems`— 一个数组，其中每个项目都是一个架构，对应于文档数组的每个索引。也就是说，一个数组，其中第一个元素验证输入数组的第一个元素，第二个元素验证输入数组的第二个元素，依此类推。 示例定义： ``` { "type": "array", "default": ["1", "2"], "items" : { "type": "string", "pattern": "^([a-zA-Z0-9_ -/]+)$" }, "minItems" : 1, "maxItems": 4, "uniqueItems" : true, } ``` 数组验证示例： ``` //Examples: ["1", "2", "3", "4"] // Schema-Compliant [] // NOT Schema-Compliant: minItems=1 ["1", "1"] // NOT Schema-Compliant: uniqueItems=true ["{"] // NOT Schema-Compliant: Does not match the RegEx pattern. ``` 使用元组验证的替代定义： ``` { "type": "array", "prefixItems": [ { "type": "number" }, { "type": "string" }, { "enum": ["Street", "Avenue", "Boulevard"] }, { "enum": ["NW", "NE", "SW", "SE"] } ] } //Examples: [1600, "Pennsylvania", "Avenue", "NW"] // Schema-Compliant // And, by default, it's also okay to add additional items to end: [1600, "Pennsylvania", "Avenue", "NW", "Washington"] // Schema-Compliant ``` ### 对象 对象类型支持以下内容： + 属性限制 + `properties`— 使用关键字定义对象的属性（键值对）。`properties`的值`properties`是一个对象，其中每个键是属性的名称，每个值都是用于验证该属性的架构。任何与关键字中的任何属性名称都不匹配的属性将被该`properties`关键字忽略。 + `required`— 默认情况下，由`properties`关键字定义的属性不是必需的。但是，您可以使用`required`关键字提供所需属性的列表。该`required`关键字采用由零个或多个字符串组成的数组。这些字符串中的每一个都必须是唯一的。 + `propertyNames`— 此关键字允许控制属性名称的 RegEx 模式。例如，您可能需要强制要求对象的所有属性都具有遵循特定惯例的名称。 + `patternProperties`— 这会将正则表达式映射到架构。如果属性名称与给定的正则表达式匹配，则该属性值必须根据相应的架构进行验证。例如，在给定特定类型的属性名称的情况下，使用`patternProperties`来指定值应与特定架构相匹配。 + `additionalProperties`— 此关键字控制如何处理额外属性。额外属性是指名称未在 properties 关键字中列出或与中的任何正则表达式匹配的属性`patternProperties`。默认情况下，允许使用其他属性。将此字段设置为`false`意味着不允许使用其他属性。 + `unevaluatedProperties`— 此关键字与类`additionalProperties`似，不同之处在于它可以识别子架构中声明的属性。 `unevaluatedProperties`通过收集在处理架构时成功验证的所有属性并将其用作允许的属性列表来工作。这允许你做更复杂的事情，例如有条件地添加属性。有关更多详细信息，请参阅以下示例。 + `anyOf`— 此关键字的值必须为非空数组。数组中的每个项目都必须是有效的 JSON 架构。如果实例成功针对该关键字的值定义的*至少*一个架构进行验证，则该实例成功地针对该关键字进行验证。 + `oneOf`— 此关键字的值必须为非空数组。数组中的每个项目都必须是有效的 JSON 架构。如果实例仅针对该关键字的值定义的一个架构成功验证，则该*实例*成功地针对该关键字进行验证。 必填示例： ``` { "type": "object", "required": ["test"] } // Schema Compliant { "test": 4 } // NOT Schema Compliant {} ``` PropertyNames 示例： ``` { "type": "object", "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } // Schema Compliant { "_a_valid_property_name_001": "value" } // NOT Schema Compliant { "001 invalid": "value" } ``` PatternProperties 示例： ``` { "type": "object", "patternProperties": { "^S_": { "type": "string" }, "^I_": { "type": "integer" } } } // Schema Compliant { "S_25": "This is a string" } { "I_0": 42 } // NOT Schema Compliant { "S_0": 42 } // Value must be a string { "I_42": "This is a string" } // Value must be an integer ``` AdditionalProperties 示例： ``` { "type": "object", "properties": { "test": { "type": "string" } }, "additionalProperties": false } // Schema Compliant { "test": "value" } OR {} // NOT Schema Compliant { "notAllowed": false } ``` UnevaluatedProperties 示例： ``` { "type": "object", "properties": { "standard_field": { "type": "string" } }, "patternProperties": { "^@": { "type": "integer" } // Allows properties starting with '@' }, "unevaluatedProperties": false // No other properties allowed } // Schema Compliant { "standard_field": "some value", "@id": 123, "@timestamp": 1678886400 } // This passes because "standard_field" is evaluated by properties, // "@id" and "@timestamp" are evaluated by patternProperties, // and no other properties remain unevaluated. // NOT Schema Compliant { "standard_field": "some value", "another_field": "unallowed" } // This fails because "another_field" is unevaluated and doesn't match // the @ pattern, leading to a violation of unevaluatedProperties: false ``` AnyOf 示例： ``` { "anyOf": [ { "type": "string", "maxLength": 5 }, { "type": "number", "minimum": 0 } ] } // Schema Compliant "short" 12 // NOT Schema Compliant "too long" -5 ``` OneOf 示例： ``` { "oneOf": [ { "type": "number", "multipleOf": 5 }, { "type": "number", "multipleOf": 3 } ] } // Schema Compliant 10 9 // NOT Schema compliant 2 // Not a multiple of either 5 or 3 15 // Multiple of both 5 and 3 is rejected. ``` ## 命名空间类型定义 命名空间类型定义是根据原始类型构建的类型。这些类型必须遵循`namespace.typename.`托管集成在`aws`和`matter`命名空间下提供预定义类型的格式。除了保留空间`aws`和命名空间之外，您可以为自定义类型使用任何命`matter`名空间。 要查找可用的命名空间类型定义，请使用`Type`过滤器设置为 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API。`definition` ### `matter` 类型 使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API 在`matter`命名空间下查找数据类型`matter`，`Type`筛选器设置为`definition`。`Namespace` ### `aws` 类型 使用 [ListSchemaVersions](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_ListSchemaVersions.html)API 在`aws`命名空间下查找数据类型`aws`，`Type`筛选器设置为`definition`。`Namespace` #### 位图类型定义 位图有两个必需的属性： + `type`必须是对象 + `properties`必须是包含每个位定义的对象。每个位都是一个具有属`extrinsicId`性和的对象`value`。每个位的值必须是一个整数，最小值为 0，最大值至少为 1。 位图定义示例： ``` { "title" : "Sample Bitmap Type", "description" : "Type definition for SampleBitmap.", "$ref" : "/schema-versions/definition/aws.bitmap@1.0 ", "type" : "object", "additionalProperties" : false, "properties" : { "Bit1" : { "extrinsicId" : "0x0000", "value" : { "type" : "integer", "maximum" : 1, "minimum" : 0 } }, "Bit2" : { "extrinsicId" : "0x0001", "value" : { "type" : "integer", "maximum" : 1, "minimum" : 0 } } } } // Schema Compliant { "Bit1": 1, "Bit1": 0 } // NOT Schema Compliant { "Bit1": -1, "Bit1": 0 } ``` #### 枚举类型定义 枚举需要三个属性： + `type`必须是对象 + `enum`必须是一个由唯一字符串组成的数组，至少包含一个项目 + `extrinsicIdMap`是一个对象，其属性是枚举值。每个属性的值都应该是与枚举值相对应的外部标识符。 枚举定义示例： ``` { "title" : "SampleEnum Type", "description" : "Type definition for SampleEnum.", "$ref" : "/schema-versions/definition/aws.enum@1.0", "type" : "string", "enum" : [ "EnumValue0", "EnumValue1", "EnumValue2" ], "extrinsicIdMap" : { "EnumValue0" : "0", "EnumValue1" : "1", "EnumValue2" : "2" } } // Schema Compliant "EnumValue0" "EnumValue1" "EnumValue2" // NOT Schema Compliant "NotAnEnumValue" ```