OSConfig と Azure IoT の CommandRunner 機能を操作する方法

OSConfig によって公開されるほとんどのデバイスプロパティは不連続であり、実装の詳細から抽象化されます。たとえば、を使用 HostName.desiredName してデバイスのホスト名を設定する場合、オペレーティングシステムのフレーバー、ランタイムの依存関係のスクリプト化、タイミングの微妙な違いについて心配する必要はありません。

ただし、柔軟性のためにシンプルさを交換したい場合もあります。次に例を示します。

デバイスからカスタム情報を取得する必要があります。たとえば、デバイスの観点からの ping example.com 結果を報告する必要がある
既存の OSConfig desired/writable プロパティがないデバイスで何かを構成する必要がある

OSConfig の CommandRunner 機能を使用すると、シェルコマンド/スクリプトを使用したカスタム構成とレポートが可能になります。また、スクリプトを必要としない特定の定義済みアクション (シャットダウン、再起動) も含まれます。

ヒント

このリファレンス記事では、CommandRunner の概念、相互作用モデルなどについて説明します。具体的な使用例については、次を参照してください。

相互作用モデルと主要なプロパティ/フィールド

相互作用モデルの概要

より微妙な使用法が可能ですが (この記事の後半で説明します)、コア相互作用モデルは簡単です。

コマンド要求を開始するには、ツインで desired commandArguments に書き込みます。
ツインから報告された commandStatus 値を読み取ると、結果が得られます。

commandArguments と commandStatus を示す図

重要

この図に示されているペイロードは、イン/アウトフローを強調するために削除されます。ここに示されていない必須メンバーを含む完全なオブジェクトモデルについては、「完全なオブジェクトモデル」を参照してください。

ラウンドトリップ識別子は次のとおりです。 `commandId`

上の図では、と commandStatus の両方commandArgumentsにというcommandIdフィールドが含まれることに注意してください。これは、この非同期操作全体の要求と結果をリンクするラウンドトリップ識別子です。

呼び出し元 (admin または admin ツールチェーン) が commandId 値を選択します。

ヒント

commandId はで commandArguments必要です。呼び出し元は、通常、値を選択するときに、次のいずれかのパターンを使用します。

"1" (最初の要求の場合)、"2" (2 番目の要求の場合) などの単調な値。または "my_ping_command" などの説明値

これらはアドホック探索に適しています。計画を必要とせず、ツインコンテンツを編集するときに簡単に入力できます
UUID などの高エントロピ自動生成値

これらは、クラウドソリューションバックエンドがプログラムによって値を作成して追跡する大規模なプログラムによる使用に適しています

の commandArguments の新しい値commandIdは、これが新しい要求であることを示します。単一のデバイスのツインのコンテキストでは、新しい commandId デバイスを設定することは、シェル環境で "Enter" にヒットするのとほぼ同じです。

commandId また、複数の要求を追跡することもできます。各デバイスの CommandRunner は、時間の経過と同時に複数の要求を受信 (および状態報告) できます。一方、 commandArguments 各デバイスのツインのおよび commandStatus コンポーネントは、いつでも 1 つの要求のみを記述できます。 commandId はラウンドトリップ識別子であり、呼び出し元は、によって commandStatus現在記述されている以前の要求を理解 (および制御) できます。実際には、 commandStatus は "id が 'foo' であった要求に対して、状態は <...>" と通信します。

いつ更新されますか `commandStatus` ?

デバイスで CommandRunner を更新 commandStatusするには、2 つのトリガーがあります。

バックグラウンド更新

commandStatus は定期的に更新されます (既定値は 30 秒)。既定では、このバックグラウンド更新により、最新の要求の状態が表されます。

実際には、これは、commandArguments を使用して要求を送信した後、約 30 から 60 秒後に commandStatus に対応する状態が表示されることを期待できることを意味します。
refreshCommandStatus

refreshCommandStatus は、2 つの高度なユースケースに対応するメカニズムです。
1. を使用して時間の経過と commandArguments同時に複数の要求を発行しており、最新の要求ではなく、特定の要求の状態を表示する必要がある
2. 最新の要求にのみ関心がある場合でも、バックグラウンドの更新を待ちたくない
このメカニズムをトリガーするには、のオブジェクトモデルに関するドキュメントを commandArguments参照してください。

CommandRunner を使用したカスタム構成とレポートのベストプラクティス

サイズの考慮事項

短いコマンド/スクリプトと短い出力の場合は、ツインを介して直接インラインで作業できます。この方法には利点があります。特に、IoT Hubの外部にネットワークまたは認証の依存関係はありません。この方法の主な欠点は、入力 (スクリプト/コマンドテキストを含む) と出力 (キャプチャされたコンソール出力を含む) がそれぞれ 4 KB に制限されていることです。

より長いスクリプトの場合は、スクリプトを別の場所 (GitHub など) に格納し、ツイン経由で OSConfig に渡す最小限のラッパーコマンドから呼び出すことができます。例については、「 Azure IoT と OSConfig を使用したカスタム構成とレポート」を参照してください。サイズに関係なく、GitHub または同様のスクリプトを管理することもできます。ツインコンテンツは単にそれらを指します。

コンソール出力がツインに対して大きすぎる scripts/commands の場合は、stdout ではなくオンプレミスまたはクラウドストレージに結果を送信するロジックをスクリプトに含めることができます。例については、「 Azure IoT と OSConfig を使用したカスタム構成とレポート」を参照してください。
自己完結型の非対話型コマンド/スクリプトを使用する

ラウンドトリップが少ない方が良く、1 回のラウンドトリップが最適です。 OSConfig と CommandRunner は、対話機能ではなくスケール用に最適化されています。 CommandRunner をシリアル的に使用することはできますが (1 つのコマンドを 1 つずつ、ライブ同期ターミナルと同様に)、エクスペリエンスは最適ではありません。対話型シェルプロンプトを処理する方法はありません。各要求にを commandId 割り当てる必要があります。ツインの同期を待機する必要があります。

代わりに、CommandRunner は、大規模なカスタム構成とレポートを実現する方法と考えてください。非対話型スクリプト (または再起動などの事前に定義されたアクション) を 1 台のデバイスまたは数百万台のデバイスに非同期的に配布し、(新しいデバイスがフリートに参加するなど) 時間の経過と共に進化しても結果を報告できます。

つまり、スペインのすべての現在および将来の Ubuntu 20.04 デバイスで 4 つのコマンドを実行する必要があるとします。これは、CommandRunner の 4 つの連続した使用とは考えないでください。これは、ペイロードに 4 つのコマンドが含まれている CommandRunner の単一の使用と考えてください。一方、IoT Hub構成などのクラウドワークフローでは、スコープ内にあるすべての現在および将来のデバイスに確実に配布できます。

完全なオブジェクトモデル

重要

バージョン 1.0.3 (2022 年 6 月 28 日公開) には、既存のユーザーに影響を与える可能性があるメンバー名の破壊的変更が含まれています。詳細については、「バージョン 1.0.3 でメンバー名が PascalCase から camelCase に切り替わる」を参照してください。

次の情報は、オブジェクトモデルの単一の必要なビューまたは報告されたビュー、および DTDL 拡張ビューに適用されます。詳細については、「プレーンな desired/reported」ツールチェーンと "DTDL Enhanced" ツールチェーンについて、OSConfig ユーザーが知る必要がある内容に関するページを参照してください。

commandArguments (admin によって設定)

説明: 管理者からの入力。新しいコマンド要求をトリガーするか、commandStatus の更新をトリガーします。
Path: properties.desired.CommandRunner.commandArguments (CommandRunner component -->commandArguments 書き込み可能なプロパティ)

メンバー

名前	Type	Notes
commandId	string	• 呼び出し元が指定した要求 ID。背景については上記を参照してください • commandId が空白の場合、commandArguments は無視されます • commandId と action の間の相互作用については、次を参照してください。
action	enum/int	以下は、新しい値 commandId と組み合わせて使用する必要があります。 • 1 (再起動) • 2 (シャットダウン) • 3 (runCommand);カスタム構成またはレポート用のシェルコマンド/スクリプトを開始します以下は、以前に使用した CommandID と組み合わせて使用する必要があります。 • 4 (refreshCommandStatus) を指定すると、commandStatus は commandId で識別された特定の要求を記述します
引数	string	• アクションが 1 (再起動) または 2 (シャットダウン) の場合、アクションをトリガーするまでに遅延する秒数 (省略可能) • action が 3 (RunCommand) の場合、実行するコマンドライン (例: `ping -c 2 example.com` • 他のアクションの種類では無視されます • Azure IoT ツインの commandArguments のサイズ (通常は引数テキストによって支配されます) は、4 KB に制限されています。より長いスクリプトについては、「適切なプラクティス」を参照してください
singleLineTextResult	boolean	• action が 3 (RunCommand) の場合、オプションのトグルを使用して、コンソール出力から改行を削除するかどうかを指定します • 他のアクションの種類では無視されます
timeout	INT	• アクションが 3 (runCommand) の場合、実行時間の長い要求は、この数秒後に強制終了されます • 省略可能 (既定値は 30) • 他のアクションの種類では無視されます

IoT Hubデバイスと実際のデバイスの例

再起動要求:

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

カスタム構成 (タイムゾーン) 要求:

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

その他の例については、次を参照してください。
- Azure IoT と OSConfig を使用してデバイスを再起動またはシャットダウンする
- Azure IoT と OSConfig を使用したカスタム構成とレポート

commandArguments (デバイスからの受信確認)

説明: これは、管理者側から commandArguments 値を受け取ったデバイス上の OSConfig エージェントからの確認です
パス: properties.reported.CommandRunner.commandArguments (書き込み可能なプロパティのデバイス受信 commandArguments 確認部分)

メンバー:

名前	Type	Notes
value	map	をミラー`properties.desired.CommandRunner.commandArguments`する必要があります。これは、デバイスがオンラインで、要求を受信したことを示します
ac	int	状態コード、名目上のケースは値です `200`

commandStatus

説明: commandArguments を介して以前に送信された要求の状態と出力を示します
パス: properties.reported.CommandRunner.commandStatus (CommandRunner コンポーネント -->commandStatus 読み取り専用プロパティ)

メンバー

名前	Type	Notes
commandId	string	• Commandstatus によって現在説明されている、以前に受信した要求を識別します • 既定では、最新の要求が表されます • 呼び出し元は、前述の refreshCommandStatus メカニズムを使用して特定の要求を記述するように、このフォーカスを変更できます
resultCode	int	要求されたコマンドの終了コード。 bash のに `echo $?` 似ています
currentState	enum/int	• 名目上のケースは値 `2` (`succeeded`) • 使用可能な値の完全な一覧については、メタデータを参照してください
textResult	string	• 要求されたコマンドのコンソール出力 • Azure IoT ツインの commandStatus のサイズ (通常は textResult コンポーネントによって支配されます) は、4 KB に制限されています。より長い出力については、「適切なプラクティス」を参照してください

IoT Hubデバイスと実際のデバイスの例
- 再起動の結果
```
"CommandRunner": {
    "__t": "c",
    "commandStatus": {
       "commandId": "my_reboot_cmd",
       "resultCode": 0,
       "textResult": "",
       "currentState": 2
    }
}
```
- カスタム構成 (タイムゾーン) の結果:
```
"CommandRunner": {
   "__t": "c",
   "commandStatus": {
      "commandId": "my_timezone_cmd",
      "testResult": "Time zone: UTC",
      "statusCode": 0
   }
}
```
- その他の例については、次を参照してください。
  - Azure IoT と OSConfig を使用してデバイスを再起動またはシャットダウンする
  - Azure IoT と OSConfig を使用したカスタム構成とレポート

重要

次のステップ

OSConfig のシナリオと機能の概要については、次を参照してください。

OSconfig for IoT とは

具体的な実用的な例については、次を参照してください。

Last updated on 2023-06-21