如何排程和發布任務

本文說明如何建立後端應用程式程式代碼來排程和廣播作業。

使用 Azure IoT 中樞來排程並追蹤作業，以更新多達數百萬部裝置進行下列操作：

• 叫用直接方法
• 更新的裝置對應項

作業會包裝上述其中一個動作，然後針對由裝置對應項查詢所定義的一組裝置，追蹤執行進度。 例如，後端應用程式可以使用任務來在 10,000 部裝置上執行直接方法，以重新啟動裝置。 您以裝置對應項查詢指定一組裝置，並排程在未來的時間執行作業。 當每個裝置接收並執行重新啟動直接方法時，作業會監視進度。

若要一一了解這些功能，請參閱：

• 裝置對應項和屬性：開始使用裝置對應項和了解並使用 IoT 中樞中的裝置對應項屬性
• 直接方法：IoT 中樞開發人員指南 - 直接方法 (部分內容可能是機器或 AI 翻譯)

注意

本文中所述的功能僅適用於 IoT 中樞的標準層。 如需有關基本和標準/免費 IoT 中樞服務層級的詳細資訊，請參閱為您的解決方案選擇合適的 IoT 中樞層和大小 (英文)。

附註

本文旨在補充本文中參考的 Azure IoT SDK 範例。 您可以使用 SDK 工具來建置裝置應用程式和後端應用程式。

必要條件

• IoT 中樞

• 已註冊的裝置

• 如果您的應用程式使用 MQTT 通訊協定，請確定防火牆中已開啟連接埠 8883。 MQTT 通訊協定會透過連接埠 8883 進行通訊。 某些公司和教育網路環境可能會封鎖此連接埠。 如需此問題的詳細資訊和解決方法，請參閱連線至 IoT 中樞 (MQTT)。

• 需要 Visual Studio

概觀

本文說明如何使用適用於 .NET 的 Azure IoT SDK，將後端服務應用程式程式代碼建立至排程作業，以叫用直接方法，或在一或多個裝置上執行裝置對應項更新。

新增服務 NuGet 套件

後端服務應用程式需要 Microsoft.Azure.Devices NuGet 套件。

使用陳述式

新增下列 using 陳述式。

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

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

連線至 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

• 共用存取原則
• Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。 此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。 若要深入瞭解，請參閱 IoT解決方案 > 雲端安全性的安全性最佳做法。

使用共用存取原則進行連線

使用 CreateFromConnectionString 將後端應用程式連線到裝置。

本文介紹後端程式碼如何安排作業以呼叫直接函式、安排作業更新設備雙胞，並監控一個或多個設備的作業進度。 若要執行這些作業，則服務需要有登錄讀取和登錄寫入權限。 根據預設，每個 IoT 中樞都是使用授與這些權限且名為 registryReadWrite 的共用存取原則所建立。

如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

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

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。 此權杖會傳遞至 IoT 中樞連線方法。 如需設定和使用 IoT 中樞 Microsoft Entra 的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞 的存取。

設定 Microsoft Entra 應用程式

您必須設定與您偏好驗證憑證一致的 Microsoft Entra 應用程式。 應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。 可用的應用程式驗證群組態如下：

• 用戶端密碼
• 證書
• 聯邦身分識別憑證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。 例如，需要 IoT 中樞 對應項參與者，才能對 IoT 中樞 裝置和模組對應項啟用讀取和寫入存取權。 如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞 的存取權。

如需設定 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 中樞連線方法的安全性權杖認證。

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 可以傳遞至 IoT 中樞方法的連線，以取得任何接受 Microsoft Entra 認證的 SDK 用戶端：

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

在此範例中， 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));

此範例在名為 "Device-1" 的裝置上為名為 "LockDoor" 的直接方法排程一項作業。 排程作業中包含的裝置包含第二個參數作為查詢條件。 如需查詢條件的詳細資訊，請參閱 IoT 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。

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。 在第二個參數中指定要以查詢方式更新的裝置。 如需查詢條件的詳細資訊，請參閱 IoT 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。

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 排程作業範例

適用於 .NET 的 Azure IoT SDK 提供處理作業排程工作之服務應用程式的工作範例。 如需詳細資訊，請參閱

• 排程對應項更新範例
• E2E 排程對應項更新範例。

• 需要 Java SE 開發工具套件 8。 請務必選取 [長期支援] 下的 [Java 8]，以瀏覽至 JDK 8 的下載。

概觀

本文說明如何使用適用於 Java 的 Azure IoT SDK 來建立後端服務應用程式程式代碼，以排程作業以叫用直接方法，或在一或多個裝置上執行裝置對應項更新。

服務匯入陳述式

JobClient 類別包含服務可用來排程作業的方法。

使用下列服務匯入語句來存取 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;

連線至 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

• 共用存取原則
• Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。 此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。 若要深入瞭解，請參閱 IoT解決方案 > 雲端安全性的安全性最佳做法。

使用共用存取原則進行連線

使用 JobClient 建構函式來建立與 IoT 中樞的連線。 JobClient 物件會處理與 IoT 中樞的通訊。

本文說明一段後端程式碼，可排程作業來呼叫直接方法、排程作業來更新裝置孿生，並監控一或多個裝置的作業進度。 若要執行這些作業，則服務需要有登錄讀取和登錄寫入權限。 根據預設，每個 IoT 中樞都是使用授與這些權限且名為 registryReadWrite 的共用存取原則所建立。

如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

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

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。 此權杖會傳遞至 IoT 中樞連線方法。 如需設定和使用 IoT 中樞 Microsoft Entra 的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞 的存取。

如需 Java SDK 驗證的概觀，請參閱 使用 Java 和 Azure 身分識別進行 Azure 驗證。

為了簡單起見，本節著重於使用用戶端密碼描述驗證。

設定 Microsoft Entra 應用程式

您必須設定一個 Microsoft Entra 應用程式，並按照您慣用的驗證認證進行配置。 應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。 可用的應用程式驗證群組態如下：

• 用戶端密碼
• 證書
• 同盟身分識別認證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。 例如，需要 IoT 中樞 對應項參與者，才能對 IoT 中樞 裝置和模組對應項啟用讀取和寫入存取權。 如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞 的存取權。

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：向 Microsoft 身分識別平台 註冊應用程式。

使用 DefaultAzureCredential 進行驗證

使用 Microsoft Entra 來驗證後端應用程式最簡單的方式是使用 DefaultAzureCredential，但在生產環境中建議使用不同的方法，包括特定的TokenCredential或簡化的ChainedTokenCredential。 如需使用 DefaultAzureCredential之優缺點的詳細資訊，請參閱 適用於 Java 的 Azure 身分識別用戶端連結庫中的認證鏈結。

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。 它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

您可以使用 DefaultAzureCredentialBuilder 來驗證Microsoft Entra 應用程式認證。 將用戶端秘密 tenantID、clientID 和用戶端秘密值等聯機參數儲存為環境變數。 建立 TokenCredential 之後，以 'credential' 參數的形式將它傳遞至 ServiceClient 或其他建立器。

在此範例中，DefaultAzureCredentialBuilder 嘗試從 DefaultAzureCredential 中描述的清單進行連線驗證。 成功的 Microsoft Entra 驗證結果為安全性令牌認證，該認證會傳遞至像是 ServiceClient 等建構函式。

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

使用 ClientSecretCredentialBuilder 進行驗證

您可以使用 ClientSecretCredentialBuilder ，使用用戶端秘密資訊建立認證。 如果成功，此方法會傳回一個 TokenCredential，可以作為 'credential' 參數傳遞至 ServiceClient 或其他產生器。

在此範例中，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();

其他驗證類別

Java SDK 也包含這些類別，這些類別會使用 Microsoft Entra 來驗證後端應用程式：

• AuthorizationCodeCredential
• AzureCliCredential
• AzureDeveloperCliCredential
• AzurePipelinesCredential
• ChainedTokenCredential
• ClientAssertionCredential
• ClientCertificateCredential (英文)
• DeviceCodeCredential
• EnvironmentCredential
• InteractiveBrowserCredential
• ManagedIdentityCredential
• OnBehalfOfCredential

程式碼範例

如需Microsoft Entra 服務驗證的工作範例，請參閱 角色型驗證範例。

排程直接方法更新作業

使用 scheduleDeviceMethod 在一或多個裝置上執行直接方法。

此範例方法在名為 "Device-1" 的裝置上為名為 "lockDoor" 的直接方法排程一項作業。

// 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 排程作業範例

適用於 Java 的 Azure IoT SDK 提供可處理作業排程工作的服務應用程式工作範例。 如需詳細資訊，請參閱 作業用戶端範例。

• Python SDK - 建議使用 Python 3.7 版或更新版本 。 請務必使用安裝程式所需的 32 位元或 64 位元安裝。 在安裝期間出現系統提示時，務必將 Python 新增至平台特有的環境變數。

概觀

本文說明如何使用適用於 Python 的 Azure IoT SDK 來建立後端服務應用程式程式代碼，以排程作業以叫用直接方法，或在一或多個裝置上執行裝置對應項所需的屬性更新。

安裝套件

必須安裝 azure-iot-hub 連結庫，才能建立後端服務應用程式。

pip install azure-iot-hub

Import 陳述式

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

連線至 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

• 共用存取原則
• Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。 此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。 若要深入瞭解，請參閱 IoT解決方案 > 雲端安全性的安全性最佳做法。

使用共用存取原則進行連線

使用 from_connection_string 連線到 IoT 中樞。

本文說明後端代碼如何排程作業以叫用直接方法、排程作業以更新設備雙胞，以及監控一個或多個設備的作業進度。 若要執行這些作業，則服務需要有登錄讀取和登錄寫入權限。 根據預設，每個 IoT 中樞都是使用授與這些權限且名為 registryReadWrite 的共用存取原則所建立。

如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

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

使用 Microsoft Entra 進行連線

使用 Microsoft Entra 的後端應用程式必須先成功驗證並取得安全性令牌認證，才能連線到 IoT 中樞。 此權杖會傳遞至 IoT 中樞連線方法。 如需設定和使用 IoT 中樞 Microsoft Entra 的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞 的存取。

設定 Microsoft Entra 應用程式

您必須設定 Microsoft Entra 應用程式，並配置為使用您偏好的驗證憑證。 應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。 可用的應用程式驗證群組態如下：

• 用戶端密碼
• 憑證
• 聯合身分憑證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。 例如，需要 IoT 中樞 對應項參與者，才能對 IoT 中樞 裝置和模組對應項啟用讀取和寫入存取權。 如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞 的存取權。

如需設定 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 中樞連線方法的安全性權杖認證。

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 可以傳遞至 IoT 中樞方法的連線，以取得任何接受 Microsoft Entra 認證的 SDK 用戶端：

• JobClient
• RegistryManager
• DigitalTwinClient
• ServiceClient

在此範例中， 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 參數附註：

• job_id 必須是唯一的
• 將 type 設定為 scheduleDeviceMethod
• 使用 cloud_to_device_method 來設定直接方法名稱和承載
• 使用 max_execution_time_in_seconds 指定以秒為單位的運行時間
• 使用 query_condition 指定要包含在直接方法呼叫中的裝置。 如需查詢條件的詳細資訊，請參閱 IoT 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。

例如：

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 參數附註：

• job_id 必須是唯一的
• 將 type 設定為 scheduleUpdateTwin
• 使用 update_twin 來設定直接方法名稱和承載
• 使用 max_execution_time_in_seconds 指定以秒為單位的運行時間
• 使用 query_condition 指定具有直接方法呼叫之一或多個裝置的條件。 如需查詢條件的詳細資訊，請參閱 IoT 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。

例如：

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 排程作業範例

適用於 Python 的 Azure IoT SDK 提供處理作業排程工作之服務應用程式的工作範例。 如需詳細資訊，請參閱

• 排程直接方法作業
• 排程裝置對應項更新。

• 需要Node.js 10.0.x 版或更新版本

概觀

本文說明如何使用適用於 Node.js 的 Azure IoT SDK 來建立後端服務應用程式程式代碼，以排程作業以叫用直接方法，或在一或多個裝置上執行裝置對應項更新。

安裝服務 SDK 套件

執行此命令，在開發電腦上安裝 azure-iothub：

npm install azure-iothub --save

JobClient 類別會公開從後端應用程式與作業排程互動所需的所有方法。

連線至 IoT 中樞

您可以使用下列方法將後端服務連線到 IoT 中樞：

• 共用存取原則
• Microsoft Entra

重要

本文包含使用共用存取簽章連線至服務的步驟。 此驗證方法方便進行測試和評估，但使用 Microsoft Entra ID 或受控識別向服務進行驗證是更安全的方法。 若要深入瞭解，請參閱 IoT解決方案 > 雲端安全性的安全性最佳做法。

使用共用存取原則進行連線

使用 fromConnectionString 連線到 IoT 中樞。

本文說明可排程作業以叫用直接方法、排程作業以更新裝置對應項以及監視一或多個裝置的作業進度的後端程式碼。 若要執行這些作業，則服務需要有登錄讀取和登錄寫入權限。 根據預設，每個 IoT 中樞都是使用授與這些權限且名為 registryReadWrite 的共用存取原則所建立。

如需共用存取原則的詳細資訊，請參閱使用共用存取簽章控制對 IoT 中樞的存取。

例如：

'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 中樞。 此權杖會傳遞至 IoT 中樞連線方法。 如需設定和使用 IoT 中樞 Microsoft Entra 的一般資訊，請參閱使用 Microsoft Entra 識別符控制對 IoT 中樞 的存取。

如需Node.js SDK 驗證的概觀，請參閱：

• 開始使用 Azure 上的用戶驗證
• 適用於 JavaScript 的 Azure 身分識別用戶端程式庫

設定 Microsoft Entra 應用程式

您必須設定 Microsoft Entra 應用程式，並將其配置為使用您偏好的驗證憑證。 應用程式包含參數，例如後端應用程式用來驗證的客戶端密碼。 可用的應用程式驗證群組態如下：

• 用戶端密碼
• 證書
• 聯合身分憑證

Microsoft Entra 應用程式可能需要特定角色許可權，視執行的作業而定。 例如，需要 IoT 中樞 對應項參與者，才能對 IoT 中樞 裝置和模組對應項啟用讀取和寫入存取權。 如需詳細資訊，請參閱使用 Azure RBAC 角色指派來管理對 IoT 中樞 的存取權。

如需設定 Microsoft Entra 應用程式的詳細資訊，請參閱快速入門：向 Microsoft 身分識別平台 註冊應用程式。

使用 DefaultAzureCredential 進行驗證

使用 Microsoft Entra 來驗證後端應用程式最簡單的方式是使用 DefaultAzureCredential，但建議在生產環境中使用其他方法，例如特定TokenCredential方法或簡化的ChainedTokenCredential方法。 為了簡單起見，本節說明使用 DefaultAzureCredential 和用戶端密碼的驗證。 如需使用 DefaultAzureCredential之優缺點的詳細資訊，請參閱 適用於 JavaScript 的 Azure 身分識別客戶端連結庫中的認證鏈結。

DefaultAzureCredential 支援不同的驗證機制，並根據執行中的環境來判斷適當的認證類型。 它會嘗試依序使用多個認證類型，直到找到有效的認證為止。

Microsoft Entra 需要此套件：

npm install --save @azure/identity

在此範例中，Microsoft Entra 應用程式註冊客戶端密碼、用戶端標識碼和租使用者標識碼已新增至環境變數。 這些環境變數是由 DefaultAzureCredential 用來驗證應用程式。 成功 Microsoft Entra 驗證的結果是傳遞至 IoT 中樞連線方法的安全性權杖認證。

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

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

然後，產生的認證權杖可以傳遞至 fromTokenCredential (部分內容可能是機器或 AI 翻譯)，以連線到 IoT 中樞，以取得任何接受 Microsoft Entra 認證的 SDK 用戶端：

• 登錄
• 用戶端
• JobClient

fromTokenCredential 需要兩個參數：

• Azure 服務 URL - Azure 服務 URL 的格式 {Your Entra domain URL}.azure-devices.net 應該不含 https:// 前置詞。 例如： MyAzureDomain.azure-devices.net 。
• Azure 認證令牌

在此範例中，會使用 DefaultAzureCredential取得 Azure 認證。 接著會提供 Azure 網域 URL 和認證給Registry.fromTokenCredential以建立與 IoT 中樞的連線。

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 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。
• 檢查 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 中樞 裝置和模組對應項、作業和訊息路由的查詢語言。
• 檢查 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 排程作業範例

適用於 Node.js的 Azure IoT SDK 提供可處理作業排程工作的服務應用程式工作範例。 如需詳細資訊，請參閱 作業用戶端 E2E 測試。