Configurar uploads de arquivo do Hub IoT usando a CLI do Azure

  • Artigo

Este artigo mostra como configurar carregamentos de arquivo no Hub IoT usando a CLI do Azure.

Para usar a funcionalidade de upload de arquivos 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 os URIs de SAS com permissões de gravação para esse contêiner de blob para dispositivos a serem usados ao carregar arquivos. Além da conta de armazenamento e do contêiner de blob, você pode definir a vida útil para o URI de SAS e o tipo de autenticação que o Hub IoT usa com o armazenamento do Azure. Você também pode definir as configurações para as notificações de upload de arquivo opcionais que o Hub IoT pode fornecer aos serviços de back-end.

Pré-requisitos

Observação

Este artigo usa a versão mais recente da extensão de IoT do Azure, chamada azure-iot. A versão herdada chama-se azure-cli-iot-ext. Você deve ter apenas uma versão instalada por vez. Use o comando az extension list para validar quais extensões estão 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ê tem instaladas, use az extension list.

Entre e configure sua conta do Azure

Entre na sua conta do Azure e selecione sua assinatura. Se estiver usando Azure Cloud Shell, você já deve estar conectado; no entanto, ainda pode precisar selecionar sua assinatura do Azure se tiver várias assinaturas.

  1. No prompt de comando, execute o comando de logon:

    az login

    Siga as instruções de autenticação usando o código e entre em sua conta do Azure por meio de um navegador da Web.

  2. Se você tiver várias assinaturas do Azure, entrar o Azure lhe dará acesso a todas as contas do Azure associadas às suas credenciais. Use o seguinte comando para listar as contas do Azure disponíveis para você usar:

    az account list

    Use o seguinte comando para selecionar a assinatura que você quer usar e executar os comandos para criar o Hub IoT. Você pode usar a ID ou nome da assinatura da saída do comando anterior:

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

Recupere 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 os uploads de arquivos dos seus dispositivos, você precisa da cadeia de conexão de uma conta de Armazenamento do Azure. A conta de armazenamento deve estar nas mesmas região e assinatura que seu Hub IoT. Você também precisa do nome de um contêiner de blob na conta de armazenamento. Use o comando a seguir 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. Ele é necessário nas etapas a seguir.

É possível usar um contêiner de blob existente para os 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 é possível configurar o Hub IoT para permitir upload de arquivos para o Hub IoT usando os detalhes da 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 na assinatura atual do Azure para associar ao Hub IoT. Você recuperou as informações da conta de armazenamento necessárias na seção anterior. O Hub IoT gera automaticamente os URIs de SAS com permissões de gravação para esse contêiner de blob para dispositivos a serem usados ao carregar arquivos.

  • Receber notificações para os arquivos carregados: habilitar ou desabilitar notificações de upload de arquivo.

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

  • TTL de configurações de notificação de arquivo padrão: o tempo de vida de uma notificação de upload de arquivo antes de sua expiração. Defina como um dia por padrão.

  • Contagem de entrega máxima de notificação de arquivo: o número de vezes que o Hub IoT tenta entregar uma notificação de carregamento de arquivo. Defina 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. Defina 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 o Hub IoT é autenticado e autoriza com o Armazenamento do Azure. O padrão é a autenticação baseada em chave; no entanto, as 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 forma segura. Para saber como configurar identidades gerenciadas em sua conta de Armazenamento do Hub IoT e do Azure, confira suporte do Hub IoT para identidades gerenciadas. Uma vez configurado, você pode definir uma de suas identidades gerenciadas a serem usadas para autenticação com o Armazenamento do Azure.

    Observação

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

Os comandos a seguir mostram como definir as configurações de upload de arquivo no seu Hub IoT. Esses comandos são mostrados separadamente para fins de clareza, mas, normalmente, você emitiria um único comando com todos os parâmetros necessários para seu cenário. Inclua aspas onde eles aparecem na linha de comando. Não inclua colchetes. 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 blobs.

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 a vida útil do URI de SAS para o padrão (uma hora).

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

O comando a seguir habilita as 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 do arquivo é definido para uma hora e a duração do bloqueio é definida para 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 pelo sistema para o Hub IoT e conceder a ela a função RBAC correta em sua conta de Armazenamento do Azure. Para saber como, consulte suporte do Hub IoT a 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 no seu Hub IoT e configuram a autenticação com uma delas. Antes de usar uma identidade gerenciada atribuída pelo usuário para autenticar, ela deve ser configurada em seu Hub IoT e receber 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 examinar as configurações no Hub IoT usando o seguinte comando:

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

Para examinar apenas as configurações de carregamento de arquivo, use o seguinte comando:

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

Na 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 carregamento de arquivo com o parâmetro --set. 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óximas etapas