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

Как планировать и распространять задания

В этой статье показано, как создать код внутреннего приложения для планирования и трансляции заданий.

Используйте Центр Интернета вещей Azure для планирования и отслеживания заданий, обновляющих до миллионов устройств для этих операций:

  • Вызов прямых методов
  • Обновленные цифровые двойники устройств

Задание объединяет одно из этих действий и отслеживает его выполнение в отношении набора устройств, определенного запросом двойника устройства. Например, бекенд-приложение может использовать задание для вызова прямого метода перезагрузки на 10 000 устройствах. Вы можете определить набор устройств с помощью запроса на двойнике устройства и запланировать момент времени в будущем для выполнения задания. Задание отслеживает ход процесса по мере того, как каждое устройство получает и выполняет непосредственный метод перезагрузки.

Дополнительные сведения об этих возможностях см. в указанных ниже статьях.

Примечание.

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

Примечание.

Эта статья предназначена для дополнения примеров пакетов SDK Для Интернета вещей Azure, на которые ссылается эта статья. Средства SDK можно использовать для создания приложений устройств и внутренних приложений.

Предварительные условия

  • Центр Интернета вещей.

  • Зарегистрированное устройство

  • Если приложение использует протокол MQTT, убедитесь, что порт 8883 открыт в брандмауэре. Протокол MQTT взаимодействует через порт 8883. В некоторых корпоративных и академических сетях этот порт может быть заблокирован. Дополнительные сведения и способы устранения этой проблемы см. в разделе о подключении к Центру Интернета вещей по протоколу MQTT.

  • Требуется Visual Studio

Обзор

В этой статье описывается, как использовать Azure IoT SDK для .NET для создания кода приложения серверной части для планирования задания по вызову прямого метода или обновления двойника устройства на одном или более устройствах.

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

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

Инструкции using

Добавьте следующие директивы using.

using Microsoft.Azure.Devices;
using Microsoft.Azure.Devices.Shared;

using System.Threading;
using System.Threading.Tasks;

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

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

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

Внимание

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

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

Подключите серверное приложение к устройству с помощью CreateFromConnectionString.

В этой статье описывается внутренний код, который может запланировать задание для вызова прямого метода, запланировать задание для обновления двойника устройства и отслеживать ход выполнения задания для одного или нескольких устройств. Для выполнения этих операций службе требуются разрешения registry read и registry write. По умолчанию каждый Центр Интернета вещей создается с помощью политики общего доступа, называемой registryReadWrite, которая предоставляет это разрешение.

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

static JobClient jobClient;
static string connectionString = "{Shared access policy connection string}";
jobClient = JobClient.CreateFromConnectionString(connString);

Подключение с помощью 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 — это учетные данные в виде маркера безопасности, передаваемые методу подключения IoT-хаба.

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 см. пример проверки подлинности на основе ролей.

Планирование задания прямого метода

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

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

Например:

// The CloudToDeviceMethod record specifies the direct method name and device connection time-out
CloudToDeviceMethod directMethod = 
new CloudToDeviceMethod("LockDoor", TimeSpan.FromSeconds(5), 
TimeSpan.FromSeconds(5));

В этом примере задание планируется для прямого метода с именем LockDoor на одном устройстве с именем Device-1. Устройства, включенные в запланированное задание, содержат второй параметр в качестве условия запроса. Дополнительные сведения об условиях запроса см. в Центр Интернета вещей языке запросов для двойников устройств и модулей, заданий и маршрутизации сообщений.

string methodJobId = Guid.NewGuid().ToString();  // a unique job ID
static string deviceId = "Device-1";             // In this example, there is only one device affected
JobResponse result = await jobClient.ScheduleDeviceMethodAsync(methodJobId,
   $"DeviceId IN ['{deviceId}']",
   directMethod,
   DateTime.UtcNow,
   (long)TimeSpan.FromMinutes(2).TotalSeconds);

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

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

Сначала создайте и заполните объект Twin устройства для обновления. Например:

static string deviceId = "Device-1";

Twin twin = new Twin(deviceId);
twin.Tags = new TwinCollection();
twin.Tags["Building"] = "43";
twin.Tags["Floor"] = "3";
twin.ETag = "*";
twin.Properties.Desired["LocationUpdate"] = DateTime.UtcNow;

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

string twinJobId = Guid.NewGuid().ToString();

JobResponse createJobResponse = jobClient.ScheduleTwinUpdateAsync(
   twinJobId,
   $"DeviceId IN ['{deviceId}']", 
   twin, 
   DateTime.UtcNow, 
   (long)TimeSpan.FromMinutes(2).TotalSeconds).Result;

мониторинг задания.

Используйте GetJobAsync для отслеживания состояния задания для определенного идентификатора задания.

В этом примере состояние задания проверяется по идентификатору периодически до тех пор, пока задание не будет завершено или не произойдет сбой. Например:

JobResponse result;
do
{
   result = await jobClient.GetJobAsync(jobId);
   Console.WriteLine("Job Status : " + result.Status.ToString());
   Thread.Sleep(2000);
} while ((result.Status != JobStatus.Completed) && (result.Status != JobStatus.Failed));

Примеры задач планировщика для SDK

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

  • Требуется пакет разработки Java SE 8. Убедитесь, что вы выбрали Java 8 в разделе долгосрочной поддержки , чтобы перейти к скачиванию для JDK 8.

Обзор

В этой статье описывается, как использовать Azure IoT SDK для Java для создания кода серверного приложения для планирования задания с целью вызова прямого метода или обновления двойника устройства одного или нескольких устройств.

Инструкции импорта служб

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

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

import com.microsoft.azure.sdk.iot.service.devicetwin.DeviceTwinDevice;
import com.microsoft.azure.sdk.iot.service.devicetwin.Pair;
import com.microsoft.azure.sdk.iot.service.devicetwin.Query;
import com.microsoft.azure.sdk.iot.service.devicetwin.SqlQuery;
import com.microsoft.azure.sdk.iot.service.jobs.JobClient;
import com.microsoft.azure.sdk.iot.service.jobs.JobResult;
import com.microsoft.azure.sdk.iot.service.jobs.JobStatus;

import java.util.Date;
import java.time.Instant;
import java.util.HashSet;
import java.util.Set;
import java.util.UUID;

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

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

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

Внимание

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

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

Используйте конструктор JobClient для создания подключения к Центру Интернета вещей. Объект JobClient обрабатывает обмен данными с центром Интернета вещей.

В этой статье описывается внутренний код, который может запланировать задание для вызова прямого метода, запланировать задание для обновления двойника устройства и отслеживать ход выполнения задания для одного или нескольких устройств. Для выполнения этих операций службе требуются разрешения registry read и registry write. По умолчанию каждый Центр Интернета вещей создается с помощью политики общего доступа, называемой registryReadWrite, которая предоставляет это разрешение.

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

Например:

public static final String iotHubConnectionString = "{Shared access policy connection string}";
JobClient jobClient = new JobClient(iotHubConnectionString);

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

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

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

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

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

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

  • Секрет клиента
  • Сертификат
  • Идентификационные данные федеративного удостоверения

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

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

Проверка подлинности с помощью 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 можно создать учетные данные с помощью сведений о секрете клиента. В случае успеха этот метод возвращает TokenCredential, который можно передать в 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 см . в примере проверки подлинности на основе ролей.

Планирование задания обновления прямого метода

Используйте scheduleDeviceMethod для запуска прямого метода на одном или нескольких устройствах.

В этом примере метод планирует выполнение прямого метода с именем "lockDoor" на устройстве под названием "Device-1".

// Schedule a job now to call the lockDoor direct method
// against a single device. Response and connection
// timeouts are set to 5 seconds.
String deviceId = "Device-1";
String jobId = "DMCMD" + UUID.randomUUID();  //Job ID must be unique

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleDeviceMethod(jobId,
    "deviceId='" + deviceId + "'",
    "lockDoor",
    5L, 5L, null,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling direct method job: " + jobId);
  System.out.println(e.getMessage());
}

Планирование задания обновления цифрового двойника устройства

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

Сначала подготовьте запись DeviceTwinDevice для обновления цифрового двойника устройства. Например:

String deviceId = "Device-1";

//Create a device twin desired properties update object
DeviceTwinDevice twin = new DeviceTwinDevice(deviceId);
Set<Pair> desiredProperties = new HashSet<Pair>();
desiredProperties.add(new Pair("Building", 43));
desiredProperties.add(new Pair("Floor", 3));
twin.setDesiredProperties(desiredProperties);
// Optimistic concurrency control
twin.setETag("*");

Затем вызовите scheduleUpdateTwin, чтобы запланировать обновление. Например:

String jobId = "DPCMD" + UUID.randomUUID();  //Unique job ID

// How long the job is permitted to run without
// completing its work on the set of devices
private static final long maxExecutionTimeInSeconds = 30;

// Schedule the update twin job to run now for a single device
System.out.println("Schedule job " + jobId + " for device " + deviceId);
try {
  JobResult jobResult = jobClient.scheduleUpdateTwin(jobId, 
    "deviceId='" + deviceId + "'",
    twin,
    new Date(),
    maxExecutionTimeInSeconds);
} catch (Exception e) {
  System.out.println("Exception scheduling desired properties job: " + jobId);
  System.out.println(e.getMessage());
}

Следите за заданием.

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

Например:

try {
  JobResult jobResult = jobClient.getJob(jobId);
  if(jobResult == null)
  {
    System.out.println("No JobResult for: " + jobId);
    return;
  }
  // Check the job result until it's completed
  while(jobResult.getJobStatus() != JobStatus.completed)
  {
    Thread.sleep(100);
    jobResult = jobClient.getJob(jobId);
    System.out.println("Status " + jobResult.getJobStatus() + " for job " + jobId);
  }
  System.out.println("Final status " + jobResult.getJobStatus() + " for job " + jobId);
} catch (Exception e) {
  System.out.println("Exception monitoring job: " + jobId);
  System.out.println(e.getMessage());
  return;
}

Запрос состояния задания

Используйте queryDeviceJob для запроса состояния задания для одного или нескольких заданий.

Например:

private static void queryDeviceJobs(JobClient jobClient, String start) throws Exception {
  System.out.println("\nQuery device jobs since " + start);

  // Create a jobs query using the time the jobs started
  Query deviceJobQuery = jobClient
      .queryDeviceJob(SqlQuery.createSqlQuery("*", SqlQuery.FromType.JOBS, "devices.jobs.startTimeUtc > '" + start + "'", null).getQuery());

  // Iterate over the list of jobs and print the details
  while (jobClient.hasNextJob(deviceJobQuery)) {
    System.out.println(jobClient.getNextJob(deviceJobQuery));
  }
}

Пример задания расписания пакета SDK

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

  • Рекомендуется использовать пакет SDK для Python версии 3.7 или более поздней версии. Обязательно используйте 32-разрядную или 64-разрядную версию установки согласно требованиям программы настройки. При появлении запроса во время установки обязательно добавьте Python в переменную среды соответствующей платформы.

Обзор

В этой статье описывается, как использовать Azure IoT SDK для Python для создания серверного приложения, чтобы планировать задания по вызову прямого метода или обновлению желаемого свойства близнеца устройства на одном или нескольких устройствах.

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

Для создания внутренних приложений службы необходимо установить библиотеку Azure-iot-hub.

pip install azure-iot-hub

Инструкции импорта

Класс IoTHubJobManager предоставляет все методы, необходимые для создания серверного приложения для планирования заданий из службы.

Добавьте следующие операторы import.

import os
import sys
import datetime
import time
import threading
import uuid
import msrest

from azure.iot.hub import IoTHubJobManager
from azure.iot.hub.models import JobProperties, JobRequest, Twin, TwinProperties, CloudToDeviceMethod

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

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

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

Внимание

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

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

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

В этой статье описывается внутренний код, который может запланировать задание для вызова прямого метода, запланировать задание для обновления двойника устройства и отслеживать ход выполнения задания для одного или нескольких устройств. Для выполнения этих операций службе требуются разрешения registry read и registry write. По умолчанию каждый Центр Интернета вещей создается с помощью политики общего доступа, называемой registryReadWrite, которая предоставляет это разрешение.

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

Например:

IoTHubConnectionString = "{Shared access policy connection string}"
iothub_job_manager = IoTHubJobManager.from_connection_string(IoTHubConnectionString)

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

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

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

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

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

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

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

Проверка подлинности с помощью 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 являются учетные данные маркера безопасности, которые передаются в метод подключения IoT Hub.

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 см. в примере проверки подлинности на основе ролей.

Запланировать работу методом прямого доступа

Используйте create_scheduled_job чтобы запланировать новый прямой метод для его выполнения на одном или нескольких устройствах.

create_scheduled_job примечания к параметру:

Например:

METHOD_NAME = "lockDoor"
METHOD_PAYLOAD = "{\"lockTime\":\"10m\"}"
job_id = uuid.uuid4()
DEVICE_ID = "Device-1"
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleDeviceMethod"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.cloud_to_device_method = CloudToDeviceMethod(method_name=METHOD_NAME, payload=METHOD_PAYLOAD)
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

Планирование задания обновления цифрового двойника устройства

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

create_scheduled_job примечания к параметру:

Например:

UPDATE_PATCH = {"building":43,"floor":3}
job_id = uuid.uuid4()
TIMEOUT = 60

job_request = JobRequest()
job_request.job_id = job_id
job_request.type = "scheduleUpdateTwin"
job_request.start_time = datetime.datetime.utcnow().isoformat()
job_request.update_twin = Twin(etag="*", properties=TwinProperties(desired=UPDATE_PATCH))
job_request.max_execution_time_in_seconds = TIMEOUT
job_request.query_condition = "DeviceId in ['{}']".format(device_id)

new_job_response = iothub_job_manager.create_scheduled_job(job_id, job_request)

контролировать задание.

Используйте get_scheduled_job для получения сведений о конкретном задании в узле IoT.

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

while True:
    get_job_response = iothub_job_manager.get_scheduled_job(job_request.job_id)
    print_job_response("Get job response: ", get_job_response)
    if get_job_response.status == "completed":
      print ( "Job is completed." )
    time.sleep(5)

Примеры заданий планировщика SDK

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

  • Требуется Node.js версии 10.0.x или более поздней

Обзор

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

Установка пакета SDK службы

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

npm install azure-iothub --save

Класс JobClient предоставляет все методы, необходимые для взаимодействия с планированием заданий из серверного приложения.

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

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

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

Внимание

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

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

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

В этой статье описывается внутренний код, который может запланировать задание для вызова прямого метода, запланировать задание для обновления двойника устройства и отслеживать ход выполнения задания для одного или нескольких устройств. Для выполнения этих операций службе требуются разрешения registry read и registry write. По умолчанию каждый Центр Интернета вещей создается с помощью политики общего доступа, называемой registryReadWrite, которая предоставляет это разрешение.

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

Например:

'use strict';
var JobClient = require('azure-iothub').JobClient;
var connectionString = '{Shared access policy connection string}';
var jobClient = JobClient.fromConnectionString(connectionString);

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

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

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

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

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

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

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

Для получения дополнительной информации о настройке приложения Microsoft Entra см. Краткое руководство: Регистрация приложения на платформе удостоверений Microsoft.

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

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

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

Для 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();

Затем полученный маркер учетных данных можно передать fromTokenCredential для подключения к Центру Интернета вещей для любого клиента 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.

Создайте задание для прямого метода

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

Сначала создайте переменную для прямого обновления метода, включающую имя метода, полезную нагрузку и время ожидания ответа. Например:

var methodParams = {
    methodName: 'lockDoor',
    payload: null,
    responseTimeoutInSeconds: 15 // Time-out after 15 seconds if device is unable to process method
};

Затем вызовите scheduleDeviceMethod, чтобы запланировать задание вызова прямого метода.

  • Каждое задание должно иметь уникальный идентификатор задания. Этот идентификатор задания можно использовать для мониторинга задания, как описано в разделе "Мониторинг задания " этой статьи.
  • queryCondition Укажите параметр для оценки устройств, в которых выполняется задание. Дополнительные сведения об условиях запроса см. в разделе язык запросов IoT Hub для двойников устройств и модулей, заданий и маршрутизации сообщений.
  • Проверьте обратный jobResult вызов для результата расписания задания. Если задание было успешно запланировано, можно отслеживать состояние задания, как показано в разделе "Мониторинг задания " этой статьи.

Например:

var methodJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

jobClient.scheduleDeviceMethod(methodJobId,
                            queryCondition,
                            methodParams,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule direct method job: ' + err.message);
    } else {
        monitorJob(methodJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor direct method job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

Назначьте задание по обновлению двойника устройства

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

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

var twinPatch = {
   etag: '*',
   properties: {
       desired: {
           building: '43',
           floor: 3
       }
   }
};

Затем запланируйте задание обновления требуемого свойства двойника устройства, вызвав scheduleTwinUpdate:

  • Каждое задание должно иметь уникальный идентификатор задания. Этот идентификатор задания можно использовать для мониторинга задания, как описано в разделе "Мониторинг задания " этой статьи.
  • queryCondition Укажите параметр для оценки устройств, в которых выполняется задание. Для получения дополнительной информации об условиях запросов см. язык запросов IoT Hub для двойников устройств и модулей, заданий и маршрутизации сообщений.
  • Проверьте обратный jobResult вызов для получения результата выполнения расписания. Если задание было успешно запланировано, можно отслеживать состояние задания, как показано в разделе "Мониторинг задания " этой статьи.

Например:

var twinJobId = uuid.v4();
var queryCondition = "deviceId IN ['myDeviceId']";
var startTime = new Date();
var maxExecutionTimeInSeconds =  300;

console.log('scheduling Twin Update job with id: ' + twinJobId);
jobClient.scheduleTwinUpdate(twinJobId,
                            queryCondition,
                            twinPatch,
                            startTime,
                            maxExecutionTimeInSeconds,
                            function(err) {
    if (err) {
        console.error('Could not schedule twin update job: ' + err.message);
    } else {
        monitorJob(twinJobId, function(err, result) {
            if (err) {
                console.error('Could not monitor twin update job: ' + err.message);
            } else {
                console.log(JSON.stringify(result, null, 2));
            }
        });
    }
});

контроль выполнения задачи.

Используйте getJob для отслеживания состояния задания для определенного идентификатора задания.

В этом примере функция проверяет состояние задания для определенного идентификатора задания периодически до завершения или сбоя задания.

function monitorJob (jobId, callback) {
    var jobMonitorInterval = setInterval(function() {
        jobClient.getJob(jobId, function(err, result) {
        if (err) {
            console.error('Could not get job status: ' + err.message);
        } else {
            console.log('Job: ' + jobId + ' - status: ' + result.status);
            if (result.status === 'completed' || result.status === 'failed' || result.status === 'cancelled') {
            clearInterval(jobMonitorInterval);
            callback(null, result);
            }
        }
        });
    }, 5000);
}

Пример запланированной задачи в SDK

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