Editar um modelo de dispositivo

Um modelo de dispositivo inclui um modelo que descreve como um dispositivo interage com o IoT Central. Esse modelo define os recursos do dispositivo e como o IoT Central interage com eles. Os dispositivos podem enviar telemetria e valores de propriedade para o IoT Central, e o IoT Central pode enviar atualizações de propriedade e comandos para um dispositivo. O IoT Central também usa o modelo para definir interações com os recursos do IoT Central, como trabalhos, regras e exportações.

As alterações no modelo em um modelo de dispositivo podem afetar todo o aplicativo, incluindo todos os dispositivos conectados. Alterações em um recurso usado por regras, exportações, grupos de dispositivos ou trabalhos podem fazer com que eles se comportem de forma inesperada ou nem funcionem. Por exemplo, se você remover uma definição de telemetria de um modelo:

• O IoT Central não é mais capaz de interpretar esse valor. O IoT Central mostra os dados do dispositivo que não podem ser interpretados como Dados não modelados na página Dados brutos do dispositivo.
• O IoT Central não inclui mais o valor em nenhuma exportação de dados.

Para ajudá-lo a evitar consequências não intencionais da edição de um modelo de dispositivo, este artigo inclui recomendações com base no estágio atual do ciclo de vida de desenvolvimento. Em geral, quanto antes você estiver no ciclo de vida de desenvolvimento, mais tolerante você pode ser às alterações de modelo de dispositivo.

Para saber mais sobre modelos de dispositivo e como criar um, confira O que são modelos de dispositivo? e Configurar um modelo de dispositivo.

Para saber como gerenciar modelos de dispositivo usando a API REST do IoT Central, consulte Como usar a API REST do IoT Central para gerenciar modelos de dispositivo.

Modificar um modelo de dispositivo

Mudanças aditivas, como adicionar um recurso ou interface a um modelo, são mudanças ininterruptas. Você pode fazer alterações aditivas em um modelo em qualquer estágio do ciclo de vida de desenvolvimento.

As alterações interruptivas incluem a remoção de partes de um modelo ou a alteração de um nome de funcionalidade ou tipo de esquema. Essas alterações podem fazer com que os recursos do aplicativo, como regras, exportações ou dashboards, exibam mensagens de erro e parem de funcionar.

Nas fases antecipadas de desenvolvimento de dispositivo, enquanto você ainda estiver projetando e testando o modelo, há maior tolerância para fazer alterações diretamente no modelo de dispositivo. Você pode editar o modelo de dispositivo diretamente, antes de conectar os dispositivos de produção a um modelo de dispositivo. O IoT Central aplica essas alterações automaticamente aos dispositivos quando você publica o modelo de dispositivo.

Depois de anexar dispositivos de produção a um modelo de dispositivo, avalie o impacto de quaisquer alterações antes de editar um modelo de dispositivo. Você não deve fazer alterações significativas em um modelo de dispositivo em produção. Para fazer essas alterações, crie uma nova versão do modelo de dispositivo. Teste o novo modelo de dispositivo e migre seus dispositivos de produção para o novo modelo em um tempo de inatividade agendado.

Atualizar um modelo de dispositivo IoT Edge

Para um dispositivo IoT Edge, o modelo agrupa os recursos por módulos que correspondem aos módulos IoT Edge em execução no dispositivo. O manifesto de implantação é um documento JSON separado que informa a um dispositivo IoT Edge quais módulos instalar, como configurá-los e quais propriedades o módulo tem. Se você modificar um manifesto de implantação, poderá atualizar o modelo do dispositivo para incluir os módulos e as propriedades definidas no manifesto:

1. Navegue até o nó Módulos no modelo de dispositivo.
2. Na página Resumo de módulos, selecione Importar módulos do manifesto.
3. Selecione o manifesto de implantação apropriado e selecione Importar.

Para saber mais, consulte Dispositivos IoT Edge e IoT Central.

Editar e publicar ações

As ações a seguir são úteis quando você edita um modelo de dispositivo:

• Salvar. Salvar as alterações cria um rascunho para o qual você pode retornar quando você altera parte do modelo de dispositivo. Essas alterações ainda não afetam os dispositivos conectados. Quaisquer dispositivos criados a partir desse modelo não terão as alterações salvas até que você as publique.
• Publicação. Quando você publica o modelo de dispositivo, ele aplica as alterações salvas às instâncias de dispositivo existentes. Instâncias de dispositivo recém-criadas sempre usam o modelo publicado mais recente.
• Fazer o controle de versão de um modelo. Quando você faz o controle da versão de um modelo de dispositivo, ele cria um novo modelo com todas as alterações salvas mais recentes. As alterações feitas em uma nova versão não afetam as instâncias de dispositivos existentes. Para saber mais, consulte Fazer o controle de versão em um modelo de dispositivo.
• Fazer o controle de versão de uma interface. Quando você faz o controle da versão de uma interface, ela cria uma nova interface com todos os recursos salvos mais recentes. Você pode reutilizar uma interface em vários locais dentro de um modelo. É por isso que uma alteração feita em uma referência a uma interface altera todos os locais no modelo que usam a interface. Quando você faz o controle da versão de uma interface, esse comportamento muda porque a nova versão agora é uma interface separada. Para saber mais, confira Controle de versão de uma interface.
• Migrar um dispositivo. Quando você migra um dispositivo, a instância do dispositivo troca de um modelo de dispositivo para outro. A migração de dispositivo pode causar um curto enquanto IoT Central processa as alterações. Para saber mais, confira Migrar um dispositivo entre versões.

Números de versão

Os modelos de dispositivo e as interfaces têm números de versão. Números de versão diferentes permitem que modelos ou interfaces compartilhem @id um valor, fornecendo um histórico de atualizações. Os números de versão só incrementam se você optar por fazer a versão do modelo ou da interface ou se alterar deliberadamente o número de versão. Você deve alterar um número de versão quando fizer uma alteração importante em um modelo ou interface.

O snippet a seguir mostra o modelo para um dispositivo de termostato. O modelo de dispositivo tem uma única interface. Você pode ver o número de versão 1 no final do campo @id.

{
  "@context": "dtmi:dtdl:context;2",
  "@id": "dtmi:com:example:Thermostat;1",
  "@type": "Interface",
  "displayName": "Thermostat",
  "description": "Reports current temperature and provides desired temperature control.",
  "contents": [
    // ...
  ]
}

Para exibir essas informações na interface do usuário do IoT Central, selecione Exibir identidade no editor de modelos de dispositivo:

Fazer o controle de versão de um modelo de dispositivo

Para fazer o controle de versão de um modelo de dispositivo:

1. Acesse a página Modelos de dispositivo.
2. Selecione o modelo de dispositivo para o qual você está fazendo o controle de versão.
3. Selecione Versão na parte superior da página e dê um novo nome ao modelo. O IoT Central sugere um novo nome, que você pode editar.
4. Selecione Criar.

Agora você criou um novo modelo com uma identidade exclusiva que não está anexada a nenhum dispositivo existente.

Fazer o controle de versão de uma interface

Para fazer o controle de versão de uma interface:

1. Acesse a página Modelos de dispositivo.
2. Selecione o modelo de dispositivo que está no modo de rascunho.
3. Selecione a interface publicada que você deseja controlar a versão e a edição.
4. Selecione Versão na parte superior da página de interface.
5. Selecione Criar.

Agora você criou uma nova interface com uma identidade exclusiva que não está sincronizada com a versão anterior da interface.

Migrar um dispositivo entre versões

É possível criar várias versões do modelo de dispositivo. Com o tempo, você terá vários dispositivos conectados usando esses modelos de dispositivo. Você pode migrar dispositivos de uma versão do modelo de dispositivo para outra. As etapas a seguir descrevem como migrar um dispositivo:

1. Acesse a página Dispositivos.

2. Selecione o dispositivo que você precisa migrar para outra versão.

3. Escolha Migrar:

   

4. Selecione o modelo de dispositivo com a versão para a qual você deseja migrar o dispositivo e selecione Migrar.

Dica

É possível usar um trabalho para migrar todos os dispositivos em um grupo de dispositivos para um novo modelo de dispositivo ao mesmo tempo.