Execução ordenada em várias etapas
A execução ordenada em várias etapas na Atualização de Dispositivo do Azure para Hub IoT permite executar tarefas de pré-instalação e pós-instalação ao implantar uma atualização over-the-air. Esse recurso faz parte do esquema de manifesto de atualização de dispositivo versão 4. Para obter mais informações, consulte Manifesto de atualização de dispositivo.
A execução ordenada em várias etapas pode ter dois tipos de etapas, etapas embutidas e etapas de referência. Uma etapa embutida é uma instrução que executa código e é o tipo padrão. Uma etapa de referência é uma etapa que contém um identificador para outra atualização.
Atualizações dos pais e das crianças
Quando um manifesto de atualização faz referência a outro manifesto de atualização, o manifesto de nível superior é chamado de atualização pai e o manifesto especificado na etapa de referência é chamado de atualização filho. Uma atualização filho não pode conter nenhuma etapa de referência, apenas etapas embutidas. A Atualização de Dispositivo valida essa restrição no momento da importação e falha na atualização se ela não for atendida.
Etapas embutidas em uma atualização pai
O agente de Atualização de Dispositivo aplica etapas embutidas especificadas em uma atualização pai ao dispositivo host. O ADUC_WorkflowData objeto que passa para o manipulador de etapas, também chamado de manipulador de conteúdo de atualização, não contém dados Selected Components . O manipulador para esse tipo de etapa não deve ser um Component-Aware manipulador.
O manipulador de conteúdo de etapa do agente de Atualização de Dispositivo aplica IsInstalled lógica de validação para cada etapa. O manipulador de etapas verifica se a atualização já está instalada, verificando se IsInstalled() retorna o código 900de resultado , ou true, e usa esse resultado para determinar se a etapa deve ser executada. Para evitar a reinstalação de uma atualização que já está no dispositivo, o agente de Atualização de Dispositivo ignora etapas futuras se uma atualização já estiver instalada.
Para relatar um resultado de atualização, escreva o resultado de uma execução do manipulador de etapas no ADUC_Result struct em um arquivo de resultado desejado, conforme especificado na --result-file opção. Com base nos resultados da execução, retorno 0 para sucesso e retorno -1 ou 0xFF para erros fatais.
Para obter mais informações, consulte Manipuladores de etapas e Como implementar um manipulador de conteúdo com reconhecimento de componente personalizado.
Etapas de referência em uma atualização pai
O agente de Atualização de Dispositivo aplica etapas de referência especificadas em uma atualização pai aos componentes no dispositivo host ou conectados a ele. Quando processa uma etapa de referência, o manipulador de etapas baixa um arquivo de manifesto de atualização desanexado especificado na etapa e valida a integridade do arquivo.
Em seguida, o manipulador de etapas analisa o manifesto de atualização filho e cria um ADUC_Workflow objeto, também chamado de dados de fluxo de trabalho filho, combinando os dados do manifesto de atualização filho e as informações de URL do arquivo do manifesto de atualização pai. Esses dados de fluxo de trabalho filho têm uma level propriedade definida como 1.
Exemplos
O exemplo de manifesto de atualização a seguir tem uma etapa embutida:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Example APT update that installs libcurl4-doc on a host device.",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-1.0"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T14:54:55.8858676Z",
"createdDateTime": "2021-11-16T14:50:47.3511877Z"
}
O exemplo de manifesto de atualização a seguir tem duas etapas embutidas:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"description": "Install libcurl4-doc on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-2.2"
}
},
{
"description": "Install tree on host device",
"handler": "microsoft/apt:1",
"files": [
"apt-manifest-tree-1.0.json"
],
"handlerProperties": {
"installedCriteria": "apt-update-test-tree-2.2"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-16T20:21:33.6514738Z",
"createdDateTime": "2021-11-16T20:19:29.4019035Z"
}
O seguinte manifesto de atualização pai tem uma etapa de referência que faz referência a uma atualização filho:
{
"updateId": {...},
"isDeployable": true,
"compatibility": [
{
"manufacturer": "du-device",
"model": "e2e-test"
}
],
"instructions": {
"steps": [
{
"type": "reference",
"description": "Cameras Firmware Update",
"updateId": {
"provider": "contoso",
"name": "virtual-camera",
"version": "1.2"
}
}
]
},
"manifestVersion": "4.0",
"importedDateTime": "2021-11-17T07:26:14.7484389Z",
"createdDateTime": "2021-11-17T07:22:10.6014567Z"
}
A atualização filho contém etapas embutidas.
{
"updateId": {
"provider": "contoso",
"name": "virtual-camera",
"version": "1.2"
},
"isDeployable": false,
"compatibility": [
{
"group": "cameras"
}
],
"instructions": {
"steps": [
{
"description": "Cameras Update - preinstall step",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh"
],
"handlerProperties": {
"scriptFileName": "contoso-camera-installscript.sh",
"arguments": "--pre-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-0"
}
},
{
"description": "Cameras Update - firmware installation (failure - missing file)",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh",
"camera-firmware-1.1.json"
],
"handlerProperties": {
"scriptFileName": "missing-contoso-camera-installscript.sh",
"arguments": "--firmware-file camera-firmware-1.1.json --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-1"
}
},
{
"description": "Cameras Update - postinstall step",
"handler": "microsoft/script:1",
"files": [
"contoso-camera-installscript.sh"
],
"handlerProperties": {
"scriptFileName": "contoso-camera-installscript.sh",
"arguments": "--post-install-sim-success --component-name --component-name-val --component-group --component-group-val --component-prop path --component-prop-val path",
"installedCriteria": "contoso-virtual-camera-1.2-step-2"
}
}
]
},
"referencedBy": [
{
"provider": "DU-Client-Eng",
"name": "MSOE-Update-Demo",
"version": "3.1"
}
],
"manifestVersion": "4.0",
"importedDateTime": "2021-11-17T07:26:14.7376536Z",
"createdDateTime": "2021-11-17T07:22:09.2232968Z",
"etag": "\"ad7a553d-24a8-492b-9885-9af424d44d58\""
}
Nota
Se você usar installedCriteria para determinar se a etapa deve ou não ser executada, você deve dar a cada etapa um valor diferente installedCriteria no manifesto de atualização.
Manifestos de atualização desanexados
Para evitar falhas de implantação devido aos limites de tamanho de dados gêmeos do Hub IoT do Azure, a Atualização de Dispositivo fornece grandes manifestos de atualização aos dispositivos como arquivos de dados JSON chamados manifestos de atualização desanexados. Quando você importa uma atualização de conteúdo grande para a Atualização de Dispositivo, o manifesto de atualização gerado contém outro arquivo de carga chamado Detached Update Manifest, que contém os dados completos do manifesto de atualização.
A UpdateManifest propriedade no dispositivo ou módulo gêmeo contém as informações do arquivo de manifesto de atualização desanexado. Quando processa o evento PnP PropertyChanged , o agente de Atualização de Dispositivo baixa automaticamente o arquivo de manifesto de atualização desanexado e cria um ADUC_WorkflowData objeto que contém os dados completos do manifesto de atualização.