Compartilhar via

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

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

  • Um Hub IoT na assinatura do Azure. Caso você ainda não tenha um hub, poderá seguir as etapas em Criar um hub IoT.

  • Uma conta do Armazenamento do Azure com um contêiner de blob. 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, consulte Criar uma conta de armazenamento.

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}

Configurar o acesso à 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 uploads de arquivos nos seus dispositivos, você precisa conceder permissões de acesso ao hub IoT na conta do 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.

Você pode usar a autenticação baseada em chave ou identidade para fornecer permissões de acesso. A Microsoft recomenda a autenticação baseada em identidade como a opção mais segura.

Autenticação baseada em chave

Para a autenticação baseada em chave, forneça a cadeia de conexão da conta de armazenamento. Use o comando az storage account show-connection-string para recuperar as chaves da conta de armazenamento.

Anote o valor connectionString. A cadeia de conexão é semelhante à seguinte saída:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your_storage_account_name};AccountKey={your_storage_account_key}"
}

Autenticação baseada em identidade

Você pode usar identidades gerenciadas atribuídas pelo sistema ou identidades gerenciadas atribuídas pelo usuário para a autenticação baseada em identidade. Para obter mais informações, confira Suporte do Hub IoT para identidades gerenciadas.

Use o comando az role assignment create para atribuir a função à identidade gerenciada. Para saber mais, consulte Atribuir uma função do Azure para acesso a dados de blob.

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 opções de autenticação de identidade gerenciada atribuídas pelo sistema ou atribuídas pelo usuário são recomendadas. As identidades gerenciadas fornecem aos serviços do Azure uma identidade gerenciada automaticamente no Microsoft Entra ID de forma segura.

    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. Para executar esse comando, você precisa habilitar a identidade gerenciada atribuída pelo sistema para o Hub IoT e conceder a ela a função de controle de acesso baseado em função correta na sua conta do 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. Para usar uma identidade gerenciada atribuída pelo usuário para se autenticar, ela precisa ser configurada no Hub IoT e receber uma função de controle de acesso baseado em função apropriada na sua conta do 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