本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 能力定义架构 一项功能是使用声明性的 JSON 文档记录的，该文档为该功能在系统中的运行方式提供了明确的协议。 对于权能，必备元素为`$id``name`、`extrinsicId`、，`extrinsicVersion`并且至少在以下一个部分中包含一个元素： + `properties` + `actions` + `events` 权能中的可选元素是`$ref``title`、`description`、`version`、`$defs`和`extrinsicProperties`。有关权能，`$ref`必须参阅`aws.capability`。 以下各节详细介绍了用于能力定义的架构。 ## $id（必填） $id 元素标识架构定义。它必须遵循以下结构： + 从 `/schema-versions/` URI 前缀开始 + 包括`capability`架构类型 + 使用正斜杠 (`/`) 作为 URI 路径分隔符 + 包括架构标识，片段之间用句点分隔 (`.`) + 使用`@`字符分隔架构 ID 和版本 + 以 semver 版本结尾，使用句点 (`.`) 分隔版本片段 架构标识必须以长度为 3-12 个字符的根命名空间开头，然后是可选的子命名空间和名称。 semver 版本包括主要版本（最多 3 位数）、次要版本（最多 3 位数）和可选的补丁版本（最多 4 位数）。 **注意** 您不能使用保留的命名空间或 `aws` `matter` **Example 示例 $id** ``` /schema-version/capability/aws.Recording@1.0 ``` ## $ref 该`$ref`元素引用系统中的现有能力。它遵循与`$id`元素相同的约束。 **注意** 类型定义或功能必须与`$ref`文件中提供的值相同。 **Example 示例 $ref** ``` /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`元素详细解释了架构文档所代表的实体。它可以包含任何字符，可在文档中使用。能力描述的最大长度为 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` 元素是可选的。它是一个字符串，表示架构文档的版本。它具有以下限制： + 使用 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``eventId`、、`fieldId`、或，具体取决于上下文。 `extrinsicId`可以是字符串化的十进制整数（1-10 位数），也可以是字符串化的十六进制整数（0x 或 0X 前缀，后面是 1-8 个十六进制数字）。 **注意** 对于 AWS，供应商 ID (VID) 为 0x1577，对于 Matter，则为 0。系统可确保自定义架构不会将这些保留的 VID 用于功能。 **Example 示例 extinSICID** ``` 0018 0x001A 0x15771002 ``` ## $defs 该`$defs`部分是子架构的映射，在 JSON 架构允许的情况下，可以在架构文档中引用这些子架构。在此地图中，键用于本地参考定义，值提供了 JSON 架构。 **注意** 系统仅强制要求该映射`$defs`是有效的映射，并且每个子架构都是有效的 JSON 架构。不强制执行其他规则。 使用定义时，请遵循以下约束： + 在定义名称中仅使用字 URI-friendly 符 + 确保每个值都是一个有效的子架构 + 包括符合架构文档大小限制的任意数量的子架构 ## 外在特性 该`extrinsicProperties`元素包含一组在外部系统中定义但保留在数据模型中的属性。对于 Matter 功能，它映射到 ZCL 集群、属性、命令或事件中不同的未建模或部分建模的元素。 外在属性必须遵循以下约束： + 属性名称必须是字母数字，不含空格或特殊字符 + 属性值可以是任何 JSON 架构值 + 最多 20 处房产 该系统支持多种功能`extrinsicProperties`，包括`access`、`apiMaturity`、`cli``cliFunctionName`、和其他。这些属性便于 ACL 进行数据模型转换 AWS （反之亦然）。 **注意** 功能的`action`、`event`、和`struct`字段元素支持外部属性`property`，但不支持能力或集群本身。 ## Properties 属性表示该功能的设备管理状态。每个状态都被定义为一个键值对，其中键描述状态的名称，值描述状态的定义。 使用属性时，请遵循以下约束： + 在属性名称中仅使用字母数字字符，不得使用空格或特殊字符 + 包括符合架构文档大小限制的任意数量的属性 ### 使用属性 功能中的属性是一个基本元素，它代表由托管集成提供支持的设备的特定状态。它代表设备的当前状态或配置。通过标准化这些属性的定义和结构，智能家居系统可确保来自不同制造商的设备能够进行有效通信，从而创造无缝且可互操作的体验。 对于能力属性，必填元素为`extrinsicId`和`value`。能力属性中的可选元素是`description``retrievable`、`mutable`、`reportable`和`extrinsicProperties`。 #### 值 一种无界结构，允许生成器设置任何 JSON-schema 合规约束来定义此属性的数据类型。 定义值时，请遵循以下约束： + 对于简单类型，请使用`type`和任何其他原生 JSON-schema 约束，例如`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`。 #### 响应描述 描述采用与相同的格式[描述](#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`。 描述元素采用的格式与相同[描述](#capability-schema-description)，最大长度为 1024 个字符。 ### `extrinsicID 和 extrinsic` `Properties` `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": { ... } ``` ### Built-in 行动 对于所有功能，您可以使用关键字`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 } } ] } ] } ] } ``` ## Events 事件是由设备实现的架构管理的单向信号。 根据以下限制实现事件： + 在事件数组中仅包含唯一的事件 + 包括符合架构文档大小限制的任意数量的事件