$id（必填）$ref 姓名（必填）删除实例快照 description version 外部版本（必填）extrinsiCid（必填）$defs 外在特性属性操作事件

能力定义架构

一项功能是使用声明性的 JSON 文档记录的，该文档为该功能在系统中的运行方式提供了明确的协议。

对于权能，必备元素为$idname、extrinsicId、，extrinsicVersion并且至少在以下一个部分中包含一个元素：

properties
actions
events

权能中的可选元素是$reftitle、description、version、$defs和extrinsicProperties。有关权能，$ref必须参阅aws.capability。

以下各节详细介绍了用于能力定义的架构。

$id（必填）

$id 元素标识架构定义。它必须遵循以下结构：

从 /schema-versions/ URI 前缀开始
包括capability架构类型
使用正斜杠 (/) 作为 URI 路径分隔符
包括架构标识，片段之间用句点分隔 (.)
使用@字符分隔架构 ID 和版本
以 semver 版本结尾，使用句点 (.) 分隔版本片段

架构标识必须以长度为 3-12 个字符的根命名空间开头，然后是可选的子命名空间和名称。

semver 版本包括主要版本（最多 3 位数）、次要版本（最多 3 位数）和可选的补丁版本（最多 4 位数）。

注意

您不能使用保留的命名空间或 aws matter

例示例 $id


/schema-version/capability/aws.Recording@1.0

$ref

该$ref元素引用系统中的现有能力。它遵循与$id元素相同的约束。

注意

类型定义或功能必须与$ref文件中提供的值相同。

例示例 $ref


/schema-version/definition/aws.capability@1.0

姓名（必填）

名称元素是一个字符串，表示架构文档中的实体名称。它通常包含缩写，必须遵循以下规则：

仅包含字母数字字符、句点 (.)、正斜杠 (/)、连字符 (-) 和空格
以字母开头
最多 64 个字符

Amazon Web Services 控制台用户界面和文档中使用名称元素。

例示例名称


Door Lock
On/Off
Wi-Fi Network Management
PM2.5 Concentration Measurement
RTCSessionController
Energy EVSE

删除实例快照

标题元素是架构文档所代表的实体的描述性字符串。它可以包含任何字符，可在文档中使用。能力标题的最大长度为 256 个字符。

例标题示例


Real-time Communication (RTC) Session Controller
Energy EVSE Capability

description

该description元素详细解释了架构文档所代表的实体。它可以包含任何字符，可在文档中使用。能力描述的最大长度为 2048 个字符

例示例描述


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 个字符之间。

例示例版本

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 位数字。

例示例版本

extrinsiCid（必填）

该extrinsicId元素表示在 Amazon Web Services 物联网系统之外管理的标识符。对于 Matter 能力 clusterIdattributeId，commandId它会根据上下文映射到fieldId、、、或。eventId

extrinsicId可以是字符串化的十进制整数（1-10 位数），也可以是字符串化的十六进制整数（0x 或 0X 前缀，后面是 1-8 个十六进制数字）。

注意

对于 AWS，供应商 ID (VID) 为 0x1577，对于 Matter，则为 0。系统确保自定义架构不会使用这些 VIDs 为功能保留的内容。

例示例 extinSICID


0018
0x001A
0x15771002

$defs

该$defs部分是子架构的映射，在 JSON 架构允许的情况下，可以在架构文档中引用这些子架构。在此地图中，键用于本地参考定义，值提供了 JSON 架构。

注意

系统仅强制要求该映射$defs是有效的映射，并且每个子架构都是有效的 JSON 架构。不强制执行其他规则。

使用定义时，请遵循以下限制：

在定义名称中仅使用 URI 友好字符
确保每个值都是一个有效的子架构
包括符合架构文档大小限制的任意数量的子架构

外在特性

该extrinsicProperties元素包含一组在外部系统中定义但保留在数据模型中的属性。对于 Matter 功能，它映射到 ZCL 集群、属性、命令或事件中不同的未建模或部分建模的元素。

外在属性必须遵循以下限制：

属性名称必须是字母数字，不含空格或特殊字符
属性值可以是任何 JSON 架构值
最多 20 处房产

该系统支持多种功能extrinsicProperties，包括access、apiMaturity、clicliFunctionName、和其他。这些属性便于 ACL 进行数据模型转换 AWS （反之亦然）。

注意

功能的action、event、和struct字段元素支持外部属性property，但不支持能力或集群本身。

属性

属性表示该功能的设备管理状态。每个状态都被定义为一个键值对，其中键描述状态的名称，值描述状态的定义。

使用属性时，请遵循以下限制：

在属性名称中仅使用字母数字字符，不得使用空格或特殊字符
包括符合架构文档大小限制的任意数量的属性

使用属性

功能中的属性是一个基本元素，它代表由托管集成提供支持的设备的特定状态。它代表设备的当前状态或配置。通过标准化这些属性的定义和结构，智能家居系统可确保来自不同制造商的设备能够进行有效通信，从而创造无缝且可互操作的体验。

对于能力属性，必填元素为extrinsicId和value。能力属性中的可选元素是descriptionretrievable、mutable、reportable和extrinsicProperties。

值

一种无界结构，允许生成器设置任何符合 JSON 架构的约束来定义此属性的数据类型。

定义值时，请遵循以下约束：

对于简单类型，请使用type和任何其他原生 JSON 架构约束，例如或 maxLength maximum
对于复合类型，请使用oneOfallOf、或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。可选元素是descriptionextrinsicProperties、request和response。

描述

描述的最大长度限制为 1536 个字符。

请求

请求部分是可选的，如果没有请求参数，则可以省略。如果省略，则系统支持仅使用名称发送没有任何有效载荷的请求Action。这用于简单的操作，例如打开或关闭灯。

复杂的动作需要额外的参数。例如，直播摄像机镜头的请求可能包含有关要使用的流媒体协议或是否将直播发送到特定显示设备的参数。

对于操作请求，必填元素为parameters。可选元素是descriptionextrinsicId、和extrinsicProperties。

请求描述

描述采用与第 3.5 节相同的格式，最大长度为 2048 个字符。

响应

在托管集成中，对于通过 SendManagedThingCommandAPI 发送的任何操作请求，该请求都会到达设备并期望得到异步响应。操作响应定义了该响应的结构。

对于操作请求，必填元素为parameters。可选元素是namedescription、extrinsicId、extrinsicProperties、errors和responseCode。

响应描述

描述采用与相同的格式description，最大长度为 2048 个字符。

响应名称

该名称的格式与以下内容相同姓名（必填），但有以下额外细节：

响应的常规名称是通过附加Response到操作名称得出的。
如果要使用其他名称，则可以在此name元素中提供该名称。如果响应中提供了 aname，则此值的优先级高于常规名称。

错误

如果在处理请求时出现错误，则在响应中提供的唯一消息的无限数组。

约束：

消息项声明为 JSON 对象，其中包含以下字段：
- code: 包含字母数字字符和_（下划线）的字符串，长度介于 1 到 64 个字符之间
- message: 一个无界限的字符串值

例错误消息示例


"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，最大长度为 1024 个字符。

`extrinsicId`并`extrinsicProperties`覆盖

extrinsicId和extrinsicProperties的格式与extrinsiCid（必填）和相同外在特性，但有以下额外细节：

如果在请求或响应中提供了，extrinsicId则该值的优先级高于在操作级别提供的值。系统必须extrinsicId先使用 request/response 关卡，如果缺少则使用操作关卡 extrinsicId
如果extrinsicProperties在请求或响应中提供，则这些属性的优先级高于在操作级别提供的 va 值。系统必须采取操作级别extrinsicProperties并替换该级别提供的键值对 request/response extrinsicProperties

例 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: 发送命令以更新某些属性。

在以下情况下，强制设备状态同步可能很有用：

设备处于离线状态一段时间，未发出任何事件。
该设备刚刚配置完毕，尚未在云中维护任何状态。
设备状态与设备的实际状态不同步。

ReadState 例子

使用 SendManagedThingCommandAPI 检查灯是开还是关：


{
  "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 示例

使用 SendManagedThingCommandAPI 更改OnTime为灯光：


{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "matter.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "UpdateState",
              "parameters": {
                "OnTime": 5
              }
            }
          ]
        }
      ]
    }
  ]
}

事件

事件是由设备实现的架构管理的单向信号。

根据以下限制实现事件：

在事件数组中仅包含唯一的事件
包括符合架构文档大小限制的任意数量的事件

Javascript 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

数据模型架构

类型定义架构

能力定义架构

$id（必填）

注意

例 示例 $id

$ref

注意

例 示例 $ref

姓名（必填）

例 示例名称

删除实例快照

例 标题示例

description

例 示例描述

version

例 示例版本

使用功能版本

外部版本（必填）

例 示例版本

extrinsiCid（必填）

注意

例 示例 extinSICID

$defs

注意

外在特性

注意

属性

使用属性

值

可检索

Mutable

可报告

操作

使用操作

描述

请求

请求描述

响应

响应描述

响应名称

错误

例 错误消息示例

响应代码

请求或响应参数

参数字段

extrinsicId并extrinsicProperties覆盖

例 extrinsicID 和 extrinsicProperties

内置动作

ReadState 例子

UpdateState 示例

事件

例示例 $id

例示例 $ref

例示例名称

例标题示例

例示例描述

例示例版本

例示例版本

例示例 extinSICID

例错误消息示例

`extrinsicId`并`extrinsicProperties`覆盖