Настройка отправки файлов в Центре Интернета вещей с помощью Azure CLI

  • Статья

В этой статье говорится о том, как настроить передачу файлов в Центре Интернета вещей с помощью Azure CLI.

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

Необходимые компоненты

  • Используйте среду Bash в Azure Cloud Shell. Дополнительные сведения см . в кратком руководстве по Bash в Azure Cloud Shell.

  • Если вы предпочитаете выполнять справочные команды CLI локально, установите Azure CLI. Если вы работаете в Windows или macOS, Azure CLI можно запустить в контейнере Docker. Дополнительные сведения см. в статье Как запустить Azure CLI в контейнере Docker.

    • Если вы используете локальную установку, выполните вход в Azure CLI с помощью команды az login. Чтобы выполнить аутентификацию, следуйте инструкциям в окне терминала. Сведения о других возможностях, доступных при входе, см. в статье Вход с помощью Azure CLI.

    • Установите расширение Azure CLI при первом использовании, когда появится соответствующий запрос. Дополнительные сведения о расширениях см. в статье Использование расширений с Azure CLI.

    • Выполните команду az version, чтобы узнать установленную версию и зависимые библиотеки. Чтобы обновиться до последней версии, выполните команду az upgrade.

Примечание.

В этой статье используется последняя версия расширения Azure IoT под названием azure-iot. Прежняя версия называется azure-cli-iot-ext. В каждый момент времени должна быть установлена только одна версия. Проверить установленные расширения можно с помощью команды az extension list.

Используйте az extension remove --name azure-cli-iot-ext, чтобы удалить устаревшую версию расширения.

Используйте az extension add --name azure-iot, чтобы добавить новую версию расширения.

Чтобы узнать, какие расширения установлены, используйте az extension list.

Выполнение входа и установка учетной записи Azure

Войдите в учетную запись Azure и выберите подписку. Если вы используете Azure Cloud Shell, вы уже должны войти в эту среду, однако вам все равно может понадобиться выбрать подписку Azure, если у вас их несколько.

  1. В командной строке запустите команду login:

    az login

    Следуйте инструкциям, чтобы выполнить аутентификацию с использованием кода и войти в учетную запись Azure через веб-браузер.

  2. Если у вас есть несколько подписок Azure, то при выполнении входа в Azure вы получаете доступ ко всем учетным записям Azure, связанным с вашими учетными данными. Используйте следующую команду для вывода учетных записей Azure, доступных для использования:

    az account list

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

    az account set --subscription {your subscription name or id}

Получение сведений об учетной записи хранения

В следующих шагах предполагается, что для создания учетной записи хранения вы использовали модель развертывания с помощью Resource Manager, а не классическую модель развертывания.

Для настройки передачи файлов с ваших устройств необходима строка подключения к учетной записи хранения Azure. Эта учетная запись хранения должна относиться к той же подписке, что и Центр Интернета вещей. Кроме того, вам понадобится имя контейнера BLOB-объектов в учетной записи хранения. Для получения ключей учетной записи хранения используйте следующую команду:

az storage account show-connection-string --name {your storage account name} \
  --resource-group {your storage account resource group}

Строка подключения будет выглядеть следующим образом:

{
  "connectionString": "DefaultEndpointsProtocol=https;EndpointSuffix=core.windows.net;AccountName={your storage account name};AccountKey={your storage account key}"
}

Запишите значение connectionString. Оно понадобится вам на следующих этапах.

Для отправки файлов можно использовать существующий контейнер BLOB-объектов или создать новый:

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

    az storage container list --connection-string "{your storage account connection string}"

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

    az storage container create --name {container name} \
  --connection-string "{your storage account connection string}"

Настройка Центра Интернета вещей

Теперь с помощью данных учетной записи хранения можно настроить Центр Интернета вещей для включения функции отправки файлов в Центр Интернета вещей.

Для настройки потребуются следующие значения:

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

  • Receive notifications for uploaded files (Получать уведомления об отправленных файлах). Включите или отключите уведомления об отправке файлов.

  • SAS TTL (Срок жизни SAS). Этот параметр определяет срок жизни универсальных кодов ресурса (URI) SAS, возвращаемых Центром Интернета вещей на устройство. Значение по умолчанию — один час.

  • File notification settings default TTL (Стандартный срок жизни уведомления о файле). Это срок жизни уведомления об отправке файла. Значение по умолчанию — один день.

  • File notification maximum delivery count(Максимальное число доставок уведомления о файле): число попыток доставки уведомления о передаче файла, предпринимаемых Центром Интернета вещей. Значение по умолчанию — 10.

  • File notification lock duration (Длительность блокировки уведомления о файле). Длительность блокировки для очереди уведомлений о файлах. По умолчанию устанавливается значение в 60 секунд.

  • Authentication type (Тип проверки подлинности): тип проверки подлинности в Центре Интернета вещей, используемый для службы хранилища Azure. Этот параметр определяет, как Центр Интернета вещей выполняет проверку подлинности и авторизацию для службы хранилища Azure. По умолчанию используется проверка подлинности на основе ключей. Однако можно также использовать управляемые удостоверения, назначаемые системой, и управляемые удостоверения, назначаемые пользователю. Управляемые удостоверения обеспечивают службы Azure автоматически управляемым удостоверением в идентификаторе Microsoft Entra ID в безопасном режиме. Узнайте, как настроить управляемые удостоверения для Центра Интернета вещей и учетной записи хранения Azure, в разделе Поддержка управляемых удостоверений для Центра Интернета вещей. После настройки можно задать одно из управляемых удостоверений для проверки подлинности в службе хранилища Azure.

    Примечание.

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

Ниже приведены команды для настройки параметров передачи файлов в Центре Интернета вещей. Эти команды отображены по отдельности для ясности, но, как правило, выполняется одна команда со всеми параметрами, необходимыми для конкретного сценария. Добавьте кавычки там, где они указаны в командной строке. Не включайте скобки. Дополнительные сведения о каждом параметре доступны в документации Azure CLI по команде az iot hub update.

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

az iot hub update --name {your iot hub name} \
    --fileupload-storage-connectionstring "{your storage account connection string}" \
    --fileupload-storage-container-name "{your container name}"

Следующая команда задает срок жизни URI SAS со значением по умолчанию (один час).

az iot hub update --name {your iot hub name} \
    --fileupload-sas-ttl 1

Следующая команда включает уведомления о файлах и устанавливает для свойств уведомлений о файлах значения по умолчанию. (Для срока жизни уведомления о передаче файла устанавливается значение в 1 час, а для длительности блокировки — значение в 60 секунд.)

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

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

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type keyBased

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

az iot hub update --name {your iot hub name} \
    --fileupload-storage-auth-type identityBased \
    --fileupload-storage-identity [system]

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

Чтобы запросить управляемые удостоверения, назначаемые пользователем, в Центре Интернета вещей, используйте команду az iot hub identity show.

az iot hub identity show --name {your iot hub name} --query userAssignedIdentities

Эта команда возвращает коллекцию управляемых удостоверений, назначаемых пользователю, которые настроены в Центре Интернета вещей. В следующих выходных данных показана коллекция, содержащая одно управляемое удостоверение, назначаемое пользователем.

{
  "/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>"
  }
}

Следующая команда настраивает проверку подлинности на основе приведенного выше удостоверения, назначаемого пользователем.

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}"

Вы можете проверить параметры в Центре Интернета вещей, выполнив следующую команду:

az iot hub show --name {your iot hub name}

Чтобы проверить только параметры передачи файлов, используйте следующую команду:

az iot hub show --name {your iot hub name}
    --query '[properties.storageEndpoints, properties.enableFileUploadNotifications, properties.messagingEndpoints.fileNotifications]'

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

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

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