Azure Sphere CLI
Importante
Esta é a documentação do Azure Sphere (herdado). O Azure Sphere (herdado) 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 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 é 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 comando do Prompt de Comando do Windows ou do azsphere PowerShell. Recomendamos o PowerShell, pois ele oferece o recurso de preenchimento de tabulação, que não está disponível no prompt de comando do Windows.
No Linux, você pode executar a CLI do Azure Sphere de qualquer CLI (interface de linha de comando). 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 preferencial 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.
Observação
Não há suporte para a forma abreviada de comandos na versão da CLI do Azure Sphere. Recomendamos que você use o recurso de preenchimento de tabulação para exibir a lista de comandos disponíveis. No Windows, o atalho do Prompt de Comando do Desenvolvedor Clássico do Azure Sphere desativado só pode ser usado com a CLI clássica do Azure Sphere.
Recursos de entrada 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 de ajuda completas para os comandos e parâmetros disponíveis usando a CLI clássica do Azure Sphere e a --help CLI do Azure Sphere.
Você pode obter uma lista completa de comandos executando o comando azsphere --help.
Por exemplo:
- Para uso
azsphere --helpda CLI clássica do Azure Sphere ouazsphere -? - Para uso
azsphere --helpda CLI do Azure Sphere ouazsphere -h
Parâmetros
O nome do parâmetro é precedido por hífens duplos (--), o que sinaliza que a palavra após 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 por 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 a ID, o nome, o IP ou o 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, --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 [Required] 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 fornecer 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 para o pacote e --destination o parâmetro especifica o caminho e o nome do arquivo para o pacote de imagem resultante.
Conclusão da guia
O preenchimento de tabulação fornece ajuda para concluir automaticamente uma entrada de comando na interface de linha de comando. Na guia CLI do Azure Sphere, há suporte para preenchimento de 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çam com o texto que você digitou inicialmente, continue a pressionar TAB até que o item desejado seja exibido.
No Windows, o PowerShell 7.1 oferece o recurso de preenchimento de tabulação, que não está disponível no Prompt de Comando do Windows.
Para habilitar o preenchimento de tabulação no Windows PowerShell, execute Import-Module -name AzsphereCli.
Esse comando habilita o preenchimento de tabulação somente para a sessão. Você pode adicionar um script ao seu perfil do PowerShell para personalizar seu ambiente e habilitar o preenchimento de tabulação para cada sessão do PowerShell iniciada.
No Linux, a CLI do Azure Sphere dá suporte ao recurso de preenchimento de tabulação para comandos no shell Bash.
Além disso, o preenchimento automático ajuda a descobrir comandos, parâmetros e valores de parâmetro 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 Linux Bash.
Por exemplo, digite azsphere product update command 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 (versão prévia)
Importante
Esse recurso está em preview. Ele pode ser alterado ou removido em uma versão futura.
A nova CLI oferece um modo interativo que exibe automaticamente as 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 interactive. O prompt de comando muda para azsphere>> indicar que agora você está executando comandos no shell interativo.
Para obter mais informações, consulte Modo interativo da CLI do Azure Sphere.
Recursos de saí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 compatíveis
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 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 à 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, o Windows PowerShell e o 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 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
Observação
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 Sphere, consulte Paginação e redirecionamento de resultado.
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 do JSON, permitindo que você selecione e modifique os dados na 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 do comando Consultar a CLI do Azure para obter mais informações e exemplos.
Compatibilidade com versões anteriores
A CLI oferece 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âmetros, valores de parâmetros) e 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 (desativando 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 com eficiência
A CLI do Azure Sphere pode ser usada no Bash, no 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 um parâmetro que inclua espaços, coloque-o entre aspas. No Bash ou no PowerShell, tanto as aspas simples quanto as duplas são interpretadas. No prompt de comando do Windows, somente as aspas duplas são interpretadas. A aspas simples são interpretadas como uma 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 encaixam corretamente no 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 script. 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 interactive. O prompt de comando muda para azsphere>> para indicar que agora você está executando comandos no shell interativo.