Cara berinteraksi dengan fitur CommandRunner dari OSConfig dan Azure IoT

Sebagian besar properti perangkat yang diekspos oleh OSConfig berbeda dan diabstraksi dari detail implementasi. Misalnya, ketika Anda menggunakan HostName.desiredName untuk mengatur nama host perangkat, Anda tidak perlu khawatir tentang rasa sistem operasi, tentang membuat skrip dependensi runtime, atau tentang nuansa waktu.

Namun, terkadang, Anda mungkin ingin memperdagangkan kesederhanaan untuk fleksibilitas. Contohnya:

• Anda perlu mengambil informasi kustom dari perangkat -- seperti ingin melaporkan hasil ping example.com dari perspektif perangkat
• Anda perlu mengonfigurasi sesuatu pada perangkat di mana tidak ada properti OSConfig yang diinginkan/dapat ditulis

Fitur CommandRunner OSConfig memungkinkan konfigurasi dan pelaporan kustom melalui perintah/skrip shell. Ini juga termasuk tindakan tertentu yang telah ditentukan sebelumnya (matikan, boot ulang) yang tidak memerlukan pembuatan skrip apa pun.

Tip

Artikel referensi ini menjelaskan konsep CommandRunner, model interaksi, dll. Untuk contoh penggunaan konkret, lihat:

• Reboot atau matikan perangkat dengan Azure IoT dan OSConfig
• Konfigurasi dan pelaporan kustom dengan Azure IoT dan OSConfig

Model interaksi dan properti/bidang utama

Ringkasan model interaksi

Meskipun penggunaan yang lebih bernuansa dimungkinkan (dan dijelaskan nanti dalam artikel ini), model interaksi inti sangat mudah:

• Anda memulai permintaan perintah dengan menulis ke yang diinginkan commandArguments dalam kembar.
• Anda mendapatkan hasilnya dengan membaca yang dilaporkan commandStatus dari kembar.

Penting

Payload yang ditunjukkan dalam diagram ini dilucuti untuk menekankan alur masuk/keluar. Untuk model objek lengkap termasuk anggota yang diperlukan yang tidak ditampilkan di sini, lihat: Model objek lengkap

Pengidentifikasi pulang-pergi adalah: commandId

Dalam diagram di atas, perhatikan bahwa dan commandArgumentscommandStatus sertakan bidang yang disebut commandId. Ini adalah pengidentifikasi pulang pergi yang menghubungkan permintaan dan hasil sepanjang operasi asinkron ini.

Pemanggil (toolchain admin atau admin) memilih nilai commandId.

Tip

commandId diperlukan dalam commandArguments. Penelepon biasanya menggunakan salah satu pola ini saat memilih nilai:

• Nilai monotonik seperti "1" (untuk permintaan pertama), "2" (untuk permintaan kedua), dll. atau nilai deskriptif seperti "my_ping_command"

  Ini sangat cocok untuk eksplorasi ad-hoc; mereka tidak memerlukan perencanaan, dan dapat ditik dengan mudah saat mengedit konten kembar

• Nilai yang dihasilkan otomatis entropi tinggi seperti UUID

  Ini sangat cocok untuk penggunaan terprogram skala besar di mana back-end solusi cloud akan secara terprogram membuat dan melacak nilai

Nilai commandId baru dalam commandArguments sinyal bahwa ini adalah permintaan baru. Dalam konteks kembar satu perangkat, mengisi perangkat baru commandId kira-kira dianalogikan dengan menekan 'Enter' di lingkungan shell.

commandId juga memungkinkan melacak beberapa permintaan. CommandRunner pada setiap perangkat dapat menerima (dan melaporkan status pada) beberapa permintaan dari waktu ke waktu. Sementara itu commandArguments komponen dan commandStatus di kembar setiap perangkat hanya dapat menggambarkan satu permintaan kapan saja. commandId adalah pengidentifikasi pulang pergi yang memungkinkan pemanggil untuk memahami (dan mengontrol) yang saat ini dijelaskan oleh permintaan sebelumnya oleh commandStatus. Akibatnya, commandStatus mengkomunikasikan "untuk permintaan Anda di mana id adalah 'foo', statusnya adalah <...>".

Kapan diperbarui commandStatus ?

Ada dua pemicu untuk CommandRunner pada perangkat untuk memperbarui commandStatus.

1. Refresh latar belakang

   commandStatus diperbarui secara berkala (defaultnya adalah 30 detik). Secara default refresh latar belakang ini menyebabkannya mewakili status permintaan terbaru.

   Dalam praktiknya, ini berarti bahwa setelah mengirimkan permintaan melalui commandArguments, Anda dapat mengharapkan untuk melihat status yang sesuai di commandStatus setelah sekitar 30-60 detik.

2. refreshCommandStatus

   refreshCommandStatus adalah mekanisme yang membahas dua kasus penggunaan lanjutan:

   1. Anda telah mengeluarkan beberapa permintaan dari waktu ke waktu melalui commandArguments, dan Anda ingin melihat status untuk permintaan tertentu, bukan permintaan terbaru
   2. Anda tidak ingin menunggu refresh latar belakang, bahkan jika Anda hanya tertarik pada permintaan terbaru

   Untuk memicu mekanisme ini, lihat dokumentasi model objek di bawah ini untuk commandArguments.

Praktik yang baik untuk konfigurasi dan pelaporan kustom dengan CommandRunner

1. Pertimbangan ukuran

   Untuk perintah/skrip pendek dan output pendek, Anda dapat bekerja langsung sebaris melalui kembar. Pendekatan ini memiliki keuntungan, terutama tidak memiliki dependensi jaringan atau autentikasi di luar IoT Hub. Kerugian utama dari pendekatan ini adalah bahwa input (termasuk teks skrip/perintah Anda) dan output (termasuk output konsol yang diambil) masing-masing terbatas pada 4KB.

   Untuk skrip yang lebih panjang, Anda dapat menyimpan skrip di tempat lain (seperti GitHub), dan memanggilnya dari perintah pembungkus minimal yang Anda berikan ke OSConfig melalui kembar. Misalnya, lihat: Konfigurasi dan pelaporan kustom dengan Azure IoT dan OSConfig. Terlepas dari ukuran, Anda mungkin juga lebih suka mengelola skrip Anda di GitHub atau sejenisnya- dengan konten kembar yang hanya menunjuk ke skrip tersebut.

   Untuk skrip/perintah yang output konsolnya terlalu besar untuk kembar, Anda dapat menyertakan logika dalam skrip untuk mengirim hasil ke penyimpanan lokal atau cloud daripada ke stdout. Misalnya, lihat: Konfigurasi dan pelaporan kustom dengan Azure IoT dan OSConfig.

2. Menggunakan perintah/skrip non-interaktif mandiri

   Lebih sedikit perjalanan pulang pergi yang lebih baik, satu perjalanan pulang pergi adalah yang terbaik. OSConfig dan CommandRunner dioptimalkan untuk skala bukan interaktivitas. Meskipun dimungkinkan untuk menggunakan CommandRunner secara serial (satu demi satu perintah, mirip dengan terminal sinkron langsung) pengalamannya tidak optimal. Tidak ada cara untuk menangani perintah shell interaktif, Anda harus menetapkan commandId untuk setiap permintaan, Anda harus menunggu sinkronisasi kembar, dll.

   Sebaliknya, anggap CommandRunner sebagai cara untuk mencapai konfigurasi kustom dan pelaporan dalam skala besar. Anda dapat mendistribusikan skrip non-interaktif secara asinkron (atau tindakan yang telah ditentukan sebelumnya seperti boot ulang) ke satu perangkat atau jutaan perangkat, dan dapat melaporkan hasilnya bahkan saat berkembang dari waktu ke waktu (saat perangkat baru bergabung dengan armada, misalnya).

   Dengan kata lain, katakanlah Anda perlu menjalankan empat perintah pada semua perangkat Ubuntu 20.04 saat ini dan yang akan datang di Spanyol. Jangan menganggapnya sebagai 4 penggunaan diskrit CommandRunner, anggap saja sebagai penggunaan tunggal CommandRunner di mana payload berisi empat perintah Anda. Sementara itu alur kerja cloud seperti konfigurasi IoT Hub dapat memastikan ini didistribusikan ke semua perangkat saat ini dan yang akan datang yang harus berada dalam cakupan.

Model objek lengkap

Penting

Versi 1.0.3 (diterbitkan 28 Juni 2022) mencakup perubahan yang melanggar pada nama anggota yang dapat memengaruhi pengguna yang ada. Untuk informasi selengkapnya, lihat: Transisi nama anggota dari PascalCase ke camelCase di versi 1.0.3

Informasi berikut berlaku untuk tampilan model objek yang diinginkan/dilaporkan biasa serta tampilan DTDL yang ditingkatkan. Untuk informasi selengkapnya, lihat Apa yang perlu diketahui pengguna OSConfig tentang toolchain "plain desired/reported" vs "DTDL enhanced".

commandArguments (diatur oleh admin)

• Deskripsi: Input dari admin, memicu permintaan perintah baru atau memicu refresh commandStatus.

• Jalur: properties.desired.CommandRunner.commandArguments (CommandRunner komponen -->commandArguments properti bisa-tulis)

• Anggota

  Nama	Jenis	Catatan
  commandId	string	• ID permintaan yang ditentukan penelepon; lihat di atas untuk latar belakang • commandArguments diabaikan ketika commandId kosong • Untuk interplay antara commandId dan action, lihat
  tindakan	enum/int	Berikut ini harus digabungkan dengan nilai baru commandId: • 1 (reboot) • 2 (matikan) • 3 (runCommand); memulai perintah/skrip shell untuk konfigurasi atau pelaporan kustom Berikut ini harus digabungkan dengan CommandID yang digunakan sebelumnya: • 4 (refreshCommandStatus) menyebabkan commandStatus menjelaskan permintaan tertentu yang diidentifikasi oleh commandId
  arguments	string	• Ketika tindakan adalah 1 (reboot) atau 2 (matikan), jumlah detik opsional untuk menunda sebelum memicu tindakan • Ketika tindakan adalah 3 (RunCommand), baris perintah untuk dijalankan, misalnya ping -c 2 example.com • Diabaikan untuk jenis tindakan lainnya • Ukuran commandArguments (biasanya didominasi oleh teks argumen) dalam kembar Azure IoT terbatas pada 4KB; untuk skrip yang lebih panjang lihat Praktik yang baik
  singleLineTextResult	boolean	• Ketika tindakan adalah 3 (RunCommand), tombol opsional untuk menentukan apakah baris baru harus dilucuti dari output konsol • Diabaikan untuk jenis tindakan lainnya
  waktu habis	int	• Ketika tindakan adalah 3 (runCommand), permintaan jangka panjang dimatikan setelah sekian detik ini • Opsional (defaultnya adalah 30) • Diabaikan untuk jenis tindakan lainnya

• Contoh dari IoT Hub dan perangkat nyata

  • Permintaan boot ulang:

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_reboot_cmd",
          "arguments": "",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 1
       }
    }
    

  • Permintaan konfigurasi kustom (zona waktu):

    "CommandRunner": {
       "__t": "c",
       "commandArguments": {
          "commandId": "my_timezone_cmd",
          "arguments": "timedatectl set-timezone Etc/UTC; timedatectl | grep Time",
          "timeout": 30,
          "singleLineTextResult": false,
          "action": 3
       }
    }
    

  • Untuk contoh tambahan, lihat:

    • Reboot atau matikan perangkat dengan Azure IoT dan OSConfig
    • Konfigurasi dan pelaporan kustom dengan Azure IoT dan OSConfig

commandArguments (pengakuan dari perangkat)

• Deskripsi: Ini adalah pengakuan dari agen OSConfig pada perangkat bahwa ia telah menerima nilai commandArguments dari sisi admin

• Jalur: properties.reported.CommandRunner.commandArguments (bagian pengakuan perangkat dari commandArguments properti bisa-tulis)

• Anggota:

  Nama	Jenis	Catatan
  nilai	peta	Harus mencerminkan properties.desired.CommandRunner.commandArguments, menunjukkan perangkat dalam online dan telah menerima permintaan
  ac	int	Kode status, kasus nominal adalah nilai 200

commandStatus

• Deskripsi: Memberikan status dan output permintaan yang sebelumnya dikirimkan melalui commandArguments

• Jalur: properties.reported.CommandRunner.commandStatus (CommandRunner komponen -->commandStatus properti baca-saja)

• Anggota

  Nama	Jenis	Catatan
  commandId	string	• Mengidentifikasi permintaan yang sebelumnya diterima saat ini dijelaskan oleh Commandstatus • Secara default permintaan terbaru diwakili • Penelepon dapat mengubah fokus ini untuk menjelaskan permintaan tertentu melalui mekanisme refreshCommandStatus yang dijelaskan di atas
  resultCode	int	Kode keluar dari perintah yang diminta. Analog dengan echo $? dalam bash
  currentState	enum/int	• Kasus nominal adalah nilai 2 (succeeded) • Lihat metadata untuk daftar lengkap nilai yang mungkin
  textResult	string	• Output konsol dari perintah yang diminta • Ukuran commandStatus (biasanya didominasi oleh komponen textResult) di kembar Azure IoT terbatas pada 4KB; untuk output yang lebih lama, lihat Praktik yang baik

• Contoh dari IoT Hub dan perangkat nyata

  • Hasil boot ulang

    "CommandRunner": {
        "__t": "c",
        "commandStatus": {
           "commandId": "my_reboot_cmd",
           "resultCode": 0,
           "textResult": "",
           "currentState": 2
        }
    }
    

  • Hasil konfigurasi kustom (zona waktu):

    "CommandRunner": {
       "__t": "c",
       "commandStatus": {
          "commandId": "my_timezone_cmd",
          "testResult": "Time zone: UTC",
          "statusCode": 0
       }
    }
    

  • Untuk contoh tambahan, lihat:

    • Reboot atau matikan perangkat dengan Azure IoT dan OSConfig
    • Konfigurasi dan pelaporan kustom dengan Azure IoT dan OSConfig

Penting

Versi 1.0.3 (diterbitkan 28 Juni 2022) mencakup perubahan yang melanggar pada nama anggota yang dapat memengaruhi pengguna yang ada. Untuk informasi selengkapnya, lihat: Transisi nama anggota dari PascalCase ke camelCase di versi 1.0.3

Langkah berikutnya

Untuk gambaran umum skenario dan kemampuan OSConfig, lihat:

• Apa itu OSconfig untuk IoT

Untuk contoh praktis tertentu, lihat:

• Membuat lingkungan lab OSConfig (dengan Azure IoT) dalam 5 menit
• Mulai cepat: Contoh kueri untuk mulai menggunakan OSConfig dan Azure IoT
• Apa yang dapat saya provisikan dan kelola?