Interface CLI Azure Sphere
Important
Il s’agit de la documentation Azure Sphere (héritée). Azure Sphere (hérité) prend sa retraite le 27 septembre 2027 et les utilisateurs doivent migrer vers Azure Sphere (intégré) pour l’instant. Utilisez le sélecteur de version situé au-dessus du TOC pour afficher la documentation Azure Sphere (intégrée).
Le Kit de développement logiciel (SDK) Azure Sphere fournit l’interface de ligne de commande Azure Sphere disponible sur PowerShell, l’invite de commandes Windows ou l’interpréteur de commandes Linux. Azure Sphere CLI est un ensemble de commandes utilisées pour créer et gérer des ressources Azure Sphere.
Azure Sphere CLI est installé en même temps que l’interface cli classique Azure Sphere sur Windows et Linux. Vous avez donc accès à l’une ou l’autre des interfaces. Pour utiliser Azure Sphere CLI :
- Sur Windows, utilisez PowerShell ou une invite de commandes Windows standard.
- Sur Linux, utilisez n’importe quel interpréteur de commandes.
Exécuter l’interface CLI Azure Sphere
Vous pouvez maintenant exécuter l’interface CLI Azure Sphere avec la commande à partir de l’invite azsphere de commandes Windows ou de PowerShell. Nous vous recommandons PowerShell, car il offre la fonctionnalité de saisie semi-automatique de tabulation qui n’est pas disponible à partir de l’invite de commandes Windows.
Sur Linux, vous pouvez exécuter Azure Sphere CLI à partir de n’importe quelle interface de ligne de commande (CLI). Pendant l’installation, une notification s’affiche qui vous permet de définir Azure Sphere CLI ou Azure Sphere Classic CLI comme version par défaut par défaut.
Tapez Yes pour choisir Azure Sphere CLI ou type No pour utiliser Azure Sphere Classic CLI. Pour plus d’informations, consultez Installer le Kit de développement logiciel (SDK) Azure Sphere.
Remarque
Le formulaire court pour les commandes n’est pas pris en charge dans la version de l’interface CLI Azure Sphere. Nous vous recommandons d’utiliser la fonctionnalité de saisie semi-automatique de tabulation pour afficher la liste des commandes disponibles. Sur Windows, le raccourci d’invite de commandes pour développeurs Azure Sphere Classic ne peut être utilisé qu’avec Azure Sphere Classic CLI.
Fonctionnalités d’entrée CLI
Cette section décrit les fonctionnalités d’entrée disponibles dans l’interface CLI Azure Sphere :
Commandes
Toutes les commandes de l’interface CLI Azure Sphere commencent par azsphere. Par exemple :
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Trouver des commandes
Les commandes de l’interface CLI sont organisées en groupes. Vous pouvez afficher des informations d’aide complètes sur les commandes et paramètres disponibles à l’aide --help de l’interface CLI classique Azure Sphere et d’Azure Sphere CLI.
Vous pouvez obtenir une liste complète des commandes en exécutant la commande azsphere --help.
Par exemple :
- Pour l’utilisation de l’interface CLI classique Azure Sphere ou
azsphere --helpazsphere -? - Pour l’utilisation d’Azure Sphere CLI ou
azsphere --helpazsphere -h
Paramètres
Le nom du paramètre est précédé de traits d’union doubles (--), ce qui signale que le mot suivant le trait d’union est un paramètre. Utilisez un espace pour séparer le nom et la valeur du paramètre. Les paramètres qui sont des mots composés sont séparés par un trait d’union (-) dans la nouvelle interface CLI.
Par exemple : --component-id ou --application-update
Identification d’objet simplifiée
Dans l’interface de ligne de commande Azure Sphere, un paramètre unique est utilisé pour identifier chaque type d’objet. Cela signifie que vous pouvez fournir l’ID, le nom, l’adresse IP ou l’emplacement applicable à ce paramètre.
Par exemple, vous pouvez utiliser l’ID de locataire ou le nom du locataire dans la commande suivante :
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
or
azsphere device list --tenant MyTenant
Cette opération a été implémentée pour les paramètres , et --tenant--product--device-group les --deviceparamètres.
Par exemple :
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
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Valeurs multiples
Certaines commandes autorisent plusieurs valeurs pour un seul paramètre, auquel cas vous pouvez fournir un paramètre avec chaque valeur, ou un paramètre unique suivi d’une liste de valeurs séparées par des espaces. Par exemple, les deux commandes suivantes sont équivalentes :
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
Paramètres obligatoires et facultatifs
Lorsque vous exécutez azsphere <command> <sub-command> --help une liste de paramètres applicables à cette commande s’affiche. Le paramètre [Obligatoire] indique si le paramètre est obligatoire pour exécuter correctement la commande. Tous les autres paramètres sont facultatifs.
Si le paramètre requis est manquant, vous êtes invité à entrer une valeur pour le paramètre.
Par exemple :
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.
Chemins d’entrée et de sortie
Dans Azure Sphere CLI, les noms de paramètres utilisés pour spécifier un chemin d’accès et un nom de fichier ont été mis à jour pour être pertinents dans le contexte de la commande.
Par exemple :
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
Ici, --package-directory spécifie le répertoire d’entrée du package et --destination du paramètre spécifie le chemin d’accès et le nom de fichier du package d’image résultant.
Achèvement des onglets
La saisie semi-automatique de tabulation fournit de l’aide pour terminer automatiquement une entrée de commande dans l’interface de ligne de commande. Dans l’onglet Cli Azure Sphere, la saisie semi-automatique est prise en charge pour les groupes, les commandes, les noms de paramètres et les valeurs de paramètres. Tapez quelques caractères d’une commande, puis appuyez sur Tab pour sélectionner le texte de saisie semi-automatique souhaité. Si plusieurs éléments commencent par le texte que vous avez tapé initialement, continuez à appuyer sur TAB jusqu’à ce que l’élément souhaité s’affiche.
Sur Windows, PowerShell 7.1 offre la fonctionnalité de saisie semi-automatique d’onglets qui n’est pas disponible à partir de l’invite de commandes Windows.
Pour activer la saisie semi-automatique de tabulation dans Windows PowerShell, exécutez Import-Module -name AzsphereCli.
Cette commande active la saisie semi-automatique des onglets uniquement pour la session. Vous pouvez ajouter un script à votre profil PowerShell pour personnaliser votre environnement et activer la saisie semi-automatique de tabulation pour chaque session PowerShell que vous démarrez.
Sur Linux, Azure Sphere CLI prend en charge la fonctionnalité d’achèvement de tabulation pour les commandes sous l’interpréteur de commandes Bash.
En outre, lacomplétion automatique vous permet de découvrir des commandes, des paramètres et des valeurs de paramètres disponibles pour l’utilisation. Ceci est disponible à l’aide de Ctrl+Espace dans Windows PowerShell ou appuyez deux fois sur TAB dans l’interpréteur de commandes Bash Linux.
Par exemple, tapez azsphere product update command and use autocompletion to see a list of available parameters.
De même, tapez azsphere product update --product and use autocompletion to see a list of available products in your tenant.
Mode interactif (préversion)
Important
Cette fonctionnalité est en version préliminaire. Elle peut être changée ou supprimée dans une version ultérieure.
La nouvelle interface CLI offre un mode interactif qui affiche automatiquement des informations d’aide et facilite la sélection de commandes, de sous-commandes, de paramètres et de valeurs de paramètre. Entrez le mode interactif avec la commande interactive azsphere. L’invite de commandes change pour azsphere>> indiquer que vous exécutez maintenant des commandes dans l’interpréteur de commandes interactif.
Pour plus d’informations, consultez le mode interactif Azure Sphere CLI.
Fonctionnalités de sortie CLI
Cette section explique les fonctionnalités de sortie disponibles dans l’interface CLI Azure Sphere :
Les sections suivantes décrivent les fonctionnalités de sortie disponibles dans la nouvelle interface CLI :
Formats de sortie pris en charge
Les formats de sortie disponibles dans la nouvelle interface CLI sont json, jsonc (JSON colorisé), tsv (Valeurs séparées par des tabulations), (tables ASCII lisibles par l’homme) table et yaml. Par défaut, l’interface CLI génère table. Pour en savoir plus sur les formats de sortie disponibles, consultez Les formats de sortie pris en charge pour Azure Sphere CLI.
Redirection et pagination
Azure Sphere CLI ne prend pas en charge la pagination interactive. Toutefois, vous pouvez rediriger la sortie standard d’une commande vers un fichier. Dans l’exemple suivant, pour l’invite de commandes Windows, Windows PowerShell et Linux Bash, la sortie standard est envoyée à output.txt et l’erreur standard est envoyée à logs.txt.
azsphere device list --verbose > output.txt 2> logs.txt
Vous pouvez également paginer la sortie à l’écran en pipant vers les outils de pagination existants.
Par exemple :
- Dans PowerShell (Windows) :
azsphere device list | Out-Host –Paging - À l’invite de commandes (Windows) :
azsphere device list | more - Dans l’interpréteur de commandes Bash (Linux) :
azsphere device list | less
Remarque
Cette opération peut être lente en fonction de la quantité de données retournées.
Pour plus d’informations sur la pagination pour Azure Azure Sphere Classic CLI, consultez Pagination et redirection des résultats.
Sortie de la commande CLI de requête
L’interface CLI Azure Sphere utilise l’argument --query pour exécuter une requête JMESPath sur les résultats des commandes. JMESPath est un langage de requête pour JSON, qui vous permet de sélectionner et de modifier des données depuis une sortie CLI. Les requêtes sont exécutées sur la sortie JSON avant toute mise en forme d’affichage.
L’argument --query est pris en charge par toutes les commandes dans Azure Sphere CLI. Pour plus d’informations et d’exemples, consultez le didacticiel JMESPath et interrogez la sortie de commande Azure CLI.
Compatibilité descendante
L’interface CLI prend en charge la compatibilité descendante. Dans chaque version, nous souhaitons maintenir la compatibilité descendante pour les entrées (noms de commandes, noms de paramètres, valeurs de paramètres) et sa sortie dans JSON et YAML. Dans les cas où cette compatibilité n’est pas possible, nous fournirons au moins 6 mois d’avis avant d’apporter des modifications. Pour plus d’informations, consultez Modifications importantes (suppression des fonctionnalités) dans Azure Sphere CLI.
Codes de sortie
Une commande réussie retourne un zéro. Toute valeur non nulle peut être interprétée comme un code d’erreur. En cas de réussite, les sorties JSON et YAML ont une garantie contractuelle rétrocompatible.
Fournir des commentaires
Si vous trouvez un bogue dans Azure Sphere, créez un problème sur GitHub. Pour fournir des commentaires à partir de la ligne de commande, utilisez la commande de commentaires.
Utiliser l’interface CLI Azure Sphere efficacement
Azure Sphere CLI peut être utilisé à partir de Bash, PowerShell ou d’une fenêtre d’invite de commandes. Voici quelques conseils pour utiliser l’interface CLI :
- Utilisation de guillemets dans des valeurs : si vous fournissez un paramètre incluant des espaces, placez-le entre guillemets. Dans Bash ou PowerShell, les guillemets simples et doubles sont interprétés. Dans l’invite de commandes Windows, seuls les guillemets doubles sont interprétés. Les guillemets simples sont interprétés comme faisant partie de la valeur. Par exemple :
azsphere product create --name "My Fridge Product". Pour plus d’informations, consultez Guillemets et caractères d’échappement. - De nombreuses commandes Azure Sphere affichent des informations dans la console au format par défaut
table. Par exemple :azsphere product device-group list --product DW100. Parfois, les informations affichées ne correspondent pas correctement à la console. Cela peut entraîner des problèmes si vous souhaitez copier et coller les informations. Nous vous recommandons d’essayer les options suivantes :- Redimensionnez la console et réexécutez la commande.
- Utilisez la sortie JSON à des fins de sortie et de script concis. Par exemple :
azsphere product device-group list --product DW100 --output json. - Utilisez la saisie semi-automatique de tabulation dans Windows PowerShell ou l’interpréteur de commandes Bash pour terminer automatiquement une entrée de commande.
- Utilisez le mode interactif qui fournit un environnement interactif pour afficher automatiquement des informations et facilite la sélection de commandes et de sous-commandes. Entrez le mode interactif avec la commande interactive azsphere. L’invite de commandes passe à azsphere>> pour indiquer que vous exécutez maintenant des commandes dans l’interpréteur de commandes interactif.