Carregar ficheiros com o Hub IoT

  • Artigo

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

Quando você precisa carregar arquivos grandes de um dispositivo, ainda pode usar a segurança e a confiabilidade do Hub IoT. Em vez de intermediar mensagens por si só, no entanto, o Hub IoT atua como um dispatcher para uma conta de armazenamento do Azure associada. O Hub IoT também pode fornecer notificação para serviços de back-end quando um dispositivo conclui um carregamento de arquivo.

Se precisar de ajuda para decidir quando usar propriedades relatadas, mensagens de dispositivo para nuvem ou uploads de arquivos, consulte Diretrizes de comunicações de dispositivo para nuvem.

Importante

A funcionalidade de carregamento de ficheiros em dispositivos que utilizam a autenticação da autoridade de certificação (CA) X.509 está em pré-visualização pública e o modo de pré-visualização tem de estar ativado. Está geralmente disponível em dispositivos que utilizam a autenticação de impressão digital X.509 ou o atestado de certificado X.509 com o Serviço de Aprovisionamento de Dispositivos do Azure. Para saber mais sobre a autenticação X.509 com o Hub IoT, consulte Certificados X.509 suportados.

Visão geral do upload de arquivos

Um hub IoT facilita o carregamento de arquivos de dispositivos conectados, fornecendo-lhes URIs de assinatura de acesso compartilhado (SAS) por carregamento para um contêiner de blob e uma conta de armazenamento do Azure que foram pré-configurados com o hub. Há três partes para usar carregamentos de arquivos com o Hub IoT: pré-configurar uma conta de armazenamento do Azure e um contêiner de blob em seu hub IoT, carregar arquivos de dispositivos e, opcionalmente, notificar os serviços de back-end sobre carregamentos de arquivos concluídos.

Antes de usar o recurso de carregamento de arquivo, você deve associar uma conta de armazenamento do Azure e um contêiner de blob ao seu hub IoT. Você também pode definir configurações que controlam como o Hub IoT se autentica com o armazenamento do Azure, o tempo de vida (TTL) dos URIs SAS que o hub IoT distribui para dispositivos e notificações de carregamento de arquivos para seus serviços de back-end. Para saber mais, consulte Associar uma conta de armazenamento do Azure ao Hub IoT.

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

  1. O dispositivo inicia o carregamento do arquivo com o hub IoT. Ele passa o nome de um blob na solicitação e obtém um URI SAS e uma ID de correlação em troca. O URI SAS contém um token SAS para armazenamento do Azure que concede ao dispositivo permissão de leitura/gravação no blob solicitado no contêiner de blob. Para obter mais informações, consulte Dispositivo: inicializar um carregamento de arquivo.

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

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

Os serviços de back-end podem se inscrever para notificações de upload de arquivos no ponto de extremidade de notificação de carregamento de arquivo voltado para o serviço do hub IoT. Se você tiver ativado essas notificações em seu hub IoT, ele as entregará nesse ponto de extremidade sempre que um dispositivo notificar o hub de que concluiu um carregamento de arquivo. Os serviços podem usar essas notificações para acionar o processamento adicional dos dados de blob. Para obter mais informações, consulte Serviço: Notificações de carregamento de arquivo.

O carregamento de ficheiros é totalmente suportado pelos SDKs de dispositivo e serviço do Azure IoT. Para obter mais informações, consulte Carregamento de arquivos usando um SDK.

Quotas e limites de carregamento de ficheiros

O Hub IoT impõe limites de limitação ao número de carregamentos de arquivos que ele pode iniciar em um determinado período. O limite é baseado na SKU e no número de unidades do seu hub IoT. Além disso, cada dispositivo é limitado a 10 carregamentos simultâneos de arquivos ativos de cada vez. Para obter mais informações, consulte Cotas e limitação do Hub IoT.

Associar uma conta de armazenamento do Azure ao Hub IoT

Você deve associar uma conta de armazenamento do Azure e um contêiner de blob ao seu hub IoT para usar os recursos de carregamento de arquivos. Todos os carregamentos de arquivos de dispositivos registrados com seu hub IoT irão para esse contêiner. Para configurar uma conta de armazenamento e um contêiner de blob em seu hub IoT, consulte Configurar carregamentos de arquivos do Hub IoT usando o portal do Azure, Configurar carregamentos de arquivos do Hub IoT usando a CLI do Azure ou Configurar carregamentos de arquivos do Hub IoT usando o PowerShell. Você também pode usar as APIs de gerenciamento do Hub IoT para configurar carregamentos 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, consulte Criar uma conta de armazenamento na documentação de armazenamento do Azure. Depois de ter uma conta de armazenamento, você pode ver como criar um contêiner de blob nos inícios rápidos do Armazenamento de Blobs do Azure. 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 maneira segura. Para saber como configurar identidades gerenciadas, consulte a seção Configurar carregamento de arquivos com identidades gerenciadas do suporte do Hub IoT para identidades gerenciadas.

O carregamento de ficheiros está sujeito às definições de firewall do Armazenamento do Azure. Com base na sua configuração de autenticação, você precisará garantir que seus dispositivos possam se comunicar com o armazenamento do Azure.

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

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

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

Propriedade Descrição Intervalo e padrão
storageEndpoints.$default.authenticationType Controla como o Hub IoT se autentica com o 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 de armazenamento do Azure a ser usada para carregamentos de arquivos. Padrão: Cadeia de caracteres vazia.
storageEndpoints.$default.containerName O nome do contêiner para o qual carregar arquivos. Padrão: Cadeia de caracteres vazia.
storageEndpoints.$default.identity A identidade gerenciada a ser usada para autenticação baseada em identidade. Os valores possíveis são [system] para a identidade gerenciada atribuída ao sistema ou um ID de recurso para uma identidade gerenciada atribuída pelo usuário. O valor não é usado para autenticação baseada em chave. Padrão: null.

Configurações de upload de arquivo

As configurações a seguir controlam o upload de arquivos do dispositivo.

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

Configurações de notificação de upload de arquivo

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

Propriedade Descrição Intervalo e padrão
enableFileUploadNotifications Controla se as notificações de carregamento de arquivo sã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. ISO_8601 intervalo de até 48 horas (mínimo de um minuto). Padrão: uma hora.
fileNotifications.lockDuration Duração do bloqueio para a fila de notificações de upload de arquivo. 5 a 300 segundos. Padrão: 60 segundos.
fileNotifications.maxDeliveryCount Contagem máxima de entrega para a fila de notificação de upload de arquivo. 1 a 100. Padrão: 10.

Upload de arquivos usando um SDK

Os guias de instruções a seguir fornecem instruções passo a passo completas para carregar arquivos usando os SDKs de dispositivo e serviço do Azure IoT. 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 trechos de código ou referem-se a exemplos que o guiam através de um upload.

Manual de instruções Exemplo de SDK de dispositivo Exemplo de SDK de serviço
.NET Sim Sim
Java Sim Sim
Node.js Sim Sim
Python Sim Não (não suportado)

Nota

O SDK do dispositivo C usa uma única chamada no cliente do dispositivo para executar carregamentos de arquivos. Para obter mais informações, consulte IoTHubDeviceClient_UploadToBlobAsync() e IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Essas funções executam todos os aspetos do carregamento de arquivo em uma única chamada: iniciar o carregamento, carregar o arquivo no armazenamento do Azure e notificar o Hub IoT quando ele for concluído. Essa interação significa que, além de qualquer protocolo que o dispositivo esteja usando para se comunicar com o Hub IoT, o dispositivo também precisa ser capaz de se comunicar por HTTPS com o armazenamento do Azure, pois essas funções fazem chamadas para as APIs de armazenamento do Azure.

Dispositivo: Inicializar um upload de arquivo

O dispositivo chama o Create File Upload, SAS URI , REST API ou a API equivalente em um dos SDKs do dispositivo para iniciar um upload de arquivo.

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

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

O Hub IoT responde com uma ID de correlação e os elementos de um URI SAS que o dispositivo pode usar para autenticar com o armazenamento do Azure. Essa resposta está sujeita aos limites de limitação e aos limites de carregamento 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 ao enviar a notificação completa de upload de arquivo para o Hub IoT.
Nome do host O nome do host da conta de armazenamento do Azure para a conta de armazenamento configurada no hub IoT
containerName O nome do contêiner de blob configurado no hub IoT.
blobNome O local onde 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 e gravação no blob com o armazenamento do Azure. O token é gerado e assinado pelo Hub IoT.

Quando recebe a resposta, o dispositivo:

  • Salva a ID de correlação para incluir na notificação completa de carregamento de arquivo no hub IoT quando ele concluir o carregamento.

  • Usa as outras propriedades para construir um URI SAS para o blob que ele usa para autenticar com o armazenamento do Azure. O URI SAS contém o URI de recurso para o blob solicitado e o token SAS. Assume a seguinte forma: https://{hostName}/{containerName}/{blobName}{sasToken} (A sasToken propriedade na resposta contém um caractere '?' à esquerda.) Os aparelhos não estão incluídos.

    Por exemplo, para os valores retornados na amostra anterior, o URI 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 obter mais informações sobre o URI SAS e o token SAS, consulte Criar uma SAS de serviço na documentação de armazenamento do Azure.

Dispositivo: carregar arquivo usando APIs de armazenamento do Azure

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

Protocolos suportados: HTTPS

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

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

Trabalhar com APIs de armazenamento do Azure está além do escopo deste artigo. Além das APIs REST de armazenamento de Blob do Azure vinculadas anteriormente nesta seção, você pode explorar a seguinte documentação para ajudá-lo a começar:

  • Para saber mais sobre como trabalhar com blobs no armazenamento do Azure, consulte a documentação do Armazenamento de Blobs do Azure.

  • Para obter informações sobre como usar SDKs de cliente de armazenamento do Azure para carregar blobs, consulte Referência da API de Armazenamento de Blobs do Azure.

Dispositivo: Notificar o Hub IoT de um carregamento de arquivo concluído

O dispositivo chama a API REST de Status de Carregamento de Arquivo de Atualização ou a API equivalente em um dos SDKs de dispositivo quando conclui o carregamento do arquivo. O dispositivo deve atualizar o status de carregamento de arquivos com o Hub IoT, independentemente de o carregamento ser bem-sucedido ou falhar.

Protocolos suportados: HTTPS
Ponto de extremidade: {iot hub}.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 A ID de correlação recebida na solicitação inicial de URI do SAS.
isSuccess Um booleano que indica se o carregamento do arquivo foi bem-sucedido.
statusCode Um inteiro que representa o código de status do upload do arquivo. Normalmente três dígitos; por exemplo, 200 ou 201.
statusDescrição Uma descrição do status de carregamento do arquivo.

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

  • Aciona uma notificação de carregamento de arquivo para serviços de back-end se as notificações de carregamento de arquivo estiverem configuradas.

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

Serviço: Notificações de upload de arquivo

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

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

Cada mensagem recuperada do ponto de extremidade de notificação de carregamento de arquivo é 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 A ID do dispositivo do dispositivo que carregou o arquivo.
blobUri O URI do arquivo carregado.
blobNome O nome do ficheiro carregado. O nome está no seguinte formato: {device ID of the device}/{name of the blob}
lastUpdatedTime Carimbo de data/hora indicando 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 acionar 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 carregamento de arquivo para revisão posterior.

Próximos passos