IoT Plug and Play na Atualização de Dispositivo do Azure para Hub IoT

Artigo
02/21/2025

A Atualização de Dispositivo para Hub IoT usa o IoT Plug and Play para descobrir e gerenciar dispositivos com capacidade para atualização remota. Esse artigo descreve como o serviço de Atualização de Dispositivo envia e recebe propriedades e mensagens em dispositivos usando interfaces IoT Plug and Play.

Para obter mais informações, consulte o Guia do desenvolvedor de dispositivos IoT Plug and Play e Como criar o agente da Atualização de Dispositivo.

Modelos da Atualização de Dispositivo

Dispositivos inteligentes usam IDs de modelo do IoT Plug and Play para anunciar seus recursos para aplicativos de Internet das Coisas do Azure. A Atualização de Dispositivo exige que o dispositivo inteligente de IoT Plug and Play anuncie uma ID de modelo como parte da conexão do dispositivo. Para saber mais, confira Comunicado da ID do modelo.

A Atualização de Dispositivo tem vários modelos de IoT Plug and Play definidos que dão suporte a recursos de Atualização de Dispositivo. O modelo **dtmi:azure:iot:deviceUpdateContractModel;3** da Atualização de Dispositivo dá suporte à funcionalidade principal e usa a interface principal da Atualização do Dispositivo para enviar ações de atualização e metadados para dispositivos e receber o status de atualização de dispositivos.

O outro modelo com suporte é **dtmi:azure:iot:deviceUpdateModel;3**, que estende **deviceUpdateContractModel;3** e também usa interfaces IoT Plug and Play que enviam informações de propriedade do dispositivo e habilitam recursos de diagnóstico. Para essas e outras versões, consulte Modelos da Atualização de Dispositivo do Azure do IoT Plug and Play.

O agente de Atualização de Dispositivo usa o **dtmi:azure:iot:deviceUpdateModel;3**, que dá suporte a todos os recursos mais recentes na Atualização de Dispositivo versão 1.1.0. Esse modelo dá suporte à versão 5.0 do manifesto de importação. Manifestos mais antigos funcionam com os agentes mais recentes, mas novos recursos exigem a versão mais recente do manifesto.

Metadados do agente

O agente da Atualização de Dispositivo usa os seguintes campos de metadados do agente para enviar informações aos serviços da Atualização de Dispositivo.

Nome	Esquema	Direção	Descrição
deviceProperties	Map	Dispositivo para nuvem	O conjunto de propriedades que contêm o fabricante, o modelo e outras informações do dispositivo. Confira Propriedades do dispositivo para obter detalhes.
compatPropertyNames	Cadeia de caracteres (separada por vírgula)	Dispositivo para nuvem	Até cinco propriedades que são usadas para verificar a compatibilidade do dispositivo para direcionar a implantação da atualização. Exemplo: "compatPropertyNames": "manufacturer,model"
lastInstallResult	Map	Dispositivo para nuvem	O resultado relatado pelo agente, que contém o código de resultado, código de resultado estendido e detalhes do resultado para a atualização principal e outras atualizações de etapa.
resultCode	Número inteiro	Dispositivo para nuvem	Um código que contém informações sobre o resultado da última ação de atualização. Pode ser preenchido com êxito ou falha. Exemplo: 700
extendedResultCode	Número inteiro	Dispositivo para nuvem	Um código que contém mais informações sobre o resultado. Pode ser preenchido com êxito ou falha. Exemplo: 0x80004005
resultDetails	string	Dispositivo para nuvem	Uma cadeia de caracteres de forma livre fornecida pelo usuário para fornecer mais detalhes do resultado. Devolvido para o gêmeo sem análise.
stepResults	mapa	Dispositivo para nuvem	O resultado relatado pelo agente, que contém o código de resultado, código de resultado estendido e detalhes de resultado para atualizações de etapa. Exemplo: "step_1": { "resultCode": 0,"extendedResultCode": 0, "resultDetails": ""}
estado	Número inteiro	Dispositivo para nuvem	Um inteiro que indica o estado atual do agente de Atualização de Dispositivo. Confira Estado para obter detalhes.
fluxo de trabalho	complex	Dispositivo para nuvem	Um conjunto de valores que indica em qual implantação o agente está trabalhando no momento, a ID da implantação atualmente instalada e a confirmação de qualquer solicitação de repetição enviada do serviço para o agente. A ID `workflow` relata um valor de `"nodeployment"` depois que uma implantação é cancelada. Exemplo: "workflow": {"action": 3,"ID": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01","retryTimestamp": "2022-01-26T11:33:29.9680598Z"}
installedUpdateId	string	Dispositivo para nuvem	Uma ID da implantação da Atualização de Dispositivo instalada no momento. Esse valor captura o JSON da ID de atualização ou `null` para um dispositivo que nunca teve uma atualização por meio da Atualização do Dispositivo. Exemplo: "installedUpdateID": "{\"provider\":\"contoso\",\"name\":\"image-update\",\"version\":\"1.0.0\"}"

Exemplo de dispositivo gêmeo do Hub IoT:

"deviceUpdate": {
                "__t": "c",
                "agent": {
                    "deviceProperties": {
                        "manufacturer": "contoso",
                        "model": "virtual-vacuum-v1",
                        "contractModelId": "dtmi:azure:iot:deviceUpdateContractModel;3",
                        "aduVer": "DU;agent/1.1.0",
                        },
                    "compatPropertyNames": "manufacturer,model",
                    "lastInstallResult": {
                        "resultCode": 700,
                        "extendedResultCode": 0,
                        "resultDetails": "",
                        "stepResults": {
                            "step_0": {
                                "resultCode": 700,
                                "extendedResultCode": 0,
                                "resultDetails": ""
                            }
                        }
                    },
                    "state": 0,
                    "workflow": {
                        "action": 3,
                        "id": "11b6a7c3-6956-4b33-b5a9-87fdd79d2f01",
                        "retryTimestamp": "2022-01-26T11:33:29.9680598Z"
                    },
                    "installedUpdateId": "{\"provider\":\"Contoso\",\"name\":\"Virtual-Vacuum\",\"version\":\"5.0\"}"
                },

Observação

O dispositivo ou módulo devem adicionar o{"__t": "c"}marcador para indicar de que elemento refere-se a um componente. Para obter mais informações, confira as Convenções de IoT Plug and Play.

Propriedades do dispositivo

O campo deviceProperties contém as informações do fabricante e do modelo para um dispositivo.

Nome	Esquema	Direção	Descrição
fabricante	string	Dispositivo para nuvem	O fabricante do dispositivo, relatado por meio do `deviceProperties`. A interface `DeviceUpdateCore` primeiro tenta ler o valor `aduc_manufacturer` do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, a interface relata por padrão a definição de tempo de compilação para `ADUC_DEVICEPROPERTIES_MANUFACTURER`. Essa propriedade é relatada somente no momento da inicialização. Valor padrão: "Contoso"
modelo	string	Dispositivo para nuvem	O modelo do dispositivo, relatado por meio de `deviceProperties`. A interface `DeviceUpdateCore` primeiro tenta ler o valor `aduc_model` do arquivo de configuração. Se o valor não for preenchido no arquivo de configuração, a interface relata por padrão a definição de tempo de compilação para `ADUC_DEVICEPROPERTIES_MODEL`. Essa propriedade é relatada somente no momento da inicialização. Valor padrão: 'Video'
contractModelId	string	Dispositivo para nuvem	A propriedade que o serviço usa para identificar a versão do modelo base que o agente da Atualização de Dispositivo usa para gerenciar e se comunicar com o agente. Valor: `dtmi:azure:iot:deviceUpdateContractModel;3` para dispositivos que usam o agente da Atualização de Dispositivo versão 1.1.0. Observação: os agentes que usam `dtmi:azure:iot:deviceUpdateModel;2` devem relatar o `contractModelId` como `dtmi:azure:iot:deviceUpdateContractModel;3`, porque `deviceUpdateModel;3` é estendido de `deviceUpdateContractModel;3`.
aduVer	string	Dispositivo para nuvem	Versão do agente de Atualização de Dispositivo em execução no dispositivo. Esse valor é lido da compilação somente se `ENABLE_ADU_TELEMETRY_REPORTING` for definido como `1` (true) durante o tempo de compilação. Você pode optar por recusar a emissão de relatórios de versão definindo o valor como `0` (false). Para obter mais informações, consulte Como criar o agente da Atualização de Dispositivo.
doVer	string	Dispositivo para nuvem	Versão do agente Otimização de Entrega em execução no dispositivo. O valor será lido do build somente se `ENABLE_ADU_TELEMETRY_REPORTING` estiver definido como `1` (true) durante o tempo de compilação. Você pode optar por recusar a emissão de relatórios de versão definindo o valor como `0` (false). Para obter mais informações, consulte Como personalizar as propriedades do agente da Otimização de Entrega.
Propriedades de compatibilidade personalizadas	Definido pelo usuário	Dispositivo para nuvem	Outras propriedades de dispositivo definidas pelo usuário a serem usadas para a verificação de compatibilidade ao direcionar a implantação de atualização.

Estado

O campo Estado é o status relatado pelo agente da Atualização de Dispositivo em resposta a uma Ação enviada pelo agente da Atualização de Dispositivo do serviço da Atualização de Dispositivo. Para obter mais informações sobre solicitações que fluem entre o serviço da Atualização de Dispositivo e o agente da Atualização de Dispositivo, confira o Fluxo de trabalho do agente.

Nome	Valor	Descrição
Ocioso	0	O dispositivo está pronto para receber uma ação do serviço de Atualização de Dispositivo. Após uma atualização bem-sucedida, o estado retorna para `Idle`.
DeploymentInprogress	6	Uma implantação está em andamento.
Com falha	255	Ocorreu uma falha durante a atualização.
DownloadSucceeded	2	Ocorreu um download bem-sucedido. Apenas dispositivos com a versão do agente 0.7.0 ou anteriores relatam esse estado.
InstallSucceeded	4	Ocorreu uma instalação bem-sucedida. Apenas dispositivos com a versão do agente 0.7.0 ou anteriores relatam esse estado.

Ação

O campo de ação representa a ação que o agente da Atualização de Dispositivo deve realizar, conforme instruído pelo serviço da Atualização de Dispositivo. O agente da Atualização de Dispositivo relata um estado para processar a ação recebida. Para obter mais informações sobre solicitações que fluem entre o serviço da Atualização de Dispositivo e o agente da Atualização de Dispositivo, confira o Fluxo de trabalho do agente.

Nome	Valor	Descrição
ApplyDeployment	3	Aplique a atualização implantada.
cancel	255	Pare de processar a ação atual e volte para `Idle`, ou diga a um agente no status `Failed` para voltar para `Idle`.
download	0	Baixar conteúdo publicado ou atualização e qualquer outro conteúdo necessário. Essa ação só é enviada para dispositivos com o agente versão 0.7.0 ou anterior.
instalar	1	Instalar esse conteúdo ou atualização normalmente chama o instalador para o conteúdo ou atualização. A Atualização de Dispositivo envia essa ação apenas para dispositivos com o agente versão 0.7.0 ou anterior.
aplicar	2	Finalize a atualização reinicializando, se necessário. A Atualização de Dispositivo envia essa ação apenas para dispositivos com o agente versão 0.7.0 ou anterior.

Metadados de serviço

Os metadados de serviço contêm campos que o serviço da Atualização de Dispositivo usa para comunicar ações e dados ao agente da Atualização de Dispositivo.

Nome	Esquema	Direção	Descrição
ação	Número inteiro	Nuvem para o dispositivo	Um inteiro que corresponde a uma ação que o agente deve executar. Consulte Ação para obter detalhes.
updateManifest	string	Nuvem para o dispositivo	Descreve o conteúdo de uma atualização. Gerado do Manifesto de Importação.
updateManifestSignature	Objeto JSON	Nuvem para o dispositivo	Uma JWS (Assinatura Web JSON) com chaves Web JSON usadas para verificação de origem.
fileUrls	Map	Nuvem para o dispositivo	Mapa de `FileID` para `DownloadUrl`. Indica ao agente quais arquivos a serem baixados e o hash a ser usado para verificar se os arquivos foram baixados corretamente.

Interface de informações do dispositivo

A interface de informações do dispositivo é um conceito usado na arquitetura de IoT Plug and Play. A interface contém propriedades de dispositivo para nuvem que fornecem informações sobre o hardware e o sistema operacional do dispositivo. A Atualização de Dispositivo usa as propriedades DeviceInformation.manufacturer e DeviceInformation.model para telemetria e diagnóstico. Para ver um exemplo da interface de informações do dispositivo, consulte https://devicemodels.azure.com/dtmi/azure/devicemanagement/deviceinformation-1.json.

Quando você implementa essa interface, o nome do componente esperado em seu modelo é deviceInformation. Para obter mais informações, confira o Guia de modelagem do IoT Plug and Play.

Nome	Tipo	Esquema	Direção	Descrição	Exemplo
fabricante	Propriedade	string	Dispositivo para nuvem	Nome da empresa do fabricante do dispositivo. O fabricante ser o mesmo que o nome do OEM (fabricante de equipamento original).	Contoso
modelo	Propriedade	string	Dispositivo para nuvem	Nome ou ID do modelo de dispositivo.	Dispositivo do IoT Edge
swVersion	Propriedade	string	Dispositivo para nuvem	Versão do software em seu dispositivo. swVersion pode ser a versão do firmware.	4.15.0-122
osName	Propriedade	string	Dispositivo para nuvem	O nome do sistema operacional no dispositivo.	Ubuntu Server 18.04
processorArchitecture	Propriedade	string	Dispositivo para nuvem	Arquitetura do processador no dispositivo.	ARM64
processorManufacturer	Propriedade	string	Dispositivo para nuvem	Nome do fabricante do processador no dispositivo.	Microsoft
totalStorage	Propriedade	string	Dispositivo para nuvem	Total de armazenamento disponível no dispositivo, em kilobytes.	2.048
totalMemory	Propriedade	string	Dispositivo para nuvem	Memória total disponível no dispositivo, em kilobytes.	256

Compartilhar via

IoT Plug and Play na Atualização de Dispositivo do Azure para Hub IoT

Modelos da Atualização de Dispositivo

Metadados do agente

Propriedades do dispositivo

Estado

Ação

Metadados de serviço

Interface de informações do dispositivo

Comentários

Recursos adicionais

Compartilhar via

IoT Plug and Play na Atualização de Dispositivo do Azure para Hub IoT

Modelos da Atualização de Dispositivo

Metadados do agente

Propriedades do dispositivo

Estado

Ação

Metadados de serviço

Interface de informações do dispositivo

Conteúdo relacionado

Comentários

Recursos adicionais