Azure Sphere CLI
Das Azure Sphere SDK stellt die Azure Sphere-Befehlszeilenschnittstelle (CLI) bereit, die in PowerShell, der Windows-Eingabeaufforderung oder der Linux-Befehlsshell verfügbar ist. Die Azure Sphere-CLI besteht aus einer Reihe von Befehlen, die zum Erstellen und Verwalten von Azure Sphere-Ressourcen verwendet werden.
Die Azure Sphere-CLI wird zusammen mit der eingestellten klassischen Azure Sphere-CLI sowohl unter Windows als auch unter Linux installiert, sodass Sie Zugriff auf beide Schnittstellen haben. So verwenden Sie die Azure Sphere-CLI:
- Verwenden Sie unter Windows PowerShell oder eine standardmäßige Windows-Eingabeaufforderung.
- Verwenden Sie unter Linux eine beliebige Befehlsshell.
Ausführen der Azure Sphere-CLI
Sie können jetzt die Azure Sphere-CLI mit dem Befehl über die azsphere Windows-Eingabeaufforderung oder PowerShell ausführen. Wir empfehlen PowerShell, da es das Feature zum Vervollständigen von Registerkarten bietet, das nicht über die Windows-Eingabeaufforderung verfügbar ist.
Unter Linux können Sie die Azure Sphere-CLI über eine beliebige Befehlszeilenschnittstelle (CLI) ausführen. Während der Installation wird eine Benachrichtigung angezeigt, mit der Sie die Azure Sphere CLI oder die klassische Azure Sphere-CLI als bevorzugte Standard-CLI-Version festlegen können.
Geben Sie ein Yes , um die Azure Sphere-CLI oder den Typ No für die Verwendung der klassischen Azure Sphere-CLI auszuwählen. Weitere Informationen finden Sie unter Installieren des Azure Sphere SDK .
Hinweis
Die Kurzform für Befehle wird in der Azure Sphere CLI-Version nicht unterstützt. Es wird empfohlen, die Funktion zum Vervollständigen der Registerkarte zu verwenden, um die Liste der verfügbaren Befehle anzuzeigen. Unter Windows kann die Ausmusterung der klassischen Azure Sphere Developer-Eingabeaufforderungsverknüpfung nur mit der klassischen Azure Sphere-CLI verwendet werden.
CLI-Eingabefeatures
In diesem Abschnitt werden die eingabefeatures beschrieben, die in der Azure Sphere CLI verfügbar sind:
Befehle
Alle Befehle in der Azure Sphere-CLI beginnen mit azsphere. Zum Beispiel:
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
Befehle suchen
Befehle in der CLI sind in Gruppen organisiert. Sie können vollständige Hilfeinformationen zu den verfügbaren Befehlen und Parametern anzeigen, indem Sie in der klassischen Azure Sphere-BEFEHLSZEILE und der Azure Sphere-CLI verwenden --help .
Sie können eine vollständige Liste der Befehle abrufen, indem Sie den Befehl azsphere --helpausführen.
Zum Beispiel:
- Für die verwendung der
azsphere --helpklassischen Azure Sphere CLI oderazsphere -? - Für die Verwendung der
azsphere --helpAzure Sphere-CLI oderazsphere -h
Parameter
Dem Namen des Parameters werden doppelte Bindestriche (--) vorangestellt, die signalisieren, dass das Wort nach dem Bindestrich ein Parameter ist. Verwenden Sie ein Leerzeichen, um den Parameternamen und den Wert zu trennen. Die Parameter, die zusammengesetzte Wörter sind, werden in der neuen CLI durch einen Bindestrich (-) getrennt.
Beispiel: --component-id oder --application-update
Vereinfachte Objektidentifikation
In der Azure Sphere-CLI wird ein einzelner Parameter verwendet, um jeden Objekttyp zu identifizieren. Dies bedeutet, dass Sie entweder die ID, den Namen, die IP-Adresse oder den Standort angeben können, die für diesen Parameter gelten.
Sie können beispielsweise entweder die Mandanten-ID oder den Mandantennamen im folgenden Befehl verwenden:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
Oder
azsphere device list --tenant MyTenant
Dies wurde für die --deviceParameter , --tenant, --productund --device-group implementiert.
Zum Beispiel:
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
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
Mehrere Werte
Einige Befehle lassen mehrere Werte für einen einzelnen Parameter zu. In diesem Fall können Sie entweder einen Parameter mit jedem Wert oder einen einzelnen Parameter angeben, gefolgt von einer Liste von Werten, die durch Leerzeichen getrennt sind. Die folgenden beiden Befehle sind z. B. gleichwertig:
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
Erforderliche und optionale Parameter
Wenn Sie eine Liste der Parameter ausführen azsphere <command> <sub-command> --help , die für diesen Befehl gelten, wird angezeigt. Die Einstellung [Erforderlich] gibt an, ob der Parameter obligatorisch ist, um den Befehl erfolgreich auszuführen. Alle anderen Parameter sind optional.
Wenn der erforderliche Parameter fehlt, werden Sie zur Eingabe eines Werts für den Parameter aufgefordert.
Zum Beispiel:
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.
Eingabe- und Ausgabepfade
In der Azure Sphere-CLI wurden die Parameternamen, die zum Angeben eines Pfads und Dateinamens verwendet werden, aktualisiert, um für den Kontext des Befehls relevant zu sein.
Zum Beispiel:
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
Gibt hier das Eingabeverzeichnis für das Paket an, --package-directory und --destination der Parameter gibt den Pfad und Dateinamen für das resultierende Imagepaket an.
Vervollständigung mit der Tabulator
Die Tabulatorvervollständigung bietet Hilfe beim automatischen Abschließen eines Befehlseintrags in der Befehlszeilenschnittstelle. Auf der Azure Sphere CLI-Registerkarte wird die Vervollständigung für Gruppen, Befehle, Parameternamen und Parameterwerte unterstützt. Geben Sie einige Zeichen eines Befehls ein, und drücken Sie dann die TAB-TASTE , um den gewünschten Vervollständigungstext auszuwählen. Wenn mehrere Elemente mit dem text beginnen, den Sie ursprünglich eingegeben haben, drücken Sie die TAB-TASTE , bis das gewünschte Element angezeigt wird.
Unter Windows bietet PowerShell 7.1 das Feature zum Vervollständigen von Registerkarten, das nicht über die Windows-Eingabeaufforderung verfügbar ist.
Führen Sie aus, um die Vervollständigung mit der TAB-TASTE in Windows PowerShell zu Import-Module -name AzsphereCliaktivieren.
Dieser Befehl aktiviert die Tabstopp-Vervollständigung nur für die Sitzung. Sie können Ihrem PowerShell-Profil ein Skript hinzufügen , um Ihre Umgebung anzupassen und die TAB-Vervollständigung für jede PowerShell-Sitzung zu aktivieren, die Sie starten.
Unter Linux unterstützt die Azure Sphere-CLI das Feature zum Vervollständigen von Registerkarten für Befehle in der Bash-Shell.
Darüber hinaus hilft Ihnen die automatische Vervollständigung bei der Ermittlung von Befehlen, Parametern und Parameterwerten, die zur Verwendung verfügbar sind. Dies ist mithilfe von STRG+LEERTASTE in Windows PowerShell verfügbar, oder drücken Sie die TAB-TASTE zweimal in der Linux Bash-Shell.
Geben Sie z. B. azsphere product update command ein, und verwenden Sie autoVervollständigen, um eine Liste der verfügbaren Parameter anzuzeigen.
Geben Sie auf ähnliche Weise azsphere product update --product ein, und verwenden Sie AutoVervollständigen, um eine Liste der verfügbaren Produkte in Ihrem Mandanten anzuzeigen.
Interaktiver Modus (Vorschau)
Wichtig
Dieses Feature befindet sich in der Vorschauphase. Sie kann in einer zukünftigen Version geändert oder entfernt werden.
Die neue CLI bietet einen interaktiven Modus, der hilfeinformationen automatisch anzeigt und die Auswahl von Befehlen, Unterbefehlen, Parametern und Parameterwerten vereinfacht. Wechseln Sie mit dem Befehl azsphere interactive in den interaktiven Modus. Die Eingabeaufforderung ändert sich in azsphere>> , um anzugeben, dass Sie jetzt Befehle in der interaktiven Shell ausführen.
Weitere Informationen finden Sie unter Interaktiver Cli-Modus von Azure Sphere.
CLI-Ausgabefeatures
In diesem Abschnitt werden die ausgabefeatures erläutert, die in der Azure Sphere CLI verfügbar sind:
In den folgenden Abschnitten werden die ausgabefeatures beschrieben, die in der neuen CLI verfügbar sind:
Unterstützte Ausgabeformate
Die verfügbaren Ausgabeformate in der neuen CLI sind json, (farbiger JSON-Code), tsv (durch Tabstopp getrennte Werte), table (für Menschen lesbare ASCII-Tabellen) und yamljsonc . Standardmäßig gibt die CLI aus table. Weitere Informationen zu den verfügbaren Ausgabeformaten finden Sie unter Unterstützte Ausgabeformate für die Azure Sphere-CLI.
Umleitung und Paginierung
Die Azure Sphere-CLI unterstützt keine interaktive Paginierung. Sie können jedoch die Standardausgabe eines Befehls an eine Datei umleiten. Im folgenden Beispiel wird für die Windows-Eingabeaufforderung, die Windows PowerShell und die Linux Bash-Shell die Standardausgabe an output.txt und der Standardfehler an logs.txt gesendet.
azsphere device list --verbose > output.txt 2> logs.txt
Sie können die Ausgabe auch auf dem Bildschirm paginieren, indem Sie eine Pipeline an vorhandene Paginierungstools senden.
Zum Beispiel:
- In PowerShell (Windows):
azsphere device list | Out-Host –Paging - An einer Eingabeaufforderung (Windows):
azsphere device list | more - In der Bash-Shell (Linux):
azsphere device list | less
Hinweis
Dieser Vorgang kann abhängig davon, wie viele Daten zurückgegeben werden, möglicherweise langsam sein.
Weitere Informationen zur Paginierung für die klassische Azure Sphere-Befehlszeilenschnittstelle finden Sie unter Paging und Ergebnisumleitung.
Abfrage-CLI-Befehlsausgabe
Die Azure Sphere-CLI verwendet das --query Argument, um eine JMESPath-Abfrage für die Ergebnisse von Befehlen auszuführen. JMESPath ist eine Abfragesprache für JSON, mit der Sie Daten aus der CLI-Ausgabe auswählen und ändern können. Abfragen werden in der JSON-Ausgabe vor jeder Anzeigeformatierung ausgeführt.
Das --query Argument wird von allen Befehlen in der Azure Sphere-CLI unterstützt. Weitere Informationen und Beispiele finden Sie unter JMESPath-Tutorial und Abfragen der Azure CLI-Befehlsausgabe .
Abwärtskompatibilität
Die CLI unterstützt die Abwärtskompatibilität. In jedem Release möchten wir abwärtskompatibilität sowohl für Eingaben (Befehlsnamen, Parameternamen, Parameterwerte) als auch für die Ausgabe in JSON und YAML gewährleisten. In Fällen, in denen eine solche Kompatibilität nicht möglich ist, werden wir mindestens 6 Monate im Voraus informieren, bevor wir Änderungen vornehmen. Weitere Informationen finden Sie unter Wichtige Änderungen (Außerbetriebnahme von Features) in der Azure Sphere-CLI.
Exitcodes
Ein erfolgreicher Befehl gibt eine Null zurück. Jeder Wert ungleich 0 kann als Fehlercode interpretiert werden. Bei Erfolg haben die JSON- und YAML-Ausgaben eine abwärtskompatible vertragliche Garantie.
Feedback geben
Wenn Sie einen Fehler in Azure Sphere finden, melden Sie ein Problem auf GitHub. Verwenden Sie den Feedbackbefehl, um Feedback über die Befehlszeile zu geben.
Effektives Verwenden der Azure Sphere-CLI
Die Azure Sphere-CLI kann über Bash, PowerShell oder ein Eingabeaufforderungsfenster verwendet werden. Hier sind einige Tipps für die Verwendung der CLI:
- Verwenden von Anführungszeichen in Werten: Wenn Sie einen Parameter angeben, der Leerzeichen enthält, schließen Sie ihn in Anführungszeichen ein. In Bash oder PowerShell werden einfache und doppelte Anführungszeichen interpretiert. In der Windows-Eingabeaufforderung werden nur doppelte Anführungszeichen interpretiert. Einfache Anführungszeichen werden als Teil des Werts interpretiert. Beispiel:
azsphere product create --name "My Fridge Product". Weitere Informationen finden Sie unter Anführungszeichen und Escapezeichen. - Viele Azure Sphere-Befehle zeigen Informationen in der Konsole im Standardformat
tablean. Beispiel:azsphere product device-group list --product DW100. Manchmal passen die angezeigten Informationen nicht ordnungsgemäß zur Konsole. Dies kann zu Problemen führen, wenn Sie die Informationen kopieren und einfügen möchten. Es wird empfohlen, die folgenden Optionen auszuprobieren:- Ändern Sie die Größe der Konsole, und führen Sie den Befehl erneut aus.
- Verwenden Sie die JSON-Ausgabe für präzise Ausgabe- und Skripterstellungszwecke. Beispiel:
azsphere product device-group list --product DW100 --output json. - Verwenden Sie die Tabulatorvervollständigung in Windows PowerShell- oder Bash-Shell, um einen Befehlseintrag automatisch abzuschließen.
- Verwenden Sie den interaktiven Modus , der eine interaktive Umgebung bereitstellt, um Informationen automatisch anzuzeigen und die Auswahl von Befehlen und Unterbefehlen zu vereinfachen. Wechseln Sie mit dem Befehl azsphere interactive in den interaktiven Modus. Die Eingabeaufforderung ändert sich in azsphere>> , um anzugeben, dass Sie jetzt Befehle in der interaktiven Shell ausführen.