Execução ordenada em várias etapas
A execução ordenada de várias etapas na Atualização de Dispositivo para Hub IoT permite executar tarefas de pré-instalação e pós-instalação ao implantar uma atualização remota. Essa funcionalidade faz parte da versão 4 do esquema do manifesto de atualização da Atualização de Dispositivo. Para obter mais informações, consulte o Manifesto de atualização da Atualização de Dispositivo.
A execução ordenada de várias etapas pode ter dois tipos de etapas: etapas embutidas e etapas de referência. Uma etapa embutida é uma instrução que executa o 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 pai e filho
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 em linha em uma atualização pai
O agente de Atualização de Dispositivo aplica as etapas embutidas especificadas em uma atualização pai para o dispositivo host. O objeto ADUC_WorkflowData 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 manipulador Component-Aware.
O manipulador de conteúdo da etapa do agente de Atualização de Dispositivo aplica a lógica de validação IsInstalled para cada etapa. O manipulador de etapas verifica se a atualização já está instalada, verificando se IsInstalled() retorna o código de resultado 900, ou “true”, e usa esse resultado para determinar se deve realizar a etapa. Para evitar a reinstalação de uma atualização que já esteja no dispositivo, o agente de Atualização de Dispositivo irá ignorar as etapas futuras se uma atualização já estiver instalada.
Para relatar o resultado de uma atualização, escreva o resultado da execução de um manipulador de etapas no struct ADUC_Result em um arquivo de resultado desejado, conforme especificado na opção --result-file. Com base nos resultados da execução, retorne 0 para êxito e -1 ou 0xFF para erros fatais.
Para obter mais informações, consulte Manipuladores de etapa e Como implementar um manipulador de conteúdo personalizado que reconhece componentes.
Etapas de referência em uma atualização pai
O agente de Atualização de Dispositivo aplica as etapas de referência especificadas em uma atualização pai aos componentes ligados ou conectados ao dispositivo host. Ao processar 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 objeto ADUC_Workflow, também chamado de dados de fluxo de trabalho secundário, combinando os dados do manifesto de atualização filho e as informações da URL do arquivo do manifesto de atualização pai. Esses dados de fluxo de trabalho secundário têm uma propriedade level definida como 1.
Exemplos
O manifesto de atualização de exemplo 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 manifesto de atualização de exemplo 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 manifesto de atualização pai a seguir 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\""
}
Observação
Se você usar installedCriteria para determinar se a etapa deve ou não ser executada, você deve dar a cada etapa um valor installedCriteria diferente 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 entrega manifestos de atualização grandes para os 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 conteúdo chamado Detached Update Manifest, que contém todos os dados do manifesto de atualização.
A propriedade UpdateManifest no dispositivo ou módulo gêmeo contém as informações do arquivo de manifesto de atualização desanexado. Quando ele 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 objeto ADUC_WorkflowData que contém todos os dados do manifesto de atualização.