As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Esquema para definições de capacidade Um recurso é documentado usando um documento JSON declarativo que fornece um contrato claro de como o recurso deve funcionar no sistema. Para um recurso, os elementos obrigatórios são `$id``name`,`extrinsicId`, `extrinsicVersion` e pelo menos um elemento em pelo menos uma das seções a seguir: + `properties` + `actions` + `events` Os elementos opcionais em um recurso são `$ref` `title``description`,`version`,, `$defs` `extrinsicProperties` e. Para obter uma capacidade, `$ref` deve consultar `aws.capability` a. As seções a seguir detalham o esquema usado para definições de capacidade. ## $id (obrigatório) O elemento $id identifica a definição do esquema. Ele deve seguir esta estrutura: + Comece com o prefixo `/schema-versions/` URI + Incluir o `capability` tipo de esquema + Use uma barra (`/`) como separador de caminho de URI + Inclua a identidade do esquema, com fragmentos separados por pontos () `.` + Use o `@` caractere para separar o ID do esquema e a versão + Termine com a versão semver, usando pontos (`.`) para separar os fragmentos da versão A identidade do esquema deve começar com um namespace raiz de 3 a 12 caracteres, seguido por um nome e um subnamespace opcionais. A versão semver inclui uma versão MAJOR (até 3 dígitos), uma versão MINOR (até 3 dígitos) e uma versão PATCH opcional (até 4 dígitos). **nota** Você não pode usar os namespaces `aws` reservados ou `matter` **Example Exemplo $id** ``` /schema-version/capability/aws.Recording@1.0 ``` ## $ ref O `$ref` elemento faz referência a um recurso existente no sistema. Ele segue as mesmas restrições do `$id` elemento. **nota** Deve existir uma definição de tipo ou capacidade com o valor fornecido no `$ref` arquivo. **Example Exemplo $ref** ``` /schema-version/definition/aws.capability@1.0 ``` ## nome (obrigatório) O elemento name é uma string que representa o nome da entidade no documento do esquema. Geralmente contém abreviações e deve seguir estas regras: + Contém somente caracteres alfanuméricos, pontos (.), barras (/), hífens (-) e espaços + Comece com uma letra + Máximo de 64 caracteres O elemento name é usado na interface de usuário e na documentação do console da Amazon Web Services. **Example Nomes de exemplo** ``` Door Lock On/Off Wi-Fi Network Management PM2.5 Concentration Measurement RTCSessionController Energy EVSE ``` ## título O elemento title é uma string descritiva para a entidade representada pelo documento do esquema. Ele pode conter qualquer caractere e é usado na documentação. O tamanho máximo de um título de capacidade é de 256 caracteres. **Example Exemplos de títulos** ``` Real-time Communication (RTC) Session Controller Energy EVSE Capability ``` ## descrição O `description` elemento fornece uma explicação detalhada da entidade representada pelo documento do esquema. Ele pode conter qualquer caractere e é usado na documentação. O tamanho máximo para uma descrição de capacidade é de 2.048 caracteres. **Example Descrição do exemplo** ``` 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 O elemento `version` é opcional. É uma string que representa a versão do documento do esquema. As seguintes restrições se aplicam: + Usa o formato semver, com os seguintes fragmentos de versão separados por `.` (pontos). + `MAJOR`versão, máximo de 3 dígitos + `MINOR`versão, máximo de 3 dígitos + `PATCH`versão (opcional), máximo de 4 dígitos + O comprimento pode ter entre 3 e 12 caracteres. **Example Versões de exemplo** ``` 1.0 ``` ``` 1.12 ``` ``` 1.4.1 ``` ### Trabalhando com versões de recursos Um recurso é uma entidade versionada imutável. Espera-se que qualquer alteração crie uma nova versão. O sistema usa versionamento semântico com MAJOR.MINOR.PATCH formato, onde: + A versão MAJOR aumenta ao fazer alterações de API incompatíveis com versões anteriores + A versão MINOR aumenta ao adicionar funcionalidades de maneira compatível com versões anteriores + A versão PATCH aumenta ao fazer pequenas adições não impactantes no recurso. Os recursos derivados dos clusters do Matter são baseados na versão 1.4 e espera-se que cada versão do Matter seja importada para o sistema. Como a versão Matter consome os níveis MAJOR e MINOR do semver, as integrações gerenciadas só podem usar as versões PATCH. Ao adicionar versões PATCH para o Matter, lembre-se de que o Matter usa revisões sequenciais. Todas as versões do PATCH devem estar em conformidade com a revisão documentada na especificação Matter e devem ser compatíveis com versões anteriores. Para corrigir quaisquer problemas de incompatibilidade com versões anteriores, você deve trabalhar com a Connectivity Standards Alliance (CSA) para resolver os problemas da especificação e lançar uma nova revisão. AWS-os recursos gerenciados foram lançados com uma versão inicial do`1.0`. Com eles, todos os três níveis da versão podem ser usados. ## Versão extrínseca (obrigatória) Essa é uma string representando uma versão gerenciada fora do AWS IoT sistema. Para recursos do Matter, `extrinsicVersion` mapeia para `revision` Ele é representado como um valor inteiro em cadeia e o comprimento pode ser de 1 a 10 dígitos numéricos. **Example Versões de exemplo** ``` 7 ``` ``` 1567 ``` ## ExtrinsICID (obrigatório) O `extrinsicId` elemento representa um identificador gerenciado fora do sistema de IoT da Amazon Web Services. Para os recursos do Matter`clusterId`, ele mapeia para `attributeId` `commandId``eventId`,,`fieldId`, ou, dependendo do contexto. O `extrinsicId` pode ser um inteiro decimal em sequência (1 a 10 dígitos) ou um inteiro hexadecimal em sequência (prefixo 0x ou 0X, seguido por 1 a 8 dígitos hexadecimais). **nota** Para AWS, o ID do fornecedor (VID) é 0x1577 e, para o Matter, é 0. O sistema garante que esquemas personalizados não usem esses VIDs reservados como recursos. **Example Exemplo de extrinsicidas** ``` 0018 0x001A 0x15771002 ``` ## $ defs A `$defs` seção é um mapa de subesquemas que podem ser referenciados no documento do esquema, conforme permitido pelo esquema JSON. Nesse mapa, a chave é usada nas definições de referência locais e o valor fornece o esquema JSON. **nota** O sistema apenas impõe que `$defs` seja um mapa válido e que cada subesquema seja um esquema JSON válido. Nenhuma regra adicional é aplicada. Siga estas restrições ao trabalhar com definições: + Use somente URI-friendly caracteres em nomes de definição + Certifique-se de que cada valor seja um subesquema válido + Inclua qualquer número de subesquemas que se encaixem nos limites de tamanho do documento do esquema ## Propriedades extrínsecas O `extrinsicProperties` elemento contém um conjunto de propriedades definidas em um sistema externo, mas mantidas dentro do modelo de dados. Para os recursos do Matter, ele mapeia para diferentes elementos não modelados ou parcialmente modelados dentro do cluster, atributo, comando ou evento ZCL. As propriedades extrínsecas devem seguir estas restrições: + Os nomes das propriedades devem ser alfanuméricos, sem espaços ou caracteres especiais + Os valores das propriedades podem ser qualquer valor do esquema JSON + Máximo de 20 propriedades O sistema oferece suporte a vários `extrinsicProperties``access`, incluindo`apiMaturity`,`cli`,`cliFunctionName`, e outros. Essas propriedades facilitam a ACL para AWS (e vice-versa) as transformações do modelo de dados. **nota** As propriedades extrínsecas são suportadas para os elementos `action``event`,`property`, e `struct` fields de um recurso, mas não para o recurso ou cluster em si. ## Propriedades As propriedades representam os estados do recurso gerenciados pelo dispositivo. Cada estado é definido como um par de valores-chave, em que a chave descreve o nome do estado e o valor descreve a definição do estado. Ao trabalhar com propriedades, siga estas restrições: + Use somente caracteres alfanuméricos nos nomes das propriedades, sem espaços ou caracteres especiais + Inclua qualquer número de propriedades que se encaixem nos limites de tamanho do documento do esquema ### Trabalhando com propriedades Uma propriedade dentro de um recurso é um elemento fundamental que representa um estado específico de um dispositivo alimentado por integrações gerenciadas. Ela representa a condição ou configuração atual do dispositivo. Ao padronizar a forma como essas propriedades são definidas e estruturadas, os sistemas domésticos inteligentes garantem que dispositivos de diferentes fabricantes possam se comunicar de forma eficaz, criando uma experiência perfeita e interoperável. Para uma propriedade de capacidade, os elementos obrigatórios são `extrinsicId` `value` e. Os elementos opcionais em uma propriedade de capacidade são `description` `retrievable``mutable`,, `reportable` `extrinsicProperties` e. #### Valor Uma estrutura ilimitada que permite que os construtores coloquem quaisquer restrições JSON-schema compatíveis para definir o tipo de dados dessa propriedade. Ao definir valores, siga estas restrições: + Para tipos simples, use `type` e quaisquer outras JSON-schema restrições nativas, como ou `maxLength` `maximum` + Para tipos compostos, use `oneOf``allOf`, ou`anyOf`. O sistema não suporta a `not` palavra-chave + Para se referir a qualquer tipo global, use `$ref` com uma referência detectável válida + Para a nulidade, siga a definição do esquema do tipo OpenAPI fornecendo ao atributo anulável um sinalizador booleano (se nulo for um valor permitido) `true` Exemplo: ``` { "$ref": "/schema-versions/definition/matter.uint16@1.4", "nullable": true, "maximum": 4096 } ``` #### Recuperável Um booleano que descreve se o estado é legível ou não. O aspecto de legibilidade do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é legível ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema. Exemplo: `true` ou `false` #### Mutable Um booleano que descreve se o estado é gravável ou não. O aspecto de capacidade de gravação do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é gravável ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema. Exemplo: `true` ou `false` #### Reportável Um booleano que descreve se o estado é relatado pelo dispositivo quando há uma mudança no estado. O aspecto de reportabilidade do estado é adiado para a implementação do recurso pelo dispositivo. O dispositivo decide se um determinado estado é reportável ou não. Esse aspecto do estado ainda não tem suporte para ser relatado no relatório de capacidade e, portanto, não é aplicado no sistema. Exemplo: `true` ou `false` ## Ações As ações são operações gerenciadas pelo esquema que seguem um modelo de solicitação-resposta. Cada ação representa uma operação implementada pelo dispositivo. Siga estas restrições ao implementar ações: + Incluir somente ações exclusivas na matriz de ações + Inclua qualquer número de ações que se encaixem nos limites de tamanho do documento do esquema ### Trabalhar com ações Uma ação é uma forma padronizada de interagir e controlar os recursos do dispositivo em um sistema de integração gerenciado. Ele representa um comando ou operação específica que pode ser executada em um dispositivo, com um formato estruturado para modelar quaisquer parâmetros de solicitação ou resposta necessários. Essas ações servem como ponte entre as intenções do usuário e as operações do dispositivo, permitindo um controle consistente e confiável em diferentes tipos de dispositivos inteligentes. Para uma ação, os elementos obrigatórios são `name` `extrinsicId` e. Os elementos opcionais são `description``extrinsicProperties`, `request` `response` e. ### Description A descrição tem uma restrição de tamanho máximo de 1536 caracteres. ### Solicitação A seção de solicitação é opcional e pode ser omitida se não houver parâmetros de solicitação. Se omitido, o sistema suporta o envio de uma solicitação sem qualquer carga usando apenas o nome de. `Action` Isso é usado em ações simples, como acender ou apagar uma luz. As ações complexas precisam de parâmetros adicionais. Por exemplo, uma solicitação para transmitir imagens da câmera pode incluir parâmetros sobre o protocolo de streaming a ser usado ou se o stream deve ser enviado para um dispositivo de exibição específico. Para uma solicitação de ação, o elemento obrigatório é`parameters`. Os elementos opcionais são `description``extrinsicId`, `extrinsicProperties` e. #### Descrição da solicitação A descrição segue o mesmo formato da seção 3.5, com um tamanho máximo de 2048 caracteres. ### Resposta Nas integrações gerenciadas, para qualquer solicitação de ação enviada pela [SendManagedThingCommand](https://docs.aws.amazon.com/iot-mi/latest/APIReference/API_SendManagedThingCommand.html)API, a solicitação chega ao dispositivo e espera uma resposta assíncrona. A resposta da ação define a estrutura dessa resposta. Para uma solicitação de ação, o elemento obrigatório é`parameters`. Os elementos opcionais são `name` `description``extrinsicId`,`extrinsicProperties`,, `errors` `responseCode` e. #### Descrição da resposta A descrição segue o mesmo formato e tem um tamanho máximo de 2048 caracteres. [descrição](#capability-schema-description) #### Nome da resposta O nome segue o mesmo formato de[nome (obrigatório)](#capability-schema-name), com esses detalhes adicionais: + O nome convencional de uma resposta é derivado do acréscimo `Response` ao nome da ação. + Se quiser usar um nome diferente, você pode fornecê-lo nesse `name` elemento. Se a `name` for fornecido na resposta, esse valor terá maior precedência do que o nome convencional. #### Erros Uma matriz ilimitada de mensagens exclusivas fornecidas na resposta, se houver erros durante o processamento da solicitação. Restrições: + Um item de mensagem é declarado como um objeto JSON com os seguintes campos: + `code`: uma sequência de caracteres contendo caracteres alfanuméricos e `_` (sublinhados), com um comprimento entre 1 e 64 caracteres + `message`: um valor de string ilimitado **Example Exemplo de mensagem de erro** ``` "errors": [ { "code": "AD_001", "message": "Unable to receive signal from the sensor. Please check connection with the sensor." } ] ``` #### Código de resposta Um código inteiro mostrando como a solicitação foi tratada. Recomendamos que o código do dispositivo retorne um código usando a especificação do código de status de resposta do servidor HTTP para permitir uniformidade no sistema. Restrição: um valor inteiro que varia de 100 a 599. ### Parâmetros de solicitação ou resposta A seção de parâmetros é definida como um mapa de pares de nomes e subesquemas. Qualquer número de parâmetros pode ser definido nos parâmetros da solicitação, se eles couberem no documento do esquema. Os nomes dos parâmetros só podem conter caracteres alfanuméricos. Espaços ou quaisquer outros caracteres não são permitidos. #### campo de parâmetros Os elementos obrigatórios em um `parameter` são `extrinsicId` `value` e. Os elementos opcionais são `description` `extrinsicProperties` e. O elemento de descrição segue o mesmo formato que[descrição](#capability-schema-description), com um comprimento máximo de 1024 caracteres. ### `Substituições de propriedades extrínsecas e extrínsecas` o `extrinsicId` e `extrinsicProperties` segue o mesmo formato de [ExtrinsICID (obrigatório)](#capability-schema-extrinsicId) e[Propriedades extrínsecas](#capability-schema-extrinsicProperties), com esses detalhes adicionais: + Se um `extrinsicId` for fornecido na solicitação ou resposta, esse valor terá maior precedência do que o valor fornecido no nível da ação. O sistema deve usar o request/response nível `extrinsicId` primeiro, se estiver faltando, use o nível de ação `extrinsicId` + Se `extrinsicProperties` forem fornecidas na solicitação ou resposta, essas propriedades terão maior precedência do que o valor va fornecido no nível da ação. O sistema deve assumir o nível de ação `extrinsicProperties` e substituir os pares de valores-chave fornecidos no nível request/response `extrinsicProperties` **Example Exemplo de substituição de extrinsicId e extrinsicProperties** ``` { "name": "ToggleWithEffect", "extrinsicId": "0x0001", "extrinsicProperties": { "apiMaturity": "provisional", "introducedIn": "1.2" }, "request": { "extrinsicProperties": { "apiMaturity": "stable", "manufacturerCode": "XYZ" }, "parameters": { ... } }, "response": { "extrinsicProperties": { "noDefaultImplementation": true }, "parameters": { { ... } } } ``` No exemplo acima, os valores efetivos para a solicitação de ação seriam: ``` # 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 ações Para todos os recursos, você pode realizar ações personalizadas usando as palavras-chave `ReadState` `UpdateState` e. Essas duas palavras-chave de ação atuarão nas propriedades do recurso definidas no modelo de dados. ReadState Envia um comando para o `managedThing` para ler os valores de suas propriedades de estado. Use `ReadState` como forma de forçar a atualização do estado do dispositivo. UpdateState Envia um comando para atualizar algumas das propriedades. Forçar a sincronização do estado do dispositivo pode ser útil nos seguintes cenários: 1. O dispositivo ficou off-line por um período de tempo e não estava emitindo eventos. 1. O dispositivo acabou de ser provisionado e ainda não tem nenhum estado mantido na nuvem. 1. O estado do dispositivo está fora de sincronia com o estado real do dispositivo. #### ReadState exemplos Verifique se a luz está acesa ou apagada usando a [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" ] } } ] } ] } ] } ``` Leia todas as propriedades de estado do `matter.OnOff` recurso: ``` { "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 exemplo Altere o `OnTime` por uma luz usando a [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 } } ] } ] } ] } ``` ## Eventos Os eventos são sinais unidirecionais gerenciados pelo esquema implementados pelo dispositivo. Implemente eventos de acordo com essas restrições: + Inclua somente eventos exclusivos na matriz de eventos + Inclua qualquer número de eventos que se encaixem nos limites de tamanho do documento do esquema