Azure Sphere CLI
O SDK do Azure Sphere fornece a CLI (interface de linha de comando) do Azure Sphere disponível no PowerShell, no Prompt de Comando do Windows ou no shell de comando do Linux. A CLI do Azure Sphere é um conjunto de comandos usados para criar e gerenciar recursos do Azure Sphere.
A CLI do Azure Sphere está instalada junto com a CLI clássica do Azure Sphere em retirada no Windows e no Linux, para que você tenha acesso a qualquer interface. Para usar a CLI do Azure Sphere:
- No Windows, use o PowerShell ou um prompt de comando padrão do Windows.
- No Linux, use qualquer shell de comando.
Executar a CLI do Azure Sphere
Agora você pode executar a CLI do Azure Sphere com o azsphere comando do Prompt de Comando do Windows ou do PowerShell. Recomendamos o PowerShell, pois ele oferece o recurso de conclusão da guia que não está disponível no Prompt de Comando do Windows.
No Linux, você pode executar a CLI do Azure Sphere em qualquer CLI (interface de linha de comando). Durante a instalação, uma notificação é exibida que permite definir a CLI do Azure Sphere ou a CLI clássica do Azure Sphere como a versão da CLI padrão preferencial.
Digite Yes para escolher a CLI do Azure Sphere ou digite No para usar a CLI clássica do Azure Sphere. Consulte Instalar o SDK do Azure Sphere para obter mais informações.
Nota
O formulário curto para comandos não tem suporte na versão da CLI do Azure Sphere. Recomendamos que você use o recurso de conclusão da guia para exibir a lista de comandos disponíveis. No Windows, o atalho do Prompt de Comando clássico do Desenvolvedor do Azure Sphere só pode ser usado com a CLI clássica do Azure Sphere.
Recursos de entrada da CLI
Esta seção descreve os recursos de entrada disponíveis na CLI do Azure Sphere:
Comandos
Todos os comandos na CLI do Azure Sphere começam com azsphere. Por exemplo:
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Localizar comandos
Os comandos na CLI são organizados em grupos. Você pode exibir informações completas de ajuda para os comandos e parâmetros disponíveis usando --help na CLI clássica do Azure Sphere e na CLI do Azure Sphere.
Você pode obter uma lista completa de comandos executando o comando azsphere --help.
Por exemplo:
- Para o uso da CLI clássica do Azure Sphere,
azsphere --helpouazsphere -? - Para uso da CLI do Azure Sphere ou
azsphere --helpazsphere -h
Parâmetros
O nome do parâmetro é precedido por hifens duplos (--), que sinaliza que a palavra que segue o hífen é um parâmetro. Use um espaço para separar o nome e o valor do parâmetro. Os parâmetros que são palavras compostas são separados com um hifen (-) na nova CLI.
Por exemplo: --component-id ou --application-update
Identificação simplificada de objeto
Na CLI do Azure Sphere, um único parâmetro é usado para identificar cada tipo de objeto. Isso significa que você pode fornecer a ID, nome, IP ou local aplicável a esse parâmetro.
Por exemplo, você pode usar a ID do locatário ou o nome do locatário no seguinte comando:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
Ou
azsphere device list --tenant MyTenant
Isso foi implementado para os --deviceparâmetros , --tenant, --producte --device-group .
Por exemplo:
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
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Vários valores
Alguns comandos permitem vários valores para um único parâmetro, nesse caso, você pode fornecer um parâmetro com cada valor ou um único parâmetro seguido por uma lista de valores separados por espaços. Por exemplo, os dois comandos a seguir são equivalentes:
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
Parâmetros obrigatórios e opcionais
Quando você executa azsphere <command> <sub-command> --help uma lista de parâmetros aplicáveis a esse comando é exibida. A configuração [Obrigatório] indica se o parâmetro é obrigatório para executar o comando com êxito. Todos os outros parâmetros são opcionais.
Se o parâmetro necessário estiver ausente, você será solicitado a obter um valor para o parâmetro.
Por exemplo:
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.
Caminhos de entrada e saída
Na CLI do Azure Sphere, os nomes de parâmetro usados para especificar um caminho e um nome de arquivo foram atualizados para serem relevantes para o contexto do comando.
Por exemplo:
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
Aqui, --package-directory especifica o diretório de entrada do pacote e --destination o parâmetro especifica o caminho e o nome do arquivo para o pacote de imagem resultante.
Conclusão da guia
A conclusão da guia fornece ajuda para concluir automaticamente uma entrada de comando na interface de linha de comando. Na conclusão da guia CLI do Azure Sphere há suporte para grupos, comandos, nomes de parâmetros e valores de parâmetro. Digite alguns caracteres de um comando e pressione TAB para selecionar o texto de conclusão desejado. Se vários itens começarem com o texto que você digitou inicialmente, continue pressionando TAB até que o item desejado seja exibido.
No Windows, o PowerShell 7.1 oferece o recurso de conclusão da guia que não está disponível no Prompt de Comando do Windows.
Para habilitar a conclusão da guia no Windows PowerShell, execute Import-Module -name AzsphereCli.
Esse comando habilita a conclusão da guia somente para a sessão. Você pode adicionar um script ao seu perfil do PowerShell para personalizar seu ambiente e habilitar a conclusão da guia para cada sessão do PowerShell iniciada.
No Linux, a CLI do Azure Sphere dá suporte ao recurso de conclusão da guia para comandos no shell bash.
Além disso, a autocompilação ajuda você a descobrir comandos, parâmetros e valores de parâmetro que estão disponíveis para uso. Isso está disponível usando CTRL+Space em Windows PowerShell ou pressione TAB duas vezes no shell do Linux Bash.
Por exemplo, digite o comando azsphere product update e use a autocompletion para ver uma lista de parâmetros disponíveis.
Da mesma forma, digite azsphere product update --product and use autocompletion para ver uma lista de produtos disponíveis em seu locatário.
Modo interativo (versão prévia)
Importante
Esse recurso está em versão prévia. Ele pode ser alterado ou removido em uma versão futura.
A nova CLI oferece um modo interativo que exibe automaticamente informações de ajuda e facilita a seleção de comandos, subconjuntos, parâmetros e valores de parâmetro. Insira o modo interativo com o comando interativo do azsphere . O prompt de comando é alterado para azsphere>> indicar que agora você está executando comandos no shell interativo.
Para obter mais informações, confira Modo interativo da CLI do Azure Sphere.
Recursos de saída da CLI
Esta seção explica os recursos de saída disponíveis na CLI do Azure Sphere:
As seções a seguir descrevem os recursos de saída disponíveis na nova CLI:
Formatos de saída com suporte
Os formatos de saída disponíveis na nova CLI são json, jsonc (JSON colorido), tsv (Valores Separados por Guia), table (tabelas ASCII legíveis pelo homem) e yaml. Por padrão, a CLI gera table. Para saber mais sobre os formatos de saída disponíveis, consulte Formatos de saída com suporte para a CLI do Azure Sphere.
Redirecionamento e paginação
A CLI do Azure Sphere não dá suporte a paginação interativa. No entanto, você pode redirecionar a saída padrão de um comando para um arquivo. No exemplo a seguir, para o shell prompt, Windows PowerShell e Linux Bash do Windows, a saída padrão é enviada para output.txt e o erro padrão é enviado para logs.txt.
azsphere device list --verbose > output.txt 2> logs.txt
Você também pode paginar a saída na tela canalizando para ferramentas de paginação existentes.
Por exemplo:
- No PowerShell (Windows):
azsphere device list | Out-Host –Paging - Em um prompt de comando (Windows):
azsphere device list | more - No shell bash (Linux):
azsphere device list | less
Nota
Essa operação pode ser potencialmente lenta dependendo da quantidade de dados retornados.
Para obter mais informações sobre paginação para a CLI clássica do Azure Azure Sphere, consulte Paging e redirecionamento de resultados.
Saída de comando da CLI de consulta
A CLI do Azure Sphere usa o --query argumento para executar uma consulta JMESPath nos resultados dos comandos. JMESPath é uma linguagem de consulta para JSON, dando a você a capacidade de selecionar e modificar dados da saída da CLI. As consultas são executadas na saída JSON antes de qualquer formatação de exibição.
O --query argumento é compatível com todos os comandos na CLI do Azure Sphere. Consulte o tutorial JMESPath e a saída de comando da CLI do Azure para obter mais informações e exemplos.
Compatibilidade com versões anteriores
A CLI dá suporte à compatibilidade com versões anteriores. Em cada versão, pretendemos manter a compatibilidade com versões anteriores para entrada (nomes de comando, nomes de parâmetro, valores de parâmetro) e sua saída em JSON e YAML. Nos casos em que essa compatibilidade não for possível, forneceremos pelo menos seis meses de aviso prévio antes de fazer alterações. Para obter mais informações, confira Alterações importantes (desativação de recursos) na CLI do Azure Sphere.
Sair de códigos
Um comando bem-sucedido retorna um zero. Qualquer valor não zero pode ser interpretado como um código de erro. Após o sucesso, as saídas JSON e YAML têm uma garantia contratual compatível com o atraso.
Fornecer comentários
Se você encontrar um bug no Azure Sphere, arquive um problema no GitHub. Para fornecer comentários da linha de comando, use o comando de comentários.
Usar a CLI do Azure Sphere efetivamente
A CLI do Azure Sphere pode ser usada na janela Bash, PowerShell ou prompt de comando. Veja algumas dicas para usar a CLI:
- Usando aspas em valores: se você fornecer um parâmetro um valor que inclua espaços, inclua-o entre aspas. Em Bash ou PowerShell, aspas simples e duplas são interpretadas. No Prompt de Comando do Windows, somente aspas duplas são interpretadas. As aspas individuais são interpretadas como parte do valor. Por exemplo,
azsphere product create --name "My Fridge Product". Para obter mais informações, consulte Aspas e os caracteres de escape. - Muitos comandos do Azure Sphere mostram informações no console no formato padrão
table. Por exemplo,azsphere product device-group list --product DW100. Às vezes, as informações exibidas não se encaixam corretamente no console. Isso pode causar problemas se você quiser copiar e colar as informações. Recomendamos experimentar as seguintes opções:- Redimensione o console e execute o comando novamente.
- Use a saída JSON para fins concisos de saída e script. Por exemplo,
azsphere product device-group list --product DW100 --output json. - Use a conclusão da guia em Windows PowerShell ou shell bash para concluir automaticamente uma entrada de comando.
- Use o modo interativo que fornece um ambiente interativo para exibir automaticamente informações e facilita a seleção de comandos e sub-comandos. Insira o modo interativo com o comando interativo do azsphere . O prompt de comando muda para a azsphere>> para indicar que agora você está executando comandos no shell interativo.