Bagikan melalui

Cara menjadwalkan dan menyiarkan pekerjaan

Artikel ini memperlihatkan kepada Anda cara membuat kode aplikasi back-end untuk menjadwalkan dan menyiarkan pekerjaan.

Gunakan Azure IoT Hub untuk menjadwalkan dan melacak pekerjaan yang memperbarui hingga jutaan perangkat untuk operasi ini:

  • Memanggil metode langsung
  • Perangkat kembar yang diperbarui

Pekerjaan membungkus salah satu tindakan ini dan melacak eksekusi terhadap kumpulan perangkat yang didefinisikan oleh kueri kembar perangkat. Misalnya, aplikasi back-end dapat menggunakan tugas untuk menjalankan metode langsung pada 10.000 perangkat untuk me-reboot perangkat tersebut. Anda menentukan kumpulan perangkat dengan kueri perangkat kembar dan menjadwalkan tugas untuk dijalankan di waktu mendatang. Tugas memantau kemajuan saat masing-masing perangkat menerima dan menjalankan metode reboot langsung.

Untuk mempelajari lebih lanjut tentang masing-masing kemampuan ini, lihat:

Catatan

Fitur yang dijelaskan dalam artikel ini hanya tersedia di tingkat standar IoT Hub. Untuk informasi selengkapnya tentang tingkat IoT Hub dasar dan standar/gratis, lihat Memilih tingkat dan ukuran IoT Hub yang tepat untuk solusi Anda.

Catatan

Artikel ini dimaksudkan untuk melengkapi sampel Azure IoT SDK yang dirujuk dari dalam artikel ini. Anda dapat menggunakan alat SDK untuk membangun aplikasi perangkat dan back-end.

Prasyarat

  • Sebuah hub IoT

  • Perangkat terdaftar

  • Jika aplikasi Anda menggunakan protokol MQTT, pastikan port 8883 terbuka di firewall Anda. Protokol MQTT berkomunikasi melalui port 8883. Port ini dapat diblokir di beberapa lingkungan jaringan perusahaan dan pendidikan. Untuk informasi selengkapnya dan cara mengatasi masalah ini, lihat Menyambungkan ke IoT Hub (MQTT).

  • Memerlukan Visual Studio

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk .NET untuk membuat kode aplikasi layanan backend ke pekerjaan jadwal untuk memanggil metode langsung atau melakukan pembaruan kembar perangkat pada satu atau beberapa perangkat.

Menambahkan paket NuGet layanan

Aplikasi layanan backend memerlukan paket NuGet Microsoft.Azure.Devices .

Menggunakan pernyataan

Tambahkan pernyataan penggunaan berikut ini.

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

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

Menyambungkan ke hub IoT

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

  • Kebijakan akses bersama
  • Microsoft Entra

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Menyambungkan menggunakan kebijakan akses bersama

Sambungkan aplikasi backend ke perangkat menggunakan CreateFromConnectionString.

Artikel ini menjelaskan kode back-end yang dapat menjadwalkan pekerjaan untuk memanggil metode langsung, menjadwalkan pekerjaan untuk memperbarui kembar perangkat, dan memantau kemajuan pekerjaan untuk satu atau beberapa perangkat. Untuk melakukan operasi ini, layanan Anda memerlukan izin baca registri dan penulisan registri. Secara default, setiap hub IoT dibuat dengan kebijakan akses bersama bernama registryReadWrite yang memberikan izin ini.

Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

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

Hubungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

  • Rahasia Klien
  • Sertifikat
  • Kredensial identitas federatif

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Perangkat Kembar IoT Hub diperlukan untuk mampu mengakses baca dan tulis ke perangkat dan modul kembar IoT Hub. Untuk informasi selengkapnya, lihat Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara termudah untuk menggunakan Microsoft Entra untuk mengauntentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau yang telah disederhanakan ChainedTokenCredential. Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Panduan penggunaan untuk DefaultAzureCredential.

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using :

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

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi 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 yang dihasilkan kemudian dapat diteruskan ke metode sambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

Dalam contoh ini, TokenCredential diteruskan ke ServiceClient.Create untuk membuat objek koneksi ServiceClient.

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

Dalam contoh ini, TokenCredential diteruskan ke RegistryManager.Create untuk membuat objek RegistryManager.

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

Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Sampel autentikasi berbasis peran.

Jadwalkan pekerjaan metode langsung

Gunakan ScheduleDeviceMethodAsync untuk menjadwalkan pekerjaan untuk menjalankan metode langsung pada satu atau beberapa perangkat.

Gunakan objek CloudToDeviceMethod untuk menentukan nama metode langsung dan nilai batas waktu koneksi perangkat.

Contohnya:

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

Contoh ini menjadwalkan tugas untuk metode langsung bernama "LockDoor" pada perangkat bernama "Device-1". Perangkat yang disertakan dalam pekerjaan terjadwal berisi parameter kedua sebagai kondisi kueri. Untuk informasi lebih lanjut tentang syarat kueri, lihat Bahasa Kueri IoT Hub untuk kembar perangkat dan modul, pekerjaan, dan perutean pesan.

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

Menjadwalkan pekerjaan pembaruan kembar perangkat

Gunakan ScheduleTwinUpdateAsync untuk menjadwalkan properti perangkat kembar baru yang diinginkan dan tugas pembaruan tag untuk dijalankan pada satu atau beberapa perangkat.

Pertama, buat dan isi objek Perangkat Kembar untuk pembaruan. Contohnya:

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;

Selanjutnya, panggil ScheduleTwinUpdateAsync. Tentukan perangkat yang akan diperbarui sebagai kueri di parameter kedua. Untuk informasi selengkapnya tentang kondisi kueri, lihat Bahasa kueri IoT Hub untuk twin perangkat dan modul, pekerjaan, dan pengaturan jalur pesan.

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

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

Memantau pekerjaan

Gunakan GetJobAsync untuk memantau status pekerjaan untuk ID pekerjaan tertentu.

Contoh ini memeriksa status pekerjaan untuk ID pekerjaan secara berkala hingga status pekerjaan selesai atau gagal. Contohnya:

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

Contoh tugas penjadwalan SDK

Azure IoT SDK untuk .NET menyediakan sampel kerja aplikasi layanan yang menangani tugas penjadwalan pekerjaan. Untuk informasi selengkapnya, lihat:

  • Memerlukan Java SE Development Kit 8. Pastikan Anda memilih Java 8 di bawah Dukungan jangka panjang untuk menavigasi ke unduhan untuk JDK 8.

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK for Java untuk membuat kode aplikasi layanan backend guna menjadwalkan pekerjaan untuk memanggil metode langsung atau melakukan pembaruan kembar perangkat pada satu atau beberapa perangkat.

Pernyataan impor layanan

Kelas JobClient berisi metode yang dapat digunakan layanan untuk menjadwalkan pekerjaan.

Gunakan pernyataan impor layanan berikut untuk mengakses Azure IoT SDK untuk 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;

Menyambungkan ke IoT Hub

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

  • Kebijakan akses bersama
  • Microsoft Entra

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Menyambungkan menggunakan kebijakan akses bersama

Gunakan konstruktor JobClient untuk membuat koneksi ke hub IoT. Objek JobClient menangani komunikasi dengan hub IoT Anda.

Artikel ini menjelaskan kode back-end yang dapat menjadwalkan tugas untuk memanggil metode langsung, menjadwalkan tugas untuk memperbarui kembar perangkat, dan memantau kemajuan tugas untuk satu atau beberapa perangkat. Untuk melakukan operasi ini, layanan Anda memerlukan izin baca registri dan penulisan registri. Secara default, setiap hub IoT dibuat dengan kebijakan akses bersama bernama registryReadWrite yang memberikan izin ini.

Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

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

Menyambungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Untuk gambaran umum autentikasi Java SDK, lihat Autentikasi Azure dengan Java dan Azure Identity.

Untuk kesederhanaan, bagian ini berfokus pada menjelaskan autentikasi menggunakan rahasia klien.

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

  • Rahasia Klien
  • Sertifikat
  • Kredensial identitas terpadu

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor diperlukan untuk memungkinkan akses baca dan tulis ke perangkat dan modul kembar IoT Hub. Untuk informasi selengkapnya, lihat Manajemen akses ke IoT Hub dengan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara termudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau diuraikan.ChainedTokenCredential Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Rantai kredensial di pustaka klien Azure Identity untuk Java.

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Anda dapat mengautentikasi kredensial aplikasi Microsoft Entra menggunakan DefaultAzureCredentialBuilder. Simpan parameter koneksi seperti tenantID rahasia klien, clientID, dan nilai rahasia klien sebagai variabel lingkungan. Setelah TokenCredential dibuat, teruskan ke ServiceClient atau penyusun lain sebagai parameter 'kredensial'.

Dalam contoh ini, DefaultAzureCredentialBuilder mencoba mengautentikasi koneksi dari daftar yang dijelaskan dalam DefaultAzureCredential. Hasil dari autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke konstruktor seperti ServiceClient.

TokenCredential defaultAzureCredential = new DefaultAzureCredentialBuilder().build();
Mengautentikasi menggunakan ClientSecretCredentialBuilder

Anda dapat menggunakan ClientSecretCredentialBuilder untuk membuat kredensial menggunakan informasi rahasia klien. Jika berhasil, metode ini mengembalikan TokenCredential yang dapat diteruskan ke ServiceClient atau pembangun lainnya sebagai parameter 'kredensial'.

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan nilai ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh ClientSecretCredentialBuilder untuk membangun kredensial.

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();
Kelas autentikasi lainnya

Java SDK juga menyertakan kelas-kelas ini yang mengautentikasi aplikasi backend dengan Microsoft Entra:

Sampel kode

Untuk sampel kerja autentikasi layanan Microsoft Entra, lihat Sampel autentikasi berbasis peran.

Menjadwalkan pekerjaan pembaruan metode langsung

Gunakan scheduleDeviceMethod untuk menjalankan metode langsung pada satu atau beberapa perangkat.

Metode contoh ini menjadwalkan pekerjaan untuk metode langsung bernama "lockDoor" pada perangkat bernama "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());
}

Jadwalkan tugas pembaruan kembar perangkat

Gunakan scheduleUpdateTwin untuk menjadwalkan pekerjaan untuk menjalankan pembaruan kembar perangkat pada satu atau beberapa perangkat.

Pertama, siapkan catatan DeviceTwinDevice untuk pembaruan kembar perangkat. Contohnya:

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

Kemudian panggil scheduleUpdateTwin untuk menjadwalkan pekerjaan pembaruan. Contohnya:

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

Memantau pekerjaan

Gunakan getJob untuk mengambil informasi pekerjaan berdasarkan ID pekerjaan tertentu. getJob mengembalikan objek JobResult yang berisi metode dan properti yang dapat Anda gunakan untuk memeriksa informasi pekerjaan termasuk status berjalan.

Contohnya:

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

Mengkueri status pekerjaan

Gunakan queryDeviceJob untuk mengkueri status pekerjaan untuk satu atau beberapa pekerjaan.

Contohnya:

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

Contoh penjadwalan pekerjaan SDK

Azure IoT SDK for Java menyediakan sampel kerja aplikasi layanan yang menangani tugas penjadwalan pekerjaan. Untuk informasi selengkapnya, lihat Sampel Klien Pekerjaan.

  • Python SDK - Python versi 3.7 atau yang lebih baru direkomendasikan. Pastikan untuk menggunakan penginstalan 32-bit atau 64-bit sesuai kebutuhan penyiapan Anda. Saat diminta selama instalasi, pastikan untuk menambahkan Python ke variabel lingkungan khusus platform Anda.

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk Python untuk membuat kode aplikasi layanan backend untuk menjadwalkan pekerjaan untuk memanggil metode langsung atau melakukan pembaruan properti yang diinginkan kembar perangkat pada satu atau beberapa perangkat.

Pasang paket

Pustaka azure-iot-hub harus diinstal untuk membuat aplikasi layanan backend.

pip install azure-iot-hub

Pernyataan impor

Kelas IoTHubJobManager mengekspos semua metode yang diperlukan untuk membuat aplikasi backend untuk menjadwalkan pekerjaan dari layanan.

Tambahkan pernyataan import berikut.

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

Menyambungkan ke hub IoT

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

  • Kebijakan akses bersama
  • Microsoft Entra

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Menghubungkan menggunakan kebijakan akses bersama

Sambungkan ke hub IoT menggunakan from_connection_string.

Artikel ini menjelaskan kode back-end yang dapat menjadwalkan pekerjaan untuk memanggil metode langsung, menjadwalkan pekerjaan untuk memperbarui kembar perangkat, dan memantau kemajuan pekerjaan untuk satu atau beberapa perangkat. Untuk melakukan operasi ini, layanan Anda memerlukan izin baca registri dan penulisan registri. Secara default, setiap hub IoT dibuat dengan kebijakan akses bersama bernama registryReadWrite yang memberikan izin ini.

Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

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

Hubungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

  • Rahasia Klien
  • Sertifikat
  • Kredensial identitas yang difederasi

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, IoT Hub Twin Contributor diperlukan untuk memungkinkan akses baca dan tulis ke perangkat dan modul kembar IoT Hub. Untuk informasi selengkapnya, lihat Mengelola akses fitur ke IoT Hub dengan menggunakan penugasan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara termudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi latar belakang adalah dengan menggunakan DefaultAzureCredential, namun disarankan menggunakan metode yang berbeda dalam lingkungan produksi, termasuk yang spesifik TokenCredential atau yang diperkecil.ChainedTokenCredential Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Panduan penggunaan untuk DefaultAzureCredential.

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket NuGet ini dan pernyataan terkait using :

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

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi 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 yang dihasilkan kemudian dapat diteruskan ke metode sambungkan ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

Dalam contoh ini, TokenCredential diteruskan ke ServiceClient.Create untuk membuat objek koneksi ServiceClient.

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

Dalam contoh ini, TokenCredential diteruskan ke RegistryManager.Create untuk membuat sebuah objek RegistryManager.

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

Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Sampel autentikasi berbasis peran.

Jadwalkan pekerjaan metode langsung

Gunakan create_scheduled_job untuk menjadwalkan metode langsung baru untuk menjalankan metode langsung pada satu atau beberapa perangkat:

create_scheduled_job catatan parameter:

  • job_id harus unik
  • Atur type ke scheduleDeviceMethod
  • Gunakan cloud_to_device_method untuk mengatur nama metode langsung dan payload
  • Gunakan max_execution_time_in_seconds untuk menentukan waktu eksekusi dalam detik
  • Gunakan query_condition untuk menentukan perangkat yang akan disertakan untuk panggilan metode langsung. Untuk informasi lebih lanjut tentang kondisi kueri, lihat Bahasa kueri IoT Hub untuk perangkat dan modul kembar, pekerjaan, serta perutean pesan.

Contohnya:

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)

Menjadwalkan pekerjaan pembaruan kembar perangkat

Gunakan create_scheduled_job untuk membuat pekerjaan baru untuk menjalankan pembaruan properti yang diinginkan kembar perangkat pada satu atau beberapa perangkat.

create_scheduled_job catatan mengenai parameter:

  • job_id harus unik
  • Atur type ke scheduleUpdateTwin
  • Gunakan update_twin untuk mengatur nama metode langsung dan payload
  • Gunakan max_execution_time_in_seconds untuk menentukan waktu eksekusi dalam detik
  • Gunakan query_condition untuk menentukan kondisi untuk satu atau beberapa perangkat yang memiliki panggilan metode langsung. Untuk informasi selengkapnya tentang kondisi kueri, lihat Bahasa kueri IoT Hub untuk perangkat dan modul kembar, pekerjaan, dan perutean pesan.

Contohnya:

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)

Memantau pekerjaan

Gunakan get_scheduled_job untuk mengambil detail pekerjaan tertentu di IoT Hub.

Contoh ini memeriksa status pekerjaan untuk ID pekerjaan tertentu setiap lima detik hingga pekerjaan selesai.

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)

Contoh penjadwalan pekerjaan SDK

Azure IoT SDK untuk Python menyediakan sampel kerja aplikasi layanan yang menangani tugas penjadwalan pekerjaan. Untuk informasi selengkapnya, lihat:

  • Memerlukan Node.js versi 10.0.x atau yang lebih baru

Gambaran Umum

Artikel ini menjelaskan cara menggunakan Azure IoT SDK untuk Node.js membuat kode aplikasi layanan backend guna menjadwalkan pekerjaan untuk memanggil metode langsung atau melakukan pembaruan kembar perangkat pada satu atau beberapa perangkat.

Menginstal paket SDK layanan

Jalankan perintah ini untuk menginstal azure-iothub di komputer pengembangan Anda:

npm install azure-iothub --save

Kelas JobClient mengekspos semua metode yang diperlukan untuk berinteraksi dengan penjadwalan pekerjaan dari aplikasi backend.

Menyambungkan ke hub IoT

Anda dapat menyambungkan layanan backend ke IoT Hub menggunakan metode berikut:

  • Kebijakan akses bersama
  • Microsoft Entra

Penting

Artikel ini menyertakan langkah-langkah untuk menyambungkan ke layanan menggunakan tanda tangan akses bersama. Metode autentikasi ini mudah untuk pengujian dan evaluasi, tetapi mengautentikasi ke layanan dengan ID Microsoft Entra atau identitas terkelola adalah pendekatan yang lebih aman. Untuk mempelajari selengkapnya, lihat Praktik terbaik keamanan untuk solusi IoT > Keamanan cloud.

Menyambungkan menggunakan kebijakan akses bersama

Gunakan fromConnectionString untuk menyambungkan ke hub IoT.

Artikel ini menjelaskan kode back-end yang dapat menjadwalkan pekerjaan untuk memanggil metode langsung, menjadwalkan pekerjaan untuk memperbarui kembar perangkat, dan memantau kemajuan pekerjaan untuk satu atau beberapa perangkat. Untuk melakukan operasi ini, layanan Anda memerlukan izin baca registri dan penulisan registri. Secara default, setiap hub IoT dibuat dengan kebijakan akses bersama bernama registryReadWrite yang memberikan izin ini.

Untuk informasi selengkapnya tentang kebijakan akses bersama, lihat Mengontrol akses ke IoT Hub dengan tanda tangan akses bersama.

Contohnya:

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

Sambungkan menggunakan Microsoft Entra

Aplikasi backend yang menggunakan Microsoft Entra harus berhasil mengautentikasi dan mendapatkan kredensial token keamanan sebelum menyambungkan ke IoT Hub. Token ini diteruskan ke metode koneksi IoT Hub. Untuk informasi umum tentang menyiapkan dan menggunakan Microsoft Entra untuk IoT Hub, lihat Mengontrol akses ke IoT Hub dengan menggunakan ID Microsoft Entra.

Untuk gambaran umum autentikasi SDK Node.js, lihat:

Mengonfigurasi aplikasi Microsoft Entra

Anda harus menyiapkan aplikasi Microsoft Entra yang dikonfigurasi untuk kredensial autentikasi pilihan Anda. Aplikasi ini berisi parameter seperti rahasia klien yang digunakan oleh aplikasi backend untuk mengautentikasi. Konfigurasi autentikasi aplikasi yang tersedia adalah:

  • Rahasia Klien
  • Sertifikat
  • Kredensial identitas terfederasi

Aplikasi Microsoft Entra mungkin memerlukan izin peran tertentu tergantung pada operasi yang dilakukan. Misalnya, Kontributor Kembar IoT Hub diperlukan untuk mengaktifkan akses baca dan tulis ke sebuah perangkat IoT Hub dan kembar modul. Untuk informasi selengkapnya, baca Mengelola akses ke IoT Hub dengan menggunakan penetapan peran Azure RBAC.

Untuk informasi selengkapnya tentang menyiapkan aplikasi Microsoft Entra, lihat Mulai Cepat: Mendaftarkan aplikasi dengan platform identitas Microsoft.

Mengautentikasi menggunakan DefaultAzureCredential

Cara termudah untuk menggunakan Microsoft Entra untuk mengautentikasi aplikasi backend adalah dengan menggunakan DefaultAzureCredential, tetapi disarankan untuk menggunakan metode yang berbeda di lingkungan produksi termasuk yang spesifik TokenCredential atau yang diperkecil.ChainedTokenCredential Untuk kesederhanaan, bagian ini menjelaskan autentikasi menggunakan DefaultAzureCredential dan Rahasia klien. Untuk informasi selengkapnya tentang pro dan kontra penggunaan DefaultAzureCredential, lihat Rantai kredensial di pustaka klien Azure Identity untuk JavaScript

DefaultAzureCredential mendukung mekanisme autentikasi yang berbeda dan menentukan jenis kredensial yang sesuai berdasarkan lingkungan tempatnya dijalankan. Ini mencoba menggunakan beberapa jenis kredensial dalam urutan hingga menemukan kredensial yang berfungsi.

Microsoft Entra memerlukan paket ini:

npm install --save @azure/identity

Dalam contoh ini, rahasia klien pendaftaran aplikasi Microsoft Entra, ID klien, dan ID penyewa telah ditambahkan ke variabel lingkungan. Variabel lingkungan ini digunakan oleh DefaultAzureCredential untuk mengautentikasi aplikasi. Hasil autentikasi Microsoft Entra yang berhasil adalah kredensial token keamanan yang diteruskan ke metode koneksi IoT Hub.

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

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

Token kredensial yang dihasilkan kemudian dapat diteruskan ke dariTokenCredential untuk terhubung ke IoT Hub untuk klien SDK apa pun yang menerima kredensial Microsoft Entra:

fromTokenCredential memerlukan dua parameter:

  • URL layanan Azure - URL layanan Azure harus dalam format {Your Entra domain URL}.azure-devices.net tanpa https:// awalan. Contohnya,MyAzureDomain.azure-devices.net.
  • Token kredensial Azure

Dalam contoh ini, kredensial Azure diperoleh menggunakan DefaultAzureCredential. Untuk membuat koneksi ke IoT Hub, URL domain Azure dan kredensial kemudian disediakan untuk Registry.fromTokenCredential.

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

Untuk sampel autentikasi layanan Microsoft Entra yang berfungsi, lihat Contoh identitas Azure.

Menciptakan pekerjaan dengan metode langsung

Gunakan scheduleDeviceMethod untuk menjadwalkan pekerjaan untuk menjalankan metode langsung pada satu atau beberapa perangkat.

Pertama, buat variabel pembaruan metode langsung dengan nama metode, payload, dan informasi waktu habis respons. Contohnya:

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

Kemudian panggil scheduleDeviceMethod untuk menjadwalkan pekerjaan panggilan metode langsung:

  • Setiap pekerjaan harus memiliki ID pekerjaan yang unik. Anda dapat menggunakan ID pekerjaan ini untuk memantau pekerjaan seperti yang dijelaskan di bagian Pantau pekerjaan di artikel ini.
  • queryCondition Tentukan parameter untuk mengevaluasi perangkat mana yang akan menjalankan pekerjaan. Untuk informasi lebih lanjut tentang kondisi kueri, lihat Bahasa kueri IoT Hub untuk perangkat dan modul, pekerjaan, serta perutean pesan.
  • Periksa jobResult callback untuk hasil penjadwalan pekerjaan. Jika pekerjaan berhasil dijadwalkan, Anda dapat memantau status pekerjaan seperti yang ditunjukkan di bagian Pantau pekerjaan di artikel ini.

Contohnya:

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

Menjadwalkan tugas pembaruan perangkat twin

Gunakan scheduleTwinUpdate untuk membuat pekerjaan baru untuk menjalankan pembaruan kembar perangkat pada satu atau beberapa perangkat.

Pertama, buat variabel pembaruan properti yang diinginkan pada device twin.

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

Kemudian panggil scheduleTwinUpdate untuk menjadwalkan pekerjaan pembaruan properti yang diinginkan pada device twin:

  • Setiap pekerjaan harus memiliki ID pekerjaan yang unik. Anda dapat menggunakan ID pekerjaan ini untuk memantau pekerjaan seperti yang dijelaskan di bagian Pantau pekerjaan di artikel ini.
  • queryCondition Tentukan parameter untuk mengevaluasi perangkat mana yang akan menjalankan pekerjaan. Untuk informasi selengkapnya tentang kondisi pencarian, lihat Bahasa pencarian IoT Hub untuk perangkat dan modul kembar, pekerjaan, serta perutean pesan.
  • Periksa jobResult callback untuk hasil penjadwalan tugas. Jika pekerjaan berhasil dijadwalkan, Anda dapat memantau status pekerjaan seperti yang ditunjukkan di bagian Pantau pekerjaan di artikel ini.

Contohnya:

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

Memantau pekerjaan

Gunakan getJob untuk memantau status pekerjaan untuk ID pekerjaan tertentu.

Contoh fungsi ini memeriksa status pekerjaan untuk ID pekerjaan tertentu secara berkala hingga pekerjaan selesai atau gagal.

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

Contoh tugas terjadwal SDK

Azure IoT SDK untuk Node.js menyediakan sampel kerja aplikasi layanan yang menangani tugas penjadwalan pekerjaan. Untuk informasi selengkapnya, lihat Pengujian E2E klien pekerjaan.

  • Last updated on