Отправка файлов с помощью Центра Интернета вещей

  • Статья

Существует множество сценариев, в которых непросто сопоставить данные, отправляемые устройством, с относительно небольшими сообщениями, отправляемыми из устройства в облако, которые принимает Центр Интернета вещей. Например, отправка больших файлов мультимедиа, таких как видео; или, отправляя большие пакеты телеметрии, передаваемые периодически подключенными устройствами или агрегированными и сжатыми для сохранения пропускной способности.

При передаче таких больших файлов с устройства вы можете рассчитывать на безопасность и надежность Центра Интернета вещей. Вместо функций брокера сообщений Центр Интернета вещей выполняет роль диспетчера для связанной учетной записи хранения Azure. Центр Интернета вещей также может предоставлять уведомления для серверных служб, когда устройство завершает передачу файла.

Если вам нужна помощь в выборе того, когда следует использовать сообщаемые свойства, сообщения из устройства в облако или отправку файлов, ознакомьтесь с рекомендациями по обмену данными между устройствами и облаком.

Важно!

Функция отправки файлов на устройствах, использующих проверку подлинности на основе сертификата X.509, доступна в общедоступной предварительной версии, при этом должен быть включен режим предварительного просмотра. Общедоступная версия доступна на устройствах, использующих проверку подлинности X.509 или аттестацию сертификатов X.509 с помощью Службы подготовки устройств Azure. Дополнительные сведения о проверке подлинности на основе сертификата X.509 с помощью Центра Интернета вещей см. в разделе Поддерживаемые сертификаты X.509.

Общие сведения о загрузке файлов

Центр Интернета вещей упрощает отправку файлов с подключенных устройств, предоставляя им URI подписанного URL-адреса (SAS) на основе каждой отправки для контейнера BLOB-объектов и учетной записи хранения Azure, предварительно настроенных с помощью центра. Существует три части использования отправки файлов с Центр Интернета вещей: предварительная настройка учетной записи хранения Azure и контейнера BLOB-объектов в Центре Интернета вещей, отправка файлов с устройств и, при необходимости, уведомление внутренних служб о завершенных отправках файлов.

Прежде чем использовать функцию передачи файлов, необходимо связать учетную запись хранения Azure и контейнер больших двоичных объектов с Центром Интернета вещей. Вы также можете настроить параметры, управляющие проверкой подлинности Центра Интернета вещей в службе хранилища Azure, срок жизни (TTL) URI SAS, которые Центр Интернета вещей передает на устройства, и уведомления об отправке файлов в серверные службы. Для получения дополнительных сведений см. раздел Связывание учетной записи хранения Azure с Центром Интернета вещей.

Для отправки файла в связанный контейнер больших двоичных объектов устройства используют процесс, состоящий из трех этапов:

  1. Устройство инициирует загрузку файла с помощью Центра Интернета вещей. Устройство передает имя большого двоичного объекта в запросе и взамен получает URI SAS и идентификатор корреляции. URI SAS содержит маркер SAS для службы хранилища Azure, предоставляющий разрешение на чтение и запись для запрошенного большого двоичного объекта в контейнере больших двоичных объектов. Дополнительные сведения см. в разделе "Устройство: инициализация отправки файла".

  2. Устройство использует URI SAS для безопасного вызова интерфейсов API хранилища больших двоичных объектов Azure, чтобы передать файл в контейнер больших двоичных объектов. Дополнительные сведения см. в статье "Устройство: отправка файла с помощью API службы хранилища Azure".

  3. После завершения передачи файла устройство уведомляет центр Интернета вещей о состоянии завершения, используя идентификатор корреляции, полученный от центра Интернета вещей при инициации отправки. Дополнительные сведения см. в разделе "Устройство: уведомление Центр Интернета вещей завершенной отправки файла".

Серверные службы могут подписываться на уведомления об отправке файлов в конечной точке уведомлений об отправке файлов, отправляемых службой Центра Интернета вещей. Если вы включили эти уведомления в Центре Интернета вещей, они доставляют их в эту конечную точку каждый раз, когда устройство уведомляет Центр о завершении передачи файла. Службы могут использовать эти уведомления для активации дальнейшей обработки данных больших двоичных объектов. Дополнительные сведения см. в разделе "Служба: уведомления о отправке файлов".

Передача файлов полностью поддерживается в пакетах SDK для устройств и служб Azure для Интернета вещей. Дополнительные сведения см. в разделе "Отправка файлов с помощью пакета SDK".

Квоты и ограничения для передачи файлов

Центр Интернета вещей накладывает ограничения на количество загрузок файлов, которые могут быть инициированы в течение заданного периода времени. Пороговое значение зависит от номера SKU и количества единиц Центра Интернета вещей. Кроме того, каждое устройство ограничено 10 параллельными активными передачами файлов за раз. Дополнительные сведения см. в разделе о квотах и регулировании Центра Интернета вещей.

Связывание учетной записи хранения Azure с Центром Интернета вещей

Чтобы использовать функцию передачи файлов, необходимо связать учетную запись хранения Azure и контейнер BLOB-объектов с Центром Интернета вещей. Все передачи файлов с устройств, зарегистрированных в Центре Интернета вещей, будут отправлены в этот контейнер. Сведения о настройке учетной записи хранения и контейнера BLOB-объектов в Центре Интернета вещей см. в статье Настройка отправки файлов Центр Интернета вещей с помощью портал Azure, настройка отправки файлов Центр Интернета вещей с помощью Azure CLI или настройка отправки файлов Центр Интернета вещей с помощью PowerShell. Вы также можете использовать API управления Центра Интернета вещей для настройки отправки файлов программным способом.

При использовании портала можно создать учетную запись хранения и контейнер во время настройки. В противном случае для создания учетной записи хранения см. раздел Создание учетной записи хранения в документации по службе хранилища Azure. После получения учетной записи хранения вы увидите, как создать контейнер BLOB-объектов в Хранилище BLOB-объектов Azure кратких руководствах. По умолчанию в Центре Интернета вещей используется проверка подлинности на основе ключей при подключении службы хранилища Azure и авторизации в ней. Вы также можете настроить управляемые удостоверения, назначаемые пользователем или системой, для проверки подлинности Центра Интернета вещей при подключении к службе хранилища Azure. Управляемые удостоверения обеспечивают службы Azure автоматически управляемым удостоверением в идентификаторе Microsoft Entra ID в безопасном режиме. Сведения о настройке управляемых удостоверений см. в разделе "Настройка отправки файлов с управляемыми удостоверениями" Центр Интернета вещей поддержке управляемых удостоверений.

Отправка файлов зависит от параметров брандмауэра служба хранилища Azure. В зависимости от конфигурации проверки подлинности необходимо убедиться, что устройства могут взаимодействовать с хранилищем Azure.

Существует несколько других параметров, управляющих поведением отправки файлов и уведомлениями об отправке файлов. В следующих сценариях перечислены все доступные параметры. В зависимости от того, используете ли вы портал Azure, Azure CLI, PowerShell или API-интерфейсы управления для настройки отправки файлов, некоторые из этих параметров могут быть недоступны. Если требуется, чтобы после завершения передачи файла уведомления отправлялись в серверные службы, убедитесь, что задан параметр enableFileUploadNotifications.

Параметры хранилища и проверки подлинности в Центре Интернета вещей

Следующие параметры связывают учетную запись хранения и контейнер с Центром Интернета вещей и управляют проверкой подлинности центра в службе хранилища Azure. Эти параметры не влияют на проверку подлинности устройств в службе хранилища Azure. Устройства всегда проходят проверку подлинности с маркером SAS, представленным в URI SAS, полученном из Центра Интернета вещей.

Свойство Description Диапазон и значение по умолчанию
storageEndpoints.$default.authenticationType Управляет проверкой подлинности Центра Интернета вещей в службе хранилища Azure. Возможными значениями являются "keyBased" и "identityBased". Значение по умолчанию: "keyBased".
storageEndpoints.$default.connectionString Строка подключения к учетной записи хранения Azure, используемой для отправки файлов. По умолчанию: пустая строка.
storageEndpoints.$default.containerName Имя контейнера, в который нужно передать файлы. По умолчанию: пустая строка.
storageEndpoints.$default.identity Управляемое удостоверение, используемое для проверки подлинности на основе удостоверений. Возможные значения — [system] для управляемого удостоверения, назначенного системой, или идентификатор ресурса для управляемого удостоверения, назначаемого пользователем. Значение не используется для проверки подлинности на основе ключей. По умолчанию: null.

Параметры отправки файла

Следующие параметры управляют отправкой файлов с устройства.

Свойство Description Диапазон и значение по умолчанию
storageEndpoints.$default.ttlAsIso8601 Срок жизни по умолчанию для URI SAS, созданных Центром Интернета вещей. ISO_8601 интервал до 48 часов (минимум одна минута). Значение по умолчанию: один час.

Параметры уведомлений об отправке файлов

Следующие параметры контролируют уведомления об отправке файлов в серверные службы.

Свойство Description Диапазон и значение по умолчанию
enableFileUploadNotifications Позволяет указать, следует ли записывать уведомления об отправке файлов в конечную точку файловых уведомлений. Bool. Значение по умолчанию: False.
fileNotifications.ttlAsIso8601 Значение TTL по умолчанию для уведомлений об отправке файлов. ISO_8601 интервал до 48 часов (минимум одна минута). Значение по умолчанию: один час.
fileNotifications.lockDuration Длительность блокировки для очереди уведомлений об отправке файлов. 5–300 секунд. Значение по умолчанию — 60 секунд.
fileNotifications.maxDeliveryCount Максимальное количество доставок для очереди уведомлений об отправке файлов. От 1 до 100. Значение по умолчанию — 10.

Отправка файлов с помощью пакета SDK

Следующие практические руководства содержат подробные пошаговые инструкции по отправке файлов с помощью пакетов SDK для устройств и служб Azure для Интернета вещей. В руководствах показано, как использовать портал Azure для связывания учетной записи хранения с Центром Интернета вещей. В руководствах также содержатся фрагменты кода или примеры, которые помогут вам выполнить отправку.

Практическое руководство Пример пакета SDK для устройства Пример пакета SDK для службы
.NET Да Да
Java Да Да
Node.js Да Да
Python Да Нет (не поддерживается)

Примечание.

В пакете SDK для устройства C для выполнения отправки файлов используется один вызов на клиенте устройства. Дополнительные сведения см. в IoTHubDeviceClient_UploadToBlobAsync() и IoTHubDeviceClient_UploadMultipleBlocksToBlobAsync(). Эти функции выполняют все аспекты отправки файла в одном вызове: инициирование отправки, отправка файла в хранилище Azure и уведомление Центр Интернета вещей после завершения. Это означает, что помимо протокола, используемого устройством для взаимодействия с Центр Интернета вещей, устройство также должно иметь возможность взаимодействовать по протоколу HTTPS с хранилищем Azure, так как эти функции выполняют вызовы к API службы хранилища Azure.

Устройство: инициализация отправки файла

Устройство вызывает REST API Создание отправки файла URI SAS или эквивалентный API в одном из пакетов SDK для устройства, чтобы инициировать отправку файла.

Поддерживаемые протоколы: HTTPS
Конечная точка: {iot hub}.azure-devices.net/devices/{deviceId}/files
Метод: POST

{
    "blobName":"myfile.txt"
}
Свойство Description
blobName Имя большого двоичного объекта, для которого создается URI SAS.

Центр Интернета вещей реагирует на идентификатор корреляции и элементы URI SAS, которые устройство может использовать для проверки подлинности в службе хранилища Azure. Этот ответ регулируется ограничениями и пределами передачи для каждого устройства в целевом Центре Интернета вещей.

{
    "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"
}
Свойство Description
correlationId Идентификатор устройства, используемого при отправке уведомления о завершении отправки файла в Центр Интернета вещей.
hostName Имя узла учетной записи хранения Azure для учетной записи хранения, настроенной в Центре Интернета вещей
containerName Имя контейнера больших двоичных объектов, настроенного в Центре Интернета вещей.
blobName Расположение, в котором будет храниться большой двоичный объект в контейнере. Имя имеет следующий формат: {device ID of the device making the request}/{blobName in the request}
sasToken Маркер SAS, предоставляющий доступ на чтение и запись для большого двоичного объекта в службе хранилища Azure. Маркер создается и подписывается в Центре Интернета вещей.

При получении ответа устройство выполняет следующие действия.

  • Сохраняет идентификатор корреляции для включения в уведомление о завершении отправки файла в Центр Интернета вещей по завершении отправки.

  • Использует другие свойства для создания URI SAS для большого двоичного объекта, который используется для проверки подлинности в службе хранилища Azure. URI SAS содержит URI ресурса для запрошенного большого двоичного объекта и маркер SAS. Он принимает следующую форму: https://{hostName}/{containerName}/{blobName}{sasToken} (свойство sasToken в ответе содержит начальный символ "?"). Фигурные скобки не включаются.

    Например, для значений, возвращаемых в предыдущем примере, используется универсальный код ресурса (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

    Дополнительные сведения об URI SAS и маркере SAS см. в документации по Созданию SAS службы в службе хранилища Azure.

Устройство: передача файла с помощью интерфейсов API службы хранилища Azure.

Устройство использует интерфейсы REST API Хранилище BLOB-объектов Azure или эквивалентные API пакета SDK службы хранилища Azure для отправки файла в хранилище Azure.

Поддерживаемые протоколы: HTTPS

В следующем примере показан запрос на размещение большого двоичного объекта для создания или обновления небольшого блочного BLOB-объекта. Обратите внимание, что универсальный код ресурса (URI), используемый для этого запроса, — это URI SAS, возвращенный Центром Интернета вещей в предыдущем разделе. Заголовок x-ms-blob-type указывает, что этот запрос предназначен для блочного BLOB-объекта. Если запрос выполнен успешно, служба хранилища Azure возвращает 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

Работа с API службы хранилища Azure выходит за рамки этой статьи. В дополнение к API-интерфейсам службы хранилища больших двоичных объектов Azure, связанным ранее в этом разделе, вы можете ознакомиться со следующей документацией, которая поможет вам приступить к работе.

Устройство: уведомление Центра Интернета вещей о завершении отправки файла

Устройство вызывает REST API файла обновления состояние отправки или эквивалентный API в одном из пакетов SDK устройства, когда оно завершает передачу файла. Устройство должно обновить состояние отправки файла в Центре Интернета вещей независимо от того, успешно ли выполнена отправка или происходит ошибка.

Поддерживаемые протоколы: HTTPS
Конечная точка: {iot hub}.azure-devices.net/devices/{deviceId}/files/notifications
Метод: POST

{
    "correlationId": "MjAyMTA3MzAwNjIxXzBiNjgwOGVkLWZjNzQtN...MzYzLWRlZmI4OWQxMzdmNF9teWZpbGUudHh0X3ZlcjIuMA==",
    "isSuccess": true,
    "statusCode": 200,
    "statusDescription": "File uploaded successfully"
}
Свойство Description
correlationId Идентификатор корреляции, полученный в исходном запросе URI SAS.
isSuccess Логическое значение, указывающее, успешно ли отправлен файл.
statusCode Целое число, представляющее код состояния для передачи файла. Обычно это три цифры, например, 200 или 201.
statusDescription Описание состояния отправки файла.

При получении уведомления о завершении отправки файла с устройства Центр Интернета вещей:

  • Запускает уведомление об отправке файла в серверные службы, если настроены уведомления об отправке файлов.

  • Освобождает ресурсы, связанные с отправкой файла. Если Центр Интернета вещей не получает уведомление, он будет поддерживать ресурсы до истечения срока действия URI SAS, связанного с отправкой.

Служба: уведомления об отправке файлов

Если уведомления о отправке файлов включены в Центре Интернета вещей, центр создает уведомление для внутренних служб при получении уведомления от устройства, которое отправляется. Центр Интернета вещей предоставляет эти уведомления об отправке файлов через конечную точку, доступную для службы. Семантика получения уведомлений об отправке файлов идентична семантике, используемой для сообщений, отправляемых из облака на устройство, и предусматривает такой же жизненный цикл сообщений. Пакеты SDK для служб предоставляют интерфейсы API для управления уведомлениями о передаче файлов.

Поддерживаемые протоколы AMQP, AMQP-WS
Конечная точка: {iot hub}.azure-devices.net/messages/servicebound/fileuploadnotifications
Метод GET

Каждое сообщение, полученное из конечной точки уведомления об отправке файла, — это запись 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"
}
Свойство Description
enqueuedTimeUtc Метка времени, указывающая, когда было создано уведомление.
deviceId Идентификатор устройства, которое отправило файл.
blobUri Код URI переданного файла.
blobName Имя отправленного файла. Имя имеет следующий формат: {device ID of the device}/{name of the blob}
lastUpdatedTime Метка времени, указывающая, когда файл был в последний раз обновлен.
blobSizeInBytes Целое число, представляющее размер отправленного файла в байтах.

Службы могут использовать уведомления для управления отправкой. Например, они могут активировать собственную обработку данных большого двоичного объекта, активировать обработку данных больших двоичных объектов с помощью других служб Azure или записать уведомление об отправке файла для последующего просмотра.

Следующие шаги