CLI de Azure Sphere
El SDK Azure Sphere proporciona la interfaz Azure Sphere línea de comandos (CLI) disponible en PowerShell, Windows símbolo del sistema o el shell de comandos de Linux. La CLI Azure Sphere es un conjunto de comandos que se usan para crear y administrar Azure Sphere recursos.
La CLI Azure Sphere se instala junto con la CLI clásica de Azure Sphere en desuso en Windows y Linux,por lo que tiene acceso a cualquiera de las interfaces. Para usar Azure Sphere CLI:
- En Windows, use PowerShell o un símbolo del sistema Windows estándar.
- En Linux, use cualquier shell de comandos.
Ejecución de la CLI de Azure Sphere
Ahora puede ejecutar la CLI Azure Sphere con el comando desde el símbolo del sistema azsphere Windows o PowerShell. Se recomienda PowerShell, ya que ofrece la característica de finalización con tabulación que no está disponible en el Windows de comandos.
En Linux, puede ejecutar la CLI Azure Sphere desde cualquier interfaz de línea de comandos (CLI). Durante la instalación, se muestra una notificación que le permite establecer la CLI Azure Sphere o la CLI Azure Sphere clásica como la versión predeterminada preferida de la CLI.
Escriba Yes para elegir Azure Sphere CLI o escriba para usar Azure Sphere CLI No clásica. Consulte Instalación del SDK Azure Sphere para obtener más información.
Nota
El formato corto de los comandos no se admite en la versión Azure Sphere CLI. Se recomienda usar la característica de finalización con tabulación para ver la lista de comandos disponibles. En Windows, el acceso directo de Azure Sphere clásico Símbolo del sistema para desarrolladores en desuso solo se puede usar con Azure Sphere CLI clásica.
Características de entrada de la CLI
En esta sección se describen las características de entrada disponibles en la CLI de Azure Sphere:
Comandos
Todos los comandos del Azure Sphere CLI comienzan por azsphere . Por ejemplo:
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Búsqueda de comandos
Los comandos de la CLI se organizan en grupos. Puede ver la información de ayuda completa de los comandos y parámetros disponibles mediante en Azure Sphere cli clásica y Azure Sphere --help CLI.
Puede obtener una lista completa de comandos ejecutando el comando azsphere --help .
Por ejemplo:
- Para Azure Sphere cli clásica,
azsphere --helpoazsphere -? - Para Azure Sphere uso de la CLI,
azsphere --helpoazsphere -h
Parámetros
El nombre del parámetro va precedido de guiones dobles (--), que indica que la palabra que sigue al guion es un parámetro. Use un espacio para separar el nombre y el valor del parámetro. Los parámetros que son palabras compuestas se separan con un guión (-) en la nueva CLI.
Por ejemplo, --component-id o --application-update.
Identificación simplificada de objetos
En la Azure Sphere CLI se usa un único parámetro para identificar cada tipo de objeto. Esto significa que puede proporcionar el identificador, el nombre, la dirección IP o la ubicación aplicable para ese parámetro.
Por ejemplo, puede usar el identificador de inquilino o el nombre del inquilino en el siguiente comando:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
o
azsphere device list --tenant MyTenant
Esto se ha implementado para los parámetros --device --tenant , , y --product --device-group .
Por ejemplo:
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
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Varios valores
Algunos comandos permiten varios valores para un único parámetro, en cuyo caso puede proporcionar un parámetro con cada valor o un único parámetro seguido de una lista de valores separados por espacios. Por ejemplo, los dos comandos siguientes son 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 obligatorios y opcionales
Al ejecutar una azsphere <command> <sub-command> --help lista de parámetros aplicables a ese comando, se muestra . El valor [Obligatorio] indica si el parámetro es obligatorio para ejecutar correctamente el comando. Todos los demás parámetros son opcionales.
Si falta el parámetro necesario, se le pedirá un valor para el parámetro .
Por ejemplo:
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.
Rutas de acceso de entrada y salida
En Azure Sphere CLI, los nombres de parámetro usados para especificar una ruta de acceso y un nombre de archivo se han actualizado para que sean pertinentes para el contexto del comando.
Por ejemplo:
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
Aquí, especifica el directorio de entrada para el paquete y el parámetro especifica la ruta de acceso y el nombre --package-directory de archivo del paquete de imagen --destination resultante.
Finalización con tabulación
La finalización con tabulación proporciona ayuda para completar automáticamente una entrada de comando en la interfaz de la línea de comandos. En la pestaña Azure Sphere la CLI se admite para grupos, comandos, nombres de parámetros y valores de parámetro. Escriba algunos caracteres de un comando y, a continuación, presione TAB para seleccionar el texto de finalización deseado. Si varios elementos empiezan por el texto que ha escrito inicialmente, siga presionando la tecla TAB hasta que aparezca el elemento deseado.
En Windows, PowerShell 7.1 ofrece la característica de finalización con tabulación que no está disponible en el símbolo Windows comandos.
Para habilitar la finalización con tabulación Windows PowerShell, ejecute Import-Module -name AzsphereCli .
Este comando habilita la finalización con tabulación solo para la sesión. Puede agregar un script a su perfil de PowerShell para personalizar el entorno y habilitar la finalización con tabulación para cada sesión de PowerShell que inicie.
En Linux, Azure Sphere CLI admite la característica de finalización con tabulación para comandos en el shell de Bash.
Además, la función de autocompletar le ayuda a detectar comandos, parámetros y valores de parámetros que están disponibles para su uso. Esto está disponible mediante CTRL+Espacio en Windows PowerShell presione TAB dos veces en el shell de Bash de Linux.
Por ejemplo, escriba el comando azsphere product update y use autocompletar para ver una lista de parámetros disponibles.
Del mismo modo, escriba azsphere product update --product y use autocompletar para ver una lista de productos disponibles en el inquilino.
Modo interactivo (versión preliminar)
Importante
Esta característica se encuentra en su versión preliminar. Esto se puede cambiar o eliminar en una versión futura.
La nueva CLI ofrece un modo interactivo que muestra automáticamente la información de ayuda y facilita la selección de comandos, subcomandos, parámetros y valores de parámetro. Escriba el modo interactivo con el comando azsphere interactive. El símbolo del sistema cambia a para indicar que ahora está azsphere>> ejecutando comandos en el shell interactivo.
Para obtener más información, consulte Azure Sphere modo interactivo de la CLI.
Características de salida de la CLI
En esta sección se explican las características de salida disponibles en la CLI de Azure Sphere:
- Formatos de salida admitidos (versión preliminar)
- Redireccionamiento y paginación
- Salida del comando de la CLI de consulta
En las secciones siguientes se describen las características de salida disponibles en la nueva CLI:
Formatos de salida admitidos (versión preliminar)
Nota
Esta característica se encuentra en su versión preliminar. Esto se puede cambiar o eliminar en una versión futura.
Los formatos de salida disponibles en la nueva CLI son json , jsonc (JSON coloreado), (valores separados por tsv tabulaciones), table (tablas ASCII legibles para personas) y yaml . De forma predeterminada, la CLI genera table. Para más información sobre los formatos de salida disponibles, consulte Formatos de salida admitidos para Azure Sphere CLI.
Redireccionamiento y paginación
Azure Sphere CLI no admite la paginación interactiva. Sin embargo, puede redirigir la salida estándar de un comando a un archivo. En el ejemplo siguiente, para Windows símbolo del sistema, Windows PowerShell y shell de Bash de Linux, la salida estándar se envía a output.txt y el error estándar se envía a logs.txt.
azsphere device list --verbose > output.txt 2> logs.txt
También puede paginar la salida en pantalla mediante la canalización a las herramientas de paginación existentes.
Por ejemplo:
- En PowerShell (Windows):
azsphere device list | Out-Host –Paging - En el símbolo del sistema (Windows):
azsphere device list | more - En el shell de Bash (Linux):
azsphere device list | less
Nota
Esta operación puede ser potencialmente lenta en función de la cantidad de datos que se devuelvan.
Para más información sobre la paginación de Azure Azure Sphere cli clásica, consulte Paginación y redireccionamiento de resultados.
Salida del comando de la CLI de consulta
La Azure Sphere CLI usa el --query argumento para ejecutar una consulta JMESPath en los resultados de los comandos. JMESPath es un lenguaje de consulta para JSON que ofrece la posibilidad de seleccionar y modificar datos de la salida de la CLI. Las consultas se ejecutan en la salida JSON antes de cualquier formato de presentación.
El --query argumento es compatible con todos los comandos de Azure Sphere CLI. Consulte tutorial de JMESPath y Consulta de CLI de Azure salida de comandos para obtener más información y ejemplos.
compatibilidad con versiones anteriores
La CLI admite la compatibilidad con versiones anteriores. En cada versión, nuestro objetivo es mantener la compatibilidad con versiones anteriores para la entrada (nombres de comando, nombres de parámetros, valores de parámetro) y su salida en JSON y YAML. En los casos en los que esta compatibilidad no sea posible, se proporcionará un aviso de al menos 6 meses antes de realizar cambios. Para obtener más información, consulte Cambios importantes (desusos) en Azure Sphere CLI.
Códigos de salida
Un comando correcto devuelve un cero. Cualquier valor distinto de cero se puede interpretar como un código de error. Una vez que se han hecho correctamente, las salidas JSON y YAML tienen una garantía contractual compatible con versiones anteriores.
Envío de comentarios
Si encuentra un error en Azure Sphere, cree un problema en GitHub. Para proporcionar comentarios desde la línea de comandos, use el comando feedback.
Uso eficaz Azure Sphere CLI
Azure Sphere CLI se puede usar desde Bash, PowerShell o una ventana del símbolo del sistema. Estas son algunas sugerencias para usar la CLI:
- Usar comillas en valores: si proporciona un parámetro con un valor que incluye espacios, escríbalo entre comillas. En Bash o PowerShell, se interpretan las comillas simples y dobles. En Windows símbolo del sistema, solo se interpretan las comillas dobles. Las comillas simples se interpretan como parte del valor. Por ejemplo,
azsphere product create --name "My Fridge Product". Para obtener más información, vea Comillas y caracteres de escape. - Muchos Azure Sphere comandos muestran información en la consola en el formato
tablepredeterminado. Por ejemplo,azsphere product device-group list --product DW100. A veces, la información mostrada no se ajusta correctamente a la consola. Esto puede causar problemas si desea copiar y pegar la información. Se recomienda probar las siguientes opciones:- Cambie el tamaño de la consola y vuelva a ejecutar el comando.
- Use la salida JSON con fines concisos de salida y scripting. Por ejemplo,
azsphere product device-group list --product DW100 --output json. - Use la finalización con tabulación Windows PowerShell o shell de Bash para completar automáticamente una entrada de comando.
- Use el modo interactivo, que proporciona un entorno interactivo para mostrar automáticamente la información y facilita la selección de comandos y subcomandos. Escriba el modo interactivo con el comando azsphere interactive. El símbolo del sistema cambia a azsphere>> para indicar que ahora está ejecutando comandos en el shell interactivo.