Aracılığıyla paylaş

İşleri nasıl programlayabilir ve yayınlayabilirsiniz?

This article shows you how to create back-end app code to schedule and broadcast jobs.

Azure IoT Hub'u kullanarak, bu işlemler için milyonlarca cihazı güncelleyen işleri planlayın ve takip edin.

  • Doğrudan yöntemleri çağır
  • Güncellenmiş cihaz eşleri

A job wraps one of these actions and tracks the execution against a set of devices that is defined by a device twin query. Örneğin, bir arka uç uygulama, cihazları yeniden başlatan doğrudan bir yöntemi işletmek için bir görevi kullanabilir. Cihaz ikizi sorgusu ile cihaz setini belirler ve işi gelecekte çalıştırılmak üzere zamanlarsınız. İş, her bir cihazın yeniden başlatma doğrudan yöntemini alıp uyguladıkça ilerlemeyi izler.

To learn more about each of these capabilities, see:

Note

Bu makalede açıklanan özellikler yalnızca IoT Hub'un standart katmanında mevcuttur. Temel ve standart/ücretsiz IoT Hub katmanları hakkında daha fazla bilgi için bkz. çözüm için doğru IoT Hub katmanını ve boyutunu seçme.

Note

Bu makale, bu makale içerisinden referans verilen Azure IoT SDK'ları örneklerini tamamlamak amacıyla hazırlanmıştır. Cihaz ve arka uç uygulamaları oluşturmak için SDK araçlarını kullanabilirsiniz.

Prerequisites

  • Bir IoT merkezi

  • Kayıtlı bir cihaz

  • Uygulamanız MQTT protokolünü kullanıyorsa, güvenlik duvarınızda 8883 numaralı portun açık olduğundan emin olun. The MQTT protocol communicates over port 8883. Bu port bazı kurumsal ve eğitim ağ ortamlarında engellenebilir. Daha fazla bilgi ve bu sorunun etrafından dolaşmanın yolları için Connecting to IoT Hub (MQTT) bölümüne bakın.

  • Requires Visual Studio

Overview

Bu makale, bir veya daha fazla cihazda doğrudan bir yöntemi çağırmak ya da cihaz ikizi güncellemesi gerçekleştirmek için programlanabilir bir iş planlamak amacıyla arka uç hizmet uygulama kodunu oluşturmak üzere Azure IoT SDK for .NET'i nasıl kullanacağınızı anlatmaktadır.

Servis NuGet paketini ekle

Backend hizmet uygulamaları, Microsoft.Azure.Devices NuGet paketini gerektirir.

Kullanım ifadeleri

Aşağıdaki 'using' ifadelerini ekleyin.

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

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

IoT merkezi ile bağlantı kur

You can connect a backend service to IoT Hub using the following methods:

  • Paylaşılan erişim politikası
  • Microsoft Entra

Önemli

Bu makale, paylaşılan bir erişim imzası kullanarak bir hizmete bağlanmak için adımları içermektedir. Bu kimlik doğrulama yöntemi, test ve değerlendirme için uygun bir seçenektir, ancak bir hizmete Microsoft Entra ID veya yönetilen kimlikler ile kimlik doğrulaması daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik uygulamaları Bulut güvenliği.

Ortak erişim politikası kullanarak bağlanın

Connect a backend application to a device using CreateFromConnectionString.

Bu makale, doğrudan bir yöntemi çağırmak için bir işi zamanlayabilen, bir cihazın ikizini güncelleyebilmek için bir işi zamanlayabilen ve bir veya daha fazla cihaz için bir işin ilerlemesini izleyebilen arka uç kodunu açıklamaktadır. To perform these operations, your service needs the registry read and registry write permissions. By default, every IoT hub is created with a shared access policy named registryReadWrite that grants these permissions.

For more information about shared access policies, see Control access to IoT Hub with shared access signatures.

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

Microsoft Entra'yı kullanarak bağlanın

A backend app that uses Microsoft Entra must successfully authenticate and obtain a security token credential before connecting to IoT Hub. This token is passed to a IoT Hub connection method. IoT Hub için Microsoft Entra'nın kurulum ve kullanımı hakkında genel bilgi için Microsoft Entra ID kullanarak IoT Hub erişimini kontrol etme bölümüne bakın.

Configure Microsoft Entra app

Bir Microsoft Entra uygulaması kurmanız gerekmektedir ve bu uygulama tercih ettiğiniz kimlik doğrulama bilgilerine göre yapılandırılmış olmalıdır. The app contains parameters such as client secret that are used by the backend application to authenticate. Mevcut uygulama kimlik doğrulama yapılandırmaları şunlardır:

  • Client secret
  • Certificate
  • Birleşik kimlik bilgisi

Microsoft Entra uygulamaları, yürütülen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak için IoT Hub Twin Contributor gereklidir. Daha fazla bilgi için, Azure RBAC rol ataması kullanarak IoT Hub erişimini yönetme konusuna bakınız.

Daha fazla bilgi için bir Microsoft Entra uygulamasını yapılandırmaya ilişkin Hızlı Başlangıç: Microsoft kimlik platformu ile bir uygulama kaydetme bölümüne bakın.

Varsayılan Azure Kimlik Bilgileri kullanarak kimlik doğrulayın

Bir arka uç uygulamasını kimlik doğrulama için Microsoft Entra kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya kısıtlanmış bir ChainedTokenCredential dahil olmak üzere farklı bir yöntem kullanılması önerilir. Basitlik için, bu bölüm kimlik doğrulamayı DefaultAzureCredential ve İstemci sırrı kullanarak açıklar. Daha fazla bilgi için, DefaultAzureCredential kullanımının avantajları ve dezavantajları hakkında DefaultAzureCredential için kullanım rehberine bakın.

DefaultAzureCredential supports different authentication mechanisms and determines the appropriate credential type based on the environment it's executing in. It attempts to use multiple credential types in an order until it finds a working credential.

Microsoft Entra, bu NuGet paketlerine ve ilgili using ifadelerine ihtiyaç duyar.

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

In this example, Microsoft Entra app registration client secret, client ID, and tenant ID are added to environment variables. These environment variables are used by DefaultAzureCredential to authenticate the application. The result of a successful Microsoft Entra authentication is a security token credential that is passed to an IoT Hub connection method.

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();

Sonuçta elde edilen TokenCredential, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanma yöntemine aktarılabilir.

Bu örnekte, TokenCredential bir ServiceClient bağlantı nesnesi oluşturmak için ServiceClient.Create'ye iletilir.

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

Bu örnekte, bir RegistryManager nesnesi oluşturmak için TokenCredential, RegistryManager.Create'e aktarılır.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Kod örneği

Microsoft Entra servis kimlik doğrulamasının çalışan bir örneği için, Rol tabanlı kimlik doğrulama örneği'ne bakın.

Schedule a direct method job

ScheduleDeviceMethodAsync kullanarak bir veya birden fazla cihazda doğrudan bir yöntem çalıştırmak için bir iş planlayabilirsiniz.

CloudToDeviceMethod nesnesini kullanarak doğrudan yöntem adını ve cihaz bağlantı zaman aşımı değerlerini belirtin.

For example:

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

Bu örnek, "Device-1" adlı bir cihazda "LockDoor" adlı doğrudan bir yöntem için bir iş planlamaktadır. Planlanmış işe dahil edilen cihazlar, ikinci parametre olarak bir sorgu koşulu içerir. Sorgu koşulları hakkında daha fazla bilgi için cihaz ve modül ikizleri, işler ve mesaj yönlendirme için IoT Hub sorgu dili sayfasına bakın.

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);

Cihaz ikizi güncelleme işini zamanlayın

Use ScheduleTwinUpdateAsync to schedule a new device twin desired properties and tags update job to run on one or more devices.

Öncelikle, güncelleme için bir cihaz Twin nesnesi oluşturun ve doldurun. For example:

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;

Sonra, ScheduleTwinUpdateAsync'yi ara. Güncellenecek cihazları ikinci parametrede bir sorgu olarak belirtin. For more information about query conditions, see IoT Hub query language for device and module twins, jobs, and message routing.

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

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

Monitor a job

Belirli bir iş kimliği için iş durumunu izlemek amacıyla GetJobAsync kullanın.

Bu örnek, bir iş kimliği için iş durumunu periyodik olarak kontrol eder ve iş durumu tamamlandığında veya başarısız olduğunda durur. For example:

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 zamanlama işi örnekleri

Azure IoT SDK for .NET, iş zamanlama görevlerini yöneten hizmet uygulamalarının çalışma örneklerini sağlar. Daha fazla bilgi için bakınız:

  • Requires Java SE Development Kit 8. JDK 8 indirmelerine gitmek için Uzun vadeli destek altında Java 8'yi seçtiğinizden emin olun.

Overview

This article describes how to use the Azure IoT SDK for Java to create backend service application code to schedule job to invoke a direct method or perform a device twin update on one or more devices.

Service import statements

The JobClient class contains methods that services can use to schedule jobs.

Use the following service import statements to access the Azure IoT SDK for 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;

Connect to the IoT Hub

Aşağıdaki yöntemlerle IoT Hub'a bir arka hizmet bağlayabilirsiniz:

  • Paylaşımlı erişim politikası
  • Microsoft Entra

Önemli

Bu makale, paylaşılan erişim imzası kullanarak bir hizmete bağlanma adımlarını içermektedir. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak Microsoft Entra ID veya yönetilen kimliklerle bir hizmete kimlik doğrulamak daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik uygulamaları Bulut güvenliği.

Paylaşılan erişim politikası kullanarak bağlan.

Use a JobClient constructor to create the connection to IoT hub. The JobClient object handles the communication with your IoT hub.

This article describes back-end code that can schedule a job to invoke a direct method, schedule a job to update a device twin, and monitors the progress of a job for one or more devices. Bu işlemleri gerçekleştirmek için hizmetinizin kayıt okuma ve kayıt yazma izinlerine ihtiyacı vardır. Varsayılan olarak, her IoT merkezi, registryReadWrite adlı paylaşılan erişim politikasıyla oluşturulur ve bu izinleri verir.

Daha fazla bilgi için paylaşılmış erişim ilkeleri hakkında, Paylaşılan erişim imzalarıyla IoT Hub'a erişimi kontrol etme konusuna bakın.

For example:

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

Connect using Microsoft Entra

A backend app that uses Microsoft Entra must successfully authenticate and obtain a security token credential before connecting to IoT Hub. Bu belirteç, bir IoT Hub bağlantı yöntemine iletilir. IoT Hub için Microsoft Entra'yı kurma ve kullanma hakkında genel bilgi için, Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme bölümüne bakın.

Java SDK kimlik doğrulaması hakkında genel bir bakış için Java ve Azure Identity ile Azure kimlik doğrulaması'na bakın.

Basitlik için bu bölüm, istemci gizliliği kullanarak kimlik doğrulamayı tanımlamaya odaklanıyor.

Microsoft Entra uygulamasını yapılandır

You must set up a Microsoft Entra app that is configured for your preferred authentication credential. The app contains parameters such as client secret that are used by the backend application to authenticate. Mevcut uygulama kimlik doğrulama yapılandırmaları şunlardır:

  • İstemci sırrı
  • Sertifika
  • Federasyon kimlik bilgisi

Microsoft Entra apps may require specific role permissions depending on operations being performed. Örneğin, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimini etkinleştirmek için IoT Hub Twin Contributor gereklidir. Daha fazla bilgi için Azure RBAC rol atamasını kullanarak IoT Hub'a erişimi yönetme sayfasına bakın.

Microsoft Entra uygulamasını ayarlama hakkında daha fazla bilgi için bkz. Hızlı Başlangıç: Microsoft kimlik platformu ile bir uygulama kaydetme.

VarsayılanAzureKimliği kullanarak kimlik doğrula

Microsoft Entra'yı kullanarak bir arka uç uygulamasını kimlik doğrulamak için en kolay yol DefaultAzureCredential'i kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya sadeleştirilmiş bir ChainedTokenCredential dahil, farklı bir yöntem kullanılması önerilir. Azure Identity istemci kitaplığı için Java'da DefaultAzureCredential kullanmanın avantajları ve dezavantajları hakkında daha fazla bilgi için bkz. Azure Kimliği istemci kitaplığındaki kimlik bilgisi zincirleri.

DefaultAzureCredential, farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortama bağlı olarak uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi bulunana kadar birden fazla kimlik bilgisi türünü sırayla kullanmayı dener.

Microsoft Entra uygulama kimlik bilgilerini DefaultAzureCredentialBuilder kullanarak doğrulayabilirsiniz. Bağlantı parametrelerini, örneğin ortam değişkenleri olarak müşteri gizliliği kiracı kimliği (tenantID), müşteri kimliği (clientID) ve müşteri gizli değerlerini kaydedin. TokenCredential oluşturulduktan sonra, 'credentials' parametresi olarak ServiceClient veya başka bir oluşturucuya iletin.

Bu örnekte, DefaultAzureCredentialBuilderDefaultAzureCredential içinde açıklanan listeden bir bağlantıyı kimlik doğrulamaya çalışıyor. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, ServiceClient gibi bir yapılandırıcıya iletilen bir güvenlik belirteci kimlik bilgisi olur.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
ClientSecretCredentialBuilder kullanarak kimlik doğrulaması yapın

ClientSecretCredentialBuilder kullanarak bir kimlik bilgisi oluşturmak için istemci gizli anahtar bilgisini kullanabilirsiniz. Başarılı olursa, bu yöntem 'kimlik bilgisi' parametresi olarak ServiceClient veya başka bir yapıcıya aktarılabilen bir TokenCredential döndürür.

Bu örnekte, Microsoft Entra uygulama kaydı istemci sırrı, istemci kimliği ve kiracı kimliği değerleri, ortam değişkenlerine eklendi. Bu ortam değişkenleri, kimlik bilgilerini oluşturmak için ClientSecretCredentialBuilder tarafından kullanılır.

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();
Other authentication classes

The Java SDK also includes these classes that authenticate a backend app with Microsoft Entra:

Kod örnekleri

Microsoft Entra hizmeti kimlik doğrulama için çalışma örnekleri için Role based authentication sample'a bakın.

Schedule a direct method update job

Bir veya birden fazla cihazda doğrudan bir yöntem çalıştırmak için scheduleDeviceMethod kullanın.

Bu örnek yöntem, "Cihaz-1" adlı bir cihazda "kapı kilitleme" adlı doğrudan yöntem için bir iş zamanılandırır.

// 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());
}

Schedule a device twin update job

Use scheduleUpdateTwin to schedule a job to run a device twin update on one or multiple devices.

Öncelikle, cihaz ikiz güncellemesi için bir DeviceTwinDevice kaydı hazırlayın. For example:

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("*");

Ardından scheduleUpdateTwin öğesini arayın ve güncelleme işini planlayın. For example:

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());
}

Bir işi izleme

Use getJob to fetch job information based on a specific job ID. getJob, çalıştırma durumu da dahil olmak üzere iş bilgilerini kontrol etmek için kullanabileceğiniz yöntemler ve özellikler içeren bir JobResult nesnesi döndürür.

For example:

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

Query a job status

Bir veya daha fazla işin durumunu sorgulamak için queryDeviceJob'i kullanın.

For example:

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 zamanlama iş örneği

Azure IoT SDK for Java, iş zamanlama görevlerini yöneten bir hizmet uygulamasının çalışan bir örneğini sağlar. Daha fazla bilgi için İş İstemcisi Örneği'ne bakın.

  • Python SDK - Python sürümü 3.7 veya üstü önerilir. Yapılandırmanızın gerektirdiği şekilde 32-bit veya 64-bit kurulumunu kullandığınızdan emin olun. Kurulum sırasında sorulduğunda, Python'u platforma özel çevre değişkenine eklediğinizden emin olun.

Overview

This article describes how to use the Azure IoT SDK for Python to create backend service application code to schedule job to invoke a direct method or perform a device twin desired property update on one or more devices.

Paket yükle

The azure-iot-hub library must be installed to create backend service applications.

pip install azure-iot-hub

Import statements

The IoTHubJobManager class exposes all methods required to create a backend application to schedule jobs from the service.

Aşağıdaki import ifadelerini ekleyin.

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

IoT hub'a bağlan

Bir arka uç hizmetini IoT Hub'a bağlamak için aşağıdaki yöntemleri kullanabilirsiniz:

  • Paylaşımlı erişim politikası
  • Microsoft Entra

Önemli

Bu makale, paylaşılan erişim imzası kullanarak bir hizmete bağlanma adımlarını içermektedir. This authentication method is convenient for testing and evaluation, but authenticating to a service with Microsoft Entra ID or managed identities is a more secure approach. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik uygulamaları Bulut güvenliği.

Connect using a shared access policy

Connect to IoT hub using from_connection_string.

This article describes back-end code that can schedule a job to invoke a direct method, schedule a job to update a device twin, and monitors the progress of a job for one or more devices. To perform these operations, your service needs the registry read and registry write permissions. Varsayılan olarak, her IoT hub, bu izinleri sağlayan registryReadWrite adlı bir paylaşılan erişim politikasıyla oluşturulur.

Daha fazla bilgi için paylaşılan erişim politikaları hakkında, Paylaşılan erişim imzalarıyla IoT Hub'a erişimi kontrol et kısmına bakın.

For example:

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

Microsoft Entra kullanarak bağlanın.

A backend app that uses Microsoft Entra must successfully authenticate and obtain a security token credential before connecting to IoT Hub. This token is passed to a IoT Hub connection method. IoT Hub için Microsoft Entra'yı kurma ve kullanma hakkında genel bilgi için Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme bölümüne bakın.

Configure Microsoft Entra app

Tercih ettiğiniz kimlik doğrulama kimliği için yapılandırılmış bir Microsoft Entra uygulaması kurmalısınız. Uygulama, arka uç uygulamasının kimlik doğrulama yapmak için kullandığı istemci sırrı gibi parametreler içerir. Kullanılabilir uygulama kimlik doğrulama yapılandırmaları şunlardır:

  • İstemci sırrı
  • Sertifika
  • Birleşik kimlik bilgisi

Microsoft Entra uygulamaları, gerçekleştirilen işlemlere bağlı olarak belirli rol izinleri gerektirebilir. Örneğin, bir IoT Hub cihazı ve modül çiftlerine okuma ve yazma erişimi sağlamak için IoT Hub Twin Contributor gereklidir. Daha fazla bilgi için, Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme konusuna bakın.

Daha fazla bilgi için, Microsoft Entra uygulaması kurulumunu ayarlama konusunda Hızlı Başlangıç: Microsoft kimlik platformu ile bir uygulama kaydetme dokümanına bakın.

Authenticate using DefaultAzureCredential

The easiest way to use Microsoft Entra to authenticate a backend application is to use DefaultAzureCredential, but it's recommended to use a different method in a production environment including a specific TokenCredential or pared-down ChainedTokenCredential. Basitlik için, bu bölümde DefaultAzureCredential ve İstemci sırrı kullanılarak kimlik doğrulama açıklanmaktadır. Daha fazla bilgi için, DefaultAzureCredential kullanmanın avantajları ve dezavantajları hakkında DefaultAzureCredential Kullanım Kılavuzu'na bakın.

DefaultAzureCredential farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortama göre uygun kimlik türünü belirler. Çalışan bir kimlik bilgisi bulana kadar birden fazla kimlik bilgisi türünü sırayla kullanmaya çalışır.

Microsoft Entra, bu NuGet paketlerini ve ilgili using ifadelerini gerektirir:

  • Azure.Core
  • Azure.Identity
using Azure.Core;
using Azure.Identity;

In this example, Microsoft Entra app registration client secret, client ID, and tenant ID are added to environment variables. Bu çevre değişkenleri, uygulamayı kimlik doğrulamak için DefaultAzureCredential tarafından kullanılır. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, bir IoT Hub bağlantı yöntemine aktarılan bir güvenlik belirteci kimliğidir.

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();

Ortaya çıkan TokenCredential, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlama yöntemine geçirilebilir.

Bu örnekte, TokenCredentialServiceClient bağlantı nesnesi oluşturmak için ServiceClient.Create'ye aktarılır.

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

Bu örnekte, TokenCredentialRegistryManager.Create'e bir RegistryManager nesnesi oluşturmak için geçirilir.

string hostname = "xxxxxxxxxx.azure-devices.net";
registryManager = RegistryManager.Create(hostname, tokenCredential);
Kod örneği

Microsoft Entra hizmeti kimlik doğrulamasının çalışır durumdaki bir örneği için, Rol tabanlı kimlik doğrulama örneği kısmına bakın.

Doğrudan yöntem işi planla

Use create_scheduled_job to schedule a new direct method to run a direct method on one or multiple devices:

create_scheduled_job parametre notları:

  • job_id benzersiz olmalıdır
  • type şunu scheduleDeviceMethod olarak ayarla
  • Use cloud_to_device_method to set the direct method name and payload
  • Yürütme süresini saniye cinsinden belirtmek için max_execution_time_in_seconds kullanın.
  • query_condition kullanarak doğrudan yöntem çağrısına dahil edilecek cihazları belirtin. Sorgu koşulları hakkında daha fazla bilgi için cihaz ve modül ikizleri, işler ve mesaj yönlendirme için IoT Hub sorgu dili'ne bakın.

For example:

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)

Schedule a device twin update job

create_scheduled_job komutunu kullanarak bir veya birden fazla cihazda, cihaz ikizinin istenen özelliklerini güncellemek için yeni bir görev oluşturun.

create_scheduled_job parametre notları:

  • job_id benzersiz olmalı
  • type öğesini scheduleUpdateTwin olarak ayarla
  • update_twin kullanarak doğrudan yöntem adını ve yükü ayarlayın.
  • Kullanın max_execution_time_in_seconds çalışma süresini saniye olarak belirtmek için
  • Bir veya birden fazla cihaz için doğrudan yöntem çağrısına sahip bir koşul belirtmek üzere query_condition kullanın. Daha fazla bilgi için sorgu koşullarıyla ilgili olarak cihaz ve modül ikizleri, işler ve mesaj yönlendirme için IoT Hub sorgu dili sayfasına bakın.

For example:

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)

Bir işi izlemek

Belirli bir görevin ayrıntılarını bir IoT Hub üzerinde almak için get_scheduled_job'u kullanın.

This example checks the job status for a specific job ID every five seconds until the job is complete.

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 zamanlanmış iş örnekleri

Python için Azure IoT SDK, iş zamanlama görevlerini yöneten servis uygulamalarının çalışan örneklerini sağlar. For more information, see:

  • Node.js sürüm 10.0.x veya üstünü gerektirir.

Overview

Bu makale, Azure IoT SDK for Node.js kullanarak bir veya daha fazla cihazda doğrudan bir yöntemi çağırmak veya cihaz ikizi güncellemesi yapmak için iş planlaması yapabilen arka uç servis uygulama kodunun nasıl oluşturulacağını açıklar.

Install service SDK package

Geliştirme makinenize azure-iothub yüklemek için bu komutu çalıştırın:

npm install azure-iothub --save

JobClient sınıfı, arka uç uygulamasından iş zamanlamasıyla etkileşim kurmak için gereken tüm yöntemleri sunar.

Connect to IoT hub

You can connect a backend service to IoT Hub using the following methods:

  • Paylaşımlı erişim politikası
  • Microsoft Entra

Önemli

This article includes steps to connect to a service using a shared access signature. Bu kimlik doğrulama yöntemi test ve değerlendirme için uygundur, ancak Microsoft Entra ID veya yönetilen kimliklerle bir hizmete kimlik doğrulama daha güvenli bir yaklaşımdır. Daha fazla bilgi edinmek için bkz . IoT çözümleri > için en iyi güvenlik uygulamaları Bulut güvenliği.

Connect using a shared access policy

Use fromConnectionString to connect to IoT hub.

Bu makale, doğrudan bir yöntemi çağırmak için bir işi planlayabilen, bir cihaz ikizini güncellemek için bir işi planlayabilen ve bir veya daha fazla cihaz için bir işin ilerlemesini izleyen arka uç kodunu açıklar. Bu işlemleri gerçekleştirmek için, hizmetinizin kayıt defteri okuma ve kayıt defteri yazma izinlerine ihtiyacı vardır. Varsayılan olarak, her IoT hub, bu izinleri veren registryReadWrite adlı paylaşımlı bir erişim politikasıyla oluşturulur.

Daha fazla bilgi için paylaşılan erişim politikaları hakkında, IoT Hub'a paylaşılan erişim imzaları ile erişimi kontrol edin başlıklı bölüme bakın.

For example:

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

Connect using Microsoft Entra

Microsoft Entra kullanan bir arka uç uygulaması, IoT Hub'a bağlanmadan önce başarılı bir şekilde kimlik doğrulaması yapmalı ve bir güvenlik belirteci kimlik bilgisi edinmelidir. Bu belirteç, bir IoT Hub bağlantı yöntemine iletilir. IoT Hub için Microsoft Entra'yı kurma ve kullanma hakkında genel bilgi için, Microsoft Entra ID kullanarak IoT Hub'a erişimi kontrol etme başlıklı makaleye bakın.

Node.js SDK kimlik doğrulama hakkında genel bir bakış için bkz:

Microsoft Entra uygulamasını yapılandırın

Tercih ettiğiniz kimlik doğrulama kimlik bilgisi için yapılandırılmış bir Microsoft Entra uygulaması kurmalısınız. Uygulama, arka uç uygulamasının kimlik doğrulaması için kullandığı "client secret" gibi parametreler içerir. Uygulama kimlik doğrulama yapılandırmaları şunlardır:

  • Client secret
  • Sertifika
  • Birleşik kimlik kimliği bilgisi

Microsoft Entra uygulamaları, gerçekleştirilen işlemler doğrultusunda belirli rol izinlerine ihtiyaç duyabilir. Örneğin, IoT Hub Twin Contributor, bir IoT Hub cihazı ve modül ikizlerine okuma ve yazma erişimi sağlamak için gereklidir. Daha fazla bilgi için Azure RBAC rol atamasını kullanarak IoT Hub erişimini yönetme konusuna bakın.

Daha fazla bilgi için, Microsoft Entra uygulaması kurulumuyla ilgili olarak Hızlı Başlangıç: Microsoft kimlik platformuyla bir uygulama kaydetme bölümüne bakın.

DefaultAzureCredential kullanarak kimlik doğrula

Bir arka uç uygulamasını kimlik doğrulamak için Microsoft Entra'yı kullanmanın en kolay yolu DefaultAzureCredential kullanmaktır, ancak üretim ortamında belirli bir TokenCredential veya daha sadeleştirilmiş bir ChainedTokenCredential içeren farklı bir yöntem kullanılması önerilir. Basitlik için, bu bölüm DefaultAzureCredential ve Müşteri sırrı kullanarak kimlik doğrulamayı açıklar. Daha fazla bilgi için, DefaultAzureCredential kullanımının avantajları ve dezavantajları hakkında, Azure Identity istemci kitaplığı JavaScript için Kimlik Bilgisi zincirleri bölümüne bakın.

DefaultAzureCredential, farklı kimlik doğrulama mekanizmalarını destekler ve çalıştığı ortama bağlı olarak uygun kimlik bilgisi türünü belirler. Çalışan bir kimlik bilgisi buluncaya kadar, farklı türde kimlik bilgilerini sırayla kullanmayı dener.

Microsoft Entra bu paketi gerektirir:

npm install --save @azure/identity

Örnekte, Microsoft Entra uygulama kaydı için istemci sırrı, istemci kimliği ve kiracı kimliği ortam değişkenlerine eklenmiştir. Bu çevre değişkenleri, uygulamayı kimlik doğrulamak için DefaultAzureCredential tarafından kullanılır. Başarılı bir Microsoft Entra kimlik doğrulamasının sonucu, bir IoT Hub bağlantı yöntemine aktarılan bir güvenlik belirteci kimlik bilgisidir.

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

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

Ortaya çıkan kimlik doğrulama belirteci, Microsoft Entra kimlik bilgilerini kabul eden herhangi bir SDK istemcisi için IoT Hub'a bağlanmak üzere fromTokenCredential'e aktarılabilir.

fromTokenCredential requires two parameters:

  • The Azure service URL - The Azure service URL should be in the format {Your Entra domain URL}.azure-devices.net without a https:// prefix. Örneğin, MyAzureDomain.azure-devices.net.
  • Azure kimlik doğrulama belirteci

In this example, the Azure credential is obtained using DefaultAzureCredential. The Azure domain URL and credential are then supplied to Registry.fromTokenCredential to create the connection to IoT Hub.

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);
Code samples

For working samples of Microsoft Entra service authentication, see Azure identity examples.

Doğrudan yöntem işi oluştur

scheduleDeviceMethod kullanarak bir veya birden fazla cihazda doğrudan bir yöntemi çalıştırmak için bir iş zamanlayın.

İlk olarak, metod adı, yük ve yanıt zaman aşımı bilgileri ile bir doğrudan metod güncelleme değişkeni oluşturun. For example:

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

Ardından scheduleDeviceMethod çağırarak doğrudan yöntem çağrısı görevi zamanlayın:

  • Her işin benzersiz bir iş kimliği olmalıdır. You can use this job ID to monitor a job as described in the Monitor a job section of this article.
  • İşin hangi cihazlarda çalıştırılacağını değerlendirmek için bir queryCondition parametresi belirleyin. For more information about query conditions, see IoT Hub query language for device and module twins, jobs, and message routing.
  • Check the jobResult callback for the job schedule result. If the job was successfully scheduled, you can monitor the job status as shown in the Monitor a job section of this article.

For example:

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));
            }
        });
    }
});

Schedule a device twin update job

Use scheduleTwinUpdate to create a new job to run a device twin update on one or multiple devices.

Öncelikle, bir cihaz çiftinin istenen özellik güncellemesi değişkeni oluşturun.

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

Ardından, aygıt ikizinin istenen özellik güncelleme görevini planlamak için scheduleTwinUpdate çağrısı yapın.

  • Her işin benzersiz bir iş kimliği olmalıdır. Bu makalenin Bir işi İzleme bölümünde açıklandığı gibi, bir işi izlemek için bu iş kimliğini kullanabilirsiniz.
  • Bir görevin hangi cihazlarda çalıştırılacağını değerlendirmek için bir queryCondition parametresi belirtin. Daha fazla bilgi için, cihaz ve modül ikizleri, işler ve mesaj yönlendirme için IoT Hub sorgu dili başlığına bakın.
  • İş programı sonucunu öğrenmek için jobResult geri çağırmayı kontrol edin. If the job was successfully scheduled, you can monitor the job status as shown in the Monitor a job section of this article.

For example:

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));
            }
        });
    }
});

Monitor a job

Belirli bir iş kimliği için iş durumunu izlemek amacıyla getJob kullanın.

Bu örnek işlev, belirli bir iş kimliği için iş durumunu, iş tamamlanana veya başarısız olana kadar belirli aralıklarla kontrol eder.

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 zamanlanmış iş örneği

Node.js için Azure IoT SDK’si, iş planlama görevlerini yöneten bir hizmet uygulamasının çalışan bir örneğini sunar. Daha fazla bilgi için Job client E2E test bakın.

  • Last updated on