Azure Sphere CLI
重要
這是 Azure Sphere （舊版） 檔。 Azure Sphere（舊版）將於 2027 年 9 月 27 日淘汰，且使用者此時必須移轉至 Azure Sphere（整合式）。 使用位於 TOC 上方的版本選取器來檢視 Azure Sphere （整合式） 檔。
Azure Sphere SDK 提供 PowerShell、Windows 命令提示字元或 Linux 命令殼層上提供的 Azure Sphere 命令行介面（CLI）。 Azure Sphere CLI 是一組用來建立和管理 Azure Sphere 資源的命令。
Azure Sphere CLI 會與 Windows 和 Linux 上淘汰的 Azure Sphere 傳統 CLI 一起安裝，因此您可以存取任一介面。 若要使用 Azure Sphere CLI：
- 在 Windows 上，使用 PowerShell 或標準 Windows 命令提示字元。
- 在 Linux 上，使用任何命令殼層。
執行 Azure Sphere CLI
您現在可以從 Windows 命令提示字元或 PowerShell 使用 azsphere 命令來執行 Azure Sphere CLI。 建議您使用PowerShell，因為它提供 Windows 命令提示字元中無法使用的索引標籤自動完成 功能。
在 Linux 上，您可以從任何命令行介面 （CLI） 執行 Azure Sphere CLI。 安裝期間會顯示通知，可讓您將 Azure Sphere CLI 或 Azure Sphere 傳統 CLI 設定為慣用的預設 CLI 版本。
輸入 Yes 以選擇 Azure Sphere CLI，或輸入 No 以使用 Azure Sphere 傳統 CLI。 如需詳細資訊，請參閱 安裝 Azure Sphere SDK 。
注意
Azure Sphere CLI 版本不支援命令的簡短格式。 我們建議您使用 索引標籤完成 功能來檢視可用的命令清單。 在 Windows 上，淘汰的 Azure Sphere 傳統開發人員命令提示字元快捷方式只能與 Azure Sphere 傳統 CLI 搭配使用。
CLI 輸入功能
本節說明 Azure Sphere CLI 中可用的輸入功能：
命令
Azure Sphere CLI 中的所有命令都會以 azsphere開頭。 例如：
azsphere login
---------------------
Name
=====================
bob@contoso.com
---------------------
尋找命令
CLI 中的命令會以群組方式組織。 您可以在 Azure Sphere 傳統 CLI 和 Azure Sphere CLI 中使用，來檢視可用命令和參數 --help 的完整說明資訊。
您可以執行 命令 來取得命令 azsphere --help的完整清單。
例如：
- 針對 Azure Sphere 傳統 CLI 使用，
azsphere --help或azsphere -? - 針對 Azure Sphere CLI 使用，
azsphere --help或azsphere -h
參數
參數的名稱前面加上雙連字元 （--），表示連字元後面的單字是參數。 使用空格來分隔參數名稱和值。 複合字的參數會以新 CLI 中的連字元 （-） 分隔。
例如： --component-id 或 --application-update
簡化的對象識別
在 Azure Sphere CLI 中，會使用單一參數來識別每個物件類型。 這表示您可以提供適用於該參數的標識碼、名稱、IP 或位置。
例如，您可以在下列命令中使用租使用者標識碼或租用戶名稱：
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
或
azsphere device list --tenant MyTenant
這已針對 、--tenant、 --product和 --device-group 參數實作--device。
例如：
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
------------------------------------ ------------------------------------ ---------- ------------------------------------ --------- ---------------------- ---------------------------------------------------------- -------------------------
多個值
某些命令允許單一參數的多個值，在此情況下，您可以為每個值提供參數，或提供單一參數，後面接著以空格分隔的值清單。 例如，下列兩個命令相等：
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
必要和選擇性參數
當您執行 azsphere <command> <sub-command> --help 適用於該命令的參數清單時，會顯示該命令。 [必要] 設定指出參數是否為成功執行命令的必要參數。 所有其他參數皆為選擇性使用。
如果遺漏必要的參數，系統會提示您輸入 參數的值。
例如：
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.
輸入和輸出路徑
在 Azure Sphere CLI 中，用來指定路徑和檔名的參數名稱已更新為與命令內容相關。
例如：
azsphere image-package pack-application --package-directory C:\AppSamples\LocalSamples\HelloWorld\HelloWorld_HighLevelApp\out\ARM-Debug\approotHelloWorld_HighLevelApp --destination myimage.imagepackage
在這裡， --package-directory 指定封裝的輸入目錄，參數 --destination 會指定所產生映像套件的路徑和檔名。
Tab 鍵自動完成
索引標籤自動完成命令列介面中的命令專案提供說明。 在 Azure Sphere CLI 索引標籤完成中，群組、命令、參數名稱和參數值都支援。 輸入命令的幾個字元，然後按 TAB 以選取所需的完成文字。 如果多個專案以您最初輸入的文字開始，請繼續按 TAB 鍵，直到您想要的項目出現為止。
在 Windows 上，PowerShell 7.1 提供 Windows 命令提示字元中無法使用的索引標籤完成功能。
若要在 Windows PowerShell 中啟用索引標籤自動完成，請執行 Import-Module -name AzsphereCli。
此命令只會啟用會話的索引標籤完成。 您可以將 腳本新增至 PowerShell 配置檔 ，以自定義您的環境，並針對您啟動的每個 PowerShell 工作階段啟用索引標籤完成。
在 Linux 上，Azure Sphere CLI 支援 Bash 殼層下命令的索引標籤完成功能。
此外，自動完成可協助您探索可供使用的命令、參數和參數值。 這可在 Windows PowerShell 中使用 CTRL+空格 鍵，或在 Linux Bash 殼層中按 TAB 鍵兩次。
例如，輸入 azsphere product update 命令 並使用自動完成來查看可用參數的清單。
同樣地，輸入 azsphere product update --product 並使用自動完成查看租使用者中可用產品的清單。
互動式模式 （預覽）
重要
此功能處於預覽。 未來版本中可能會變更或移除。
新的 CLI 提供互動式模式，可自動顯示說明資訊，並讓您更輕鬆地選取命令、子命令、參數和參數值。 使用 azsphere interactive 命令進入互動式模式。 命令提示字元會變更為 azsphere>> ，表示您現在正在互動式殼層中執行命令。
如需詳細資訊，請參閱 Azure Sphere CLI 互動式模式。
CLI 輸出功能
本節說明 Azure Sphere CLI 中可用的輸出功能：
下列各節說明新 CLI 中可用的輸出功能：
支援的輸出格式
新 CLI 中的可用輸出格式為 json、（色彩化 JSON）、（Tab 分隔值）、 tsv table （人類可讀取的 ASCII 資料表）和 yamljsonc 。 根據預設，CLI 會輸出 table。 若要深入瞭解可用的輸出格式，請參閱 Azure Sphere CLI 支援的輸出格式。
重新導向和分頁
Azure Sphere CLI 不支援互動式分頁。 不過，您可以將命令的標準輸出重新導向至檔案。 在下列範例中，針對 Windows 命令提示字元、Windows PowerShell 和 Linux Bash 殼層，會將標準輸出傳送至 output.txt，並將標準錯誤傳送至 logs.txt。
azsphere device list --verbose > output.txt 2> logs.txt
您也可以將管線傳送至現有的分頁工具，以分頁畫面上的輸出。
例如：
- 在 PowerShell 中（Windows）：
azsphere device list | Out-Host –Paging - 在命令提示字元中（Windows）：
azsphere device list | more - 在Bash殼層中（Linux）：
azsphere device list | less
注意
視傳回的數據量而定，此作業可能會變慢。
如需 Azure Sphere 傳統 CLI 分頁的詳細資訊，請參閱 分頁和結果重新導向。
查詢 CLI 命令輸出
Azure Sphere CLI 會使用 --query 自變數在命令結果上執行 JMESPath 查詢。 JMESPath 是 JSON 的查詢語言，可讓您從 CLI 輸出中選取和修改數據。 查詢會在任何顯示格式設定之前，於 JSON 輸出上執行。
Azure Sphere CLI 中的所有命令都支援自 --query 變數。 如需詳細資訊和範例，請參閱 JMESPath 教學 課程和 查詢 Azure CLI 命令輸出 。
回溯相容性
CLI 支援回溯相容性。 在每個版本中，我們的目標是維護輸入（命令名稱、參數名稱、參數值）及其 JSON 和 YAML 輸出的回溯相容性。 如果無法達到這類相容性，我們會在進行變更之前提供至少 6 個月的通知。 如需詳細資訊，請參閱 Azure Sphere CLI 中的重要變更（淘汰功能）。
結束代碼
成功的命令會傳回零。 任何非零值都可以解譯為錯誤碼。 成功時， JSON 和 YAML 輸出具有回溯相容的合約保證。
提供意見反應
如果您在 Azure Sphere 中找到 Bug， 請在 GitHub 上提出問題。 若要從命令行提供意見反應，請使用 意見反應命令。
有效地使用 Azure Sphere CLI
您可以從 Bash、PowerShell 或命令提示字元視窗使用 Azure Sphere CLI。 以下是使用 CLI 的一些秘訣：
- 在值中使用引號：如果您提供參數包含空格的值，請以引號括住它。 在Bash或PowerShell中，會解譯單引號和雙引號。 在 Windows 命令提示字元中，只會解譯雙引號。 單引號會解譯為值的一部分。 例如：
azsphere product create --name "My Fridge Product"。 如需詳細資訊，請參閱 引號和逸出字元。 - 許多 Azure Sphere 命令會以預設
table格式顯示控制台中的資訊。 例如：azsphere product device-group list --product DW100。 有時顯示的資訊不符合控制台。 如果您想要複製並貼上資訊，這可能會導致問題。 建議您試著下列選項：- 調整主控台的大小，然後再次執行命令。
- 使用 JSON 輸出 進行簡潔的輸出和腳本。 例如：
azsphere product device-group list --product DW100 --output json。 - 在 Windows PowerShell 或 Bash 殼層中使用 Tab 鍵自動 完成命令專案。
- 使用互動式模式，提供互動式環境來自動顯示資訊，並讓您更輕鬆地選取命令和子命令。 使用 azsphere interactive 命令進入互動式模式。 命令提示字元會變更為 azsphere>> ，表示您現在正在互動式殼層中執行命令。