CLI de Azure Sphere
Importante
Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).
El SDK de Azure Sphere proporciona la interfaz de la línea de comandos (CLI) de Azure Sphere disponible en PowerShell, el símbolo del sistema de Windows o el 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 de Azure Sphere retirada 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 estándar de Windows.
- En Linux, use cualquier shell de comandos.
Ejecución de 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. Se recomienda 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 preferida de la CLI.
Escriba Yes para elegir la CLI de Azure Sphere o el tipo No para usar la CLI clásica de Azure Sphere. Consulte Instalación del SDK de Azure Sphere para obtener más información.
Nota:
El formato corto para los comandos no se admite en la versión de la CLI de Azure Sphere. Se recomienda usar la característica de finalización de pestañas para ver la lista de comandos disponibles. En Windows, el acceso directo del símbolo del sistema para desarrolladores clásicos de Azure Sphere solo se puede usar 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
---------------------
Búsqueda de comandos
Los comandos de la CLI se organizan en grupos. Puede ver toda la información de ayuda de los comandos y parámetros disponibles mediante el uso --help de la CLI clásica de Azure Sphere y la CLI de Azure Sphere.
Para obtener una lista completa de comandos, ejecute el comando azsphere --help.
Por ejemplo:
- Para el uso de la CLI clásica de Azure Sphere,
azsphere --helpoazsphere -? - Para el uso de la CLI de Azure Sphere,
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 guion (-) en la nueva CLI.
Por ejemplo, --component-id o --application-update.
Identificación simplificada de objetos
En la CLI de Azure Sphere 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 aplicables a ese parámetro.
Por ejemplo, puede usar el identificador de inquilino o el nombre de inquilino en el comando siguiente:
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. 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 la CLI de Azure Sphere, los nombres de parámetro que se usan 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 del paquete y --destination el parámetro especifica la ruta de acceso y el nombre de archivo del paquete de imagen resultante.
Finalización con tabulación
La finalización de tabulación proporciona ayuda para completar automáticamente una entrada de comando en la interfaz de la línea de comandos. En la finalización de pestañas de la CLI de Azure Sphere se admite para grupos, comandos, nombres de parámetros y valores de parámetro. Escriba algunos caracteres de un comando y 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 de pestañas que no está disponible en el símbolo del sistema de Windows.
Para habilitar la finalización de tabulación en Windows PowerShell, ejecute Import-Module -name AzsphereCli.
Este comando habilita la finalización de tabulación solo para la sesión. Puede agregar un script al perfil de PowerShell para personalizar el 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 pestañas para comandos en el shell de Bash.
Además, la función autocompletar le ayuda a detectar comandos, parámetros y valores de parámetro que están disponibles para su uso. Esto está disponible mediante CTRL+Espacio en Windows PowerShell o presione TAB dos veces en el shell de Linux Bash.
Por ejemplo, escriba el comando azsphere product update y use autocompletion para ver una lista de parámetros disponibles.
Del mismo modo, escriba azsphere product update --product y use autocompletion para ver una lista de los productos disponibles en el inquilino.
Modo interactivo (versión preliminar)
Importante
Esta característica está en 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 información de ayuda y facilita la selección de comandos, sub comandos, parámetros y valores de parámetro. 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.
Para más información, consulte Modo interactivo de la CLI de Azure Sphere.
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
- 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 compatibles
Los formatos de salida disponibles en la nueva CLI son json, jsonc (JSON coloreado), tsv (valores separados por tabulaciones), table (tablas ASCII legibles) 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 la CLI de Azure Sphere.
Redireccionamiento y paginación
La CLI de Azure Sphere 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 el símbolo del sistema de Windows, Windows PowerShell y el 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 canalizando a las 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 el shell de Bash (Linux):
azsphere device list | less
Nota:
Esta operación puede ser lenta en función de la cantidad de datos que se devuelvan.
Para más información sobre la paginación de la CLI clásica de Azure Sphere, consulte Paginación y redirección de resultados.
Salida del comando de la CLI de consulta
La CLI de Azure Sphere 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 la CLI de Azure Sphere. Consulte el tutorial de JMESPath y consulta la salida del comando de la CLI de Azure para obtener más información y ejemplos.
Compatibilidad con versiones anteriores
La CLI admite compatibilidad con versiones anteriores. En cada versión, pretendemos mantener la compatibilidad con versiones anteriores para la entrada (nombres de comandos, nombres de parámetros, valores de parámetro) y su salida en JSON y YAML. En los casos en los que dicha compatibilidad no sea posible, proporcionaremos al menos 6 meses de aviso antes de realizar cambios. Para más información, consulte Cambios importantes (retirada de características) 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, 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, abra un problema en GitHub. Para proporcionar comentarios desde la línea de comandos, use el comando feedback.
Uso eficaz de la CLI de Azure Sphere
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:
- Uso de comillas en valores: si proporciona un parámetro un valor que incluye espacios, escríbalo entre comillas. En Bash o PowerShell, se interpretan las 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 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 de salida y scripting concisos. Por ejemplo,
azsphere product device-group list --product DW100 --output json. - Use la finalización de tabulación en Windows PowerShell o el shell de Bash para completar automáticamente una entrada de comando.
- Use el modo interactivo que proporciona un entorno interactivo para mostrar automáticamente información y facilita la selección de comandos y sub comandos. 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.