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

Статья
12/19/2024

В этой статье демонстрируются следующие возможности.

Используйте возможности отправки файлов Центр Интернета вещей для отправки файла в Хранилище BLOB-объектов Azure с помощью пакетов SDK для устройств и служб Azure IoT.
Уведомите Центр Интернета вещей, что файл был успешно отправлен и создайте серверную службу для получения уведомлений о отправке файлов из Центр Интернета вещей с помощью пакетов SDK службы Интернета вещей Azure.

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

Видео
Большие файлы, содержащие изображения.
Данные вибрации с высокой частотой выборки.
Некоторые виды предварительно обработанных данных.

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

Эта статья предназначена для дополнения примеров пакета SDK для запуска, на которые ссылается эта статья.

Дополнительные сведения см. в разделе:

Обзор передачи файлов с помощью Центра Интернета вещей
Общие сведения о хранилище BLOB-объектов Azure
IoT Hub SDKs (Пакеты SDK для Центра Интернета вещей)

Внимание

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

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

Центр Интернета вещей. Для некоторых вызовов пакета SDK требуется Центр Интернета вещей основной строка подключения, поэтому запишите строка подключения.
Зарегистрированное устройство. Для некоторых вызовов пакета SDK требуется основной строка подключения устройства, поэтому запишите строка подключения.
Центр Интернета вещей разрешение Service Connect. Чтобы получать сообщения уведомления об отправке файлов, серверная служба должна иметь разрешение Service Connect. По умолчанию каждый Центр Интернета вещей создается с помощью политики общего доступа, называемой службой, которая предоставляет это разрешение. Дополнительные сведения см. в разделе "Подключение к Центру Интернета вещей".
Настройте отправку файлов в Центре Интернета вещей, связав учетную запись служба хранилища Azure и контейнер Хранилище BLOB-объектов Azure. Эти параметры можно настроить с помощью портал Azure, Azure CLI или Azure PowerShell.

Обзор

В этом руководстве содержатся два раздела:

Отправка файла из приложения устройства
Получение уведомления о отправке файлов в серверном приложении

Отправка файла из приложения устройства

В этом разделе описывается отправка файла с устройства в Центр Интернета вещей с помощью класса DeviceClient в пакете SDK Для Интернета вещей Azure для .NET.

Выполните следующую процедуру, чтобы отправить файл с устройства в Центр Интернета вещей:

Подключение к Центру Интернета вещей
Получение URI SAS из Центра Интернета вещей
Отправка файла в хранилище Azure
Уведомление Центра Интернета вещей о состоянии отправки файлов

Подключение устройства к Центру Интернета вещей

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

Сертификат X.509
Общий ключ доступа

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к Центр Интернета вещей с помощью сертификата X.509:

Используйте DeviceAuthenticationWithX509Certificate для создания объекта, содержащего сведения об устройстве и сертификате. DeviceAuthenticationWithX509Certificate передается в качестве второго параметра DeviceClient.Create (шаг 2).
Используйте DeviceClient.Create для подключения устройства к Центр Интернета вещей с помощью сертификата X.509.

В этом примере сведения об устройстве и сертификате заполняются в объекте authDeviceAuthenticationWithX509Certificate , передаваемом в DeviceClient.Create.

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используйте Environment.GetEnvironmentVariable("HOSTNAME") для чтения переменной среды имени узла.

RootCertPath = "~/certificates/certs/sensor-thl-001-device.cert.pem";
Intermediate1CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate1.cert.pem";
Intermediate2CertPath = "~/certificates/certs/sensor-thl-001-device.intermediate2.cert.pem";
DevicePfxPath = "~/certificates/certs/sensor-thl-001-device.cert.pfx";
DevicePfxPassword = "1234";
DeviceName = "MyDevice";
HostName = "xxxxx.azure-devices.net";

var chainCerts = new X509Certificate2Collection();
chainCerts.Add(new X509Certificate2(RootCertPath));
chainCerts.Add(new X509Certificate2(Intermediate1CertPath));
chainCerts.Add(new X509Certificate2(Intermediate2CertPath));
using var deviceCert = new X509Certificate2(DevicePfxPath, DevicePfxPassword);
using var auth = new DeviceAuthenticationWithX509Certificate(DeviceName, deviceCert, chainCerts);

using var deviceClient = DeviceClient.Create(
    HostName,
    auth,
    TransportType.Amqp);

Дополнительные сведения о проверке подлинности сертификатов см. в следующем разделе:

Примеры кода

Примеры работы проверки подлинности сертификата X.509 см. в статье:

Проверка подлинности с помощью общего ключа доступа

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

AMQP — это протокол транспорта по умолчанию.

static string connectionString = "{device primary connection string}";
deviceClient = DeviceClient.CreateFromConnectionString(connectionString);

Получение URI SAS из Центра Интернета вещей

Вызовите GetFileUploadSasUriAsync , чтобы получить сведения о отправке файла. URI SAS используется на следующем шаге для отправки файла с устройства в хранилище BLOB-объектов.

const string filePath = "TestPayload.txt";
using var fileStreamSource = new FileStream(filePath, FileMode.Open);
var fileName = Path.GetFileName(fileStreamSource.Name);
var fileUploadSasUriRequest = new FileUploadSasUriRequest
{
    BlobName = fileName
};

FileUploadSasUriResponse sasUri = await _deviceClient.GetFileUploadSasUriAsync(fileUploadSasUriRequest, System.Threading.CancellationToken cancellationToken = default);
Uri uploadUri = sasUri.GetBlobUri();

Отправка файла в хранилище Azure

Чтобы отправить файл в хранилище Azure, выполните приведенные действия.

Создайте объект blockBlobClient, передав URI отправки файла.
Используйте метод UploadAsync для отправки файла в хранилище BLOB-объектов, передав URI SAS. При необходимости можно добавить параметры отправки BLOB-объектов и параметры маркера отмены.

Клиент BLOB-объектов Azure всегда использует HTTPS в качестве протокола для отправки файла в служба хранилища Azure.

В этом примере передается универсальный код ресурса (URI) SAS для BlockBlobClient создания клиента служба хранилища Azure блочного BLOB-объекта и отправки файла:

var blockBlobClient = new BlockBlobClient(uploadUri);
await blockBlobClient.UploadAsync(fileStreamSource, null, null);

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

Используйте CompleteFileUploadAsync , чтобы уведомить Центр Интернета вещей о том, что клиент устройства завершил отправку, передав объект FileUploadCompletionNotification . Флаг IsSuccess указывает, выполнена ли отправка успешно. После уведомления центр Интернета вещей освобождает ресурсы, связанные с отправкой (URI SAS).

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

var successfulFileUploadCompletionNotification = new FileUploadCompletionNotification
{
    // Mandatory. Must be the same value as the correlation id returned in the sas uri response
    CorrelationId = sasUri.CorrelationId,

    // Mandatory. Will be present when service client receives this file upload notification
    IsSuccess = true,

    // Optional, user defined status code. Will be present when service client receives this file upload notification
    StatusCode = 200,

    // Optional, user-defined status description. Will be present when service client receives this file upload notification
    StatusDescription = "Success"
};

await _deviceClient.CompleteFileUploadAsync(successfulFileUploadCompletionNotification);

Пример отправки файла ПАКЕТА SDK

Пакет SDK включает этот пример отправки файлов.

Получение уведомления о отправке файла в серверном приложении

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

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

Добавление пакета NuGet службы

Для приложений серверной службы требуется пакет NuGet Microsoft.Azure.Devices .

Подключение к Центру Интернета вещей

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

Политика общего доступа
Microsoft Entra

Внимание

В этой статье содержатся шаги по подключению к службе с помощью подписанного URL-адреса. Этот метод проверки подлинности удобнее для тестирования и оценки, но проверка подлинности в службе с помощью идентификатора Microsoft Entra или управляемых удостоверений является более безопасным подходом. Дополнительные сведения см. в статье "Рекомендации > по безопасности cloud security".

Подключение с помощью политики общего доступа

Подключите серверное приложение к устройству с помощью CreateFromConnectionString. Приложению требуется разрешение на подключение службы. Укажите эту политику общего доступа строка подключения в качестве параметраfromConnectionString. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

Например:

using Microsoft.Azure.Devices;
static ServiceClient serviceClient;
static string connectionString = "{Shared access policy connection string}";
serviceClient = ServiceClient.CreateFromConnectionString(connectionString);

Подключение с помощью Microsoft Entra

Серверное приложение, использующее Microsoft Entra, должно успешно пройти проверку подлинности и получить учетные данные маркера безопасности перед подключением к Центр Интернета вещей. Этот маркер передается методу подключения Центр Интернета вещей. Общие сведения о настройке и использовании Microsoft Entra для Центр Интернета вещей см. в разделе "Управление доступом к Центр Интернета вещей с помощью идентификатора Microsoft Entra".

Настройка приложения Microsoft Entra

Необходимо настроить приложение Microsoft Entra, настроенное для предпочитаемых учетных данных проверки подлинности. Приложение содержит такие параметры, как секрет клиента, используемый серверным приложением для проверки подлинности. Доступные конфигурации проверки подлинности приложений:

Секрет клиента
Сертификат
Учетные данные федеративного удостоверения

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

Дополнительные сведения о настройке приложения Microsoft Entra см. в кратком руководстве. Регистрация приложения с помощью платформа удостоверений Майкрософт.

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для проверки подлинности серверного приложения — использовать DefaultAzureCredential, но рекомендуется использовать другой метод в рабочей среде, включая определенный TokenCredential или синтаксический анализ ChainedTokenCredential. Для простоты в этом разделе описывается использование проверки DefaultAzureCredential подлинности и секрет клиента. Дополнительные сведения об преимуществах и недостатках использования DefaultAzureCredentialсм . в руководстве по использованию DefaultAzureCredential.

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

Для Microsoft Entra требуются следующие пакеты NuGet и соответствующие using инструкции:

Azure.Core
Azure.Identity

using Azure.Core;
using Azure.Identity;

В этом примере секрет клиента регистрации приложений Microsoft Entra, идентификатор клиента и идентификатор клиента добавляются в переменные среды. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. Результат успешной проверки подлинности Microsoft Entra — это учетные данные маркера безопасности, передаваемые методу подключения Центр Интернета вещей.

string clientSecretValue = "xxxxxxxxxxxxxxx";
string clientID = "xxxxxxxxxxxxxx";
string tenantID = "xxxxxxxxxxxxx";

Environment.SetEnvironmentVariable("AZURE_CLIENT_SECRET", clientSecretValue);
Environment.SetEnvironmentVariable("AZURE_CLIENT_ID", clientID);
Environment.SetEnvironmentVariable("AZURE_TENANT_ID", tenantID);

TokenCredential tokenCredential = new DefaultAzureCredential();

Результирующий tokenCredential можно передать в подключение к методу Центр Интернета вещей для любого клиента ПАКЕТА SDK, который принимает учетные данные Microsoft Entra:

В этом примере TokenCredential передается для ServiceClient.Create создания объекта подключения ServiceClient .

string hostname = "xxxxxxxxxx.azure-devices.net";
using var serviceClient = ServiceClient.Create(hostname, tokenCredential, TransportType.Amqp);

В этом примере TokenCredential передается для RegistryManager.Create создания объекта RegistryManager .

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);

Пример кода

Рабочий пример проверки подлинности службы Microsoft Entra см . в примере проверки подлинности на основе ролей.

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

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

Создайте отменуToken.
Вызовите GetFileNotificationReceiver , чтобы создать приемник уведомлений.
Используйте цикл с ReceiveAsync , чтобы ждать уведомления о отправке файла.

Например:

// Define the cancellation token
CancellationTokenSource source = new CancellationTokenSource();
CancellationToken token = source.Token;

// Create a notification receiver
var notificationReceiver = serviceClient.GetFileNotificationReceiver();
Console.WriteLine("\nReceiving file upload notification from service");

// Check for file upload notifications
while (true)
{
    var fileUploadNotification = await notificationReceiver.ReceiveAsync(token);
    if (fileUploadNotification == null) continue;
    Console.ForegroundColor = ConsoleColor.Yellow;
    Console.WriteLine("Received file upload notification: {0}", 
        string.Join(", ", fileUploadNotification.BlobName));
    Console.ResetColor();
    await notificationReceiver.CompleteAsync(fileUploadNotification);
}

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

Пакет SDK включает этот пример приемника отправки файлов.

Обзор

В этом руководстве содержатся два раздела:

Отправка файла из приложения устройства
Получение уведомления о отправке файлов в серверном приложении

Отправка файла из приложения устройства

В этом разделе описывается отправка файла с устройства в Центр Интернета вещей с помощью класса DeviceClient из пакета SDK Интернета вещей Azure для Java.

Выполните следующую процедуру, чтобы отправить файл с устройства в Центр Интернета вещей:

Подключение устройства к Центр Интернета вещей
Получение URI SAS из Центра Интернета вещей
Отправка файла в служба хранилища Azure
Отправка уведомления о состоянии отправки файлов в Центр Интернета вещей

Подключение устройства к Центру Интернета вещей

Сертификат X.509
Общий ключ доступа

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к Центр Интернета вещей с помощью сертификата X.509:

Создайте объект SSLContext с помощью buildSSLContext.
SSLContext Добавьте сведения в объект ClientOptions.
Вызов DeviceClient с помощью ClientOptions сведений для создания подключения "устройство — Центр Интернета вещей".

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используется Environment.GetEnvironmentVariable("PUBLICKEY") для чтения переменной строки строки сертификата открытого ключа.

private static final String publicKeyCertificateString =
        "-----BEGIN CERTIFICATE-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END CERTIFICATE-----\n";

//PEM encoded representation of the private key
private static final String privateKeyString =
        "-----BEGIN EC PRIVATE KEY-----\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX\n" +
        "-----END EC PRIVATE KEY-----\n";

SSLContext sslContext = SSLContextBuilder.buildSSLContext(publicKeyCertificateString, privateKeyString);
ClientOptions clientOptions = ClientOptions.builder().sslContext(sslContext).build();
DeviceClient client = new DeviceClient(connString, protocol, clientOptions);

Дополнительные сведения о проверке подлинности сертификатов см. в следующем разделе:

Примеры кода

Примеры работы проверки подлинности сертификата X.509 см. в статье:

Проверка подлинности с помощью общего ключа доступа

Операции отправки файлов всегда используют ПРОТОКОЛ HTTPS, но DeviceClient может определить IotHubClientProtocol для других служб, таких как телеметрия, метод устройства и двойник устройства.

IotHubClientProtocol protocol = IotHubClientProtocol.MQTT;

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

String connString = "{IoT hub connection string}";
DeviceClient client = new DeviceClient(connString, protocol);

Получение URI SAS из Центра Интернета вещей

Вызовите getFileUploadSasUri , чтобы получить объект FileUploadSasUriResponse .

FileUploadSasUriResponse включает эти методы и возвращаемые значения. Возвращаемые значения можно передать в методы отправки файлов.

Способ	Возвращаемое значение
`getCorrelationId()`	Идентификатор корреляции
`getContainerName()`	Имя контейнера
`getBlobName()`	Имя BLOB-объекта
`getBlobUri()`	URI BLOB-объекта

Например:

FileUploadSasUriResponse sasUriResponse = client.getFileUploadSasUri(new FileUploadSasUriRequest(file.getName()));

System.out.println("Successfully got SAS URI from IoT hub");
System.out.println("Correlation Id: " + sasUriResponse.getCorrelationId());
System.out.println("Container name: " + sasUriResponse.getContainerName());
System.out.println("Blob name: " + sasUriResponse.getBlobName());
System.out.println("Blob Uri: " + sasUriResponse.getBlobUri());

Отправка файла в служба хранилища Azure

Передайте конечную точку URI большого двоичного объекта в BLOBClientBuilder.buildclient, чтобы создать объект BlobClient.

BlobClient blobClient =
    new BlobClientBuilder()
        .endpoint(sasUriResponse.getBlobUri().toString())
        .buildClient();

Вызовите uploadFromFile , чтобы отправить файл в хранилище BLOB-объектов.

String fullFileName = "Path of the file to upload";
blobClient.uploadFromFile(fullFileName);

Отправка уведомления о состоянии отправки файлов в Центр Интернета вещей

Отправьте уведомление о состоянии отправки в Центр Интернета вещей после попытки отправки файла.

Создайте объект FileUploadCompletionNotification. Передайте состояние успешной отправки и isSuccess отправки correlationId файла. isSuccess true Передайте значение, когда отправка файла прошла успешно, false когда нет.

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

В этом примере передается успешное состояние.

FileUploadCompletionNotification completionNotification = new FileUploadCompletionNotification(sasUriResponse.getCorrelationId(), true);
client.completeFileUpload(completionNotification);

Закройте клиент

client Освободить ресурсы.

client.closeNow();

Создание серверного приложения

В этом разделе описывается, как получить уведомление о отправке файлов в серверном приложении.

Добавление инструкций импорта

Добавьте эти инструкции импорта для использования пакета SDK Для Java Для Интернета вещей Azure и обработчика исключений.

import com.microsoft.azure.sdk.iot.service.*;
import java.io.IOException;
import java.net.URISyntaxException;

Подключение к Центру Интернета вещей

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

Политика общего доступа
Microsoft Entra

Внимание

Подключение с помощью политики общего доступа

Определение протокола подключения

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

IotHubServiceClientProtocolпринимает только перечислениеAMQPS.AMQPS_WS

private static final IotHubServiceClientProtocol protocol =    
    IotHubServiceClientProtocol.AMQPS;

Создание объекта ServiceClient

Создайте объект ServiceClient, предоставляя строка подключения и протокол Центра Iot.

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

В качестве параметра конструктору ServiceClient предоставьте политику общего доступа службы . Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

String iotHubConnectionString = "HostName=xxxxx.azure-devices.net;SharedAccessKeyName=service;SharedAccessKey=xxxxxxxxxxxxxxxxxxxxxxxx";
private static final ServiceClient serviceClient (iotHubConnectionString, protocol);

Открытие подключения между приложением и Центр Интернета вещей

Откройте подключение отправителя AMQP. Этот метод создает соединение между приложением и Центр Интернета вещей.

serviceClient.open();

Подключение с помощью Microsoft Entra

Общие сведения о проверке подлинности пакета SDK для Java см. в статье "Проверка подлинности Azure с помощью Java и удостоверений Azure".

Для простоты в этом разделе рассматривается описание проверки подлинности с помощью секрета клиента.

Настройка приложения Microsoft Entra

Секрет клиента
Сертификат
Учетные данные федеративного удостоверения

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для проверки подлинности серверного приложения — использовать DefaultAzureCredential, но рекомендуется использовать другой метод в рабочей среде, включая определенный TokenCredential или синтаксический анализ ChainedTokenCredential. Дополнительные сведения о преимуществах и недостатках использования DefaultAzureCredentialсм. в цепочках учетных данных в клиентской библиотеке удостоверений Azure для Java.

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

Учетные данные приложения Microsoft Entra можно выполнить с помощью DefaultAzureCredentialBuilder. Сохраните параметры подключения, такие как client secretID, clientID и значения секрета клиента в качестве переменных среды. TokenCredential После создания передайте его в ServiceClient или другой построитель в качестве параметра credential.

В этом примере DefaultAzureCredentialBuilder пытается выполнить проверку подлинности подключения из списка, описанного в defaultAzureCredential. Результат успешной проверки подлинности Microsoft Entra — это учетные данные маркера безопасности, передаваемые конструктору, например ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();

Проверка подлинности с помощью ClientSecretCredentialBuilder

С помощью ClientSecretCredentialBuilder можно создать учетные данные с помощью сведений о секрете клиента. В случае успешного выполнения этот метод возвращает токенCredential , который можно передать в ServiceClient или другому построителю в качестве параметра credential.

В этом примере в переменные среды добавлены секрет клиента регистрации приложений Microsoft Entra, идентификатор клиента и значения идентификатора клиента. Эти переменные среды используются ClientSecretCredentialBuilder для создания учетных данных.

string clientSecretValue = System.getenv("AZURE_CLIENT_SECRET");
string clientID = System.getenv("AZURE_CLIENT_ID");
string tenantID = System.getenv("AZURE_TENANT_ID");

TokenCredential credential =
     new ClientSecretCredentialBuilder()
          .tenantId(tenantID)
          .clientId(clientID)
          .clientSecret(clientSecretValue)
          .build();

Другие классы проверки подлинности

Пакет SDK для Java также включает следующие классы, которые проходят проверку подлинности серверного приложения с помощью Microsoft Entra:

Примеры кода

Примеры работы проверки подлинности службы Microsoft Entra см . в примере проверки подлинности на основе ролей.

Проверка состояния отправки файлов

Чтобы проверить состояние отправки файла, выполните следующие действия.

Создайте объект getFileUploadNotificationReceiver.
Используйте открытую для подключения к Центру Интернета вещей.
Вызов, чтобы проверить состояние отправки файла. Этот метод возвращает объект fileUploadNotification . Если уведомление о отправке получено, можно просмотреть поля состояния отправки с помощью методов fileUploadNotification .

Например:

FileUploadNotificationReceiver receiver = serviceClient.getFileUploadNotificationReceiver();
receiver.open();
FileUploadNotification fileUploadNotification = receiver.receive(2000);

if (fileUploadNotification != null)
{
    System.out.println("File Upload notification received");
    System.out.println("Device Id : " + fileUploadNotification.getDeviceId());
    System.out.println("Blob Uri: " + fileUploadNotification.getBlobUri());
    System.out.println("Blob Name: " + fileUploadNotification.getBlobName());
    System.out.println("Last Updated : " + fileUploadNotification.getLastUpdatedTimeDate());
    System.out.println("Blob Size (Bytes): " + fileUploadNotification.getBlobSizeInBytes());
    System.out.println("Enqueued Time: " + fileUploadNotification.getEnqueuedTimeUtcDate());
}
else
{
    System.out.println("No file upload notification");
}

// Close the receiver object
receiver.close();

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

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

Установка пакетов

Перед вызовом любого связанного кода необходимо установить библиотеку azure-iot-device.

pip install azure-iot-device

Пакет azure.storage.blob используется для отправки файла.

pip install azure.storage.blob

Отправка файла из приложения устройства

В этом разделе описывается отправка файла с устройства в Центр Интернета вещей с помощью класса IoTHubDeviceClient из пакета SDK Интернета вещей Azure для Python.

Импорт библиотек

import os
from azure.iot.device import IoTHubDeviceClient
from azure.core.exceptions import AzureError
from azure.storage.blob import BlobClient

Подключение устройства к Центру Интернета вещей

Сертификат X.509
Общий ключ доступа

Проверка подлинности с помощью сертификата X.509

Чтобы подключить устройство к Центр Интернета вещей с помощью сертификата X.509:

Добавление параметров сертификата X.509 с помощью create_from_x509_certificate
Вызов подключения для подключения клиента устройства

В этом примере показаны значения входных параметров сертификата в качестве локальных переменных для ясности. В рабочей системе храните конфиденциальные входные параметры в переменных среды или другом безопасном расположении хранилища. Например, используйте os.getenv("HOSTNAME") для чтения переменной среды имени узла.

# The Azure IoT hub name
hostname = "xxxxx.azure-devices.net"

# The device that has been created on the portal using X509 CA signing or self-signing capabilities
device_id = "MyDevice"

# The X.509 certificate file name
cert_file = "~/certificates/certs/sensor-thl-001-device.cert.pfx"
key_file = "~/certificates/certs/sensor-thl-001-device.cert.key"
# The optional certificate pass phrase
pass_phrase = "1234"

x509 = X509(
    cert_file,
    key_file,
    pass_phrase,
)

# The client object is used to interact with your Azure IoT hub.
device_client = IoTHubDeviceClient.create_from_x509_certificate(
    hostname=hostname, device_id=device_id, x509=x509
)

# Connect to IoT Hub
await device_client.connect()

Дополнительные сведения о проверке подлинности сертификатов см. в следующем разделе:

Примеры кода

Рабочие примеры проверки подлинности сертификата X.509 см. в примерах, имена файлов которых заканчиваются в сценариях x509 в концентраторе Async.

Проверка подлинности с помощью общего ключа доступа

Чтобы подключить устройство к Центр Интернета вещей, выполните действия.

Вызовите create_from_connection_string, чтобы добавить основной строка подключения устройства.
Вызовите подключение для подключения клиента устройства.

Например:

# Add your IoT hub primary connection string
CONNECTION_STRING = "{Device primary connection string}"
device_client = IoTHubDeviceClient.create_from_connection_string(CONNECTION_STRING)

# Connect the client
device_client.connect()

Получение сведений о хранилище BLOB-объектов

Вызовите get_storage_info_for_blob, чтобы получить сведения из Центра Интернета вещей о связанной учетной записи служба хранилища Azure. Эти сведения включают имена узла, контейнера и BLOB-объекта, а также маркер SAS. Метод get_storage_info_for_blob также возвращает correlation_idзначение, которое используется в методе notify_blob_upload_status . Это correlation_id Центр Интернета вещей способ пометить, над каким BLOB-объектом вы работаете.

# Get the storage info for the blob
PATH_TO_FILE = "{Full path to local file}"
blob_name = os.path.basename(PATH_TO_FILE)
blob_info = device_client.get_storage_info_for_blob(blob_name)

Отправка файла в хранилище BLOB-объектов

Чтобы отправить файл в хранилище BLOB-объектов, выполните приведенные действия.

Используйте from_blob_url для создания объекта BlobClient из URL-адреса БОЛЬШОго двоичного объекта.
Вызовите upload_blob для отправки файла в хранилище BLOB-объектов.

В этом примере анализируется blob_info структура для создания URL-адреса, который он использует для инициализации BLOBClient. Затем он вызывает upload_blob отправку файла в хранилище BLOB-объектов.

try:
    sas_url = "https://{}/{}/{}{}".format(
        blob_info["hostName"],
        blob_info["containerName"],
        blob_info["blobName"],
        blob_info["sasToken"]
    )

    print("\nUploading file: {} to Azure Storage as blob: {} in container {}\n".format(file_name, blob_info["blobName"], blob_info["containerName"]))

    # Upload the specified file
    with BlobClient.from_blob_url(sas_url) as blob_client:
        with open(file_name, "rb") as f:
            result = blob_client.upload_blob(f, overwrite=True)
            return (True, result)

except FileNotFoundError as ex:
    # catch file not found and add an HTTP status code to return in notification to IoT hub
    ex.status_code = 404
    return (False, ex)

except AzureError as ex:
    # catch Azure errors that might result from the upload operation
    return (False, ex)

Уведомление Центра Интернета вещей о состоянии отправки

Используйте notify_blob_upload_status для уведомления Центра Интернета вещей о состоянии операции хранилища BLOB-объектов. correlation_id Передайте полученный методомget_storage_info_for_blob. Центр correlation_id Интернета вещей используется для уведомления любой службы, которая может прослушивать уведомление о состоянии задачи отправки файла.

В этом примере центр Интернета вещей уведомляет об успешной отправке файлов:

device_client.notify_blob_upload_status(storage_info["correlationId"], True, 200, "OK: {}".format(PATH_TO_FILE)

Завершение работы клиента устройства

Завершите работу клиента. После вызова этого метода любая попытка дальнейших вызовов клиентов приводит к возникновению клиентаError .

device_client.shutdown()

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

Пакет SDK включает два примера отправки файлов:

Обзор

В этой статье описывается, как использовать пакет SDK Для Интернета вещей Azure для Node.js для создания приложения устройства для отправки файла и приложения серверной службы получения уведомления о отправке файлов.

Создание приложения устройства

В этом разделе описывается, как отправить файл с устройства в Центр Интернета вещей с помощью пакета azure-iot-device в пакете SDK Для Интернета вещей Azure для Node.js.

Установка пакетов SDK

Выполните следующую команду, чтобы установить пакет SDK для устройств Azure-iot-device , azure-iot-device-mqtt и пакеты @azure/storage-blob на компьютере разработки:

npm install azure-iot-device azure-iot-device-mqtt @azure/storage-blob --save

Пакет azure-iot-device содержит объекты, которые интерфейсирует с устройствами Интернета вещей.

Выполните следующую процедуру, чтобы отправить файл с устройства в Центр Интернета вещей:

Подключение устройства к Центр Интернета вещей
Получение маркера подписанного URL-адреса (SAS) BLOB-объекта из Центр Интернета вещей
Отправка файла в служба хранилища Azure
Отправка уведомления о состоянии отправки файлов в Центр Интернета вещей

Создание модулей

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

const Protocol = require('azure-iot-device-mqtt').Mqtt;
const errors = require('azure-iot-common').errors;
const path = require('path');

Подключение устройства к Центру Интернета вещей

Сертификат X.509
Общий ключ доступа

Проверка подлинности с помощью сертификата X.509

Сертификат X.509 подключен к транспорту подключения устройства к Центр Интернета вещей.

Чтобы настроить подключение "устройство к Центр Интернета вещей" с помощью сертификата X.509:

Вызовите fromConnectionString, чтобы добавить строка подключения модуля устройства или удостоверения и тип транспорта в Client объект. Добавьте x509=true в строка подключения, чтобы указать, что сертификат добавляется DeviceClientOptionsв . Например:
- Устройство строка подключения:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
- Модуль удостоверений строка подключения:
  
  HostName=xxxxx.azure-devices.net;DeviceId=Device-1;ModuleId=Module-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true
Настройте переменную JSON с сведениями о сертификате и передайте ее в DeviceClientOptions.
Вызов setOptions для добавления сертификата и ключа X.509 (при необходимости парольной фразы) в транспорт клиента.
Вызовите, чтобы открыть подключение с устройства, чтобы Центр Интернета вещей.

В этом примере показаны сведения о конфигурации сертификата в переменной JSON. Конфигурация сертификации clientOptions передается setOptions, и подключение открывается с помощью open.

const Client = require('azure-iot-device').Client;
const Protocol = require('azure-iot-device-mqtt').Mqtt;
// Connection string illustrated for demonstration only. Never hard-code the connection string in production. Instead use an environmental variable or other secure storage.
const connectionString = `HostName=xxxxx.azure-devices.net;DeviceId=Device-1;SharedAccessKey=xxxxxxxxxxxxx;x509=true`
const client = Client.fromConnectionString(connectionString, Protocol);

var clientOptions = {
   cert: myX509Certificate,
   key: myX509Key,
   passphrase: passphrase,
   http: {
     receivePolicy: {
       interval: 10
     }
   }
 }

 client.setOptions(clientOptions);
 client.open(connectCallback);

Дополнительные сведения о проверке подлинности сертификатов см. в следующем разделе:

Пример кода

Рабочий пример проверки подлинности сертификата X.509 см. в разделе "Простой пример устройства X.509".

Проверка подлинности с помощью общего ключа доступа

Выбор транспортного протокола

Объект Client поддерживает следующие протоколы:

Amqp
Http— При использовании HttpClient экземпляр проверяет наличие сообщений из Центр Интернета вещей редко (как минимум каждые 25 минут).
Mqtt
MqttWs
AmqpWs

Установите необходимые транспортные протоколы на компьютере разработки.

Например, эта команда устанавливает Amqp протокол:

npm install azure-iot-device-amqp --save

Дополнительные сведения о различиях между MQTT, AMQP и HTTPS см. в статьях Руководство по обмену данными между облаком и устройством и Выбор протокола связи.

Создание клиентского объекта

Client Создайте объект с помощью установленного пакета.

Например:

const Client = require('azure-iot-device').Client;

Создание объекта протокола

Protocol Создайте объект с помощью установленного транспортного пакета.

В этом примере назначается протокол AMQP:

const Protocol = require('azure-iot-device-amqp').Amqp;

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

Вызов изConnectionString для предоставления параметров подключения устройства:

connStr — устройство строка подключения.
transportCtor — транспортный протокол.

В этом примере используется транспортный Amqp протокол:

const deviceConnectionString = "{IoT hub device connection string}"
const Protocol = require('azure-iot-device-mqtt').Amqp;
let client = Client.fromConnectionString(deviceConnectionString, Protocol);

Открытие подключения к Центр Интернета вещей

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

Например:

client.open(function(err) {
  if (err) {
    console.error('error connecting to hub: ' + err);
    process.exit(1);
  }
})

Получение маркера SAS из Центра Интернета вещей

Используйте getBlobSharedAccessSignature , чтобы получить маркер SAS связанной учетной записи хранения из Центра Интернета вещей.

Например:

// make sure you set these environment variables prior to running the sample.
const localFilePath = process.env.PATH_TO_FILE;
const storageBlobName = path.basename(localFilePath);
const blobInfo = await client.getBlobSharedAccessSignature(storageBlobName);
if (!blobInfo) {
throw new errors.ArgumentError('Invalid upload parameters');
}

Отправка файла в Центр Интернета вещей

Чтобы отправить файл с устройства в Центр Интернета вещей, выполните приведенные действия.

Создание конвейера потоков
Создание URL-адреса БОЛЬШОго двоичного объекта
Создание BlockBlobClient для отправки файлов в хранилище BLOB-объектов
Вызов uploadFile для отправки файла в хранилище BLOB-объектов
Вызов notifyBlobUploadStatus , чтобы уведомить Центр Интернета вещей об успешной отправке или сбое

Например:

// Open the pipeline
const pipeline = newPipeline(new AnonymousCredential(), {
retryOptions: { maxTries: 4 },
telemetry: { value: 'HighLevelSample V1.0.0' }, // Customized telemetry string
keepAliveOptions: { enable: false }
});

// Construct the blob URL
const { hostName, containerName, blobName, sasToken } = blobInfo;
const blobUrl = `https://${hostName}/${containerName}/${blobName}${sasToken}`;

// Create the BlockBlobClient for file upload to Blob Storage
const blobClient = new BlockBlobClient(blobUrl, pipeline);

// Setup blank status notification arguments to be filled in on success/failure
let isSuccess;
let statusCode;
let statusDescription;

const uploadStatus = await blobClient.uploadFile(localFilePath);
console.log('uploadStreamToBlockBlob success');

  try {
    const uploadStatus = await blobClient.uploadFile(localFilePath);
    console.log('uploadStreamToBlockBlob success');

    // Save successful status notification arguments
    isSuccess = true;
    statusCode = uploadStatus._response.status;
    statusDescription = uploadStatus._response.bodyAsText;

    // Notify IoT hub of upload to blob status (success)
    console.log('notifyBlobUploadStatus success');
  }
  catch (err) {
    isSuccess = false;
    statusCode = err.code;
    statusDescription = err.message;

    console.log('notifyBlobUploadStatus failed');
    console.log(err);
  }

// Send file upload status notification to IoT hub
await client.notifyBlobUploadStatus(blobInfo.correlationId, isSuccess, statusCode, statusDescription);

Отправка локального файла в хранилище BLOB-объектов

Локальный файл можно передать в хранилище BLOB-объектов с компьютера.

const deviceClient = Client.fromConnectionString(deviceConnectionString, Protocol);
uploadToBlob(localFilePath, deviceClient)
  .catch((err) => {
    console.log(err);
  })
  .finally(() => {
    process.exit();
  });

Пример отправки файла ПАКЕТА SDK

Пакет SDK включает отправку в расширенный пример BLOB-объектов.

Создание серверного приложения

В этом разделе описывается, как получать уведомления о отправке файлов в серверном приложении.

Установка пакета ПАКЕТА SDK службы

Выполните следующую команду, чтобы установить azure-iothub на компьютере разработки:

npm install azure-iothub --save

Подключение к Центру Интернета вещей

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

Политика общего доступа
Microsoft Entra

Внимание

Подключение с помощью политики общего доступа

Используйте fromConnectionString для подключения к Центру Интернета вещей.

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

В качестве параметра CreateFromConnectionStringукажите политику общего доступа службы строка подключения. Дополнительные сведения о политиках общего доступа см. в статье "Управление доступом к Центр Интернета вещей с помощью подписанных URL-адресов".

var Client = require('azure-iothub').Client;
var connectionString = '{IoT hub shared access policy connection string}';
var client = Client.fromConnectionString(connectionString);

Подключение с помощью Microsoft Entra

Общие сведения о проверке подлинности пакета SDK для Node.js см. в следующих статье:

Настройка приложения Microsoft Entra

Секрет клиента
Сертификат
Учетные данные федеративного удостоверения

Проверка подлинности с помощью DefaultAzureCredential

Самый простой способ использовать Microsoft Entra для проверки подлинности серверного приложения — использовать DefaultAzureCredential, но рекомендуется использовать другой метод в рабочей среде, включая определенный TokenCredential или синтаксический анализ ChainedTokenCredential. Для простоты в этом разделе описывается использование проверки DefaultAzureCredential подлинности и секрет клиента. Дополнительные сведения о преимуществах и недостатках использования DefaultAzureCredentialсм. в разделе "Учетные данные" в клиентской библиотеке удостоверений Azure для JavaScript

Для Microsoft Entra требуется этот пакет:

npm install --save @azure/identity

В этом примере в переменные среды были добавлены секрет клиента регистрации приложений Microsoft Entra, идентификатор клиента и идентификатор клиента. Эти переменные среды используются DefaultAzureCredential для проверки подлинности приложения. Результат успешной проверки подлинности Microsoft Entra — это учетные данные маркера безопасности, передаваемые методу подключения Центр Интернета вещей.

import { DefaultAzureCredential } from "@azure/identity";

// Azure SDK clients accept the credential as a parameter
const credential = new DefaultAzureCredential();

Затем полученный маркер учетных данных можно передать изTokenCredential для подключения к Центр Интернета вещей для любого клиента ПАКЕТА SDK, который принимает учетные данные Microsoft Entra:

fromTokenCredential требуется два параметра:

URL-адрес службы Azure— URL-адрес службы Azure должен находиться в формате {Your Entra domain URL}.azure-devices.net без https:// префикса. Например, MyAzureDomain.azure-devices.net.
Маркер учетных данных Azure

В этом примере учетные данные Azure получаются с помощью DefaultAzureCredential. Затем для создания подключения к Центр Интернета вещей предоставляется Registry.fromTokenCredential URL-адрес домена Azure и учетные данные.

const { DefaultAzureCredential } = require("@azure/identity");

let Registry = require('azure-iothub').Registry;

// Define the client secret values
clientSecretValue = 'xxxxxxxxxxxxxxx'
clientID = 'xxxxxxxxxxxxxx'
tenantID = 'xxxxxxxxxxxxx'

// Set environment variables
process.env['AZURE_CLIENT_SECRET'] = clientSecretValue;
process.env['AZURE_CLIENT_ID'] = clientID;
process.env['AZURE_TENANT_ID'] = tenantID;

// Acquire a credential object
const credential = new DefaultAzureCredential()

// Create an instance of the IoTHub registry
hostName = 'MyAzureDomain.azure-devices.net';
let registry = Registry.fromTokenCredential(hostName,credential);

Примеры кода

Примеры работы проверки подлинности службы Microsoft Entra см . в примерах удостоверений Azure.

Создание приемника обратного вызова уведомления о отправке файла

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

Вызов getFileNotificationReceiver. Укажите имя метода обратного вызова отправки файла, вызываемого при получении уведомлений.
Обработка уведомлений о отправке файлов в методе обратного вызова.

В этом примере настраивается приемник обратного receiveFileUploadNotification вызова уведомлений. Получатель интерпретирует сведения о состоянии отправки файла и выводит сообщение о состоянии в консоль.

//Set up the receiveFileUploadNotification notification message callback receiver
serviceClient.getFileNotificationReceiver(function receiveFileUploadNotification(err, receiver){
if (err) {
  console.error('error getting the file notification receiver: ' + err.toString());
} else {
  receiver.on('message', function (msg) {
    console.log('File upload from device:')
    console.log(msg.getData().toString('utf-8'));
    receiver.complete(msg, function (err) {
      if (err) {
        console.error('Could not finish the upload: ' + err.message);
      } else {
        console.log('Upload complete');
      }
    });
  });
}

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

Пакет SDK включает пример отправки файлов.

Поделиться через

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

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

Обзор

Отправка файла из приложения устройства

Подключение устройства к Центру Интернета вещей

Проверка подлинности с помощью сертификата X.509

Примеры кода

Проверка подлинности с помощью общего ключа доступа

Получение URI SAS из Центра Интернета вещей

Отправка файла в хранилище Azure

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

Пример отправки файла ПАКЕТА SDK

Получение уведомления о отправке файла в серверном приложении

Добавление пакета NuGet службы

Подключение к Центру Интернета вещей

Подключение с помощью политики общего доступа

Подключение с помощью Microsoft Entra

Настройка приложения Microsoft Entra

Проверка подлинности с помощью DefaultAzureCredential

Пример кода

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

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

Обзор

Отправка файла из приложения устройства

Подключение устройства к Центру Интернета вещей

Проверка подлинности с помощью сертификата X.509

Примеры кода

Проверка подлинности с помощью общего ключа доступа

Получение URI SAS из Центра Интернета вещей

Отправка файла в служба хранилища Azure

Отправка уведомления о состоянии отправки файлов в Центр Интернета вещей

Закройте клиент

Создание серверного приложения

Добавление инструкций импорта

Подключение к Центру Интернета вещей

Подключение с помощью политики общего доступа

Определение протокола подключения

Создание объекта ServiceClient

Открытие подключения между приложением и Центр Интернета вещей

Подключение с помощью Microsoft Entra

Настройка приложения Microsoft Entra

Проверка подлинности с помощью DefaultAzureCredential

Проверка подлинности с помощью ClientSecretCredentialBuilder

Другие классы проверки подлинности

Примеры кода

Проверка состояния отправки файлов

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

Установка пакетов

Отправка файла из приложения устройства

Импорт библиотек

Подключение устройства к Центру Интернета вещей

Проверка подлинности с помощью сертификата X.509

Примеры кода

Проверка подлинности с помощью общего ключа доступа

Получение сведений о хранилище BLOB-объектов

Отправка файла в хранилище BLOB-объектов

Уведомление Центра Интернета вещей о состоянии отправки

Завершение работы клиента устройства

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

Обзор

Создание приложения устройства

Установка пакетов SDK

Создание модулей

Подключение устройства к Центру Интернета вещей

Проверка подлинности с помощью сертификата X.509

Пример кода

Проверка подлинности с помощью общего ключа доступа

Выбор транспортного протокола

Создание клиентского объекта

Создание объекта протокола

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

Открытие подключения к Центр Интернета вещей

Получение маркера SAS из Центра Интернета вещей

Отправка файла в Центр Интернета вещей

Отправка локального файла в хранилище BLOB-объектов

Пример отправки файла ПАКЕТА SDK

Создание серверного приложения

Установка пакета ПАКЕТА SDK службы

Подключение к Центру Интернета вещей