CLI do Azure Sphere
Importante
Esta é a documentação do Azure Sphere (Legado). O Azure Sphere (Legado) será desativado em 27 de setembro de 2027 e os usuários devem migrar para o Azure Sphere (Integrado) até esse momento. Use o seletor de versão localizado acima do sumário para exibir a documentação do Azure Sphere (Integrado).
O SDK do Azure Sphere fornece a interface de linha de comando (CLI) 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 é instalada junto com a CLI clássica do Azure Sphere desativada no Windows e no Linux, para que você tenha acesso a qualquer uma das interfaces. 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 de guia que não está disponível no Prompt de Comando do Windows.
No Linux, você pode executar a CLI do Azure Sphere a partir de qualquer interface de linha de comando (CLI). Durante a instalação, é exibida uma notificação que permite definir a CLI do Azure Sphere ou a CLI clássica do Azure Sphere como a versão padrão preferida da CLI.
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 é suportado na versão da CLI do Azure Sphere. Recomendamos que você use o recurso de preenchimento de guias para exibir a lista de comandos disponíveis. No Windows, o atalho desativado do Prompt de Comando do Desenvolvedor do Azure Sphere Classic 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
---------------------
Encontrar comandos
Os comandos na CLI são organizados em grupos. Você pode exibir informações de ajuda completas para os comandos e parâmetros disponíveis usando --help a CLI clássica do Azure Sphere e a CLI do Azure Sphere.
Você pode obter uma lista completa de comandos executando o comando azsphere --help.
Por exemplo:
- Para o uso clássico da CLI do Azure Sphere,
azsphere --helpouazsphere -? - Para uso da CLI do Azure Sphere,
azsphere --helpouazsphere -h
Parâmetros
O nome do parâmetro é precedido por hífenes duplo (--), 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 hífen (-) na nova CLI.
Por exemplo: --component-id ou --application-update
Identificação simplificada de objetos
Na CLI do Azure Sphere, um único parâmetro é usado para identificar cada tipo de objeto. Isso significa que você pode fornecer o ID, nome, IP ou local aplicável para esse parâmetro.
Por exemplo, você pode usar o 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, --product, e --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, caso em que 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 faltando, será solicitado 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âmetros 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 para o pacote e --destination o parâmetro especifica o caminho e o nome do arquivo para o pacote de imagem resultante.
Preenchimento de tabulação
O preenchimento de guias fornece ajuda para concluir automaticamente uma entrada de comando na interface de linha de comando. No Azure Sphere, a conclusão da guia CLI é suportada para grupos, comandos, nomes de parâmetros e valores de parâmetros. 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 apareça.
No Windows, o PowerShell 7.1 oferece o recurso de conclusão de guia que não está disponível no Prompt de Comando do Windows.
Para habilitar o preenchimento de guias no Windows PowerShell, execute Import-Module -name AzsphereCli.
Este comando permite o preenchimento de tabulações apenas para a sessão. Você pode adicionar um script ao seu perfil do PowerShell para personalizar seu ambiente e habilitar o preenchimento de guias para cada sessão do PowerShell que iniciar.
No Linux, a CLI do Azure Sphere dá suporte ao recurso de conclusão de guia para comandos sob o shell Bash.
Além disso, o preenchimento automático ajuda você a descobrir comandos, parâmetros e valores de parâmetros que estão disponíveis para uso. Isso está disponível usando CTRL+Espaço no Windows PowerShell ou pressione TAB duas vezes no shell do Linux Bash.
Por exemplo, digite o comando azsphere product update e use o preenchimento automático para ver uma lista de parâmetros disponíveis.
Da mesma forma, digite azsphere product update --product e use o preenchimento automático para ver uma lista de produtos disponíveis em seu locatário.
Modo interativo (pré-visualização)
Importante
Esta funcionalidade está em pré-visualização. 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, subcomandos, parâmetros e valores de parâmetros. Entre no modo interativo com o comando azsphere interativo. O prompt de comando muda para azsphere>> indicar que você está executando comandos no shell interativo.
Para obter mais informações, consulte 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 suportados
Os formatos de saída disponíveis na nova CLI são json, jsonc (JSON colorido), tsv (Valores separados por tabulação), table (tabelas ASCII legíveis por humanos) e yaml. Por predefinição, a CLI produz table. Para saber mais sobre os formatos de saída disponíveis, consulte Formatos de saída suportados para a CLI do Azure Sphere.
Redirecionamento e paginação
A CLI do Azure Sphere não oferece suporte à 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 Prompt de Comando do Windows, Windows PowerShell e shell Bash do Linux, 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 as 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 Paginação e redirecionamento de resultados.
Saída do comando Query CLI
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-lhe a capacidade de selecionar e modificar dados da saída CLI. As consultas são executadas na saída JSON antes de qualquer formatação de exibição.
O --query argumento é suportado por todos os comandos na CLI do Azure Sphere. Consulte o tutorial JMESPath e a saída do comando Query Azure CLI para obter mais informações e exemplos.
Compatibilidade com versões anteriores
A CLI suporta compatibilidade com versões anteriores. Em cada versão, nosso objetivo é manter a compatibilidade com versões anteriores tanto para a entrada (nomes de comandos, nomes de parâmetros, valores de parâmetros) quanto para sua saída em JSON e YAML. Nos casos em que tal compatibilidade não for possível, forneceremos um aviso prévio de pelo menos 6 meses antes de fazer alterações. Para obter mais informações, consulte Alterações importantes (desativação de recursos) na CLI do Azure Sphere.
Códigos de saída
Um comando bem-sucedido retorna um zero. Qualquer valor diferente de 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 versões anteriores.
Enviar comentários
Se você encontrar um bug no Azure Sphere, registre um problema no GitHub. Para fornecer comentários da linha de comando, use o comando feedback.
Usar a CLI do Azure Sphere de forma eficaz
A CLI do Azure Sphere pode ser usada em Bash, PowerShell ou em uma janela do Prompt de Comando. Aqui estão algumas dicas para usar a CLI:
- Usando aspas em valores: se você fornecer a um parâmetro um valor que inclua espaços, coloque-o entre aspas. No Bash ou PowerShell, aspas simples e duplas são interpretadas. No Prompt de Comando do Windows, apenas aspas duplas são interpretadas. Aspas simples são interpretadas como parte do valor. Por exemplo,
azsphere product create --name "My Fridge Product". Para obter mais informações, consulte Aspas e 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 ajustam corretamente ao console. Isso pode causar problemas se você quiser copiar e colar as informações. Recomendamos tentar as seguintes opções:- Redimensione o console e execute o comando novamente.
- Use a saída JSON para fins de saída concisa e scripting. Por exemplo,
azsphere product device-group list --product DW100 --output json. - Use o preenchimento de tabulação no Windows PowerShell ou no shell Bash para concluir automaticamente uma entrada de comando.
- Use o modo interativo, que fornece um ambiente interativo para exibir informações automaticamente e facilita a seleção de comandos e subcomandos. Entre no modo interativo com o comando azsphere interativo. O prompt de comando muda para azsphere>> para indicar que você está executando comandos no shell interativo.