Azure Sphere CLI
El SDK de Azure Sphere proporciona la interfaz de línea de comandos (CLI) de Azure Sphere disponible en PowerShell, símbolo del sistema de Windows o shell de comandos de Linux. La CLI de Azure Sphere es un conjunto de comandos que se usan para crear y administrar recursos de Azure Sphere.
La CLI de Azure Sphere se instala junto con la CLI clásica retirada de Azure Sphere en Windows y Linux, por lo que tiene acceso a cualquiera de las interfaces. Para usar la CLI de Azure Sphere:
- En Windows, use PowerShell o un símbolo del sistema de Windows estándar.
- En Linux, use cualquier shell de comandos.
Ejecutar la CLI de Azure Sphere
Ahora puede ejecutar la CLI de Azure Sphere con el comando desde el azsphere símbolo del sistema de Windows o PowerShell. Recomendamos PowerShell, ya que ofrece la característica de finalización de pestañas , que no está disponible en el símbolo del sistema de Windows.
En Linux, puede ejecutar la CLI de 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 de Azure Sphere o la CLI clásica de Azure Sphere como la versión predeterminada de la CLI preferida.
Escriba Yes para elegir la CLI de Azure Sphere o escriba No para usar la CLI clásica de Azure Sphere. Consulte Instalar el SDK de Azure Sphere para obtener más información.
Nota
El formulario breve para comandos no es compatible con la versión de la CLI de Azure Sphere. Le recomendamos que use la característica de finalización de tabulaciones para ver la lista de comandos disponibles. En Windows, el método abreviado de símbolo del sistema para desarrolladores de Azure Sphere Classic que se retira solo puede usarse con la CLI clásica de Azure Sphere.
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 de la CLI de Azure Sphere comienzan por azsphere. Por ejemplo:
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Buscar comandos
Los comandos de la CLI se organizan en grupos. Puede ver toda la información de ayuda para los comandos y parámetros disponibles mediante --help la CLI clásica de Azure Sphere y la CLI de Azure Sphere.
Puede obtener una lista completa de comandos ejecutando el comando azsphere --help.
Por ejemplo:
- Para la CLI clásica de Azure Sphere,
azsphere --helpo bienazsphere -? - Para la CLI de Azure Sphere,
azsphere --helpo bienazsphere -h
Parámetros
El nombre del parámetro va precedido de dos guiones (--), lo que indica que la palabra que sigue al guión 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 de objetos simplificada
En la CLI de Azure Sphere se usa un único parámetro para identificar cada tipo de objeto. Esto significa que puede proporcionar el Id., el nombre, la IP o la ubicación aplicables a ese parámetro.
Por ejemplo, puede usar el id. 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 --deviceparámetros , --tenant, --producty --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 azsphere <command> <sub-command> --help una 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. El resto de 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 entrada y salida
En la CLI de Azure Sphere, los nombres de los parámetros usados para especificar una ruta de acceso y un nombre de archivo se han actualizado para que sean relevantes 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í, --package-directory especifica el directorio de entrada para el paquete y --destination parámetro especifica la ruta de acceso y el nombre de archivo para el paquete de imagen resultante.
Finalización de tabulación
La finalización de tabulaciones proporciona ayuda para completar automáticamente una entrada de comando en la interfaz de la línea de comandos. En la finalización de la pestaña azure Sphere CLI se admite para grupos, comandos, nombres de parámetros y valores de parámetros. Escriba algunos caracteres de un comando y, después, presione la tecla TAB para seleccionar el texto de finalización deseado. Si varios elementos comienzan con el texto que escribió inicialmente, siga presionando la tecla TAB hasta que aparezca el elemento que desee.
En Windows, PowerShell 7.1 ofrece la función de finalización de pestañas, que no está disponible en el símbolo del sistema de Windows.
Para habilitar la finalización de tabulaciones en Windows PowerShell, ejecute Import-Module -name AzsphereCli.
Este comando solo permite la finalización de pestañas para la sesión. Puede agregar un script a su perfil de PowerShell para personalizar su entorno y habilitar la finalización de pestañas para cada sesión de PowerShell que inicie.
En Linux, la CLI de Azure Sphere admite la característica de finalización de tabulaciones para los comandos del shell de Bash.
Además, la función autocompletar le ayuda a descubrir los comandos, parámetros y valores de parámetros que están disponibles para usar. Esto está disponible usando CTRL+Espacio en Windows PowerShell o presionaNDO TAB dos veces en el shell de Linux Bash.
Por ejemplo, escriba azsphere product update command y use autocompletion para ver una lista de parámetros disponibles.
Del mismo modo, escriba azsphere product update --product and use autocompletion para ver una lista de productos disponibles en su inquilino.
Modo interactivo (vista previa)
Importante
Esta característica está en versión preliminar. Puede cambiarse o quitarse en una versión futura.
La nueva CLI ofrece un modo interactivo que muestra automáticamente información de ayuda y facilita la selección de comandos, sub comandos, parámetros y valores de parámetro. Entrar en el modo interactivo con el comando azsphere interactive . El símbolo del sistema cambia para azsphere>> indicar que está ejecutando comandos en el shell interactivo.
Para obtener más información, consulte Modo interactivo de la CLI de Azure Sphere.
Características de salida de la CLI
Esta sección explica las características de salida disponibles en la CLI de Azure Sphere:
Las siguientes secciones describen las características de salida disponibles en la nueva CLI:
Formatos de salida admitidos
Los formatos de salida disponibles en la nueva CLI son json, jsonc (JSON colorizado), tsv (valores separados por tabulaciones), table (tablas ASCII legibles por el usuario) y yaml. De forma predeterminada, la CLI genera resultados table. Para obtener más información sobre los formatos de salida disponibles, consulte Formatos de salida admitidos para la CLI de Azure Sphere.
Redireccionamiento y paginación
La CLI de Azure Sphere no admite paginación interactiva. Sin embargo, puede redirigir la salida estándar de un comando a un archivo. En el siguiente ejemplo, para el shell del símbolo del sistema de Windows, Windows PowerShell y Linux Bash, 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 se puede paginar la salida en pantalla por tuberías a herramientas de paginación existentes.
Por ejemplo:
- En PowerShell (Windows):
azsphere device list | Out-Host –Paging - En un símbolo del sistema (Windows):
azsphere device list | more - En Shell de Bash (Linux):
azsphere device list | less
Nota
Esta operación puede ser potencialmente lenta dependiendo de cuántos datos se devuelvan.
Para obtener más información sobre la paginación de la CLI clásica de Azure Azure Sphere, consulte Paginación y redireccionamiento de resultados.
Resultado del comando Query CLI
La CLI de Azure Sphere usa el --query argumento para ejecutar una consulta de JMESPath en los resultados de los comandos. JMESPath es un lenguaje de consulta para JSON, que le ofrece la capacidad de seleccionar y modificar datos de la salida de la CLI. Las consultas se ejecutan en la salida JSON antes de cualquier formato de visualización.
El --query argumento es compatible con todos los comandos de la CLI de Azure Sphere. Vea tutorial de JMESPath y resultado del comando de la CLI de Query Azure para obtener más información y ejemplos.
Compatibilidad
La CLI admite la compatibilidad con versiones anteriores. En cada versión, nuestro objetivo es mantener la compatibilidad con versiones anteriores tanto de entrada (nombres de comandos, nombres de parámetros, valores de parámetros) como su salida en JSON y YAML. En los casos en los que dicha compatibilidad no sea posible, proporcionaremos al menos 6 meses de antelación antes de realizar los cambios. Para obtener más información, consulte Cambios importantes (características retiradas) en la CLI de Azure Sphere.
Códigos de salida
Un comando correcto devuelve un cero. Cualquier valor distinto de cero se puede interpretar como un código de error. Tras el éxito, los productos JSON y YAML tienen una garantía contractual compatible con versiones anteriores.
Enviar comentarios
Si encuentras un error en Azure Sphere, envía un problema en GitHub. Para enviar comentarios desde la línea de comandos, use el comando comentarios.
Usar la CLI de Azure Sphere de forma eficaz
La CLI de Azure Sphere 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 un valor que incluye espacios, escríbalo entre comillas. En Bash o PowerShell, se interpretan comillas simples y dobles. En el símbolo del sistema de Windows, 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 comandos de Azure Sphere muestran información en la consola en el formato predeterminado
table. Por ejemplo,azsphere product device-group list --product DW100. A veces, la información que se muestra no encaja correctamente en la consola. Esto puede causar problemas si desea copiar y pegar la información. Se recomienda probar las siguientes opciones:- Cambia el tamaño de la consola y vuelve a ejecutar el comando.
- Use la salida JSON para fines de scripting y salida concisos. Por ejemplo,
azsphere product device-group list --product DW100 --output json. - Usa la finalización de tabulaciones en 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 información automáticamente y facilita la selección de comandos y sub comandos. Entrar en el modo interactivo con el comando azsphere interactive . El símbolo del sistema cambia a azsphere>> para indicar que está ejecutando comandos en el shell interactivo.