Compartilhar via

Configurar uploads de arquivo do Hub IoT usando o Portal do Azure

A configuração de uploads de arquivos no hub IoT permite que seus dispositivos conectados carreguem arquivos em uma conta de armazenamento do Azure. Este artigo mostra como configurar uploads de arquivos no hub IoT usando o portal do Azure, a CLI do Azure e o Azure PowerShell.

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.

Configurar o hub IoT no portal do Azure

  1. No portal do Azure, navegue até o Hub IoT e selecione Upload de arquivo para exibir as propriedades de upload de arquivo. Em seguida, selecione Contêiner de Armazenamento do Azure em Configurações do contêiner armazenamento.

    Captura de tela que mostra como definir as configurações de upload de arquivo no portal.

  2. Selecione uma conta de armazenamento do Azure e um contêiner de blobs em sua assinatura atual a ser associado ao hub IoT. Se for necessário, você pode criar uma conta de Armazenamento do Azure no painel Contas de armazenamento e criar um contêiner de blob no painel Contêineres.

    Captura de tela que mostra como exibir contêineres de armazenamento para upload de arquivo.

  3. Depois de selecionar uma conta de Armazenamento do Azure e um contêiner de blob, configure o restante das propriedades de upload de arquivo.

    • Receber notificações para os arquivos carregados: habilitar ou desabilitar notificações de upload de arquivo por meio de um botão de opção.

    • TTL de SAS: essa configuração é o tempo de vida dos URIs de SAS retornados para o dispositivo pelo Hub IoT. Definido para uma hora por padrão, mas pode ser personalizado para outros valores usando o controle deslizante.

    • 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. Definido para um dia por padrão, mas pode ser personalizado para outros valores usando o controle deslizante.

    • 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. Definido como 10 por padrão, mas pode ser personalizado para outros valores usando o controle deslizante.

    • Tipo de autenticação: por padrão, o Hub IoT do Azure usa a autenticação baseada em chave para se conectar e autorizar com o Armazenamento do Azure. Você também pode configurar identidades gerenciadas atribuídas pelo usuário ou pelo sistema para autenticar o Hub IoT do Azure com o Armazenamento do Azure. 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, confira suporte do Hub IoT para identidades gerenciadas. Depois de configurar uma ou mais identidades gerenciadas em sua conta de Armazenamento do Azure e no hub IoT, você pode selecionar uma para autenticação com o armazenamento do Azure com os botões Atribuído pelo sistema ou Atribuído pelo usuário.

      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.

  4. Selecione salvar para salvar suas configurações. Verifique se a confirmação foi concluída com êxito. Algumas seleções, como o Tipo de autenticação, são validadas somente depois que você salva suas configurações.

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 de armazenamento do Azure com um container de blobs. 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.

Entre e defina sua conta do Azure

Entre na sua conta do Azure e selecione sua assinatura. Se você estiver usando o Azure Cloud Shell, já deverá estar conectado; no entanto, talvez você ainda precise 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 comando a seguir para selecionar a assinatura que você deseja usar para 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 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 de seus dispositivos, você precisa conceder permissões de acesso ao hub IoT para a conta de Armazenamento do Azure. A conta de armazenamento deve estar na mesma assinatura do 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 uma opção mais segura.

Autenticação baseada em chave

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

Anote o valor connectionString. A string de conexão é semelhante ao seguinte resultado:

{
  "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 autenticação baseada em identidade. Para obter mais informações, consulte o suporte do Hub IoT para identidades gerenciadas.

Use o comando az role assignment create para atribuir uma função à sua identidade gerenciada. Para obter mais informações, consulte Atribuir uma função do Azure para acesso aos dados de blob.

Configurar seu Hub IoT

Agora você pode configurar o hub IoT para habilitar a capacidade de carregar arquivos no 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 necessárias da conta de armazenamento 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 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. Definido como uma hora por padrão.

  • Configurações de notificação de arquivo padrão TTL: o tempo de vida útil de uma notificação de upload de arquivo antes de expirar. Definido 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. Definido como 10 por padrão.

  • Duração do bloqueio da notificação de arquivo: a duração do bloqueio da 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 o hub IoT se autentica 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 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 seu cenário. Inclua aspas onde elas aparecem na linha de comando. Não inclua as chaves. 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 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 como seus valores padrão. (O tempo de notificação de upload de arquivo em tempo real é 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 pelo sistema para o hub IoT e conceder a ele a função de controle de acesso baseada em função correta em sua conta de Armazenamento do Azure. Para saber como, consulte o 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 no 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 o suporte do Hub IoT para identidades gerenciadas.

Para consultar identidades gerenciadas atribuídas pelo usuário no 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 no 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 upload de arquivo, use 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é-requisitos

Entre e defina sua conta do Azure

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

  1. No prompt de PowerShell, execute o cmdlet Connect-AzAccount

    Connect-AzAccount

  2. Se você tiver várias assinaturas do Azure, entrar no Azure concederá acesso a todas as assinaturas do Azure associadas às suas credenciais. Use o comando Get-AzSubscription para listar as assinaturas do Azure disponíveis para uso:

    Get-AzSubscription

    Use o comando a seguir para selecionar a assinatura que você deseja usar para executar os comandos para gerenciar o hub IoT. Você pode usar a ID ou nome da assinatura da saída do comando anterior:

    Select-AzSubscription `
    -Name "{your subscription name}"

    Observação

    O comando Select-AzSubscription é um alias do Select-AzContext que permite que você use o nome da assinatura (Nome) ou a ID da assinatura (ID) retornada pelo comando Get-AzSubscription em vez do nome de contexto mais complexo necessário para o comando Select-AzContext .

Recuperar os detalhes da 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 de seus dispositivos, você precisa da cadeia de conexão para uma conta de armazenamento do Azure. A conta de armazenamento deve estar na mesma assinatura do hub IoT. Você também precisa do nome de um contêiner de blob na conta de armazenamento. Use o comando Get-AzStorageAccountKey para recuperar as chaves da conta de armazenamento:

Get-AzStorageAccountKey `
  -Name {your storage account name} `
  -ResourceGroupName {your storage account resource group}

Anote o valor da chave da conta de armazenamento key1 . Você precisa dela nas etapas a seguir.

Você pode usar um contêiner de blob existente para uploads de arquivo ou criar um:

  • Para listar os contêineres de blob existentes em sua conta de armazenamento, use os comandos New-AzStorageContext e Get-AzStorageContainer :

    $ctx = New-AzStorageContext `
    -StorageAccountName {your storage account name} `
    -StorageAccountKey {your storage account key}
Get-AzStorageContainer -Context $ctx

  • Para criar um contêiner de blob em sua conta de armazenamento, use os comandos New-AzStorageContext e New-AzStorageContainer :

    $ctx = New-AzStorageContext `
    -StorageAccountName {your storage account name} `
    -StorageAccountKey {your storage account key}
New-AzStorageContainer `
    -Name {your new container name} `
    -Permission Off `
    -Context $ctx

Configurar seu Hub IoT

Agora você pode configurar o hub IoT para carregar arquivos no 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 necessárias da conta de armazenamento 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 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. Definido 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. Definido 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. Definido como 10 por padrão.

Use o comando Set-AzIotHub para definir as configurações de upload de arquivo no hub IoT:

Set-AzIotHub `
    -ResourceGroupName "{your iot hub resource group}" `
    -Name "{your iot hub name}" `
    -FileUploadNotificationTtl "01:00:00" `
    -FileUploadSasUriTtl "01:00:00" `
    -EnableFileUploadNotifications $true `
    -FileUploadStorageConnectionString "DefaultEndpointsProtocol=https;AccountName={your storage account name};AccountKey={your storage account key};EndpointSuffix=core.windows.net" `
    -FileUploadContainerName "{your blob container name}" `
    -FileUploadNotificationMaxDeliveryCount 10

Observação

Por padrão, o Hub IoT é autenticado com o Armazenamento do Microsoft Azure usando a chave de conta na cadeia de conexão. A autenticação usando identidades gerenciadas atribuídas pelo sistema ou atribuídas pelo usuário também está disponível. As identidades gerenciadas fornecem aos serviços do Azure uma identidade gerenciada automaticamente no Microsoft Entra ID de forma segura. Para saber mais, confira o suporte do Hub IoT para identidades gerenciadas. Atualmente, não há parâmetros no comando Set-AzIotHub para definir o tipo de autenticação.

  • Last updated on