Implementar uma atualização de software para um grupo (pré-visualização)

Para criar um grupo no portal do Azure:

1. Na navegação do namespace, abra Operations>Groups (preview) e depois inicie a criação de grupos a partir da barra de comandos.

2. Na página Básicos , insira um Nome descritivo e, opcionalmente, uma Descrição que identifique a coorte de dispositivos pretendida.

3. Na página de Definição, em Definir condições de filtro, introduza uma consulta que selecione os dispositivos ligados ao Hub IoT que pretende atualizar.

   

   Os filtros de grupo são imutáveis após a criação. Para usar critérios de adesão diferentes, crie outro grupo com uma consulta diferente.

4. Na página de Revisão, verifique as Noções básicas, Definição e Filtro de consulta e, depois, selecione Criar.

   

Um grupo é um recurso Microsoft.DeviceRegistry/namespaces/groups. O properties.query valor seleciona os dispositivos registados ligados ao Hub IoT que se tornam membros do grupo, com base nas propriedades do dispositivo como manufacturer, model, ou softwareRevision. Depois de criares o grupo, não podes alterar a consulta dele. Para usar critérios de adesão diferentes, crie outro grupo com uma consulta diferente.

Crie um ficheiro Bicep com o seguinte conteúdo. Substitua os valores provisórios, como <NAMESPACE_NAME> e <GROUP_NAME>, pelos seus próprios.

param namespaceName string = '<NAMESPACE_NAME>'
param groupName string = 'contoso-tractors'
param groupDescription string = 'Devices to receive the software update'
param groupQuery string = 'WHERE manufacturer = \'contoso\' AND model = \'tractor\''

resource namespace 'Microsoft.DeviceRegistry/namespaces@2026-11-02-preview' existing = {
  name: namespaceName
}

resource group 'Microsoft.DeviceRegistry/namespaces/groups@2026-11-02-preview' = {
  parent: namespace
  name: groupName
  location: namespace.location
  properties: {
    description: groupDescription
    query: groupQuery
  }
}

1. No portal Azure, vá ao seu Registo de Dispositivos Azure e selecione o namespace que contém os dispositivos que pretende atualizar.

2. No namespace, selecione Operations>Jobs. O ecrã Tarefas lista as tarefas definidas com o seu estado, tipo de tarefa e grupo-alvo. A partir deste ecrã, pode também visualizar os grupos e as atualizações de software no espaço de nomes.

   

3. Selecione Criar para criar uma nova tarefa.

4. Na página Básico, forneça um nome e uma descrição do trabalho.

5. Para o tipo de trabalho, selecione atualização de software.

   Em pré-visualização, os tipos de trabalho disponíveis são atualização de software e atualização de integração inicial. Um trabalho de atualização de software direciona-se para um grupo de dispositivos, e um trabalho de atualização de integração inicial direciona-se para dispositivos que são integrados num namespace. Este artigo aborda a tarefa de atualização de software.

6. Seleciona o grupo que queres direcionar. Utilize o seletor de grupos para procurar e selecionar um grupo. O seletor mostra o número aproximado de dispositivos em cada grupo.

   Para informações sobre como a pertença a grupos é atualizada, consulte Conceitos de Grupos (pré-visualização).

7. Guarda a seleção do grupo. O portal mostra uma amostra dos dispositivos do grupo e a contagem de dispositivos.

8. Defina a ação a executar ao selecionar uma das atualizações de software importadas para o espaço de nomes. Cada atualização de software inclui uma verificação de compatibilidade que determina se se aplica a um dispositivo. O portal executa uma verificação de compatibilidade para o grupo selecionado para determinar se a atualização de software é compatível.

   

9. Selecione Seguinte para ver um resumo do trabalho. O resumo mostra o número de membros do grupo e uma estimativa do número de membros compatíveis que o trabalho provavelmente irá atualizar com sucesso.

   

10. Selecione Criar. O estado do trabalho mostra A criar e depois muda para Pronto após um momento.

Um trabalho de atualização de software é um recurso Microsoft.DeviceRegistry/namespaces/jobs com properties.jobType definido como SoftwareUpdate. A target.resourceId propriedade refere-se ao grupo ao qual o trabalho aplica a atualização e deve ser um ID de recurso para um Microsoft.DeviceRegistry/namespaces/groups recurso no mesmo espaço de nomes. A propriedade definition.update.updateId identifica a atualização de software a aplicar pelo fornecedor, nome e versão. Atualmente, definition.schedulingType apenas suporta o valor Continuous.

Depois de criar a tarefa, as suas propriedades — incluindo target e definition— tornam-se imutáveis. Para alterar o grupo-alvo ou atualizar a definição, apague a tarefa e crie uma nova.

Crie um ficheiro Bicep com o seguinte conteúdo. Substitua os valores provisórios, como <NAMESPACE_NAME>, <GROUP_NAME>, e os valores do identificador de atualização, pelos seus próprios.

param namespaceName string = '<NAMESPACE_NAME>'
param jobName string = '<JOB_NAME>'
param groupName string = '<GROUP_NAME>'
param updateProvider string = '<UPDATE_PROVIDER>'
param updateName string = '<UPDATE_NAME>'
param updateVersion string = '<UPDATE_VERSION>'

resource namespace 'Microsoft.DeviceRegistry/namespaces@2026-11-02-preview' existing = {
  name: namespaceName
}

resource group 'Microsoft.DeviceRegistry/namespaces/groups@2026-11-02-preview' existing = {
  parent: namespace
  name: groupName
}

resource softwareUpdateJob 'Microsoft.DeviceRegistry/namespaces/jobs@2026-11-02-preview' = {
  parent: namespace
  name: jobName
  location: namespace.location
  properties: {
    description: 'Software update job'
    jobType: 'SoftwareUpdate'
    target: {
      resourceId: group.id
    }
    definition: {
      schedulingType: 'Continuous'
      update: {
        updateId: {
          provider: updateProvider
          name: updateName
          version: updateVersion
        }
      }
    }
  }
}

1. No ecrã Jobs, selecione a tarefa que pretende executar.

2. Selecione uma das seguintes opções:

   • Corre agora: A tarefa é executada imediatamente.
   • Agendar para mais tarde: Escolhe uma hora nos próximos sete dias. A tarefa é executada na hora que selecionar.

Depois de executares ou agendares a tarefa, o portal passa para o separador Execuções.

O Bicep declara recursos, por isso não pode ativar diretamente uma ação como executar ou agendar uma tarefa. Em vez disso, usa a ação do schedule trabalho, que podes chamar com o CLI do Azure. Para executar o trabalho imediatamente, omita scheduledTime. Para agendar o trabalho, inclua um scheduledTime valor.

az rest --method post \
  --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.DeviceRegistry/namespaces/<NAMESPACE_NAME>/jobs/<JOB_NAME>/schedule?api-version=2026-11-02-preview" \
  --body '{
    "scheduledTime": "2026-11-15T14:30:00Z",
    "timeout": "PT1H"
  }'

• scheduledTime: A data e hora UTC para executar a tarefa. Omita esta propriedade para executar a tarefa imediatamente.
• timeout: Uma duração ISO 8601 que limita o tempo permitido da execução, por exemplo PT1H para uma duração de uma hora. Esta propriedade é opcional.

Depois de executares ou agendares o trabalho, usa o portal do Azure ou as APIs de execução de trabalhos para monitorizar a execução.

1. Selecione o separador Runs para ver os Runs e o seu estado.

2. Selecione uma execução concluída para ver as suas estatísticas. Os detalhes da execução mostram o número de dispositivos atualizados e os detalhes desses dispositivos.

3. Verifica um dispositivo específico. Para confirmar se um dispositivo específico foi atualizado, use a caixa de pesquisa nos detalhes da execução para encontrar o dispositivo.

As execuções de tarefas são recursos apenas de leitura, por isso monitorizas-nas ao consultar o tipo de recurso Microsoft.DeviceRegistry/namespaces/jobs/runs em vez de as declarar no Bicep. Use a CLI do Azure para listar as execuções do trabalho e verificar o seu estado:

az rest --method get \
  --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.DeviceRegistry/namespaces/<NAMESPACE_NAME>/jobs/<JOB_NAME>/runs?api-version=2026-11-02-preview"

Cada execução inclui um valor status, como Scheduled, Running ou Ended, e um resumo results com contagens de dispositivos sucedidos, falhados, em curso, pendentes e cancelados.

Para verificar um dispositivo específico, obtenha os resultados de uma execução e filtre por estado:

az rest --method post \
  --uri "https://management.azure.com/subscriptions/<SUBSCRIPTION_ID>/resourceGroups/<RESOURCE_GROUP>/providers/Microsoft.DeviceRegistry/namespaces/<NAMESPACE_NAME>/jobs/<JOB_NAME>/runs/<RUN_NAME>/listResults?api-version=2026-11-02-preview" \
  --body '{
    "filter": "status eq '\''Failed'\''"
  }'

Cada entrada nos resultados identifica o dispositivo alvo e o seu estado por dispositivo. Omita a filter propriedade no corpo do pedido para devolver todos os resultados dos dispositivos para a execução.