Azure Sphere CLI
O SDK do Azure Sphere fornece a interface de linha de comandos (CLI) do Azure Sphere disponível no PowerShell, na Linha de Comandos do Windows ou na shell de comandos do Linux. A CLI do Azure Sphere é um conjunto de comandos utilizados para criar e gerir recursos do Azure Sphere.
A CLI do Azure Sphere está instalada juntamente com a CLI clássica do Azure Sphere descontinuada no Windows e no Linux, para que tenha acesso a qualquer uma das interfaces. Para utilizar a CLI do Azure Sphere:
- No Windows, utilize o PowerShell ou uma Linha de Comandos padrão do Windows.
- No Linux, utilize qualquer shell de comandos.
Executar a CLI do Azure Sphere
Agora pode executar a CLI do Azure Sphere com o azsphere comando da Linha de Comandos do Windows ou do PowerShell. Recomendamos o PowerShell, uma vez que oferece a funcionalidade de conclusão de separadores que não está disponível na Linha de Comandos do Windows.
No Linux, pode executar a CLI do Azure Sphere a partir de qualquer interface de linha de comandos (CLI). Durante a instalação, é apresentada uma notificação que lhe permite definir a CLI do Azure Sphere ou a CLI clássica do Azure Sphere como a versão predefinida preferencial da CLI.
Escreva Yes para escolher a CLI do Azure Sphere ou escreva No para utilizar a CLI clássica do Azure Sphere. Veja Instalar o SDK do Azure Sphere para obter mais informações.
Nota
O formato abreviado para comandos não é suportado na versão da CLI do Azure Sphere. Recomendamos que utilize a funcionalidade de conclusão de separadores para ver a lista de comandos disponíveis. No Windows, o atalho da Linha de Comandos do Programador Clássico do Azure Sphere descontinuado só pode ser utilizado com a CLI clássica do Azure Sphere.
Funcionalidades de entrada da CLI
Esta secção descreve as funcionalidades 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 estão organizados em grupos. Pode ver informações de ajuda completas para os comandos e parâmetros --help disponíveis com a CLI clássica do Azure Sphere e a CLI do Azure Sphere.
Pode obter uma lista completa de comandos ao executar o comando azsphere --help.
Por exemplo:
- Para a utilização clássica da CLI do Azure Sphere ou
azsphere --helpazsphere -? - Para a utilização da CLI do Azure Sphere,
azsphere --helpouazsphere -h
Parâmetros
O nome do parâmetro é precedido por hífenes duplos (--), o que sinaliza que a palavra que se segue ao hífen é um parâmetro. Utilize 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, é utilizado um único parâmetro para identificar cada tipo de objeto. Isto significa que pode fornecer o ID, o nome, o IP ou a localização aplicável a esse parâmetro.
Por exemplo, pode utilizar o ID do inquilino ou o nome do inquilino no seguinte comando:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
ou
azsphere device list --tenant MyTenant
Isto 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, caso em que pode fornecer um parâmetro com cada valor ou um único parâmetro seguido de uma lista de valores separados por espaços. Por exemplo, os dois comandos seguintes 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 executa azsphere <command> <sub-command> --help uma lista de parâmetros aplicáveis a esse comando, é apresentada. A definiçã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 faltar o parâmetro necessário, ser-lhe-á pedido 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 dos parâmetros utilizados para especificar um caminho e o nome de ficheiro 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 ficheiro para o pacote de imagem resultante.
Conclusão do separador
A conclusão da tabulação ajuda a concluir automaticamente uma entrada de comando na interface de linha de comandos. Na conclusão do separador da CLI do Azure Sphere é suportada para grupos, comandos, nomes de parâmetros e valores de parâmetros. Escreva alguns carateres de um comando e, em seguida, prima a Tecla de Tabulação para selecionar o texto de conclusão pretendido. Se vários itens começarem com o texto que inicialmente escreveu, continue a premir a Tecla de Tabulação até o item que pretende aparecer.
No Windows, o PowerShell 7.1 oferece a funcionalidade de conclusão de separadores que não está disponível na Linha de Comandos do Windows.
Para ativar a conclusão do separador no Windows PowerShell, execute Import-Module -name AzsphereCli.
Este comando ativa a conclusão do separador apenas para a sessão. Pode adicionar um script ao seu perfil do PowerShell para personalizar o seu ambiente e ativar a conclusão de separadores para cada sessão do PowerShell iniciada.
No Linux, a CLI do Azure Sphere suporta a funcionalidade de conclusão de separadores para comandos na shell do Bash.
Além disso, a conclusão automática ajuda-o a detetar comandos, parâmetros e valores de parâmetros que estão disponíveis para utilização. Esta opção está disponível através de CTRL+Espaço no Windows PowerShell ou prima a Tecla de Tabulação duas vezes na shell bash do Linux.
Por exemplo, escreva o comando azsphere product update e utilize a conclusão automática para ver uma lista de parâmetros disponíveis.
Da mesma forma, escreva azsphere product update --product e utilize a conclusão automática para ver uma lista de produtos disponíveis no seu inquilino.
Modo interativo (pré-visualização)
Importante
Esta funcionalidade está em pré-visualização. Pode ser alterado ou removido numa versão futura.
A nova CLI oferece um modo interativo que apresenta automaticamente informações de ajuda e facilita a seleção de comandos, sub comandos, parâmetros e valores de parâmetros. Entre no modo interativo com o comando interativo azsphere . A linha de comandos muda para azsphere>> para indicar que está agora a executar comandos na shell interativa.
Para obter mais informações, veja Modo interativo da CLI do Azure Sphere.
Funcionalidades de saída da CLI
Esta secção explica as funcionalidades de saída disponíveis na CLI do Azure Sphere:
As secções seguintes descrevem as funcionalidades 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ções), 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, veja Formatos de saída suportados para a CLI do Azure Sphere.
Redirecionamento e paginação
A CLI do Azure Sphere não suporta a paginação interativa. No entanto, pode redirecionar a saída padrão de um comando para um ficheiro. No exemplo seguinte, para a Linha de Comandos 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
Também pode paginar a saída no ecrã ao encaminhar para as ferramentas de paginação existentes.
Por exemplo:
- No PowerShell (Windows):
azsphere device list | Out-Host –Paging - Numa linha de comandos (Windows):
azsphere device list | more - Na shell do Bash (Linux):
azsphere device list | less
Nota
Esta operação pode ser potencialmente lenta, dependendo da quantidade de dados devolvidos.
Para obter mais informações sobre a paginação da CLI clássica do Azure Azure Sphere, veja Paginação e redirecionamento de resultados.
Resultado do comando da CLI de Consulta
A CLI do Azure Sphere utiliza o --query argumento para executar uma consulta JMESPath nos resultados dos comandos. JMESPath é uma linguagem de consulta para JSON, que lhe permite selecionar e modificar dados a partir da saída da CLI. As consultas são executadas na saída JSON antes de qualquer formatação de apresentação.
O --query argumento é suportado por todos os comandos na CLI do Azure Sphere. Veja JMESPath tutorial and Query Azure CLI command output (Tutorial JMESPath e Consultar a saída do comando da CLI do Azure) para obter mais informações e exemplos.
Retrocompatibilidade
A CLI suporta retrocompatibilidade. Em cada versão, pretendemos manter a retrocompatibilidade tanto para a entrada (nomes de comandos, nomes de parâmetros, valores de parâmetros) como para a respetiva saída em JSON e YAML. Nos casos em que tal compatibilidade não seja possível, forneceremos um aviso prévio de, pelo menos, 6 meses antes de efetuar alterações. Para obter mais informações, veja Alterações importantes (funcionalidades de extinção) na CLI do Azure Sphere.
Códigos de saída
Um comando com êxito devolve um zero. Qualquer valor diferente de zero pode ser interpretado como um código de erro. Após o êxito, as saídas JSON e YAML têm uma garantia contratual retrocompatível.
Fornecer comentários
Se encontrar um erro no Azure Sphere, submeta um problema no GitHub. Para fornecer feedback a partir da linha de comandos, utilize o comando feedback.
Utilizar a CLI do Azure Sphere de forma eficaz
A CLI do Azure Sphere pode ser utilizada a partir do Bash, do PowerShell ou de uma janela da Linha de Comandos. Seguem-se algumas sugestões para utilizar a CLI:
- Utilizar aspas nos valores: se fornecer a um parâmetro um valor que inclua espaços, coloque-o entre aspas. No Bash ou no PowerShell, as aspas simples e duplas são interpretadas. Na Linha de Comandos do Windows, apenas aspas duplas são interpretadas. As plicas são interpretadas como parte do valor. Por exemplo,
azsphere product create --name "My Fridge Product". Para obter mais informações, veja Aspas e carateres de escape. - Muitos comandos do Azure Sphere mostram-lhe informações na consola no formato predefinido
table. Por exemplo,azsphere product device-group list --product DW100. Por vezes, as informações apresentadas não se ajustam corretamente à consola. Isto pode causar problemas se quiser copiar e colar as informações. Recomendamos que experimente as seguintes opções:- Redimensione a consola e execute o comando novamente.
- Utilize a saída JSON para fins concisos de saída e scripting. Por exemplo,
azsphere product device-group list --product DW100 --output json. - Utilize a conclusão de separadores no Windows PowerShell ou na shell do Bash para concluir automaticamente uma entrada de comando.
- Utilize o modo interativo que fornece um ambiente interativo para apresentar informações automaticamente e facilita a seleção de comandos e sub-comandos. Entre no modo interativo com o comando interativo azsphere . A linha de comandos muda para azsphere>> para indicar que está agora a executar comandos na shell interativa.