Azure Sphere-CLI
Wichtig
Dies ist die Dokumentation zu Azure Sphere (Legacy). Azure Sphere (Legacy) wird am 27. September 2027 eingestellt, und Benutzer müssen bis zu diesem Zeitpunkt zu Azure Sphere (integriert) migrieren. Verwenden Sie die Versionsauswahl oberhalb des Inhaltsverzeichniss, um die Dokumentation zu Azure Sphere (Integriert) anzuzeigen.
Das Azure Sphere SDK stellt die Azure Sphere-Befehlszeilenschnittstelle (CLI) bereit, die auf PowerShell, Windows-Eingabeaufforderung oder Linux-Befehlsshell verfügbar ist. Die Azure Sphere CLI ist eine Reihe von Befehlen zum Erstellen und Verwalten von Azure Sphere-Ressourcen.
Die Azure Sphere CLI wird neben der eingestellten klassischen Azure Sphere CLI sowohl unter Windows als auch unter Linux installiert, sodass Sie Zugriff auf beide Schnittstellen haben. So verwenden Sie Azure Sphere CLI:
- Verwenden Sie unter Windows PowerShell oder eine Windows-Standard-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. PowerShell wird empfohlen, da es das Feature zum Abschließen der Registerkarte bietet, das über die Windows-Eingabeaufforderung nicht verfügbar ist.
Unter Linux können Sie Azure Sphere CLI über jede Befehlszeilenschnittstelle (CLI) ausführen. Während der Installation wird eine Benachrichtigung angezeigt, mit der Sie azure Sphere CLI oder die klassische Azure Sphere CLI als bevorzugte Standard-CLI-Version festlegen können.
Geben Sie den Yes Typ ein, um Azure Sphere CLI oder Typ No auszuwählen, um die klassische Azure Sphere CLI zu verwenden. Weitere Informationen finden Sie unter Installieren des Azure Sphere SDK .
Hinweis
Das kurze Formular für Befehle wird in der Azure Sphere CLI-Version nicht unterstützt. Es wird empfohlen, die Registerkartenvervollständigen-Funktion zum Anzeigen der Liste der verfügbaren Befehle zu verwenden. Unter Windows kann die absagende Azure Sphere Classic 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
---------------------
Suchen nach Befehlen
Befehle in der CLI sind in Gruppen organisiert. Sie können vollständige Hilfeinformationen für die verfügbaren Befehle und Parameter anzeigen, indem Sie die klassische Azure Sphere CLI und Azure Sphere CLI verwenden --help .
Sie können eine vollständige Liste von Befehlen abrufen, indem Sie den Befehl azsphere --helpausführen.
Zum Beispiel:
- Für die klassische Cli-Verwendung
azsphere --helpvon Azure Sphere oderazsphere -? - Für die Verwendung von
azsphere --helpAzure Sphere CLI oderazsphere -h
Parameter
Dem Namen des Parameters wird zwei Bindestriche (--) vorangestellt, die signalisieren, dass das Wort, das dem Bindestrich folgt, ein Parameter ist. Verwenden Sie ein Leerzeichen, um den Parameternamen und den Wert zu trennen. Die Parameter, die zusammengesetzte Wörter sind, werden durch einen Bindestrich (-) in der neuen CLI 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 oder den ort angeben können, der für diesen Parameter gilt.
Sie können z. B. entweder die Mandanten-ID oder den Mandantennamen im folgenden Befehl verwenden:
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
or
azsphere device list --tenant MyTenant
Dies wurde für die --deviceParameter , , --tenantund --product--device-group dies 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 ermöglichen mehrere Werte für einen einzelnen Parameter. In diesem Fall können Sie entweder einen Parameter für jeden Wert oder einen einzelnen Parameter angeben, gefolgt von einer Liste von Werten, die durch Leerzeichen getrennt sind. Die folgenden zwei Befehle sind beispielsweise äquivalent:
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 erforderlich 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 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
--package-directory Hier gibt das Eingabeverzeichnis für das Paket und --destination den Parameter den Pfad und Dateinamen für das resultierende Bildpaket an.
Registerkartenvervollständigung
Der Abschluss der Registerkarte bietet Hilfe beim automatischen Abschließen eines Befehlseintrags in der Befehlszeilenschnittstelle. Der Abschluss der Azure Sphere CLI-Registerkarte wird für Gruppen, Befehle, Parameternamen und Parameterwerte unterstützt. Geben Sie ein paar Zeichen eines Befehls ein, und drücken Sie dann die TAB-TASTE, um den gewünschten Abschlusstext auszuwählen. Gibt es mehrere Elemente, die mit dem Text beginnen, den Sie ursprünglich eingegeben haben, drücken Sie so lange die TAB-TASTE, bis das gewünschte Element angezeigt wird.
Unter Windows bietet PowerShell 7.1 das Feature zum Abschließen der Registerkarte, das über die Windows-Eingabeaufforderung nicht verfügbar ist.
Führen Sie die Ausführung der Registerkarte in Windows PowerShell aus, um den Abschluss der Import-Module -name AzsphereCliRegisterkarte zu aktivieren.
Mit diesem Befehl wird der Tabstoppabschluss nur für die Sitzung aktiviert. Sie können Ihrem PowerShell-Profil ein Skript hinzufügen, um Ihre Umgebung anzupassen und den Abschluss der Registerkarte für jede powerShell-Sitzung zu aktivieren, die Sie starten.
Unter Linux unterstützt Azure Sphere CLI das Feature zum Abschließen der Registerkarte für Befehle unter der Bash-Shell.
Darüber hinaus können Sie mithilfe von AutoVervollständigen Befehle, Parameter und Parameterwerte ermitteln, die zur Verwendung verfügbar sind. Dies ist mit STRG+LEERTASTE in Windows PowerShell verfügbar, oder drücken Sie zweimal die TAB-TASTE in der Linux-Bash-Shell.
Geben Sie z. B. den Befehl "azsphere product update" ein, und verwenden Sie "AutoVervollständigen", um eine Liste der verfügbaren Parameter anzuzeigen.
Ebenso geben Sie azsphere Produktupdate --Produkt und verwenden AutoVervollständigen, um eine Liste der verfügbaren Produkte in Ihrem Mandanten anzuzeigen.
Interaktiver Modus (Vorschau)
Wichtig
Dieses Feature befindet sich in der Vorschau. Sie kann in einem zukünftigen Release geändert oder entfernt werden.
Die neue CLI bietet einen interaktiven Modus, der Automatisch Hilfeinformationen anzeigt und die Auswahl von Befehlen, Unterbefehlen, Parametern und Parameterwerten erleichtert. Geben Sie den interaktiven Modus mit dem interaktiven Azsphere-Befehl ein. Die Eingabeaufforderung ändert sich, azsphere>> um anzugeben, dass Sie jetzt Befehle in der interaktiven Shell ausführen.
Weitere Informationen finden Sie im interaktiven Azure Sphere CLI-Modus.
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 , ( jsonc farbige JSON), tsv (tabtrennte Werte), table (lesbare ASCII-Tabellen) und yaml.json Die CLI gibt standardmäßig table aus. Weitere Informationen zu den verfügbaren Ausgabeformaten finden Sie unter Unterstützte Ausgabeformate für Azure Sphere CLI.
Umleitung und Paginierung
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, Windows PowerShell und die Linux Bash-Shell die Standardausgabe an output.txt gesendet, und Standardfehler werden 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 vorhandene Paginierungstools anfügen.
Zum Beispiel:
- In PowerShell (Windows):
azsphere device list | Out-Host –Paging - An einer Eingabeaufforderung (Windows):
azsphere device list | more - In Bash Shell (Linux):
azsphere device list | less
Hinweis
Dieser Vorgang kann möglicherweise langsam sein, je nachdem, wie viele Daten zurückgegeben werden.
Weitere Informationen zur Paginierung für die klassische Azure Sphere-CLI 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, die es ermöglicht, Daten aus der CLI-Ausgabe auszuwählen und zu ändern. Abfragen werden vor jeder Anzeigeformatierung auf der JSON-Ausgabe ausgeführt.
Das --query Argument wird von allen Befehlen in Azure Sphere CLI unterstützt. Weitere Informationen und Beispiele finden Sie im JMESPath-Lernprogramm und in der Abfrage der Azure CLI-Befehlsausgabe .
Abwärtskompatibilität
Die CLI unterstützt die Abwärtskompatibilität. In jeder Version wird die Abwärtskompatibilität sowohl für Eingaben (Befehlsnamen, Parameternamen, Parameterwerte) als auch für die Ausgabe in JSON und YAML beibehalten. In Fällen, in denen eine solche Kompatibilität nicht möglich ist, werden wir mindestens 6 Monate vor änderungsbereit stellen. Weitere Informationen finden Sie unter Wichtige Änderungen (Einstellungsfeatures) in Azure Sphere CLI.
Exitcodes
Ein erfolgreicher Befehl gibt eine Null zurück. Jeder Wert ungleich Null kann als Fehlercode interpretiert werden. Nach Erfolg haben die JSON- und YAML-Ausgaben eine abwärtskompatible vertragliche Garantie.
Feedback geben
Wenn Sie einen Fehler in Azure Sphere finden, legen Sie ein Problem auf GitHub fest. Verwenden Sie den Feedbackbefehl, um Feedback über die Befehlszeile bereitzustellen.
Effektive Verwendung von Azure Sphere CLI
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 sowohl einfache als auch 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 Ihnen 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 zu testen:- Ä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 Skriptzwecke. Beispiel:
azsphere product device-group list --product DW100 --output json. - Verwenden Sie die Registerkartenvervollständigung in Windows PowerShell oder Bash-Shell, um automatisch einen Befehlseintrag abzuschließen.
- Verwenden Sie den interaktiven Modus , der eine interaktive Umgebung zum automatischen Anzeigen von Informationen bereitstellt und die Auswahl von Befehlen und Unterbefehlen erleichtert. Geben Sie den interaktiven Modus mit dem interaktiven Azsphere-Befehl ein. Die Eingabeaufforderung ändert sich in azsphere>> , um anzugeben, dass Sie jetzt Befehle in der interaktiven Shell ausführen.