Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà. # Schema per le definizioni delle funzionalità Una funzionalità è documentata utilizzando un documento JSON dichiarativo che fornisce un contratto chiaro su come la funzionalità dovrebbe funzionare all'interno del sistema. Per una funzionalità, gli elementi obbligatori sono `$id``name`,`extrinsicId`, `extrinsicVersion` e almeno un elemento in almeno una delle seguenti sezioni: + `properties` + `actions` + `events` Gli elementi opzionali di una funzionalità sono `$ref``title`,`description`,`version`, `$defs` e`extrinsicProperties`. Per una funzionalità, `$ref` deve fare riferimento a`aws.capability`. Le sezioni seguenti descrivono in dettaglio lo schema utilizzato per le definizioni delle funzionalità. ## $id (obbligatorio) L'elemento $id identifica la definizione dello schema. Deve seguire questa struttura: + Inizia con il prefisso `/schema-versions/` URI + Includi il tipo di `capability` schema + Usa una barra in avanti (`/`) come separatore di percorso URI + Includi l'identità dello schema, con frammenti separati da punti () `.` + Usa il `@` carattere per separare l'ID e la versione dello schema + Termina con la versione semver, usando period (`.`) per separare i frammenti di versione L'identità dello schema deve iniziare con uno spazio dei nomi radice lungo 3-12 caratteri, seguito da uno spazio dei nomi secondario e da un nome opzionali. La versione semver include una versione MAJOR (fino a 3 cifre), una versione MINOR (fino a 3 cifre) e una versione PATCH opzionale (fino a 4 cifre). **Nota** Non è possibile utilizzare i namespace riservati o `aws` `matter` **Example Esempio $id** ``` /schema-version/capability/aws.Recording@1.0 ``` ## $ref L'`$ref`elemento fa riferimento a una funzionalità esistente all'interno del sistema. Segue gli stessi vincoli dell'`$id`elemento. **Nota** È necessario che esista una definizione o una funzionalità del tipo con il valore fornito nel `$ref` file. **Example Esempio $ref** ``` /schema-version/definition/aws.capability@1.0 ``` ## nome (obbligatorio) L'elemento name è una stringa che rappresenta il nome dell'entità nel documento dello schema. Spesso contiene abbreviazioni e deve seguire queste regole: + Contiene solo caratteri alfanumerici, punti (.), barre (/), trattini (-) e spazi + Inizia con una lettera + Massimo 64 caratteri L'elemento name viene utilizzato nell'interfaccia utente e nella documentazione della console di Amazon Web Services. **Example Nomi di esempio** ``` Door Lock On/Off Wi-Fi Network Management PM2.5 Concentration Measurement RTCSessionController Energy EVSE ``` ## titolo L'elemento title è una stringa descrittiva per l'entità rappresentata dal documento dello schema. Può contenere qualsiasi carattere e viene utilizzato nella documentazione. La lunghezza massima per un titolo di funzionalità è di 256 caratteri. **Example Titoli di esempio** ``` Real-time Communication (RTC) Session Controller Energy EVSE Capability ``` ## description L'`description`elemento fornisce una spiegazione dettagliata dell'entità rappresentata dal documento dello schema. Può contenere qualsiasi carattere e viene utilizzato nella documentazione. La lunghezza massima per una descrizione delle funzionalità è di 2048 caratteri **Example Descrizione di esempio** ``` 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 L’elemento `version` è facoltativo. È una stringa che rappresenta la versione del documento dello schema. Vengono applicati i seguenti vincoli: + Utilizza il formato semver, con i seguenti frammenti di versione separati da `.` (punti). + `MAJOR`versione, massimo 3 cifre + `MINOR`versione, massimo 3 cifre + `PATCH`versione (opzionale), massimo 4 cifre + La lunghezza può essere compresa tra 3 e 12 caratteri. **Example Versioni di esempio** ``` 1.0 ``` ``` 1.12 ``` ``` 1.4.1 ``` ### Utilizzo delle versioni con funzionalità Una funzionalità è un'entità con versioni immutabili. Qualsiasi modifica dovrebbe creare una nuova versione. Il sistema utilizza il controllo delle versioni semantiche con MAJOR.MINOR.PATCH formato, dove: + La versione MAJOR aumenta quando si apportano modifiche all'API incompatibili con le versioni precedenti + La versione MINOR aumenta quando si aggiungono funzionalità in modo retrocompatibile + La versione PATCH aumenta quando si apportano aggiunte minori e senza impatto sulla funzionalità. Le funzionalità derivate dai cluster Matter sono basate sulla versione 1.4 e ogni versione di Matter dovrebbe essere importata nel sistema. Poiché la versione Matter utilizza i livelli MAJOR e MINOR di semver, le integrazioni gestite possono utilizzare solo le versioni PATCH. Quando aggiungi versioni PATCH per Matter, assicurati di tenere conto del fatto che Matter utilizza revisioni sequenziali. Tutte le versioni PATCH devono essere conformi alla revisione documentata nella specifica Matter e devono essere retrocompatibili. Per risolvere eventuali problemi di incompatibilità con le versioni precedenti, è necessario collaborare con la Connectivity Standards Alliance (CSA) per risolverli nelle specifiche e rilasciare una nuova revisione. AWS-le funzionalità gestite sono state rilasciate con una versione iniziale di. `1.0` Con queste, è possibile utilizzare tutti e tre i livelli di versione. ## Extrinsic Version (obbligatoria) Questa è una stringa che rappresenta una versione gestita all'esterno del sistema. AWS IoT Per le funzionalità di Matter, esegue il `extrinsicVersion` mapping a `revision` È rappresentato come un valore intero con stringhe e la lunghezza può essere compresa tra 1 e 10 cifre numeriche. **Example Versioni di esempio** ``` 7 ``` ``` 1567 ``` ## ExtrinsICID (obbligatorio) L'`extrinsicId`elemento rappresenta un identificatore gestito all'esterno del sistema IoT di Amazon Web Services. Per le funzionalità di Matter, viene mappato a `clusterId` `attributeId``commandId`,`eventId`,, o`fieldId`, a seconda del contesto. `extrinsicId`Può essere un numero intero decimale con stringhe (1-10 cifre) o un intero esadecimale con stringhe (prefisso 0x o 0X, seguito da 1-8 cifre esadecimali). **Nota** Per, l' AWS ID fornitore (VID) è 0x1577 e per Matter è 0. Il sistema garantisce che gli schemi personalizzati non utilizzino questi VID riservati per le funzionalità. **Example Esempio: ExtrinsICIDS** ``` 0018 0x001A 0x15771002 ``` ## $defs La `$defs` sezione è una mappa di sottoschemi a cui è possibile fare riferimento all'interno del documento dello schema, come consentito dallo schema JSON. In questa mappa, la chiave viene utilizzata nelle definizioni di riferimento locali e il valore fornisce lo schema JSON. **Nota** Il sistema impone solo che `$defs` sia una mappa valida e che ogni sottoschema sia uno schema JSON valido. Non viene applicata alcuna regola aggiuntiva. Segui questi vincoli quando lavori con le definizioni: + Usa solo URI-friendly caratteri nei nomi delle definizioni + Assicurati che ogni valore sia un sottoschema valido + Includi un numero qualsiasi di sottoschemi che rientrano nei limiti di dimensione del documento dello schema ## Proprietà estrinseche L'`extrinsicProperties`elemento contiene un insieme di proprietà definite in un sistema esterno ma mantenute all'interno del modello di dati. Per quanto riguarda le funzionalità di Matter, esegue il mapping a diversi elementi non modellati o parzialmente modellati all'interno del cluster, dell'attributo, del comando o dell'evento ZCL. Le proprietà estrinseche devono rispettare questi vincoli: + I nomi delle proprietà devono essere alfanumerici senza spazi o caratteri speciali + I valori delle proprietà possono essere qualsiasi valore dello schema JSON + Massimo 20 proprietà Il sistema supporta diverse funzionalità`extrinsicProperties`, tra cui `access``apiMaturity`,`cli`,`cliFunctionName`, e altre ancora. Queste proprietà facilitano le trasformazioni tra ACL e modelli di dati AWS (e viceversa). **Nota** Le proprietà estrinseche sono supportate per gli elementi `action``event`,`property`, e `struct` fields di una funzionalità, ma non per la capacità o il cluster stesso. ## Properties Le proprietà rappresentano gli stati della funzionalità gestiti dal dispositivo. Ogni stato è definito come una coppia chiave-valore, in cui la chiave descrive il nome dello stato e il valore descrive la definizione dello stato. Quando lavorate con le proprietà, seguite questi vincoli: + Utilizzate solo caratteri alfanumerici nei nomi delle proprietà, senza spazi o caratteri speciali + Includi un numero qualsiasi di proprietà che rientrano nei limiti di dimensione del documento dello schema ### Lavorare con le proprietà Una proprietà all'interno di una funzionalità è un elemento fondamentale che rappresenta uno stato specifico di un dispositivo basato su integrazioni gestite. Rappresenta la condizione o la configurazione corrente del dispositivo. Standardizzando il modo in cui queste proprietà sono definite e strutturate, i sistemi di casa intelligente garantiscono che i dispositivi di diversi produttori possano comunicare in modo efficace, creando un'esperienza fluida e interoperabile. Per una proprietà di capacità, gli elementi obbligatori sono e. `extrinsicId` `value` Gli elementi opzionali di una proprietà di capacità sono `description``retrievable`,`mutable`, `reportable` e`extrinsicProperties`. #### Valore Una struttura illimitata che consente ai costruttori di imporre qualsiasi vincolo JSON-schema conforme per definire il tipo di dati di questa proprietà. Quando definisci i valori, segui questi vincoli: + Per tipi semplici, usa `type` e qualsiasi altro JSON-schema vincolo nativo come o `maxLength` `maximum` + Per i tipi compositi, usa `oneOf``allOf`, o. `anyOf` Il sistema non supporta la `not` parola chiave + Per fare riferimento a qualsiasi tipo globale, usala `$ref` con un riferimento rilevabile valido + Per l'annullabilità, segui la definizione dello schema del tipo OpenAPI fornendo all'attributo nullable un flag booleano (se null è un valore consentito) `true` Esempio: ``` { "$ref": "/schema-versions/definition/matter.uint16@1.4", "nullable": true, "maximum": 4096 } ``` #### Recuperabile Un booleano che descrive se lo stato è leggibile o meno. L'aspetto della leggibilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è leggibile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema. Esempio: `true` o `false` #### Mutable Un booleano che descrive se lo stato è scrivibile o meno. L'aspetto della scrivibilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è scrivibile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema. Esempio: `true` o `false` #### Segnalabile Un booleano che descrive se lo stato viene segnalato dal dispositivo quando c'è un cambiamento nello stato. L'aspetto relativo alla rendicontabilità dello stato è rimandato all'implementazione della funzionalità da parte del dispositivo. Il dispositivo decide se un determinato stato è segnalabile o meno. Questo aspetto dello stato non è ancora supportato per essere riportato nel rapporto sulla capacità e quindi non è applicato all'interno del sistema. Esempio: `true` o `false` ## Azioni Le azioni sono operazioni gestite dallo schema che seguono un modello di richiesta-risposta. Ogni azione rappresenta un'operazione implementata dal dispositivo. Segui questi vincoli durante l'implementazione delle azioni: + Includi solo azioni univoche nell'array delle azioni + Includi un numero qualsiasi di azioni che rientrano nei limiti di dimensione del documento dello schema ### Utilizzo di operazioni Un'azione è un modo standardizzato per interagire e controllare le funzionalità dei dispositivi in un sistema di integrazione gestito. Rappresenta un comando o un'operazione specifico che può essere eseguito su un dispositivo, completo di un formato strutturato per modellare qualsiasi parametro di richiesta o risposta necessario. Queste azioni fungono da ponte tra le intenzioni degli utenti e le operazioni del dispositivo, consentendo un controllo coerente e affidabile su diversi tipi di dispositivi intelligenti. Per un'azione, gli elementi obbligatori sono `name` e`extrinsicId`. Gli elementi opzionali sono `description``extrinsicProperties`, `request` e`response`. ### Description La descrizione ha un limite di lunghezza massimo di 1536 caratteri. ### Richiesta La sezione di richiesta è facoltativa e può essere omessa se non ci sono parametri di richiesta. Se omessa, il sistema supporta l'invio di una richiesta senza alcun payload utilizzando semplicemente il nome di. `Action` Viene utilizzato per azioni semplici, come accendere o spegnere una luce. Le azioni complesse richiedono parametri aggiuntivi. Ad esempio, una richiesta di streaming delle riprese della telecamera potrebbe includere parametri relativi al protocollo di streaming da utilizzare o se inviare lo streaming a un dispositivo di visualizzazione specifico. Per una richiesta di azione, l'elemento obbligatorio è`parameters`. Gli elementi opzionali sono `description``extrinsicId`, e`extrinsicProperties`. #### Descrizione della richiesta La descrizione segue lo stesso formato della sezione 3.5, con una lunghezza massima di 2048 caratteri. ### Risposta Nelle integrazioni gestite, per ogni richiesta di azione inviata tramite l'[SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API, la richiesta raggiunge il dispositivo e prevede una risposta asincrona. La risposta all'azione definisce la struttura di questa risposta. Per una richiesta di azione, l'elemento obbligatorio è`parameters`. Gli elementi opzionali sono `name``description`,`extrinsicId`,`extrinsicProperties`, `errors` e`responseCode`. #### Descrizione della risposta La descrizione segue lo stesso [description](#capability-schema-description) formato e ha una lunghezza massima di 2048 caratteri. #### Nome della risposta Il nome segue lo stesso formato di[nome (obbligatorio)](#capability-schema-name), con questi dettagli aggiuntivi: + Il nome convenzionale di una risposta è derivato dall'aggiunta `Response` al nome dell'azione. + Se desideri utilizzare un nome diverso, puoi fornirlo in questo `name` elemento. Se nella risposta `name` viene fornito a, questo valore ha la precedenza maggiore rispetto al nome convenzionale. #### Errori Una matrice illimitata di messaggi univoci fornita nella risposta, in caso di errori durante l'elaborazione della richiesta. Vincoli: + Un elemento del messaggio viene dichiarato come oggetto JSON con i seguenti campi: + `code`: Una stringa contenente caratteri alfanumerici e `_` (caratteri di sottolineatura), con una lunghezza compresa tra 1 e 64 caratteri + `message`: valore di stringa illimitato **Example Esempio di messaggio di errore** ``` "errors": [ { "code": "AD_001", "message": "Unable to receive signal from the sensor. Please check connection with the sensor." } ] ``` #### Codice di risposta Un codice intero che mostra come è stata gestita la richiesta. È consigliabile che il codice del dispositivo restituisca un codice utilizzando la specifica del codice di stato della risposta del server HTTP per consentire l'uniformità all'interno del sistema. Vincolo: un valore intero compreso tra 100 e 599. ### Parametri di richiesta o risposta La sezione dei parametri è definita come una mappa di coppie di nomi e sottoschemi. È possibile definire un numero qualsiasi di parametri all'interno dei parametri della richiesta, se rientrano nel documento dello schema. I nomi dei parametri possono contenere solo caratteri alfanumerici. Gli spazi o altri caratteri non sono consentiti. #### campo dei parametri Gli elementi obbligatori in a `parameter` sono `extrinsicId` e`value`. Gli elementi opzionali sono `description` e`extrinsicProperties`. L'elemento di descrizione segue lo stesso formato di[description](#capability-schema-description), con una lunghezza massima di 1024 caratteri. ### `ExtrinSicID ed ExtrinsicProperties sovrascrivono` `extrinsicId`e `extrinsicProperties` seguono lo stesso formato di e, con questi dettagli aggiuntivi: [ExtrinsICID (obbligatorio)](#capability-schema-extrinsicId) [Proprietà estrinseche](#capability-schema-extrinsicProperties) + Se nella richiesta o nella risposta `extrinsicId` viene fornito un, questo valore ha la precedenza maggiore rispetto al valore fornito a livello di azione. Il sistema deve `extrinsicId` prima utilizzare request/response il livello, se manca utilizzare il livello di azione `extrinsicId` + `extrinsicProperties`Se fornite nella richiesta o nella risposta, queste proprietà hanno la precedenza maggiore rispetto al valore va fornito a livello di azione. Il sistema deve passare al livello di azione `extrinsicProperties` e sostituire le coppie chiave-valore fornite a livello request/response `extrinsicProperties` **Example Esempio di override di ExtrinsicId ed ExtrinsicProperties** ``` { "name": "ToggleWithEffect", "extrinsicId": "0x0001", "extrinsicProperties": { "apiMaturity": "provisional", "introducedIn": "1.2" }, "request": { "extrinsicProperties": { "apiMaturity": "stable", "manufacturerCode": "XYZ" }, "parameters": { ... } }, "response": { "extrinsicProperties": { "noDefaultImplementation": true }, "parameters": { { ... } } } ``` Nell'esempio precedente, i valori effettivi per la richiesta di azione sarebbero: ``` # 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 azioni Per tutte le funzionalità, è possibile eseguire azioni personalizzate utilizzando le parole chiave `ReadState` e`UpdateState`. Queste due parole chiave di azione agiranno sulle proprietà della funzionalità definite nel modello di dati. ReadState Invia un comando a `managedThing` per leggere i valori delle sue proprietà di stato. Viene utilizzato `ReadState` come metodo per forzare l'aggiornamento dello stato del dispositivo. UpdateState Invia un comando per aggiornare alcune proprietà. Forzare la sincronizzazione dello stato del dispositivo può essere utile nei seguenti scenari: 1. Il dispositivo è rimasto offline per un periodo di tempo e non emetteva eventi. 1. Il dispositivo è stato appena fornito e non dispone ancora di alcuno stato mantenuto nel cloud. 1. Lo stato del dispositivo non è sincronizzato con lo stato reale del dispositivo. #### ReadState esempi Controlla se la luce è accesa o spenta utilizzando l'[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" ] } } ] } ] } ] } ``` Leggi tutte le proprietà dello stato relative alla `matter.OnOff` funzionalità: ``` { "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 esempio Cambia il `OnTime` formato per una luce usando l'[SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API: ``` { "Endpoints": [ { "endpointId": "1", "capabilities": [ { "id": "matter.OnOff", "name": "On/Off", "version": "1", "actions": [ { "name": "UpdateState", "parameters": { "OnTime": 5 } } ] } ] } ] } ``` ## Eventi Gli eventi sono segnali unidirezionali gestiti dallo schema e implementati dal dispositivo. Implementa gli eventi in base a questi vincoli: + Includi solo eventi unici nell'array degli eventi + Includi un numero qualsiasi di eventi che rientrano nei limiti di dimensione del documento dello schema