Azure Sphere CLI
Azure Sphere SDK 提供 Azure Sphere 命令行接口 (CLI) PowerShell、Windows 命令提示符或 Linux 命令行界面。 Azure Sphere CLI 是一组用于创建和管理 Azure Sphere 资源的命令。
Azure Sphere CLI 与 即将停用的 Azure Sphere 经典 CLI 一起安装在 Windows 和 Linux 上，因此你可以访问任一接口。 若要使用 Azure Sphere CLI，请：
- 在 Windows 上，使用 PowerShell 或标准 Windows 命令提示符。
- 在 Linux 上，使用任何命令行界面。
运行 Azure Sphere CLI
现在，可以使用 Windows 命令提示符或 PowerShell 中的 命令运行 Azure Sphere CLI azsphere 。 建议使用 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 --helpazsphere -? - 对于 Azure Sphere CLI，请使用 或
azsphere --helpazsphere -h
参数
参数名称前面是双连字符 (--) ，这表示连字符后面的单词是参数。 使用空格分隔参数名称和值。 作为复合词的参数在新 CLI 中用连字符 ( ) 分隔。
例如： --component-id 或 --application-update
简化的对象标识
在 Azure Sphere CLI 中，单个参数用于标识每个对象类型。 这意味着可以提供适用于该参数的 ID、名称、IP 或位置。
例如，可以在以下命令中使用租户 ID 或租户名称：
azsphere device list --tenant 143adbc9-1bf0-4be2-84a2-084a331d81cb
或
azsphere device list --tenant MyTenant
这已针对 --device、 --tenant、 --product和 --device-group 参数实现。
例如：
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 自动补全
Tab 补全有助于自动完成命令行界面中的命令条目。 在 Azure Sphere CLI 选项卡中，组、命令、参数名称和参数值支持完成。 键入命令的几个字符，然后按 Tab 选择所需的完成文本。 如果多个项目以最初键入的文本开头，请继续按 Tab ，直到出现所需项。
在 Windows 上，PowerShell 7.1 提供 Windows 命令提示符中不可用的选项卡补全功能。
若要在 Windows PowerShell 中启用制表符补全，请运行 Import-Module -name AzsphereCli。
此命令仅对会话启用 Tab 补全。 可以将 脚本添加到 PowerShell 配置文件 ，以自定义环境，并为启动的每个 PowerShell 会话启用 Tab 自动补全。
在 Linux 上，Azure Sphere CLI 支持 Bash shell 下的命令的选项卡补全功能。
此外，自动完成有助于发现可用的命令、参数和参数值。 这可以通过在 Windows PowerShell 中使用 CTRL+Space 或在 Linux Bash shell 中按两次 TAB 来获得。
例如，键入 azsphere product update 命令 并使用自动完成查看可用参数的列表。
同样，键入 azsphere product update --product 并使用自动完成查看租户中可用产品的列表。
交互模式 (预览)
重要
此功能以预览版提供。 将来的版本中可能会更改或删除它。
新的 CLI 提供了一种交互式模式，该模式可自动显示帮助信息，并更易于选择命令、子命令、参数和参数值。 使用 azsphere interactive 命令进入交互模式。 命令提示符更改为 azsphere>> ，以指示你现在正在交互式 shell 中运行命令。
有关详细信息，请参阅 Azure Sphere CLI 交互模式。
CLI 输出功能
本部分介绍 Azure Sphere CLI 中可用的输出功能：
以下部分介绍新 CLI 中可用的输出功能：
支持的输出格式
新 CLI 中的可用输出格式为 json、 jsonc (着色的 JSON) 、 tsv (制表分隔值) 、 table (人工可读的 ASCII 表) 和 yaml。 默认情况下，CLI 输出 table。 若要详细了解可用的输出格式，请参阅 Azure Sphere CLI 支持的输出格式。
重定向和分页
Azure Sphere CLI 不支持交互式分页。 但是，可以将命令的标准输出重定向到文件。 在以下示例中，对于 Windows 命令提示符、Windows PowerShell和 Linux Bash shell，标准输出将发送到 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 shell (Linux) 中：
azsphere device list | less
注意
此操作可能会很慢，具体取决于返回的数据量。
有关 Azure Azure Sphere 经典 CLI 的分页的详细信息，请参阅 分页和结果重定向。
查询 CLI 命令输出
Azure Sphere CLI 使用 --query 参数对命令的结果运行 JMESPath 查询。 JMESPath 是 JSON 的查询语言，可用于从 CLI 输出中选择和修改数据。 查询在任何显示格式设置之前对 JSON 输出运行。
--query Azure Sphere CLI 中的所有命令都支持参数。 有关详细信息和示例，请参阅 JMESPath 教程 和 查询 Azure CLI 命令输出 。
向后兼容性
CLI 支持向后兼容性。 在每个版本中，我们旨在保持输入 (命令名称、参数名称、参数值) 及其 JSON 和 YAML 输出的向后兼容性。 如果无法实现此类兼容性，我们将在进行更改前至少提前 6 个月发出通知。 有关详细信息，请参阅 Azure Sphere CLI 中) (停用功能的重要更改。
退出代码
成功的命令返回零。 任何非零值都可以解释为错误代码。 成功后， JSON 和 YAML 输出具有向后兼容的合同保证。
提供反馈
如果在 Azure Sphere 中发现 bug，请在 GitHub 上提交问题。 若要从命令行提供反馈，请使用 feedback 命令。
有效使用 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 shell 中的选项卡补全功能自动完成命令条目。
- 使用 交互式模式 ，该模式提供交互式环境来自动显示信息，并使其更易于选择命令和子命令。 使用 azsphere interactive 命令进入交互模式。 命令提示符更改为 azsphere>> ，以指示你现在正在交互式 shell 中运行命令。