Cenário: Fazer Upgrade de uma Instância Digital Twin para uma Versão Compatível do Modelo Digital Twin

1. Revise regras de controle de versão compatíveis do modelo de gêmeo digital.
2. Crie o modelo de gêmeo digital HVAC base.
3. Crie o adaptador de gêmeo digital HVAC base.
4. Crie a instância de gêmeo digital.
5. Enviar telemetria para a instância de gêmeo digital base.
6. Crie uma versão de modelo de gêmeo digital secundário compatível.
7. Crie um adaptador de gêmeo digital para a nova versão do modelo de gêmeo digital.
8. Atualize a instância do gêmeo digital para usar o novo adaptador do gêmeo digital.
9. Valide a telemetria da instância do gêmeo digital após o upgrade.
10. Verifique as Perguntas Mais Frequentes.
11. Diagnosticar e solucionar problemas de upgrade de modelo de gêmeo digital.

• Adicionando valores a um modelo de gêmeo digital existente: Use as etapas deste cenário para criar uma versão DTMI menor para alterações aditivas do modelo de gêmeo digital, por exemplo, altere a versão número de 1 a 1.1, isso mantém a versão principal do DTMI a mesma ao atualizar uma instância de gêmeo digital existente para um novo adaptador de gêmeo digital, conforme suportado na Especificação DTDL v3:

  dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;1.1

• Criando novos valores em seu modelo de gêmeo digital e, em seguida, criar uma nova instância de gêmeo digital: use uma nova versão DTMI principal, quando precisar criar um modelo de gêmeo digital com valores diferentes. Para esse tipo de atualização, você precisa criar uma nova instância de gêmeo digital com uma alteração de versão principal do novo modelo de gêmeo digital, por exemplo:

  dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;2

• Herança recomendada: Para atualizações secundárias, adicionando novos valores, é recomendável usar a herança para alterações aditivas no modelo de gêmeo digital, como um modelo de gêmeo digital que estende a versão anterior do modelo de gêmeo digital. Em vez de redefinir atributos básicos como @id, localização ou status principal para cada nova versão de modelo de gêmeo digital, o novo modelo de gêmeo digital herda os valores automaticamente, reduzindo erros e economizando tempo de desenvolvimento.
• Mantenha a telemetria, as propriedades, os comandos, os relacionamentos e os esquemas existentes compatíveis. Não renomeie, remova, restrinja ou altere os elementos de contrato existentes durante uma pequena atualização.
• Crie um novo adaptador de gêmeo digital para a nova versão de modelo de gêmeo digital e mantenha o adaptador de gêmeo digital anterior disponível para rollback até que os dispositivos atualizados sejam validados.
• Testar payloads com telemetria representativa antes de um rollout de produção.

• hvac-model.json: Modelo gêmeo digital da base DTDL para a telemetria da temperatura e da umidade.
• hvac-envelope.json: Envelope do adaptador gêmeo digital base que extrai timeObserved.
• hvac-routes.json: Mapeamento de rota do adaptador gêmeo digital base para temperatura e umidade.
• hvac-e-model.json: Versão compatível do modelo digital twin DTDL menor que adiciona telemetria de consumo de energia.
• hvac-e-envelope.json: Envelope de adaptador de gêmeo digital atualizado que aceita o campo de telemetria extra.
• hvac-e-routes.json: Mapeamento de rota de adaptador duplo digital atualizado para temperatura, umidade e consumo de energia.

Quando você cria um modelo de gêmeo digital, o OCI IoT verifica se já existe um modelo de gêmeo digital ativo para a mesma versão principal.

Se houver um, um novo modelo de gêmeo digital de versão secundária deverá ser estritamente aditivo com um número de versão e valores compatíveis. Quando você atualizar uma instância de gêmeo digital para usar outro adaptador de gêmeo digital, o adaptador deverá fazer referência à mesma versão de modelo de gêmeo digital ou a uma versão secundária superior compatível.

As seguintes verificações de compatibilidade se aplicam entre a versão antiga do modelo de gêmeo digital e a nova versão do modelo de gêmeo digital:

Quando você cria uma interface de gêmeo digital e uma versão de modelo atualizadas, a nova versão secundária deve ser exatamente a versão secundária anterior mais .1, por exemplo:

dtmi:com:oracle:example:hvac;1 a dtmi:com:oracle:example:hvac;1.1

Todos os valores da interface @id, incluindo o esquema e o caminho, devem corresponder; a nova versão secundária, as únicas coisas que podem ser novas, são o número da versão com incrementos menores e quaisquer valores adicionais que sejam adicionados ao modelo existente. As atualizações só são compatíveis quando a versão principal permanece constante e permanece inalterada.

Crie o modelo gêmeo digital base com telemetria de temperatura e umidade.

Crie um adaptador de gêmeo digital que faça referência à versão de modelo de gêmeo digital HVAC base e mapeie a carga útil do dispositivo para os campos de telemetria de modelo de gêmeo digital.

Crie uma instância de gêmeo digital que use o adaptador de gêmeo digital HVAC base. A chave externa é o nome de usuário que o dispositivo usa quando se conecta.

Envie um payload que corresponda ao mapeamento do adaptador de gêmeo digital base e, em seguida, obtenha o conteúdo da instância de gêmeo digital para verificar a telemetria normalizada.

Obtenha o conteúdo da instância do gêmeo digital para verificar os valores normalizados mais recentes.

Crie uma versão compatível do modelo de gêmeo digital secundário que extends o modelo de gêmeo digital HVAC base e adicione telemetria para consumo de energia. A versão principal permanece 1 e a versão secundária aumenta para 1.1.

Crie um novo adaptador de gêmeo digital que faça referência à versão de modelo de gêmeo digital HVAC menor compatível e mapeie o campo de telemetria adicional.

Atualize a instância de gêmeo digital existente para fazer referência ao adaptador de gêmeo digital para a versão de modelo de gêmeo digital secundário compatível. A instância de gêmeo digital mantém a mesma identidade, chave externa e continuidade de dados enquanto começa a aceitar cargas úteis para o novo contrato de modelo de gêmeo digital.

Envie um payload que inclua o novo campo de telemetria e verifique se o conteúdo da instância de gêmeo digital inclui os valores mapeados pelo adaptador de gêmeo digital atualizado.

Se a validação falhar, compare o modelo de gêmeo digital DTMI, o adaptador de gêmeo digital --digital-twin-model-spec-uri, o mapeamento de envelope e o mapeamento de payload de rota. O adaptador de gêmeo digital atualizado deve fazer referência à versão do modelo de gêmeo digital secundário compatível e mapear os campos de payload para os nomes definidos por esse modelo de gêmeo digital.

Obtenha o conteúdo da instância do gêmeo digital para verificar os valores normalizados mais recentes.