Come interagire con la funzionalità CommandRunner di OSConfig e Azure IoT

La maggior parte delle proprietà del dispositivo esposte da OSConfig è discreta e astratta dai dettagli dell'implementazione. Ad esempio, quando si usa HostName.desiredName per impostare il nome host di un dispositivo, non è necessario preoccuparsi del sapore del sistema operativo, sulle dipendenze del runtime di script o sulle sfumature di intervallo.

A volte, tuttavia, potresti voler scambiare semplicità per la flessibilità. Ad esempio:

• È necessario recuperare informazioni personalizzate dal dispositivo, ad esempio la necessità di segnalare i risultati del dispositivo dal punto di ping example.com vista del dispositivo
• È necessario configurare un elemento nel dispositivo in cui non esiste alcuna proprietà desiderata/scrivibile di OSConfig esistente

La funzionalità CommandRunner di OSConfig consente la configurazione personalizzata e la creazione di report tramite comandi/script della shell. Include anche alcune azioni predefinite (arresto, riavvio) che non richiedono script.

Suggerimento

Questo articolo di riferimento descrive i concetti di CommandRunner, il modello di interazione e così via. Per esempi di utilizzo concreto, vedere:

• Riavviare o arrestare i dispositivi con Azure IoT e OSConfig
• Configurazione e creazione di report personalizzati con Azure IoT e OSConfig

Modello di interazione e proprietà/campi chiave

Riepilogo del modello di interazione

Anche se l'utilizzo più dettagliato è possibile (e descritto più avanti in questo articolo), il modello di interazione principale è semplice:

• Si avvia una richiesta di comando scrivendo su desiderata commandArguments nel gemello.
• Si ottengono i risultati leggendo segnalati commandStatus dal gemello.

Importante

I payload illustrati in questo diagramma vengono rimossi per evidenziare il flusso in/out. Per il modello a oggetti completo, inclusi i membri obbligatori non visualizzati qui, vedere: Modello a oggetti completo

L'identificatore round trip è: commandId

Nel diagramma precedente si noti che entrambi commandArguments e commandStatus includono un campo denominato commandId. Si tratta dell'identificatore di round trip che collega la richiesta e il risultato durante questa operazione asincrona.

Il chiamante (admin o admin toolchain) sceglie il valore commandId.

Suggerimento

commandId è obbligatorio in commandArguments. I chiamanti usano in genere uno di questi modelli quando si scelgono i valori:

• Valori monotonici come "1" (per la prima richiesta), "2" (per la seconda richiesta) e così via. o valori descrittivi come "my_ping_command"

  Questi sono ben adatti per l'esplorazione ad hoc; non richiedono la pianificazione e possono essere digitati facilmente durante la modifica di contenuti gemelli

• Valori generati automaticamente ad alta entropia, ad esempio UUID

  Questi sono adatti per l'utilizzo a livello di codice su larga scala in cui un back-end della soluzione cloud creerà e mantiene traccia dei valori a livello di codice

Nuovo valore di nei commandArguments segnali che si tratta di commandId una nuova richiesta. Nel contesto di un singolo dispositivo gemello, popolando un nuovo commandId è approssimativamente analogo al raggiungimento di "Invio" in un ambiente shell.

commandId consente inoltre di tenere traccia di più richieste. CommandRunner in ogni dispositivo può ricevere (e segnalare lo stato) più richieste nel tempo. Nel frattempo, i commandArguments componenti e commandStatus nel gemello di ogni dispositivo possono descrivere una sola richiesta in qualsiasi momento. commandId è l'identificatore round trip che consente al chiamante di comprendere (e controllare) quale richiesta precedente è attualmente descritta da commandStatus. In effetti, commandStatus comunica "per la richiesta in cui l'ID era "foo", lo stato è <...>".

Quando viene commandStatus aggiornato?

Esistono due trigger per CommandRunner nel dispositivo per aggiornare commandStatus.

1. Aggiornamento in background

   commandStatus viene aggiornato a intervalli regolari (il valore predefinito è 30 secondi). Per impostazione predefinita, questo aggiornamento in background causa la rappresentazione dello stato della richiesta più recente.

   In pratica, ciò significa che dopo aver inviato una richiesta tramite il comandoArguments, è possibile prevedere di visualizzare lo stato corrispondente in commandStatus dopo circa 30-60 secondi.

2. refreshCommandStatus

   refreshCommandStatus è un meccanismo che risolve due casi d'uso avanzati:

   1. Sono state inviate più richieste nel tempo tramite commandArgumentse si vuole visualizzare lo stato per una richiesta specifica, non la richiesta più recente
   2. Non si vuole attendere l'aggiornamento in background, anche se si è interessati solo alla richiesta più recente

   Per attivare questo meccanismo, vedere la documentazione del modello a oggetti seguente per commandArguments.

Procedure consigliate per la configurazione personalizzata e la creazione di report con CommandRunner

1. Considerazioni sulle dimensioni

   Per brevi comandi/script e output brevi, è possibile lavorare direttamente inline tramite il gemello. Questo approccio offre vantaggi, soprattutto senza dipendenze di rete o autenticazione all'esterno della hub IoT. Lo svantaggio principale di questo approccio è che gli input (inclusi il testo script/comandi) e gli output (inclusi gli output della console acquisita) sono limitati a 4 KB.

   Per gli script più lunghi, è possibile archiviare lo script altrove (ad esempio GitHub) e chiamarlo da un comando wrapper minimo passato a OSConfig sul gemello. Per esempi, vedere Configurazione personalizzata e creazione di report con Azure IoT e OSConfig. Indipendentemente dalla dimensione, è anche consigliabile gestire gli script in GitHub o simili, con contenuti gemelli che puntano semplicemente a quelli.

   Per gli script/comandi di cui l'output della console è troppo grande per il gemello, è possibile includere la logica nello script per inviare i risultati all'archiviazione locale o cloud anziché a stdout. Per esempi, vedere Configurazione personalizzata e creazione di report con Azure IoT e OSConfig.

2. Usare comandi autonomi e non interattivi/script

   Meno round trip sono migliori, un round trip è migliore. OSConfig e CommandRunner sono ottimizzati per la scalabilità non interattività. Anche se è possibile usare CommandRunner serialmente (un comando dopo un altro, simile a un terminale sincrono live) l'esperienza non è ottimale. Non è possibile gestire i prompt interattivi della shell, è necessario assegnare un commandId oggetto a ogni richiesta, è necessario attendere la sincronizzazione dei gemelli e così via.

   Si pensi invece a CommandRunner come un modo per ottenere la configurazione personalizzata e la creazione di report su larga scala. È possibile distribuire in modo asincrono uno script non interattivo (o un'azione predefinita come il riavvio) a un dispositivo o a milioni di dispositivi e può segnalare i risultati anche quando si evolve nel tempo (ad esempio nuovi dispositivi si uniscono alla flotta).

   In altre parole, si supponga di dover eseguire quattro comandi su tutti i dispositivi Ubuntu 20.04 correnti e futuri in Spagna. Non pensare a questo come 4 usi sequenziali discreti di CommandRunner, considerarlo come un singolo uso di CommandRunner in cui il payload contiene i quattro comandi. Nel frattempo, un flusso di lavoro cloud, ad esempio hub IoT Configurazioni, può assicurarsi che questo sia distribuito a tutti i dispositivi correnti e futuri che devono trovarsi nell'ambito.

Modello a oggetti completo

Importante

La versione 1.0.3 (pubblicata 28 giugno 2022) include modifiche di rilievo ai nomi dei membri che potrebbero influire sugli utenti esistenti. Per altre informazioni, vedere: I nomi dei membri passano da PascalCase a camelCase nella versione 1.0.3

Le informazioni seguenti si applicano alle visualizzazioni desiderate/segnalate in modo normale del modello a oggetti e alle viste avanzate DTDL. Per altre informazioni, vedere Informazioni sugli utenti di OSConfig su "normale desiderato/segnalato" rispetto alle toolchain avanzate di DTDL.

commandArguments (impostato da amministratore)

• Descrizione: l'input dall'amministratore attiva una nuova richiesta di comando o attiva l'aggiornamento dei comandiStatus.

• Path: properties.desired.CommandRunner.commandArguments (CommandRunner componente -->commandArguments proprietà scrivibile)

• Members

  Nome	Type	Note
  Commandid	string	• ID richiesta specificato dal chiamante; vedere sopra per lo sfondo • il comandoArguments viene ignorato quando commandId è vuoto • Per l'interazione tra commandId e azione, vedere quanto segue
  azione	enum/int	Il comando seguente deve essere associato a un nuovo valore di commandId: • 1 (riavvio) • 2 (arresto) • 3 (runCommand); avvia il comando/lo script della shell per la configurazione personalizzata o la creazione di report Il comando seguente deve essere associato a un commandID usato in precedenza: • 4 (refreshCommandStatus) causa il comandoStatus per descrivere una richiesta specifica identificata da commandId
  argomenti	string	• Quando l'azione è 1 (riavvio) o 2 (arresto), un numero facoltativo di secondi da ritardare prima di attivare l'azione • Quando l'azione è 3 (RunCommand), la riga di comando da eseguire, ad esempio ping -c 2 example.com • Ignorato per qualsiasi altro tipo di azione • Dimensioni del comandoArguments (in genere dominato da argomenti di testo) in Gemelli IoT di Azure in limitato a 4 KB; per gli script più lunghi, vedere Procedure consigliate
  SingleLineTextResult	boolean	• Quando l'azione è 3 (RunCommand), opzione facoltativa per specificare se le nuove linee devono essere rimosse dall'output della console • Ignorato per qualsiasi altro tipo di azione
  timeout	INT	• Quando l'azione è 3 (runCommand), le richieste a esecuzione prolungata vengono eliminate dopo questo numero di secondi • Facoltativo (impostazione predefinita è 30) • Ignorato per qualsiasi altro tipo di azione

• Esempi di hub IoT e dispositivi reali

  • Richiesta di riavvio:

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

  • Richiesta di configurazione personalizzata (fuso orario):

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

  • Per altri esempi, vedere:

    • Riavviare o arrestare i dispositivi con Azure IoT e OSConfig
    • Configurazione e creazione di report personalizzati con Azure IoT e OSConfig

commandArguments (riconoscimento dal dispositivo)

• Descrizione: questo è il riconoscimento dell'agente OSConfig nel dispositivo che ha ricevuto il valore commandArguments dal lato amministratore

• Percorso: properties.reported.CommandRunner.commandArguments (parte di riconoscimento del dispositivo della commandArguments proprietà scrivibile)

• Membri:

  Nome	Type	Note
  Valore	map	Deve eseguire il mirroring properties.desired.CommandRunner.commandArguments, che indica il dispositivo online e ha ricevuto la richiesta
  ac	INT	Codice di stato, la maiuscola nominale è il valore 200

commandStatus

• Descrizione: fornisce lo stato e l'output di una richiesta inviata in precedenza tramite il comandoArguments

• Percorso: properties.reported.CommandRunner.commandStatus (CommandRunner componente ->commandStatus proprietà di sola lettura)

• Members

  Nome	Type	Note
  Commandid	string	• Identifica la richiesta ricevuta in precedenza descritta da Commandstatus • Per impostazione predefinita, la richiesta più recente è rappresentata • Il chiamante può modificare questo stato attivo per descrivere una richiesta specifica tramite il meccanismo refreshCommandStatus descritto in precedenza
  resultCode	INT	Codice di uscita del comando richiesto. Analogo a echo $? in bash
  Currentstate	enum/int	• Il caso nominale è valore 2 (succeeded) • Vedere i metadati per l'elenco completo dei valori possibili
  textResult	string	• Output della console del comando richiesto • Dimensione del comandoStatus (in genere dominata dal componente textResult) in Gemelli IoT di Azure in limitato a 4 KB; per gli output più lunghi, vedere Procedure consigliate

• Esempi di hub IoT e dispositivi reali

  • Risultato riavvio

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

  • Risultato della configurazione personalizzata (fuso orario):

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

  • Per altri esempi, vedere:

    • Riavviare o arrestare i dispositivi con Azure IoT e OSConfig
    • Configurazione e creazione di report personalizzati con Azure IoT e OSConfig

Importante

La versione 1.0.3 (pubblicata 28 giugno 2022) include modifiche di rilievo ai nomi dei membri che potrebbero influire sugli utenti esistenti. Per altre informazioni, vedere: I nomi dei membri passano da PascalCase a camelCase nella versione 1.0.3

Passaggi successivi

Per una panoramica degli scenari e delle funzionalità osConfig, vedere:

• Che cos'è OSconfig per IoT

Per esempi pratici specifici, vedere:

• Creare un ambiente lab OSConfig (con Azure IoT) in 5 minuti
• Guida introduttiva: Esempi di query per iniziare a usare OSConfig e Azure IoT
• Cosa è possibile effettuare il provisioning e gestire?