Configurar carregamentos de arquivos do Hub IoT usando a CLI do Azure

  • Artigo

Este artigo mostra como configurar carregamentos de arquivos em seu hub IoT usando a CLI do Azure.

Para usar a funcionalidade de carregamento de arquivo no Hub IoT, você deve primeiro associar uma conta de armazenamento do Azure e um contêiner de blob ao seu hub IoT. O Hub IoT gera automaticamente URIs SAS com permissões de gravação para esse contêiner de blob para os dispositivos usarem quando carregarem arquivos. Além da conta de armazenamento e do contêiner de blob, você pode definir o tempo de vida útil para o URI SAS e o tipo de autenticação que o Hub IoT usa com o armazenamento do Azure. Você também pode definir configurações para as notificações de carregamento de arquivo opcionais que o Hub IoT pode fornecer aos serviços de back-end.

Pré-requisitos

  • Uma conta ativa do Azure. Se não tiver uma conta, pode criar uma conta gratuita em apenas alguns minutos.

  • Um hub IoT do Azure. Se você não tiver um hub IoT, poderá usar o comando para criar um ou Criar um hub IoT usando o az iot hub create portal.

  • Uma conta do Armazenamento do Azure. Se você não tiver uma conta de Armazenamento do Azure, poderá usar a CLI do Azure para criar uma. Para obter mais informações, veja Criar uma conta de armazenamento.

  • Use o ambiente Bash no Azure Cloud Shell. Para obter mais informações, consulte Guia de início rápido para Bash no Azure Cloud Shell.

  • Se preferir executar comandos de referência da CLI localmente, instale a CLI do Azure. Se estiver a utilizar o Windows ou macOS, considere executar a CLI do Azure num contentor Docker. Para obter mais informações, consulte Como executar a CLI do Azure em um contêiner do Docker.

    • Se estiver a utilizar uma instalação local, inicie sessão no CLI do Azure ao utilizar o comando az login. Para concluir o processo de autenticação, siga os passos apresentados no seu terminal. Para outras opções de entrada, consulte Entrar com a CLI do Azure.

    • Quando solicitado, instale a extensão da CLI do Azure na primeira utilização. Para obter mais informações sobre as extensões, veja Utilizar extensões com o CLI do Azure.

    • Execute o comando az version para localizar a versão e as bibliotecas dependentes instaladas. Para atualizar para a versão mais recente, execute o comando az upgrade.

Nota

Este artigo usa a versão mais recente da extensão do Azure IoT, chamada azure-iot. A versão herdada é chamada azure-cli-iot-extde . Você só deve ter uma versão instalada de cada vez. Você pode usar o comando az extension list para validar as extensões atualmente instaladas.

Use az extension remove --name azure-cli-iot-ext para remover a versão herdada da extensão.

Use az extension add --name azure-iot para adicionar a nova versão da extensão.

Para ver quais extensões você instalou, use az extension list.

Entre e defina sua conta do Azure

Inicie sessão na sua conta do Azure e selecione a sua subscrição. Se você estiver usando o Azure Cloud Shell, já deve estar conectado; no entanto, você ainda precisará selecionar sua assinatura do Azure se tiver várias assinaturas.

  1. Na linha de comandos, execute o comando login:

    az login

    Siga as instruções para se autenticar com o código e inicie sessão na sua conta do Azure através de um browser.

  2. Se tiver várias subscrições do Azure, iniciar sessão no Azure dá-lhe acesso a todas as contas do Azure associadas às suas credenciais. Utilize o comando para listar as contas do Azure disponíveis e que pode utilizar:

    az account list

    Use o comando a seguir para selecionar a assinatura que você deseja usar para executar os comandos para criar seu hub IoT. Pode utilizar o nome ou o ID da subscrição da saída do comando anterior:

    az account set --subscription {your subscription name or id}

Recuperar os detalhes da sua conta de armazenamento

As etapas a seguir pressupõem que você criou sua conta de armazenamento usando o modelo de implantação do Resource Manager e não o modelo de implantação Clássico.

Para configurar carregamentos de ficheiros a partir dos seus dispositivos, precisa da cadeia de ligação para uma conta de Armazenamento do Azure. A conta de armazenamento deve estar na mesma assinatura que seu hub IoT. Você também precisa do nome de um contêiner de blob na conta de armazenamento. Use o seguinte comando para recuperar as chaves da conta de armazenamento:

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

A cadeia de conexão será semelhante à seguinte saída:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}

Anote o valor connectionString. Você precisa dele nas etapas a seguir.

Você pode usar um contêiner de blob existente para seus uploads de arquivos ou criar um novo:

  • Para listar os contêineres de blob existentes em sua conta de armazenamento, use o seguinte comando:

    az storage container list --connection-string "{your storage account connection string}"

  • Para criar um contêiner de blob em sua conta de armazenamento, use o seguinte comando:

    az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

Configurar seu hub IoT

Agora você pode configurar seu hub IoT para habilitar a capacidade de carregar arquivos para o hub IoT usando os detalhes da sua conta de armazenamento.

A configuração requer os seguintes valores:

  • Contêiner de armazenamento: um contêiner de blob em uma conta de armazenamento do Azure em sua assinatura atual do Azure para associar ao seu hub IoT. Você recuperou as informações necessárias da conta de armazenamento na seção anterior. O Hub IoT gera automaticamente URIs SAS com permissões de gravação para esse contêiner de blob para os dispositivos usarem quando carregarem arquivos.

  • Receber notificações de ficheiros carregados: ative ou desative as notificações de carregamento de ficheiros.

  • TTL SAS: essa configuração é o tempo de vida útil dos URIs SAS retornados ao dispositivo pelo Hub IoT. Defina como uma hora por padrão.

  • Configurações de notificação de arquivo TTL padrão: o tempo de vida útil de uma notificação de upload de arquivo antes que ela expire. Definido como um dia por padrão.

  • Contagem máxima de entrega de notificação de arquivo: o número de vezes que o Hub IoT tenta entregar uma notificação de carregamento de arquivo. Definido como 10 por padrão.

  • Duração do bloqueio de notificação de arquivo: a duração do bloqueio para a fila de notificação de arquivo. Definido como 60 segundos por padrão.

  • Tipo de autenticação: o tipo de autenticação para o Hub IoT a ser usado com o Armazenamento do Azure. Essa configuração determina como seu hub IoT autentica e autoriza com o Armazenamento do Azure. O padrão é a autenticação baseada em chave; no entanto, identidades gerenciadas atribuídas pelo sistema e pelo usuário também podem ser usadas. As identidades gerenciadas fornecem aos serviços do Azure uma identidade gerenciada automaticamente no Microsoft Entra ID de maneira segura. Para saber como configurar identidades gerenciadas em seu hub IoT e conta de Armazenamento do Azure, consulte Suporte do Hub IoT para identidades gerenciadas. Uma vez configurado, você pode definir uma de suas identidades gerenciadas para usar para autenticação com o armazenamento do Azure.

    Nota

    A configuração de tipo de autenticação define como seu hub IoT é autenticado com sua conta de Armazenamento do Azure. Os dispositivos sempre se autenticam no Armazenamento do Azure usando o URI SAS que obtêm do hub IoT.

Os comandos a seguir mostram como definir as configurações de carregamento de arquivos em seu hub IoT. Esses comandos são mostrados separadamente para maior clareza, mas, normalmente, você emitiria um único comando com todos os parâmetros necessários para o seu cenário. Inclua aspas onde elas aparecem na linha de comando. Não inclua os aparelhos. Mais detalhes sobre cada parâmetro podem ser encontrados na documentação da CLI do Azure para o comando az iot hub update .

O comando a seguir configura a conta de armazenamento e o contêiner de blob.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

O comando a seguir define o tempo de vida do URI SAS como padrão (uma hora).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

O comando a seguir habilita notificações de arquivo e define as propriedades de notificação de arquivo para seus valores padrão. (O tempo de notificação de upload de arquivo para viver é definido como uma hora e a duração do bloqueio é definida como 60 segundos.)

az iot hub update --name {your iot hub name} \
    --fileupload-notifications true  \
    --fileupload-notification-max-delivery-count 10 \
    --fileupload-notification-ttl 1 \
    --fileupload-notification-lock-duration 60

O comando a seguir configura a autenticação baseada em chave:

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

O comando a seguir configura a autenticação usando a identidade gerenciada atribuída pelo sistema do hub IoT. Antes de executar esse comando, você precisa habilitar a identidade gerenciada atribuída ao sistema para seu hub IoT e conceder-lhe a função RBAC correta em sua conta de Armazenamento do Azure. Para saber como, consulte Suporte do Hub IoT para identidades gerenciadas.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

Os comandos a seguir recuperam as identidades gerenciadas atribuídas pelo usuário configuradas em seu hub IoT e configuram a autenticação com uma delas. Antes de poder usar uma identidade gerenciada atribuída pelo usuário para autenticar, ela deve ser configurada em seu hub IoT e concedida uma função RBAC apropriada em sua conta de Armazenamento do Azure. Para obter mais detalhes e etapas, consulte Suporte do Hub IoT para identidades gerenciadas.

Para consultar identidades gerenciadas atribuídas pelo usuário em seu hub IoT, use o comando az iot hub identity show .

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

O comando retorna uma coleção das identidades gerenciadas atribuídas pelo usuário configuradas em seu hub IoT. A saída a seguir mostra uma coleção que contém uma única identidade gerenciada atribuída pelo usuário.

{
  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}": 
  {
    "clientId": "<client ID GUID>",
    "principalId": "<principal ID GUID>"
  }
}

O comando a seguir configura a autenticação para usar a identidade atribuída pelo usuário acima.

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity  "/subscriptions/{your subscription ID}/resourcegroups/{your resource group}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{your user-assigned managed identity name}"

Você pode revisar as configurações em seu hub IoT usando o seguinte comando:

az iot hub show --name {your iot hub name}

Para rever apenas as definições de carregamento de ficheiros, utilize o seguinte comando:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

Para a maioria das situações, usar os parâmetros nomeados nos comandos da CLI do Azure é mais fácil; no entanto, você também pode definir as configurações de upload de arquivo com o --set parâmetro. Os comandos a seguir podem ajudá-lo a entender como.

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.connectionString="{your storage account connection string}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.containerName="{your storage container name}"

az iot hub update --name {your iot hub name} \
  --set properties.storageEndpoints.'$default'.sasTtlAsIso8601=PT1H0M0S

az iot hub update --name {your iot hub name} \
  --set properties.enableFileUploadNotifications=true

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.maxDeliveryCount=10

az iot hub update --name {your iot hub name} \
  --set properties.messagingEndpoints.fileNotifications.ttlAsIso8601=PT1H0M0S

Próximos passos