Schema für Funktionsdefinitionen

Eine Fähigkeit wird mithilfe eines deklarativen JSON-Dokuments dokumentiert, das einen klaren Vertrag darüber enthält, wie die Fähigkeit innerhalb des Systems funktionieren soll.

Bei einer Fähigkeit sind die obligatorischen Elemente $idname,extrinsicId, extrinsicVersion und mindestens ein Element in mindestens einem der folgenden Abschnitte:

• properties

• actions

• events

Die optionalen Elemente in einer Fähigkeit sind $reftitle,description,version, $defs undextrinsicProperties. Für eine Fähigkeit $ref muss auf verwiesen werdenaws.capability.

In den folgenden Abschnitten wird das für Funktionsdefinitionen verwendete Schema detailliert beschrieben.

$id (verpflichtend)

Das $id-Element identifiziert die Schemadefinition. Es muss dieser Struktur folgen:

• Beginnen Sie mit dem /schema-versions/ URI-Präfix

• Schließen Sie den capability Schematyp ein

• Verwenden Sie einen Schrägstrich (/) als URI-Pfadtrennzeichen

• Fügen Sie die Schema-Identität ein, wobei die Fragmente durch Punkte (.) getrennt sind

• Verwenden Sie das @ Zeichen, um die Schema-ID und die Version zu trennen

• Beenden Sie mit der Serverversion und verwenden Sie Punkte (.), um Versionsfragmente zu trennen

Die Schema-Identität muss mit einem Stamm-Namespace beginnen, der 3-12 Zeichen lang ist, gefolgt von einem optionalen Unternamespace und einem Namen.

Die Semver-Version umfasst eine HAUPTVERSION (bis zu 3 Ziffern), eine NEBENVERSION (bis zu 3 Ziffern) und eine optionale PATCH-Version (bis zu 4 Ziffern).

Anmerkung

Sie können die reservierten aws Namespaces nicht verwenden oder matter

Beispiel $id

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

$ref

Das $ref Element verweist auf eine bestehende Fähigkeit innerhalb des Systems. Es unterliegt den gleichen Einschränkungen wie das $id Element.

Anmerkung

Es muss eine Typdefinition oder Fähigkeit mit dem in der $ref Datei angegebenen Wert vorhanden sein.

Beispiel $ref

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

Name (verpflichtend)

Das Namenselement ist eine Zeichenfolge, die den Entitätsnamen im Schemadokument darstellt. Es enthält häufig Abkürzungen und muss den folgenden Regeln entsprechen:

• Enthält nur alphanumerische Zeichen, Punkte (.), Schrägstriche (/), Bindestriche (-) und Leerzeichen

• Beginne mit einem Buchstaben

• Maximal 64 Zeichen

Das name-Element wird in der Benutzeroberfläche und in der Dokumentation der Amazon Web Services Services-Konsole verwendet.

Beispielnamen

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

Titel

Das Titelelement ist eine beschreibende Zeichenfolge für die Entität, die durch das Schemadokument repräsentiert wird. Es kann beliebige Zeichen enthalten und wird in der Dokumentation verwendet. Die maximale Länge für einen Funktionstitel beträgt 256 Zeichen.

Beispieltitel

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

description

Das description Element bietet eine detaillierte Erläuterung der Entität, die durch das Schemadokument repräsentiert wird. Es kann beliebige Zeichen enthalten und wird in der Dokumentation verwendet. Die maximale Länge für eine Funktionsbeschreibung beträgt 2048 Zeichen

Beispiel für eine Beschreibung

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

Das Element version ist optional. Es ist eine Zeichenfolge, die die Version des Schemadokuments darstellt. Es gelten die folgenden Einschränkungen:

• Verwendet das Semver-Format, wobei die folgenden Versionsfragmente durch . (Punkte) getrennt sind.

  • MAJORVersion, maximal 3 Ziffern

  • MINORVersion, maximal 3 Ziffern

  • PATCHVersion (optional), maximal 4 Ziffern

• Die Länge kann zwischen 3 und 12 Zeichen liegen.

Beispielversionen

1.0

1.12

1.4.1

Mit Capability-Versionen arbeiten

Eine Fähigkeit ist eine unveränderliche versionierte Entität. Es wird erwartet, dass bei jeder Änderung eine neue Version erstellt wird. Das System verwendet semantische Versionierung im Format MAJOR.MINOR.PATCH, wobei:

• Die MAJOR-Version nimmt zu, wenn abwärtsinkompatible API-Änderungen vorgenommen werden

• Die MINOR-Version nimmt zu, wenn Funktionen auf abwärtskompatible Weise hinzugefügt werden

• Die PATCH-Version erhöht sich, wenn geringfügige Funktionserweiterungen vorgenommen werden, die sich nicht negativ auswirken.

Die von Matter-Clustern abgeleiteten Funktionen basieren auf Version 1.4, und es wird erwartet, dass jede Matter-Version in das System importiert wird. Da die Matter-Version sowohl die MAJOR- als auch die MINOR-Ebene von Semver verwendet, können verwaltete Integrationen nur PATCH-Versionen verwenden.

Wenn Sie PATCH-Versionen für Matter hinzufügen, müssen Sie berücksichtigen, dass Matter sequentielle Revisionen verwendet. Alle PATCH-Versionen müssen der in der Matter-Spezifikation dokumentierten Version entsprechen und diese müssen abwärtskompatibel sein.

Um alle Probleme mit der Abwärtsinkompatibilität zu beheben, müssen Sie mit der Connectivity Standards Alliance (CSA) zusammenarbeiten, um die Probleme in der Spezifikation zu lösen und eine neue Version zu veröffentlichen.

AWS-verwaltete Funktionen wurden mit einer ersten Version von veröffentlicht. 1.0 Mit diesen können alle drei Versionsebenen verwendet werden.

ExtrinsicVersion (verpflichtend)

Dies ist eine Zeichenfolge, die eine Version darstellt, die außerhalb des Systems verwaltet wird. AWS IoT Für extrinsicVersion Matter-Funktionen entspricht revision

Er wird als Ganzzahl mit Zeichenketten dargestellt, und die Länge kann zwischen 1 und 10 numerischen Ziffern liegen.

Beispielversionen

7

1567

extrinsICid (verpflichtend)

Das extrinsicId Element stellt eine Kennung dar, die außerhalb des IoT-Systems von Amazon Web Services verwaltet wird. Bei Matter-Funktionen wird es je nach Kontext clusterId attributeId commandIdeventId,fieldId,, oder zugeordnet.

Dabei extrinsicId kann es sich entweder um eine stringifizierte dezimale Ganzzahl (1—10 Ziffern) oder um eine stringifizierte hexadezimale Ganzzahl (0x- oder 0X-Präfix, gefolgt von 1—8 hexadezimalen Ziffern) handeln.

Anmerkung

Für AWS ist die Lieferanten-ID (VID) 0x1577 und für Matter 0. Das System stellt sicher, dass benutzerdefinierte Schemas diese für Funktionen reservierten VIDs Daten nicht verwenden.

Beispiel: ExtrinsICIDs

0018
0x001A
0x15771002

$defs

Der $defs Abschnitt ist eine Zuordnung von Unterschemas, auf die innerhalb des Schemadokuments verwiesen werden kann, sofern das JSON-Schema dies zulässt. In dieser Map wird der Schlüssel in den lokalen Referenzdefinitionen verwendet und der Wert stellt das JSON-Schema bereit.

Anmerkung

Das System erzwingt nur, dass $defs es sich um eine gültige Map handelt und dass jedes Unterschema ein gültiges JSON-Schema ist. Es werden keine zusätzlichen Regeln durchgesetzt.

Beachten Sie bei der Arbeit mit Definitionen die folgenden Einschränkungen:

• Verwenden Sie in Definitionsnamen nur URI-freundliche Zeichen

• Stellen Sie sicher, dass jeder Wert ein gültiges Unterschema ist

• Schließen Sie eine beliebige Anzahl von Unterschemas ein, die innerhalb der Größenbeschränkungen für Schemadokumente liegen

Extrinsische Eigenschaften

Das extrinsicProperties Element enthält eine Reihe von Eigenschaften, die in einem externen System definiert sind, aber innerhalb des Datenmodells verwaltet werden. Bei Matter-Fähigkeiten ist es verschiedenen unmodellierten oder teilweise modellierten Elementen innerhalb eines ZCL-Clusters, -Attributs, -Befehls oder -Ereignisses zugeordnet.

Extrinsische Eigenschaften müssen den folgenden Einschränkungen entsprechen:

• Eigenschaftsnamen müssen alphanumerisch ohne Leerzeichen oder Sonderzeichen sein

• Eigenschaftswerte können beliebige JSON-Schemawerte sein

• Maximal 20 Eigenschaften

Das System unterstützt verschiedeneextrinsicProperties, darunter accessapiMaturity,cli,cliFunctionName, und andere. Diese Eigenschaften erleichtern Transformationen von ACL zu Datenmodellen AWS (und umgekehrt).

Anmerkung

Extrinsische Eigenschaften werden für die Elementeaction, eventproperty, und struct fields einer Fähigkeit unterstützt, nicht jedoch für die Fähigkeit oder den Cluster selbst.

Eigenschaften

Eigenschaften stellen den vom Gerät verwalteten Status der Funktion dar. Jeder Status ist als Schlüssel-Wert-Paar definiert, wobei der Schlüssel den Namen des Status und der Wert die Definition des Zustands beschreibt.

Beachten Sie bei der Arbeit mit Eigenschaften die folgenden Einschränkungen:

• Verwenden Sie in Eigenschaftsnamen nur alphanumerische Zeichen ohne Leerzeichen oder Sonderzeichen

• Fügen Sie eine beliebige Anzahl von Eigenschaften ein, die innerhalb der Größenbeschränkungen für Schemadokumente liegen

Mit Eigenschaften arbeiten

Eine Eigenschaft innerhalb einer Funktion ist ein grundlegendes Element, das einen bestimmten Status eines Geräts darstellt, das durch verwaltete Integrationen unterstützt wird. Sie stellt den aktuellen Zustand oder die aktuelle Konfiguration des Geräts dar. Durch die Standardisierung der Definition und Struktur dieser Eigenschaften stellen Smart-Home-Systeme sicher, dass Geräte verschiedener Hersteller effektiv kommunizieren können, wodurch ein nahtloses und interoperables Erlebnis entsteht.

Für eine Fähigkeitseigenschaft sind extrinsicId die obligatorischen Elemente und. value Die optionalen Elemente in einer Funktionseigenschaft sind descriptionretrievable,mutable, reportable undextrinsicProperties.

Wert

Eine unbegrenzte Struktur, die es Buildern ermöglicht, beliebige JSON-Schema-konforme Einschränkungen festzulegen, um den Datentyp dieser Eigenschaft zu definieren.

Beachten Sie bei der Definition von Werten die folgenden Einschränkungen:

• Verwenden Sie type für einfache Typen alle anderen systemeigenen JSON-Schema-Einschränkungen wie oder maxLength maximum

• Verwenden Sie für zusammengesetzte Typen, oneOfallOf, oder. anyOf Das System unterstützt das not Schlüsselwort nicht

• Um auf einen beliebigen globalen Typ zu verweisen, verwenden Sie es $ref mit einer gültigen, auffindbaren Referenz

• Für die Nullfähigkeit folgen Sie der OpenAPI-Typschemadefinition, indem Sie das nullable -Attribut mit einem booleschen Flag versehen (truefalls Null ein zulässiger Wert ist)

Beispiel:

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

Abrufbar

Ein boolescher Wert, der beschreibt, ob der Status lesbar ist oder nicht.

Der Aspekt der Lesbarkeit des Status wird auf die Implementierung der Funktion durch das Gerät zurückgestellt. Das Gerät entscheidet, ob ein bestimmter Status lesbar ist oder nicht. Es wird noch nicht unterstützt, dass dieser Aspekt des Status im Fähigkeitsbericht gemeldet wird und daher nicht innerhalb des Systems durchgesetzt wird.

Beispiel: oder true false

Mutable

Ein boolescher Wert, der beschreibt, ob der Status beschreibbar ist oder nicht.

Der Aspekt der Schreibfähigkeit des Status wird auf die Implementierung der Funktion durch das Gerät zurückgestellt. Das Gerät entscheidet, ob ein bestimmter Status beschreibbar ist oder nicht. Es wird noch nicht unterstützt, dass dieser Aspekt des Zustands im Fähigkeitsbericht gemeldet wird und daher nicht innerhalb des Systems durchgesetzt wird.

Beispiel: oder true false

Meldepflichtig

Ein boolescher Wert, der beschreibt, ob der Status vom Gerät gemeldet wird, wenn sich der Status ändert.

Der Aspekt der Berichtbarkeit des Zustands wird auf die Implementierung der Funktion durch das Gerät zurückgestellt. Das Gerät entscheidet, ob ein bestimmter Status meldepflichtig ist oder nicht. Es wird noch nicht unterstützt, dass dieser Aspekt des Zustands im Fähigkeitsbericht gemeldet wird und daher nicht innerhalb des Systems durchgesetzt wird.

Beispiel: oder true false

Aktionen

Aktionen sind schemaverwaltete Operationen, die einem Anfrage-Antwort-Modell folgen. Jede Aktion steht für einen vom Gerät implementierten Vorgang.

Beachten Sie bei der Implementierung von Aktionen die folgenden Einschränkungen:

• Nehmen Sie nur eindeutige Aktionen in das Aktions-Array auf

• Schließen Sie eine beliebige Anzahl von Aktionen ein, die innerhalb der Größenbeschränkungen für Schemadokumente liegen

Verwenden von Aktionen

Eine Aktion ist eine standardisierte Methode, um mit Gerätefunktionen in einem verwalteten Integrationssystem zu interagieren und diese zu steuern. Sie stellt einen bestimmten Befehl oder Vorgang dar, der auf einem Gerät ausgeführt werden kann, und verfügt über ein strukturiertes Format zur Modellierung aller erforderlichen Anforderungs- oder Antwortparameter. Diese Aktionen dienen als Brücke zwischen Benutzerabsichten und Geräteoperationen und ermöglichen eine konsistente und zuverlässige Steuerung über verschiedene Arten von intelligenten Geräten hinweg.

Für eine Aktion sind die obligatorischen Elemente name undextrinsicId. Die optionalen Elemente sind descriptionextrinsicProperties, request undresponse.

Beschreibung

Die Beschreibung hat eine maximale Längenbeschränkung von 1536 Zeichen.

Anforderung

Der Anforderungsabschnitt ist optional und kann weggelassen werden, wenn keine Anforderungsparameter vorhanden sind. Wenn er weggelassen wird, unterstützt das System das Senden einer Anfrage ohne Nutzlast, indem es einfach den Namen von Action verwendet. Dies wird bei einfachen Aktionen verwendet, z. B. beim Ein- oder Ausschalten eines Lichts.

Die komplexen Aktionen benötigen zusätzliche Parameter. Beispielsweise kann eine Anfrage zum Streamen von Kamerabildern Parameter über das zu verwendende Streaming-Protokoll oder darüber enthalten, ob der Stream an ein bestimmtes Anzeigegerät gesendet werden soll.

Für eine Aktionsanfrage ist das obligatorische Elementparameters. Die optionalen Elemente sind descriptionextrinsicId, undextrinsicProperties.

Beschreibung der Anforderung

Die Beschreibung folgt demselben Format wie Abschnitt 3.5, mit einer maximalen Länge von 2048 Zeichen.

Antwort

Bei verwalteten Integrationen erreicht jede über die SendManagedThingCommandAPI gesendete Aktionsanfrage das Gerät und erwartet eine asynchrone Antwort. Die Aktionsantwort definiert die Struktur dieser Antwort.

Für eine Aktionsanfrage ist das obligatorische Elementparameters. Die optionalen Elemente sind namedescription,extrinsicId,extrinsicProperties, errors undresponseCode.

Beschreibung der Antwort

Die Beschreibung folgt demselben Format wie description und hat eine maximale Länge von 2048 Zeichen.

Name der Antwort

Der Name folgt demselben Format wieName (verpflichtend), mit diesen zusätzlichen Details:

• Der herkömmliche Name einer Antwort wird abgeleitet, indem er Response an den Aktionsnamen angehängt wird.

• Wenn Sie einen anderen Namen verwenden möchten, können Sie ihn in diesem name Element angeben. Wenn in der Antwort a angegeben name wird, hat dieser Wert Vorrang vor dem herkömmlichen Namen.

Fehler

Ein unbegrenztes Array von eindeutigen Nachrichten, die in der Antwort bereitgestellt werden, falls bei der Verarbeitung der Anfrage Fehler auftreten.

Einschränkungen:

• Ein Nachrichtenelement wird als JSON-Objekt mit den folgenden Feldern deklariert:

  • code: Eine Zeichenfolge mit alphanumerischen Zeichen und _ (Unterstrichen) mit einer Länge zwischen 1 und 64 Zeichen

  • message: Ein unbegrenzter Zeichenkettenwert

Beispiel für eine Fehlermeldung

"errors": [
   {  
      "code": "AD_001", 
      "message": "Unable to receive signal from the sensor. Please check connection with the sensor." 
   }
]

Antwortcode

Ein Integer-Code, der anzeigt, wie die Anfrage behandelt wurde. Wir empfehlen, dass der Gerätecode einen Code zurückgibt, der die Spezifikation für den Statuscode der HTTP-Serverantwort verwendet, um Einheitlichkeit innerhalb des Systems zu gewährleisten.

Einschränkung: Ein ganzzahliger Wert im Bereich von 100 bis 599.

Anfrage- oder Antwortparameter

Der Parameterbereich ist als eine Zuordnung von Namens- und Subschemapaaren definiert. In den Anforderungsparametern können beliebig viele Parameter definiert werden, sofern sie in das Schemadokument passen.

Parameternamen dürfen nur alphanumerische Zeichen enthalten. Leerzeichen oder andere Zeichen sind nicht zulässig.

Parameterfeld

Die obligatorischen Elemente in a parameter sind extrinsicId undvalue. Die optionalen Elemente sind description undextrinsicProperties.

Das Beschreibungselement hat dasselbe Format wiedescription, mit einer maximalen Länge von 1024 Zeichen.

extrinsicIdund extrinsicProperties überschreibt

die extrinsicId und extrinsicProperties folgen demselben Format wie extrinsICid (verpflichtend) undExtrinsische Eigenschaften, mit diesen zusätzlichen Details:

• Wenn in der Anfrage oder Antwort ein angegeben extrinsicId wird, hat dieser Wert eine höhere Priorität als der auf Aktionsebene angegebene Wert. Das System muss extrinsicId zuerst die request/response Ebene verwenden. Fehlt sie, muss die Aktionsebene verwendet werden extrinsicId

• Wenn sie in der Anfrage oder Antwort angegeben extrinsicProperties werden, haben diese Eigenschaften eine höhere Priorität als der Va-Wert, der auf der Aktionsebene angegeben wurde. Das System muss die Aktionsebene übernehmen extrinsicProperties und die auf der Ebene bereitgestellten Schlüssel-Wert-Paare ersetzen request/response extrinsicProperties

Beispiel ExtrinsicID und ExtrinsicProperties überschreiben das Beispiel

{
   "name": "ToggleWithEffect",
   "extrinsicId": "0x0001",
  
   "extrinsicProperties": {
      "apiMaturity": "provisional",
      "introducedIn": "1.2"
   },
   "request": {
      "extrinsicProperties": {
         "apiMaturity": "stable",
         "manufacturerCode": "XYZ"
      },
      "parameters": {
         ...
      }
   },
   "response": {
      "extrinsicProperties": {
         "noDefaultImplementation": true
      },
      "parameters": {
 {
         ...
      }
   }
}

Im obigen Beispiel wären die effektiven Werte für die Aktionsanforderung:

# 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": {
   ...
}

Integrierte Aktionen

Für alle Funktionen können Sie benutzerdefinierte Aktionen mit den Schlüsselwörtern ReadState und ausführenUpdateState. Diese beiden Aktionsschlüsselwörter wirken sich auf die im Datenmodell definierten Eigenschaften der Funktion aus.

ReadState

Sendet einen Befehl an diemanagedThing, um die Werte ihrer Statuseigenschaften zu lesen. Wird ReadState verwendet, um die Aktualisierung des Gerätestatus zu erzwingen.

UpdateState

Sendet einen Befehl zum Aktualisieren einiger Eigenschaften.

Das Erzwingen einer Gerätestatussynchronisierung kann in den folgenden Szenarien nützlich sein:

1. Das Gerät war für einen bestimmten Zeitraum offline und hat keine Ereignisse ausgelöst.

2. Das Gerät wurde gerade bereitgestellt und hat noch keinen Status, der in der Cloud verwaltet wird.

3. Der Gerätestatus stimmt nicht mit dem tatsächlichen Zustand des Geräts überein.

ReadState Beispiele

Prüfen Sie mithilfe der SendManagedThingCommandAPI, ob das Licht ein- oder ausgeschaltet ist:

{
  "Endpoints": [
    {
      "endpointId": "1",
      "capabilities": [
        {
          "id": "aws.OnOff",
          "name": "On/Off",
          "version": "1",
          "actions": [
            {
              "name": "ReadState",
              "parameters": {
                "propertiesToRead": [ "OnOff" ]
              }
            }
          ]
        }
      ]
    }
  ]
}

Lesen Sie alle Statuseigenschaften für die matter.OnOff Fähigkeit:

{
  "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 Beispiel

Ändern Sie das OnTime für ein Licht mithilfe der SendManagedThingCommandAPI:

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

--Ereignisse

Ereignisse sind schemaverwaltete, unidirektionale Signale, die vom Gerät implementiert werden.

Implementieren Sie Ereignisse gemäß den folgenden Einschränkungen:

• Schließt nur eindeutige Ereignisse in das Event-Array ein

• Schließen Sie eine beliebige Anzahl von Ereignissen ein, die innerhalb der Größenbeschränkungen für Schemadokumente liegen