OSConfig ve Azure IoT'nin CommandRunner özelliğiyle etkileşim kurma

OSConfig tarafından kullanıma sunulan çoğu cihaz özelliği ayrıktır ve uygulama ayrıntılarından soyutlanır. Örneğin, bir cihazın ana bilgisayar adını ayarlamak için kullandığınızda HostName.desiredName işletim sistemi durumu, betik çalışma zamanı bağımlılıkları veya zamanlama nüansları hakkında endişelenmeniz gerekmez.

Ancak bazen esneklik için kolaylık sağlamak isteyebilirsiniz. Örnek:

• Cihazdan özel bilgiler almanız gerekir; örneğin, cihazın perspektifinden sonuçlarını ping example.com raporlamak isteme
• Cihazda OSConfig istenen/yazılabilir özelliği olmayan bir şey yapılandırmanız gerekir

OSConfig'in CommandRunner özelliği, kabuk komutları/betikleri aracılığıyla özel yapılandırma ve raporlama sağlar. Ayrıca, herhangi bir betik gerektirmeyen önceden tanımlanmış bazı eylemleri (kapatma, yeniden başlatma) içerir.

İpucu

Bu başvuru makalesinde CommandRunner kavramları, etkileşim modeli vb. açıklanmaktadır. Somut kullanım örnekleri için bkz:

• Azure IoT ve OSConfig ile cihazları yeniden başlatma veya kapatma
• Azure IoT ve OSConfig ile özel yapılandırma ve raporlama

Etkileşim modeli ve anahtar özellikleri/alanları

Etkileşim modelinin özeti

Daha ayrıntılı kullanım mümkün olsa da (ve bu makalenin ilerleyen bölümlerinde açıklanmaktadır), çekirdek etkileşim modeli basittir:

• İkizde istenene commandArguments yazarak bir komut isteği başlatırsınız.
• İkizden bildirilenleri commandStatus okuyarak sonuçları alırsınız.

Önemli

Bu diyagramda gösterilen yüklerin çıkarılmış olması, içeri/dışarı akışını vurgular. Burada gösterilmeyen gerekli üyeler de dahil olmak üzere tam nesne modeli için bkz. Tam nesne modeli

Gidiş dönüş tanımlayıcısı: commandId

Yukarıdaki diyagramda, hem commandStatus hem de commandArguments adlı commandIdbir alan içerdiğini unutmayın. Bu, bu zaman uyumsuz işlem boyunca isteği ve sonucu bağlayan gidiş dönüş tanımlayıcısıdır.

Çağıran (yönetici veya yönetici araç zinciri) commandId değerini seçer.

İpucu

commandId içinde commandArgumentsgereklidir. Çağıranlar genellikle değerleri seçerken şu desenlerden birini kullanır:

• "1" (ilk istek için), "2" (ikinci istek için) gibi monoton değerler. veya "my_ping_command" gibi açıklayıcı değerler

  Bunlar geçici keşifler için uygundur; planlama gerektirmezler ve ikiz içeriklerini düzenlerken kolayca yazılabilirler

• UUID'ler gibi otomatik olarak oluşturulan yüksek entropi değerleri

  Bunlar, bulut çözümü arka ucunun program aracılığıyla değer oluşturacağı ve takip edeceği büyük ölçekli programlı kullanım için uygundur

sinyallerinde commandArguments değerinin commandId yeni bir değeri bunun yeni bir istek olduğunu gösterir. Tek bir cihazın ikizi bağlamında, yeni commandId bir doldurma işlemi kabaca kabuk ortamında 'Enter' tuşuna basmaya benzer.

commandId ayrıca birden çok isteğin izlenmesini sağlar. Her cihazdaki CommandRunner, zaman içinde birden çok istek alabilir (ve durumunu bildirebilir). Bu arada commandArguments her cihazın ikizindeki ve commandStatus bileşenleri her an yalnızca bir isteği açıklayabilir. commandId , çağıranın tarafından şu anda hangi önceki isteğin açıklanmış commandStatusolduğunu anlamasını (ve denetlemesini) sağlayan gidiş dönüş tanımlayıcısıdır. Aslında, commandStatus "kimliğin 'foo' olduğu isteğiniz için durum <...>" iletir.

commandStatus Ne zaman güncelleştirildi?

Cihazda CommandRunner'ın güncelleştirilecek commandStatusiki tetikleyicisi vardır.

1. Arka plan yenileme

   commandStatus düzenli aralıklarla güncelleştirilir (varsayılan değer 30 saniyedir). Varsayılan olarak bu arka plan yenilemesi, en son isteğin durumunu temsil eder.

   Uygulamada bu, commandArguments aracılığıyla bir istek gönderdikten sonra, yaklaşık 30-60 saniye sonra commandStatus'ta ilgili durumu görmeyi bekleyebileceğiniz anlamına gelir.

2. refreshCommandStatus

   refreshCommandStatus iki gelişmiş kullanım örneğini ele alan bir mekanizmadır:

   1. aracılığıyla zaman commandArgumentsiçinde birden çok istek yayımladınız ve en son isteği değil belirli bir isteğin durumunu görmek istiyorsunuz
   2. Yalnızca en son istekle ilgileniyor olsanız bile arka plan yenilemesini beklemek istemezsiniz

   Bu mekanizmayı tetikleyebilmek için commandArgumentsaşağıdaki için nesne modeli belgelerine bakın.

CommandRunner ile özel yapılandırma ve raporlama için iyi uygulamalar

1. Boyutla ilgili dikkat edilmesi gerekenler

   Kısa komutlar/betikler ve kısa çıkışlar için ikiz aracılığıyla doğrudan satır içi çalışabilirsiniz. Bu yaklaşımın avantajları vardır, özellikle de IoT Hub dışında ağ veya kimlik doğrulama bağımlılığı yoktur. Bu yaklaşımın birincil dezavantajı, girişlerin (betik/komut metniniz dahil) ve çıkışların (yakalanan konsol çıkışları dahil) her birinin 4 KB ile sınırlı olmasıdır.

   Daha uzun betikler için betiği başka bir yerde (GitHub gibi) depolayabilir ve bunu ikizi üzerinden OSConfig'e geçirdiğiniz en düşük sarmalayıcı komutundan çağırabilirsiniz. Örnekler için bkz. Azure IoT ve OSConfig ile özel yapılandırma ve raporlama. Boyuttan bağımsız olarak, betiklerinizi GitHub'da veya benzer bir şekilde yönetmeyi tercih edebilirsiniz. İkiz içeriği yalnızca bunları işaret eder.

   Konsol çıkışı ikiz için çok büyük olan betikler/komutlar için, sonuçları stdout yerine şirket içi veya bulut depolamaya göndermek için betikte mantık ekleyebilirsiniz. Örnekler için bkz. Azure IoT ve OSConfig ile özel yapılandırma ve raporlama.

2. Bağımsız, etkileşimli olmayan komutları/betikleri kullanma

   Daha az gidiş dönüş daha iyidir, bir gidiş dönüş en iyisidir. OSConfig ve CommandRunner, ölçek etkileşimi için iyileştirilmiştir. CommandRunner'ı seri olarak kullanmak mümkün olsa da (canlı bir zaman uyumlu terminale benzer şekilde bir komut diğerine benzer) deneyim en uygun değildir. Etkileşimli kabuk istemlerini işlemenin bir yolu yoktur, her isteğe bir commandId atamanız, ikiz eşitlemesini beklemeniz vb. gerekir.

   Bunun yerine, CommandRunner'ı büyük ölçekte özel yapılandırma ve raporlama elde etmenin bir yolu olarak düşünün. Etkileşimli olmayan bir betiği (veya yeniden başlatma gibi önceden tanımlanmış bir eylemi) zaman uyumsuz olarak bir cihaza veya milyonlarca cihaza dağıtabilir ve zaman içinde geliştikçe bile sonuçları raporlayabilirsiniz (örneğin, yeni cihazlar filoya katıldığında).

   Başka bir deyişle, İspanya'daki tüm mevcut ve gelecekteki Ubuntu 20.04 cihazlarında dört komut çalıştırmanız gerektiğini varsayalım. Bunu CommandRunner'ın 4 ayrı sıralı kullanımı olarak düşünmeyin, yükün dört komutunuzu içerdiği CommandRunner'ın tek kullanımı olarak düşünün. Bu arada IoT Hub Yapılandırmaları gibi bir bulut iş akışı, bunun kapsamda olması gereken tüm geçerli ve gelecekteki cihazlara dağıtılmasını sağlayabilir.

Tam nesne modeli

Önemli

Sürüm 1.0.3 (28 Haziran 2022'de yayımlandı), mevcut kullanıcıları etkileyebilecek üye adlarına hataya neden olan değişiklikler içerir. Daha fazla bilgi için bkz. Sürüm 1.0.3'te üye adları PascalCase'ten camelCase'e geçiş

Aşağıdaki bilgiler, nesne modelinin düz istenen/bildirilen görünümlerinin yanı sıra DTDL gelişmiş görünümleri için de geçerlidir. Daha fazla bilgi için bkz . OSConfig kullanıcılarının "düz istenen/bildirilen" ile "DTDL gelişmiş" araç zincirleri hakkında bilmesi gerekenler.

commandArguments (yönetici tarafından ayarlanır)

• Açıklama: Yöneticiden gelen giriş, yeni komut isteğini tetikler veya commandStatus'un yenilenmesini tetikler.

• Yol: properties.desired.CommandRunner.commandArguments (CommandRunner bileşen -->commandArguments yazılabilir özellik)

• Üyeler

  Ad	Tür	Notlar
  Commandıd	string	• Arayan belirtilen istek kimliği; arka plan için yukarıya bakın • commandId boş olduğunda commandArguments yoksayılır • commandId ile eylem arasında etkileşim için aşağıdakilere bakın
  action	enum/int	Aşağıdakiler yeni commandId değeriyle birleştirilmelidir: • 1 (yeniden başlatma) • 2 (kapatma) • 3 (runCommand); özel yapılandırma veya raporlama için kabuk komutu/betiği başlatır Aşağıdakiler daha önce kullanılan bir CommandID ile birleştirilmelidir: • 4 (refreshCommandStatus), commandStatus'un commandId ile tanımlanan belirli bir isteği tanımlamasına neden olur
  Bağımsız değişken	string	• Eylem 1 (yeniden başlatma) veya 2 (kapatma) olduğunda, eylemi tetiklemeden önce gecikmek için isteğe bağlı saniye sayısı • Eylem 3 olduğunda (RunCommand), yürütülecek komut satırı, örneğin ping -c 2 example.com • Başka bir eylem türü için yoksayılır • Azure IoT ikizlerinde 4 KB ile sınırlı olan commandArguments (genellikle bağımsız değişken metni tarafından baskındır) boyutu; daha uzun betikler için bkz . İyi uygulamalar
  singleLineTextResult	boolean	• Eylem 3 olduğunda (Komut Çalıştır), yeni çizgilerin konsol çıkışından çıkarılıp çıkarılmayacağını belirtmek için isteğe bağlı iki durumlu düğme • Başka bir eylem türü için yoksayılır
  timeout	int	• Eylem 3 olduğunda (runCommand), uzun süre çalışan istekler bu kadar saniye sonra sonlandırılır • İsteğe bağlı (varsayılan değer 30'dur) • Başka bir eylem türü için yoksayılır

• IoT Hub ve gerçek cihazlardan örnekler

  • Yeniden başlatma isteği:

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

  • Özel yapılandırma (saat dilimi) isteği:

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

  • Ek örnekler için bkz:

    • Azure IoT ve OSConfig ile cihazları yeniden başlatma veya kapatma
    • Azure IoT ve OSConfig ile özel yapılandırma ve raporlama

commandArguments (cihazdan onay)

• Açıklama: Bu, cihazdaki OSConfig aracısından yönetici tarafından commandArguments değerini aldığına ilişkin onaydır

• Yol: properties.reported.CommandRunner.commandArguments (yazılabilir özelliğin commandArguments cihaz onay bölümü)

• Üyeler:

  Ad	Tür	Notlar
  değer	map	properties.desired.CommandRunner.commandArgumentsYansıtmalı, cihazın çevrimiçi olduğunu ve isteği aldığını gösterir
  Ac	int	Durum kodu, nominal büyük/küçük harf değerdir 200

commandStatus

• Açıklama: Daha önce commandArguments aracılığıyla gönderilen bir isteğin durumunu ve çıkışını verir

• Yol: properties.reported.CommandRunner.commandStatus (CommandRunner bileşen -->commandStatus salt okunur özellik)

• Üyeler

  Ad	Tür	Notlar
  Commandıd	string	• Daha önce alınan isteğin şu anda Commandstatus tarafından açıklandığını tanımlar • Varsayılan olarak en son istek temsil edilir • Çağıran, yukarıda açıklanan refreshCommandStatus mekanizması aracılığıyla belirli bir isteği açıklamak için bu odağı değiştirebilir
  Resultcode	int	İstenen komutun çıkış kodu. Bash'te benzer echo $?
  Currentstate	enum/int	• Nominal büyük/küçük harf değerdir 2 (succeeded) • Olası değerlerin tam listesi için meta verileri görün
  textResult	string	• İstenen komutun konsol çıkışı • Azure IoT ikizlerinde commandStatus (genellikle textResult bileşeni tarafından baskındır) boyutu 4 KB ile sınırlıdır; daha uzun çıkışlar için bkz . İyi uygulamalar

• IoT Hub ve gerçek cihazlardan örnekler

  • Yeniden başlatma sonucu

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

  • Özel yapılandırma (saat dilimi) sonucu:

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

  • Ek örnekler için bkz:

    • Azure IoT ve OSConfig ile cihazları yeniden başlatma veya kapatma
    • Azure IoT ve OSConfig ile özel yapılandırma ve raporlama

Önemli

Sürüm 1.0.3 (28 Haziran 2022'de yayımlandı), mevcut kullanıcıları etkileyebilecek üye adlarına hataya neden olan değişiklikler içerir. Daha fazla bilgi için bkz. Sürüm 1.0.3'te üye adları PascalCase'ten camelCase'e geçiş

Sonraki adımlar

OSConfig senaryolarına ve özelliklerine genel bakış için bkz:

• IoT için OSconfig nedir?

Belirli pratik örnekler için bkz:

• 5 dakika içinde OSConfig (Azure IoT ile) laboratuvar ortamı oluşturma
• Hızlı Başlangıç: OSConfig ve Azure IoT kullanmaya başlamak için sorgu örnekleri
• Neleri sağlayabilir ve yönetebilirim?