Condividi tramite

Interfaccia della riga di comando di Azure Sphere

  • Articolo

Importante

Questa è la documentazione di Azure Sphere (legacy). Azure Sphere (legacy) viene ritirato il 27 settembre 2027 e gli utenti devono eseguire la migrazione ad Azure Sphere (integrato) entro questo periodo. Usare il selettore di versione posizionato sopra il sommario per visualizzare la documentazione di Azure Sphere (integrata).

Azure Sphere SDK fornisce l'interfaccia della riga di comando di Azure Sphere disponibile nella shell dei comandi di PowerShell, del prompt dei comandi di Windows o linux. L'interfaccia della riga di comando di Azure Sphere è un set di comandi usati per creare e gestire le risorse di Azure Sphere.

L'interfaccia della riga di comando di Azure Sphere viene installata insieme all'interfaccia della riga di comando classica di Azure Sphere sia in Windows che in Linux, quindi è possibile accedere a entrambe le interfacce. Per usare l'interfaccia della riga di comando di Azure Sphere:

  • In Windows usare PowerShell o un prompt dei comandi di Windows standard.
  • In Linux usare qualsiasi shell dei comandi.

Eseguire l'interfaccia della riga di comando di Azure Sphere

È ora possibile eseguire l'interfaccia della riga di comando di Azure Sphere con il azsphere comando dal prompt dei comandi di Windows o da PowerShell. È consigliabile usare PowerShell perché offre la funzionalità di completamento della scheda che non è disponibile dal prompt dei comandi di Windows.

In Linux è possibile eseguire l'interfaccia della riga di comando di Azure Sphere da qualsiasi interfaccia della riga di comando. Durante l'installazione viene visualizzata una notifica che consente di impostare l'interfaccia della riga di comando di Azure Sphere o l'interfaccia della riga di comando classica di Azure Sphere come versione predefinita preferita dell'interfaccia della riga di comando. Digitare Yes per scegliere l'interfaccia della riga di comando di Azure Sphere o il tipo No per usare l'interfaccia della riga di comando classica di Azure Sphere. Per altre informazioni, vedere Installare Azure Sphere SDK .

Nota

Il formato breve per i comandi non è supportato nella versione dell'interfaccia della riga di comando di Azure Sphere. È consigliabile usare la funzionalità di completamento tramite tabulazione per visualizzare l'elenco dei comandi disponibili. In Windows, il collegamento al prompt dei comandi per gli sviluppatori classici di Azure Sphere può essere usato solo con l'interfaccia della riga di comando classica di Azure Sphere.

Funzionalità di input dell'interfaccia della riga di comando

Questa sezione descrive le funzionalità di input disponibili nell'interfaccia della riga di comando di Azure Sphere:

Comandi

Tutti i comandi nell'interfaccia della riga di comando di Azure Sphere iniziano con azsphere. Ad esempio:

azsphere login
 ---------------------
 Name
 =====================
 bob@contoso.com
 ---------------------

Trovare i comandi

I comandi nell'interfaccia della riga di comando sono organizzati in gruppi. È possibile visualizzare informazioni della Guida complete per i comandi e i parametri disponibili usando --help l'interfaccia della riga di comando classica di Azure Sphere e l'interfaccia della riga di comando di Azure Sphere.

È possibile ottenere un elenco completo dei comandi eseguendo il comando azsphere --help.

Ad esempio:

  • Per l'uso dell'interfaccia della riga di comando azsphere --help classica di Azure Sphere o azsphere -?
  • Per l'uso dell'interfaccia della riga di comando azsphere --help di Azure Sphere o azsphere -h

Parametri

Il nome del parametro è preceduto da trattini doppi (--), che segnala che la parola che segue il trattino è un parametro. Usare uno spazio per separare il nome e il valore del parametro. I parametri composti sono separati da un trattino (-) nella nuova interfaccia della riga di comando.

Ad esempio: --component-id o --application-update

Identificazione semplificata degli oggetti

Nell'interfaccia della riga di comando di Azure Sphere viene usato un singolo parametro per identificare ogni tipo di oggetto. Ciò significa che è possibile specificare l'ID, il nome, l'IP o la posizione applicabili per tale parametro.

Ad esempio, è possibile usare l'ID tenant o il nome del tenant nel comando seguente:

azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb

or

azsphere device list --tenant MyTenant

Questa operazione è stata implementata per i --deviceparametri , --tenant--product, e --device-group .

Ad esempio:

azsphere device-group update --device-group CoffeeMaker/Development
   ------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
   Id                                   TenantId                             OsFeedType ProductId                            Name      Description            UpdatePolicy                                               AllowCrashDumpsCollection
   ===============================================================================================================================================================================================================================================
   7f860cc1-4949-4000-a541-9a988ba4c3cd 143adbc9-1bf0-4be2-84a2-084a331d81cb Retail     6f52bead-700d-4289-bdc2-2f11f774270e Marketing Marketing device group Accept all updates from the Azure Sphere Security Service. False
   ------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------

Più valori

Alcuni comandi consentono più valori per un singolo parametro, nel qual caso è possibile specificare un parametro con ogni valore o un singolo parametro seguito da un elenco di valori separati da spazi. Ad esempio, i due comandi seguenti sono equivalenti:

azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 --executables filepath-2

azsphere image-package pack-application --package-directory myDirectory --destination myImagePackage --executables filepath-1 filepath-2

Parametri obbligatori e facoltativi

Quando si esegue azsphere <command> <sub-command> --help un elenco di parametri applicabili a tale comando viene visualizzato. L'impostazione [Obbligatorio] indica se il parametro è obbligatorio per eseguire correttamente il comando. Tutti gli altri parametri sono facoltativi.

Se il parametro obbligatorio manca, viene richiesto un valore per il parametro .

Ad esempio:

azsphere role delete --help

Command
    azsphere role delete : Deletes a role from a user in the current Azure Sphere tenant.

Arguments
    --role -r [Required] : Role to be deleted. Values from: azsphere role show-types.
    --user -u [Required] : The user from whom the role is being deleted. Specify user e-mail.
                           Values from: azsphere role list.

Tenant Selection Arguments
    --tenant -t          : The tenant to perform this operation in. Overrides the default selected
                           tenant. Specify tenant ID or tenant name. Values from: azsphere tenant
                           list.

Global Arguments
    --debug              : Increase logging verbosity to show all debug logs.
    --help -h            : Show this help message and exit.
    --only-show-errors   : Only show errors, suppressing warnings.
    --output -o          : Output format. Allowed values: json, jsonc, none, table, tsv, yaml,
                           yamlc. Default: table.
    --query              : JMESPath query string. See http://jmespath.org/ for more information and
                           examples.
    --verbose            : Increase logging verbosity. Use --debug for full debug logs.

Percorsi di input e output

Nell'interfaccia della riga di comando di Azure Sphere i nomi dei parametri usati per specificare un percorso e un nome file sono stati aggiornati in modo che siano rilevanti per il contesto del comando.

Ad esempio:

azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage

In questo caso, --package-directory specifica la directory di input per il pacchetto e --destination il parametro specifica il percorso e il nome file per il pacchetto immagine risultante.

Completamento tramite tasto TAB

Il completamento tramite tabulazione consente di completare automaticamente una voce di comando nell'interfaccia della riga di comando. Il completamento della scheda dell'interfaccia della riga di comando di Azure Sphere è supportato per i gruppi, i comandi, i nomi dei parametri e i valori dei parametri. Digitare alcuni caratteri di un comando e quindi premere TAB per selezionare il testo di completamento desiderato. Se più elementi iniziano con il testo digitato originariamente, continuare a premere TAB fino a quando non verrà visualizzato l'elemento desiderato.

In Windows PowerShell 7.1 offre la funzionalità di completamento della scheda che non è disponibile dal prompt dei comandi di Windows.

Per abilitare il completamento tramite tabulazione in Windows PowerShell, eseguire Import-Module -name AzsphereCli. Questo comando abilita il completamento tramite tabulazione solo per la sessione. È possibile aggiungere uno script al profilo di PowerShell per personalizzare l'ambiente e abilitare il completamento tramite tabulazione per ogni sessione di PowerShell avviata.

In Linux l'interfaccia della riga di comando di Azure Sphere supporta la funzionalità di completamento tramite tabulazione per i comandi nella shell Bash.

Inoltre, il completamento automatico consente di individuare comandi, parametri e valori dei parametri disponibili per l'uso. Questa opzione è disponibile usando CTRL+SPAZIO in Windows PowerShell o premere TAB due volte nella shell Bash di Linux.

Ad esempio, digitare il comando azsphere product update e usare il completamento automatico per visualizzare un elenco dei parametri disponibili.

Parametri di completamento automatico di PowerShell

Analogamente, digitare azsphere product update --product e usare il completamento automatico per visualizzare un elenco dei prodotti disponibili nel tenant.

Prodotti di completamento automatico di PowerShell

Modalità interattiva (anteprima)

Importante

Questa funzionalità si trova in anteprima. Potrebbe essere modificato o rimosso in una versione futura.

La nuova interfaccia della riga di comando offre una modalità interattiva che visualizza automaticamente le informazioni della Guida e semplifica la selezione dei comandi, i sottocom command, i parametri e i valori dei parametri. Immettere la modalità interattiva con il comando azsphere interactive. Il prompt dei comandi cambia per azsphere>> indicare che sono ora in esecuzione comandi nella shell interattiva. Per altre informazioni, vedere Modalità interattiva dell'interfaccia della riga di comando di Azure Sphere.

Modalità interattiva di Azure Sphere

Funzionalità di output dell'interfaccia della riga di comando

Questa sezione illustra le funzionalità di output disponibili nell'interfaccia della riga di comando di Azure Sphere:

Le sezioni seguenti descrivono le funzionalità di output disponibili nella nuova interfaccia della riga di comando:

Formati di output supportati

I formati di output disponibili nella nuova interfaccia della riga di comando sono json, jsonc (JSON con colori), tsv (valori separati da tabulazioni), table (tabelle ASCII leggibili) e yaml. Per impostazione predefinita, l'output dell'interfaccia della riga di comando è in formato table. Per altre informazioni sui formati di output disponibili, vedere Formati di output supportati per l'interfaccia della riga di comando di Azure Sphere.

Reindirizzamento e paginazione

L'interfaccia della riga di comando di Azure Sphere non supporta l'impaginazione interattiva. È tuttavia possibile reindirizzare l'output standard di un comando a un file. Nell'esempio seguente, per il prompt dei comandi di Windows, Windows PowerShell e la shell Bash Linux l'output standard viene inviato a output.txt e viene inviato un errore standard a logs.txt.

azsphere device list --verbose > output.txt 2> logs.txt

È anche possibile impaginare l'output sullo schermo tramite pipe agli strumenti di impaginazione esistenti.

Ad esempio:

  • In PowerShell (Windows): azsphere device list | Out-Host –Paging
  • Al prompt dei comandi (Windows): azsphere device list | more
  • Nella shell Bash (Linux): azsphere device list | less

Nota

Questa operazione può essere potenzialmente lenta a seconda della quantità di dati restituiti.

Per altre informazioni sull'impaginazione per l'interfaccia della riga di comando classica di Azure Sphere, vedere Paging e reindirizzamento dei risultati.

Output dei comandi dell'interfaccia della riga di comando di query

L'interfaccia della riga di comando di Azure Sphere usa l'argomento --query per eseguire una query JMESPath sui risultati dei comandi. JMESPath è un linguaggio di query per JSON che offre la possibilità di selezionare e modificare i dati dell'output dell'interfaccia della riga di comando. Le query vengono eseguite nell'output JSON prima di qualsiasi formattazione di visualizzazione.

L'argomento --query è supportato da tutti i comandi nell'interfaccia della riga di comando di Azure Sphere. Per altre informazioni ed esempi, vedere Esercitazione su JMESPath e Eseguire query sull'output dei comandi dell'interfaccia della riga di comando di Azure.

Compatibilità con le versioni precedenti

L'interfaccia della riga di comando supporta la compatibilità con le versioni precedenti. In ogni versione si intende mantenere la compatibilità con le versioni precedenti per entrambi gli input (nomi dei comandi, nomi dei parametri, valori dei parametri) e il relativo output in JSON e YAML. Nei casi in cui tale compatibilità non è possibile, forniremo almeno 6 mesi di preavviso prima di apportare modifiche. Per altre informazioni, vedere Modifiche importanti (ritiro delle funzionalità) nell'interfaccia della riga di comando di Azure Sphere.

Codici di uscita

Un comando riuscito restituisce uno zero. Qualsiasi valore diverso da zero può essere interpretato come codice di errore. In caso di esito positivo, gli output JSON e YAML hanno una garanzia contrattuale compatibile con le versioni precedenti.

Inviare commenti

Se viene rilevato un bug in Azure Sphere, segnalare un problema in GitHub. Per fornire commenti e suggerimenti dalla riga di comando, usare il comando feedback.

Usare l'interfaccia della riga di comando di Azure Sphere in modo efficace

L'interfaccia della riga di comando di Azure Sphere può essere usata da Bash, PowerShell o da una finestra del prompt dei comandi. Ecco alcuni suggerimenti per l'uso dell'interfaccia della riga di comando:

  • Uso delle virgolette nei valori: se si specifica un parametro un valore che include spazi, racchiuderlo tra virgolette. In Bash o PowerShell le virgolette singole e doppie vengono interpretate. Nel prompt dei comandi di Windows vengono interpretate solo virgolette doppie. Le virgolette singole vengono interpretate come parte del valore. Ad esempio: azsphere product create --name "My Fridge Product". Per altre informazioni, vedere Virgolette e caratteri di escape.
  • Molti comandi di Azure Sphere mostrano informazioni nella console nel formato predefinito table . Ad esempio: azsphere product device-group list --product DW100. A volte le informazioni visualizzate non si adattano correttamente alla console. Ciò può causare problemi se si desidera copiare e incollare le informazioni. È consigliabile provare le opzioni seguenti:
    • Ridimensionare la console ed eseguire di nuovo il comando.
    • Usare l'output JSON per scopi di output e scripting concisi. Ad esempio: azsphere product device-group list --product DW100 --output json.
    • Usare il completamento tramite tabulazione in Windows PowerShell o nella shell Bash per completare automaticamente una voce di comando.
    • Usare la modalità interattiva che fornisce un ambiente interattivo per visualizzare automaticamente le informazioni e semplifica la selezione dei comandi e dei sottocom commandi. Immettere la modalità interattiva con il comando azsphere interactive. Il prompt dei comandi cambia in azsphere>> per indicare che sono ora in esecuzione comandi nella shell interattiva.

Vedi anche