功能定義的結構描述

使用宣告式 JSON 文件來記錄功能，該文件提供明確的合約，說明該功能在系統中應如何運作。

對於 功能，以下至少一個區段中的強制元素為 $id、extrinsicId、 nameextrinsicVersion和至少一個元素：

• properties

• actions

• events

功能中的選用元素為 $ref、title、version、 description$defs和 extrinsicProperties。對於 功能， $ref 必須參考 aws.capability。

下列各節詳細說明用於功能定義的結構描述。

$id （強制性）

$id 元素可識別結構描述定義。它必須遵循此結構：

• 從 /schema-versions/ URI 字首開始

• 包含capability結構描述類型

• 使用正斜線 (/) 做為 URI 路徑分隔符號

• 包含結構描述身分，片段以句點 (.) 分隔

• 使用 @ 字元來分隔結構描述 ID 和版本

• 以 semver 版本結尾，使用句點 (.) 分隔版本片段

結構描述身分的開頭必須是長度為 3-12 個字元的根命名空間，後面接著選用的子命名空間和名稱。

轉換器版本包含 MAJOR 版本 （最多 3 位數）、MINOR 版本 （最多 3 位數） 和選用的 PATCH 版本 （最多 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 主控台 UI 和 文件。

範例名稱

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 元素是選用項目。這是代表結構描述文件版本的字串。它有下列限制條件：

• 使用轉換器格式，下列版本片段以 .（期間） 分隔。

  • MAJOR 版本，最多 3 位數

  • MINOR 版本，最多 3 位數

  • PATCH 版本 （選用），最多 4 位數

• 長度可以介於 3 到 12 個字元之間。

範例版本

1.0

1.12

1.4.1

使用 功能版本

功能是不可變的版本化實體。任何變更都應該建立新的版本。系統會使用 MAJOR.MINOR.PATCH 格式的語意版本控制，其中：

• 進行回溯不相容 API 變更時，主要版本會增加

• 以回溯相容的方式新增功能時，MINOR 版本會增加

• PATCH 版本會在 功能中進行次要且不影響的新增時增加。

從事項叢集衍生的功能是以 1.4 版為基礎，且每個事項版本預期都會匯入系統。由於Matter 版本同時使用主要和次要層級的轉換器，受管整合只能使用 PATCH 版本。

當您為事項新增 PATCH 版本時，請務必考量該事項使用循序修訂。所有 PATCH 版本都必須符合事項規格中記載的修訂，而且這些修訂必須回溯相容。

若要修正任何回溯不相容的問題，您必須與連線標準聯盟 (CSA) 合作，以解決規格中的問題，並發行新的修訂版本。

AWS受管功能已使用 的初始版本發行1.0。透過這些，可以使用這三個層級的版本。

extrinsicVersion （強制性）

這是代表 AWS IoT 系統外部受管版本的字串。對於事項功能， extrinsicVersion 映射到 revision

它以字串化整數值表示，長度可以是 1 到 10 個數字。

範例版本

7

1567

extrinsicId （強制性）

extrinsicId 元素代表在 Amazon Web Services IoT 系統外部管理的識別符。對於事項功能，它fieldId會根據內容對應至 clusterId、eventId、、 attributeId commandId或 。

extrinsicId 可以是字串化十進位整數 (1-10 位數） 或字串化十六進位整數 (0x 或 0X 字首，後面接著 1-8 個十六進位位數）。

注意

對於 AWS，廠商 ID (VID) 為 0x1577，對於事項，則為 0。系統會確保自訂結構描述不會將這些預留 VIDs用於 功能。

範例 extrinsicIds

0018
0x001A
0x15771002

$defs

$defs 區段是子結構描述的映射，可在 JSON 結構描述允許的結構描述文件中參考。在此映射中， 金鑰用於本機參考定義，而 值提供 JSON 結構描述。

注意

系統只會強制執行 $defs是有效的映射，而且每個子結構描述都是有效的 JSON 結構描述。不會強制執行其他規則。

使用 定義時，請遵循下列限制條件：

• 在定義名稱中僅使用 URI 易記字元

• 確保每個值都是有效的子結構描述

• 包含符合結構描述文件大小限制的任何數量的子結構描述

extrinsicProperties

extrinsicProperties 元素包含一組在外部系統中定義的屬性，但在資料模型中維護。對於事項功能，它會映射到 ZCL 叢集內不同的未建模或部分建模元素、屬性、命令或事件。

外部屬性必須遵循下列限制：

• 屬性名稱必須為英數字元，不含空格或特殊字元

• 屬性值可以是任何 JSON 結構描述值

• 最多 20 個屬性

系統支援各種 extrinsicProperties，包括 access、apiMaturity、cliFunctionName、 cli等。這些屬性有助於 ACL 轉換 AWS （反之亦然） 資料模型。

注意

功能的 action、property、 event和 struct 欄位元素支援外部屬性，但功能或叢集本身不支援。

屬性

屬性代表 功能的裝置受管狀態。每個狀態都定義為索引鍵/值對，其中索引鍵描述狀態的名稱，而值描述狀態的定義。

使用屬性時，請遵循下列限制條件：

• 在屬性名稱中僅使用英數字元，不含空格或特殊字元

• 包含符合結構描述文件大小限制的任何數量屬性

使用屬性

功能中的屬性是基本元素，代表由受管整合提供支援的裝置的特定狀態。它代表裝置目前的條件或組態。透過標準化這些屬性的定義和結構，智慧型家庭系統可確保來自不同製造商的裝置進行有效通訊，進而建立無縫且可互通的體驗。

對於功能屬性，強制性元素為 extrinsicId和 value。功能屬性中的選用元素為 description、mutable、 retrievablereportable和 extrinsicProperties。

Value

無限制的結構，可讓建置器放置任何 JSON 結構描述合規限制，以定義此屬性的資料類型。

定義值時，請遵循下列限制條件：

• 對於簡單類型，請使用 type和任何其他原生 JSON 結構描述限制，例如 maxLength或 maximum

• 對於複合類型，請使用 oneOf、 allOf或 anyOf。系統不支援 not關鍵字

• 若要參考任何全域類型，請使用 $ref搭配有效的可探索參考

• 如需 nullability，請遵循 OpenAPI 類型結構描述定義，方法是使用布林值旗標提供 nullable 屬性 (true如果 null 是允許的值）

範例：

{
    "$ref": "/schema-versions/definition/matter.uint16@1.4",
    "nullable": true,
    "maximum": 4096
}

可擷取

說明狀態是否可讀取的布林值。

狀態的可讀性方面會延遲至裝置的 功能實作。裝置會決定指定狀態是否可讀取。狀態的這個方面尚不支援在功能報告中報告，因此未在系統內強制執行。

範例： true 或 false

Mutable

說明狀態是否可寫入的布林值。

狀態的可寫入性方面會延遲至裝置的 功能實作。裝置會決定指定狀態是否可寫入。狀態的這個方面尚不支援在功能報告中報告，因此未在系統內強制執行。

範例： true 或 false

可報告

布林值，說明當狀態變更時，裝置是否報告狀態。

狀態的可報告性方面會延遲至裝置的 功能實作。裝置會決定指定狀態是否可報告。狀態的這個方面尚不支援在功能報告中報告，因此未在系統內強制執行。

範例： true 或 false

動作

動作是遵循請求回應模型的結構描述受管操作。每個動作代表裝置實作的操作。

實作動作時，請遵循下列限制：

• 在動作陣列中僅包含唯一動作

• 包含符合結構描述文件大小限制的任何數量動作

使用動作

動作是與受管整合系統中的裝置功能互動和控制其功能的標準化方式。它代表可在裝置上執行的特定命令或操作，並使用結構化格式來建立任何必要請求或回應參數的模型。這些動作可做為使用者意圖和裝置操作之間的橋樑，在不同類型的智慧型裝置上實現一致且可靠的控制。

對於 動作，必要元素為 name和 extrinsicId。選用元素為 description、 extrinsicPropertiesrequest和 response。

描述

描述的長度限制上限為 1536 個字元。

請求

請求區段是選用的，如果沒有請求參數，則可以省略。如果省略，則系統支援傳送沒有任何承載的請求，只要使用 的名稱即可Action。這用於簡單的動作，例如開啟或關閉燈光。

複雜動作需要額外的參數。例如，串流攝影機影片的請求可能包含有關要使用的串流通訊協定或是否將串流傳送至特定顯示裝置的參數。

對於動作請求，強制性元素為 parameters。選用元素為 description、 extrinsicId和 extrinsicProperties。

請求說明

描述遵循與第 3.5 節相同的格式，長度上限為 2048 個字元。

回應

在受管整合中，對於透過 SendManagedThingCommand API 傳送的任何動作請求，請求會到達裝置並預期傳回非同步回應。動作回應會定義此回應的結構。

對於動作請求，強制性元素為 parameters。選用元素為 name、description、extrinsicProperties、 extrinsicIderrors和 responseCode。

回應描述

描述遵循與 相同的格式description，長度上限為 2048 個字元。

回應名稱

名稱遵循與 相同的格式名稱 （必要），其中包含這些其他詳細資訊：

• 回應的傳統名稱是透過附加Response至動作名稱來衍生。

• 如果您想要使用不同的名稱，您可以在此name元素中提供它。如果在回應name中提供 ，則此值的優先順序高於傳統名稱。

錯誤

如果處理請求時發生錯誤，回應中提供的唯一訊息的未限制陣列。

約束:

• 訊息項目會宣告為具有下列欄位的 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 之間的整數值。

請求或回應參數

參數區段定義為名稱和子結構描述對的映射。如果參數可以符合結構描述文件，則可以在請求參數中定義任意數量的參數。

參數名稱只能包含英數字元。不允許使用空格或任何其他字元。

參數欄位

中的必要元素parameter為 extrinsicId和 value。選用元素為 description和 extrinsicProperties。

描述元素遵循與 相同的格式description，長度上限為 1024 個字元。

extrinsicId 和 extrinsicProperties覆寫

extrinsicId 和 extrinsicProperties 遵循與 extrinsicId （強制性）和 相同的格式extrinsicProperties，其中包含這些其他詳細資訊：

• 如果在請求或回應中提供 extrinsicId ，則此值的優先順序高於動作層級提供的值。系統必須先使用請求/回應層級extrinsicId，如果遺失，請使用動作層級 extrinsicId

• 如果在請求或回應extrinsicProperties中提供 ，則這些屬性的優先順序高於動作層級提供的 VAR 值。系統必須採取動作層級，extrinsicProperties並取代在請求/回應層級提供的鍵值對 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

傳送命令來更新某些屬性。

在下列情況中，強制裝置狀態同步可能很有用：

1. 裝置已離線一段時間，且未發出事件。

2. 裝置剛佈建，尚未在雲端中維護任何狀態。

3. 裝置狀態與裝置的真實狀態不同步。

ReadState 範例

使用 SendManagedThingCommand 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 API 變更光源OnTime的 ：

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

事件

事件是由裝置實作的結構描述受管、單向訊號。

根據這些限制條件實作事件：

• 在事件陣列中僅包含唯一事件

• 包含符合結構描述文件大小限制的任何數量的事件