Carregar arquivos com o Hub IoT

  • Artigo

Há muitos cenários em que você não pode facilmente mapear os dados do dispositivo para as mensagens relativamente pequenas do dispositivo para a nuvem que o Hub IoT aceita. Por exemplo, o envio de grandes arquivos de mídia, como vídeos, ou grandes lotes de telemetria carregados por dispositivos conectados intermitentemente ou agregados e compactados para economizar largura de banda.

Quando você precisar carregar arquivos grandes de um dispositivo, ainda poderá usar a segurança e a confiabilidade do Hub IoT. Em vez de agenciar mensagens por meio do próprio Hub IoT, ele age como um dispatcher para uma conta do Armazenamento do Azure associada. O Hub IoT também pode fornecer notificação aos serviços de back-end quando um dispositivo conclui o upload de um arquivo.

Se precisar de ajuda para decidir quando usar as propriedades relatadas, as mensagens do dispositivo para a nuvem ou os uploads de arquivos relatados, veja Diretrizes de comunicações do dispositivo para a nuvem.

Importante

A funcionalidade de carregamento de arquivo em dispositivos que usam a autenticação da autoridade de certificação (AC) de certificados X.509 está em versão prévia. Além disso, é necessário habilitar o modo de versão prévia. Geralmente está disponível em dispositivos que usam a autenticação de impressão digital X. 509 ou o atestado de certificado X. 509 com o Serviço de Provisionamento de Dispositivos do Azure. Para saber mais sobre a autenticação X.509 com o Hub IoT, confira Certificados X.509 com suporte.

Visão geral do upload de arquivos

Um hub IoT facilita os uploads de arquivos de dispositivos conectados ao fornecer URIs de SAS (assinatura de acesso compartilhado) com base em cada upload para um contêiner de blob e uma conta do Armazenamento do Azure que foram pré-configurados com o hub. Há três partes no uso dos uploads de arquivos com o Hub IoT: pré-configurar uma conta do Armazenamento do Azure e um contêiner de blobs no Hub IoT, upload de arquivos de dispositivos e, opcionalmente, notificação dos serviços de back-end sobre os uploads de arquivos concluídos.

Antes de usar o recurso de upload de arquivos, você deve associar uma conta do Armazenamento do Azure e um contêiner de blobs ao Hub IoT. Você também pode definir configurações que controlam como o Hub IoT é autenticado com o Armazenamento do Azure, a TTL (vida útil) dos URIs de SAS que o Hub IoT distribui aos dispositivos e notificações sobre upload de arquivo para seus serviços de back-end. Para saber mais, confira Associar uma conta do Armazenamento do Azure ao Hub IoT.

Os dispositivos seguem um processo de três etapas para carregar um arquivo no contêiner de blobs associado:

  1. O dispositivo inicia o upload do arquivo com o Hub IoT. Ele transmite o nome de um blob na solicitação e obtém um URI de SAS e um ID de correlação de volta. O URI de SAS contém um token SAS para o Armazenamento do Azure que concede a permissão de leitura/gravação do dispositivo para o blob solicitado no contêiner de blobs. Para obter mais informações, consulte Dispositivo: inicializar um upload de arquivo.

  2. O dispositivo usa o URI de SAS para chamar com segurança as APIs do Armazenamento de Blobs do Azure e carregar o arquivo no contêiner de blobs. Para obter mais informações, consulte Dispositivo: carregar arquivo usando as APIs do armazenamento do Azure.

  3. Quando o upload do arquivo é concluído, o dispositivo notifica o Hub IoT sobre status de conclusão usando o ID de correlação recebido do Hub IoT quando ele iniciou o upload. Para obter mais informações, consulte Dispositivo: notificar o Hub IoT sobre um upload de arquivo concluído.

Os serviços de back-end podem assinar notificações sobre upload de arquivos no ponto de extremidade de notificação sobre upload de arquivos voltado para o serviço do Hub IoT. Se você habilitou essas notificações no Hub IoT, elas serão enviadas para esse ponto de extremidade sempre que um dispositivo notificar o Hub de que ele concluiu um upload de arquivo. Os serviços podem usar essas notificações para disparar o processamento adicional dos dados do blob. Para obter mais informações, consulte Serviço: notificações de upload de arquivo.

O upload de arquivos é totalmente compatível com o dispositivo IoT do Azure e SDKs de serviço. Para obter mais informações, consulte Upload de arquivo usando um SDK.

Limites e cotas de upload de arquivos

O Hub IoT impõe limites ao número de uploads de arquivos que podem ser iniciados em determinado período. O limite é baseado no SKU e no número de unidades do hub IoT. Além disso, cada dispositivo é limitado a 10 uploads de arquivos ativos simultâneos por vez. Para obter mais informações, confira Cotas e limitação do Hub IoT.

Associar uma conta do Armazenamento do Azure ao Hub IoT

Você deve associar uma conta do Armazenamento do Azure e um contêiner de blobs ao hub IoT para usar os recursos de upload de arquivos. Todos os uploads de arquivos de dispositivos registrados no hub IoT vão para esse contêiner. Para configurar uma conta de armazenamento e um contêiner de blob no hub IoT, confira Configurar uploads de arquivo do Hub IoT usando o portal do Azure, Configurar uploads de arquivo do Hub IoT usando a CLI do Azure ou Configurar uploads de arquivo do Hub IoT usando o PowerShell. Você também pode usar as APIs de gerenciamento do Hub IoT para configurar uploads de arquivos programaticamente.

Se você usar o portal, poderá criar uma conta de armazenamento e um contêiner durante a configuração. Caso contrário, para criar uma conta de armazenamento, veja Criar uma conta de armazenamento na documentação do Armazenamento do Azure. Depois de criar uma conta de armazenamento, você poderá ver como criar um contêiner de blobs nos guias de início rápido do Armazenamento de Blobs do Azure. Por padrão, o Hub IoT do Azure usa a autenticação baseada em chave para se conectar ao Armazenamento do Azure e autorizá-lo. 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, consulte a seção Configurar upload de arquivo com identidades gerenciadas do Suporte do Hub IoT para identidades gerenciadas.

O upload de arquivos está sujeito às Configurações de firewall do Armazenamento do Azure. Com base na configuração de autenticação, você precisará garantir que os dispositivos possam se comunicar com o armazenamento do Azure.

Há várias outras configurações que controlam o comportamento de uploads de arquivos e notificações sobre upload de arquivos. As seções a seguir listam todas as configurações disponíveis. Dependendo do que você usa, o portal do Azure, a CLI do Azure, o PowerShell ou as APIs de gerenciamento para configurar uploads de arquivos, algumas dessas configurações poderão não estar disponíveis. Defina a configuração enableFileUploadNotifications se desejar que as notificações sejam enviadas aos serviços de back-end quando um upload de arquivos for concluído.

Configurações de armazenamento e autenticação do Hub IoT

As configurações a seguir associam uma conta de armazenamento e um contêiner ao seu hub IoT e controlam como o hub é autenticado no Armazenamento do Azure. Essas configurações não afetam o modo como os dispositivos são autenticados no Armazenamento do Azure. Os dispositivos sempre se autenticam com o token SAS apresentado no URI de SAS recuperado do Hub IoT.

Propriedade Descrição Intervalo e padrão
storageEndpoints.$default.authenticationType Controla como o Hub IoT é autenticado no Armazenamento do Azure. Os valores possíveis são keyBased e identityBased. Padrão: keyBased.
storageEndpoints.$default.connectionString A cadeia de conexão para a conta do Armazenamento do Azure a ser usada para uploads de arquivos. Padrão: cadeia de caracteres vazia.
storageEndpoints.$default.containerName O nome do contêiner no qual os arquivos serão carregados. Padrão: cadeia de caracteres vazia.
storageEndpoints.$default.identity A identidade gerenciada a ser usada na autenticação baseada em identidade. Os valores possíveis são [system] para a identidade gerenciada atribuída pelo sistema ou um ID de recurso para uma identidade gerenciada atribuída pelo usuário. O valor não é usado na autenticação baseada em chave. Padrão: nulo.

Configurações de upload de arquivos

As configurações a seguir controlam os uploads de arquivos do dispositivo.

Propriedade Descrição Intervalo e padrão
storageEndpoints.$default.ttlAsIso8601 TTL padrão para URIs de SAS gerados pelo Hub IoT. Intervalo de ISO_8601 de até 48 horas (mínimo de 1 minuto). Padrão: uma hora.

Configurações de notificação sobre upload de arquivos

As configurações a seguir controlam as notificações sobre upload de arquivos para serviços de back-end.

Propriedade Descrição Intervalo e padrão
enableFileUploadNotifications Controla se as notificações de upload de arquivos serão gravadas no ponto de extremidade de notificações de arquivo. Bool. Padrão: false.
fileNotifications.ttlAsIso8601 TTL padrão para notificações de upload de arquivos. Intervalo de ISO_8601 de até 48 horas (mínimo de 1 minuto). Padrão: uma hora.
fileNotifications.lockDuration Duração de bloqueio para a fila de notificações de upload de arquivos. 5 a 300 segundos. Padrão: 60 segundos.
fileNotifications.maxDeliveryCount Contagem máxima de entregas para a fila de notificação de upload de arquivos. 1 a 100. Padrão: 10.

Upload de arquivo usando um SDK

Os guias de instruções a seguir fornecem instruções completas passo a passo para carregar arquivos usando os SDKs de serviço e o dispositivo IoT do Azure. Os guias mostram como usar o portal do Azure para associar uma conta de armazenamento a um hub IoT. Os guias também contêm snippets de código ou se referem a exemplos que orientam você ao longo de um upload.

Guia de instruções Exemplo de SDK do dispositivo Exemplo do SDK do serviço
.NET Sim Sim
Java Sim Sim
Node.js Sim Sim
Python Sim Não (sem suporte)

Observação

O SDK do dispositivo C usa uma única chamada no cliente do dispositivo para fazer uploads de arquivos. Para saber mais, confira IoTHubDeviceClient_UploadToBlobAsync() e IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Essas funções executam todos os aspectos do upload do arquivo em uma só chamada: início do upload, upload do arquivo no Armazenamento do Azure e notificação do Hub IoT quando isso for concluído. Essa interação significa que, além dos protocolos que o dispositivo estiver usando para se comunicar com o Hub IoT, o dispositivo também precisará ser capaz de se comunicar via HTTPS com o Armazenamento do Azure, pois essas funções fazem chamadas às APIs do Armazenamento do Azure.

Dispositivo: inicializar um upload de arquivo

O dispositivo chama a API REST Criar URI de SAS para Upload de Arquivos a API equivalente em um dos SDKs do dispositivo para iniciar um upload de arquivos.

Protocolos com suporte: HTTPS
Ponto de extremidade: {hub iot}.azure-devices.net/devices/{deviceId}/files
Método: POST

{
    "blobName":"myfile.txt"
}
Propriedade Descrição
blobName O nome do blob para o qual gerar o URI de SAS.

O Hub IoT responde com um ID de correlação e os elementos de um URI de SAS que o dispositivo pode usar para autenticar no Armazenamento do Azure. Essa resposta está sujeita à limitação e aos limites de upload por dispositivo do Hub IoT de destino.

{
    "correlationId":"MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "hostName":"contosostorageaccount.blob.core.windows.net",
    "containerName":"device-upload-container",
    "blobName":"mydevice/myfile.txt",
    "sasToken":"?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw"
}
Propriedade Descrição
correlationId O identificador do dispositivo a ser usado no envio da notificação completa sobre upload de arquivos para o Hub IoT.
hostName O nome do host da conta do Armazenamento do Azure para a conta de armazenamento configurada no Hub IoT
containerName O nome do contêiner de blobs configurado no Hub IoT.
blobName O local em que o blob será armazenado no contêiner. O nome está no seguinte formato: {device ID of the device making the request}/{blobName in the request}
sasToken Um token SAS que concede acesso de leitura/gravação no blob com Armazenamento do Azure. O token é gerado e assinado pelo Hub IoT.

Quando ele recebe a resposta, o dispositivo:

  • Salva o ID de correlação a ser incluído na notificação completa sobre upload de arquivos para o Hub IoT quando conclui o upload.

  • Usa as outras propriedades para gerar um URI de SAS para o blob usado na autenticação no Armazenamento do Azure. O URI de SAS contém o URI do recurso para o blob solicitado e o token SAS. Ele assume o seguinte formato: https://{hostName}/{containerName}/{blobName}{sasToken} (A propriedade sasToken na resposta contém um caractere “?” à frente.) As chaves não estão incluídas.

    Por exemplo, para os valores retornados no exemplo anterior, o URI de SAS é https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw

    Para saber mais sobre o URI de SAS e o token SAS, confira Criar um SAS de serviço na documentação do Armazenamento do Azure.

Dispositivo: carregar arquivo usando APIs do Armazenamento do Azure

O dispositivo usa as APIs REST do Armazenamento de Blobs do Azure ou APIs equivalentes do SDK do Armazenamento do Azure para carregar o arquivo no blob no Armazenamento do Azure.

Protocolos com suporte: HTTPS

O exemplo a seguir mostra uma solicitação Put Blob para criar ou atualizar um blob de blocos pequeno. Observe que o URI usado nessa solicitação é o URI de SAS retornado pelo Hub IoT na seção anterior. O cabeçalho x-ms-blob-type indica que essa solicitação é para um blob de blocos. Se a solicitação for bem-sucedida, o Armazenamento do Azure retornará um 201 Created.

PUT https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt?sv=2018-03-28&sr=b&sig=mBLiODhpKXBs0y9RVzwk1S...l1X9qAfDuyg%3D&se=2021-07-30T06%3A11%3A10Z&sp=rw HTTP/1.1
Content-Length: 11
Content-Type: text/plain; charset=UTF-8
Host: contosostorageaccount.blob.core.windows.net
x-ms-blob-type: BlockBlob

hello world

O trabalho com APIs do Armazenamento do Azure está além do escopo deste artigo. Além das APIs REST do Armazenamento de Blobs do Azure vinculadas anteriormente nesta seção, você pode explorar a seguinte documentação para começar:

Dispositivo: notificar o Hub IoT sobre um upload de arquivo concluído

O dispositivo chama a API REST Atualizar Status do Upload de Arquivos ou a API equivalente em um dos SDKs do dispositivo quando conclui o upload do arquivo. O dispositivo deve atualizar o status de upload de arquivos com o Hub IoT independentemente de o upload ser bem-sucedido ou falhar.

Protocolos com suporte: HTTPS
Ponto de extremidade: {hub iot}.azure-devices.net/devices/{deviceId}/files/notifications
Método: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Propriedade Descrição
correlationId O ID de correlação recebido na solicitação inicial do URI de SAS.
isSuccess Um booliano que indica se o upload do arquivo foi bem-sucedido.
statusCode Um inteiro que representa o código de status do upload do arquivo. Normalmente com três dígitos, por exemplo, 200 ou 201.
statusDescription Uma descrição do status de upload do arquivo.

Quando ele recebe uma notificação completa sobre upload de arquivos do dispositivo, o Hub IoT:

  • Dispara uma notificação sobre upload de arquivos para os serviços de back-end se as notificações sobre upload de arquivos estão configuradas.

  • Libera recursos associados ao upload de arquivos. Sem receber uma notificação, o Hub IoT manterá os recursos até que a TTL (vida útil) do URI da SAS associado ao upload expire.

Serviço: notificações sobre upload de arquivo

Se as notificações de upload de arquivos estão habilitadas no Hub IoT, seu hub gera uma mensagem de notificação para os serviços de back-end quando recebe uma notificação de um dispositivo de que um upload de arquivo foi concluído. O Hub IoT fornece essas notificações sobre upload de arquivos por meio de um ponto de extremidade voltado para o serviço. A semântica de recebimento das notificações de upload de arquivos é a mesma das mensagens da nuvem para dispositivo e tem o mesmo ciclo de vida da mensagem. Os SDKs de serviço expõem APIs para lidar com notificações sobre upload de arquivos.

Protocolos aceitos AMQP, AMQP-WS
Ponto de extremidade: {hub iot}.azure-devices.net/messages/servicebound/fileuploadnotifications
Método GET

Cada mensagem recuperada do ponto de extremidade de notificação sobre upload de arquivos é um registro JSON:

{
    "deviceId":"mydevice",
    "blobUri":"https://contosostorageaccount.blob.core.windows.net/device-upload-container/mydevice/myfile.txt",
    "blobName":"mydevice/myfile.txt",
    "lastUpdatedTime":"2021-07-31T00:26:50+00:00",
    "blobSizeInBytes":11,
    "enqueuedTimeUtc":"2021-07-31T00:26:51.5134008Z"
}
Propriedade Descrição
enqueuedTimeUtc Carimbo de data/hora que indica quando a notificação foi criada.
deviceId O ID do dispositivo que carregou o arquivo.
blobUri O URI do arquivo carregado.
blobName O nome do arquivo carregado. O nome está no seguinte formato: {device ID of the device}/{name of the blob}
lastUpdatedTime Carimbo de data/hora que indica quando o arquivo foi atualizado pela última vez.
blobSizeInBytes Um inteiro que representa o tamanho do arquivo carregado em bytes.

Os serviços podem usar notificações para gerenciar uploads. Por exemplo, eles podem disparar seu próprio processamento dos dados de blob, disparar o processamento dos dados de blob usando outros serviços do Azure ou registrar a notificação de upload de arquivos para revisão posterior.

Próximas etapas