你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
Azure CLI 命令
本文介绍可在 Bicep CLI 中使用的命令。 执行这些命令有两个选择:利用 Azure CLI 或直接调用 Bicep CLI 命令。 每种方法都需要不同的安装过程。 有关详细信息,请参阅安装 Azure CLI 和安装 Azure PowerShell。
本文演示如何在 Azure CLI 中运行命令。 在通过 Azure CLI 运行时,使用 az
来启动该命令。 如果不使用 Azure CLI,则无需在命令开始部分使用 az
来运行命令。 例如,az bicep build
变为 bicep build
,az bicep version
变为 bicep --version
。
build
build
命令将 Bicep 文件转换为 Azure 资源管理器模板(ARM 模板)。 通常,无需运行此命令,因为它会在部署 Bicep 文件时自动运行。 如果想查看基于 Bicep 文件创建的 ARM 模板 JSON,请手动运行该命令。
使用以下任何 Bicep 功能会自动启用语言版本 2.0 代码生成:
下面的示例将名为 main.bicep 的 Bicep 文件转换为名为 main.json 的 ARM 模板 。 新文件的创建位置与 Bicep 文件所在的目录相同。
az bicep build --file main.bicep
下一个示例将 main.json 保存到其他目录。
az bicep build --file main.bicep --outdir c:\jsontemplates
下一个示例指定要创建的文件的名称和位置。
az bicep build --file main.bicep --outfile c:\jsontemplates\azuredeploy.json
若要将文件输出到 stdout
,请使用:
az bicep build --file main.bicep --stdout
如果你的 Bicep 文件包含引用外部注册表的模块,则构建命令会自动调用 restore。 restore 命令从注册表获取文件,并存储在本地缓存中。
注意
restore 命令不会刷新缓存。 有关详细信息,请参阅 restore。
如果不希望自动调用 restore,请使用 --no-restore
开关:
az bicep build --no-restore <bicep-file>
如果其中一个外部模块尚未被缓存,则使用 --no-restore
开关的构建过程将失败:
The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.
出现此错误时,请运行不含 --no-restore
开关的 build
命令,或先运行 bicep restore
。
要使用 --no-restore
开关,你必须拥有 Bicep CLI 版本 0.4.X 或更高版本。
build-params
build-params
命令将 .bicepparam 文件生成为 JSON 参数文件。
az bicep build-params --file params.bicepparam
此命令将 params.bicepparam 参数文件转换为 params.json JSON 参数文件。
反向编译
decompile
命令将 ARM 模板 JSON 转换为 Bicep 文件。
az bicep decompile --file main.json
该命令在与 main.json 相同的目录中创建名为 main.bicep 的文件。 如果此相同目录中存在 main.bicep,请使用 --force 开关覆盖现有的 Bicep 文件。
有关如何使用此命令的详细信息,请参阅将 ARM 模板 JSON 反向编译为 Bicep。
decompile-params
decompile-params
命令将 JSON 参数文件反向编译为 .bicepparam 参数文件。
az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/main.bicep
此命令将 azuredeploy.parameters.json 参数文件反向编译为 azuredeploy.parameters.bicepparam 文件。 --bicep-file
指定在 using
声明中引用的 Bicep 文件的路径(相对于 .bicepparam 文件)。
format
format
命令格式化 Bicep 文件。 它具有与 Visual Studio Code 中的 SHIFT+ALT+F
快捷方式相同的功能。
az bicep format --file main.bicep
generate-params
generate-params
命令从给定 bicep 文件生成参数文件,如果存在现有参数文件则会进行更新。
az bicep generate-params --file main.bicep --output-format bicepparam --include-params all
该命令创建一个名为 main.bicepparam 的 Bicep 参数文件。 参数文件包含 Bicep 文件中的所有参数,无论是否使用默认值进行配置。
az bicep generate-params --file main.bicep --outfile main.parameters.json
该命令创建一个名为 main.parameters.json的参数文件。 参数文件仅包含未在 Bicep 文件中配置的默认值的参数。
install
install
命令将 Bicep CLI 添加到本地环境。 有关详细信息,请参阅安装 Bicep 工具。 此命令只可通过 Azure CLI 使用。
若要安装最新版本,请运行以下命令:
az bicep install
安装特定版本:
az bicep install --version v0.3.255
jsonrpc
该 jsonrpc
命令允许使用 JSON-RPC 接口运行 Bicep CLI,从而允许编程方式与结构化输出进行交互,并避免在编译多个文件时出现冷启动延迟。 此设置还支持构建库以编程方式以 non-.NET 语言与 Bicep 文件交互。
发送和接收输入/输出的线路格式是标头分隔的,使用以下结构,其中 \r
并 \n
表示回车符和换行符:
Content-Length: <length>\r\n\r\n<message>\r\n\r\n
<length>
是字符串的<message>
长度,包括尾随\r\n\r\n
。<message>
是原始 JSON 消息。
例如:
Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n
以下消息显示了 Bicep 版本的示例。
输入:
{ "jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {} }
输出:
{ "jsonrpc": "2.0", "id": 0, "result": { "version": "0.24.211" } }
有关可用方法和请求/响应正文,请参阅 ICliJsonRpcProtocol.cs
。
有关使用 Node 以编程方式建立 JSONRPC 连接并与 Bicep 文件交互的示例,请参阅 jsonrpc.test.ts
。
命名管道的用法
使用以下语法作为 JSONRPC 客户端连接到现有的命名管道。
bicep jsonrpc --pipe <named_pipe>`
<named_pipe>
是用于将 JSONRPC 客户端连接到的现有命名管道。
若要连接到 OSX/Linux 上的命名管道,
bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock
若要连接到 Windows 上的命名管道,
bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`
TCP 套接字的使用
使用以下语法将现有 TCP 套接字作为 JSONRPC 客户端连接到。
bicep jsonrpc --socket <tcp_socket>
<tcp_socket>
是用于将 JSONRPC 客户端连接到的套接字号。
连接到 TCP 套接字
bicep jsonrpc --socket 12345
stdin 和 stdout 的使用
使用以下语法通过 stdin 和 stdout 为消息运行 JSONRPC 接口。
bicep jsonrpc --stdio
lint
lint
命令返回 Bicep 文件的错误和 linter 规则冲突。
az bicep lint --file main.bicep
如果你的 Bicep 文件包含引用外部注册表的模块,则 lint 命令会自动调用 restore。 restore 命令从注册表获取文件,并存储在本地缓存中。
注意
restore 命令不会刷新缓存。 有关详细信息,请参阅 restore。
如果不希望自动调用 restore,请使用 --no-restore
开关:
az bicep lint --no-restore <bicep-file>
如果其中一个外部模块尚未被缓存,则使用 --no-restore
开关的 lint 过程将失败:
The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.
出现此错误时,请运行不含 --no-restore
开关的 lint
命令,或先运行 bicep restore
。
list-versions
list-versions
命令返回 Bicep CLI 的所有可用版本。 使用此命令查看是否要升级或安装新版本。 此命令只可通过 Azure CLI 使用。
az bicep list-versions
该命令返回可用版本的数组。
[
"v0.28.1",
"v0.27.1",
"v0.26.170",
"v0.26.54",
"v0.25.53",
"v0.25.3",
"v0.24.24",
"v0.23.1",
"v0.22.6",
"v0.21.1",
"v0.20.4",
"v0.19.5",
"v0.18.4",
"v0.17.1",
"v0.16.2",
"v0.16.1",
"v0.15.31",
"v0.14.85",
"v0.14.46",
"v0.14.6",
"v0.13.1",
"v0.12.40",
"v0.12.1",
"v0.11.1",
"v0.10.61",
"v0.10.13",
"v0.9.1",
"v0.8.9",
"v0.8.2",
"v0.7.4"
]
发布
publish
命令可将模块添加到注册表。 Azure 容器注册表必须存在,并且发布到注册表的帐户必须具有正确的权限。 有关设置模块注册表的更多信息,请参阅对 Bicep 模块使用专用注册表。 若要发布模块,该帐户必须具有正确的配置文件和权限以便访问注册表。 你可以在 Bicep 配置文件中设置配置文件和凭据优先级,以用于向注册表证明身份。
将文件发布到注册表后,可以在模块中引用文件。
要使用“发布”命令,你必须拥有 Bicep CLI 版本 0.14.X 或更高版本。 要使用 --documentationUri
/-d
参数,你必须拥有 Bicep CLI 版本 0.14.X 或更高版本。
若要将模块发布到注册表,请使用:
az bicep publish --file <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>
例如:
az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html
publish
命令无法识别 bicepconfig.json 文件中指定的别名。 提供完整的模块路径。
警告
发布到同一目标会覆盖旧模块。 建议在更新时递增版本。
还原
当 Bicep 文件使用已发布到注册表的模块时,restore
命令会从注册表获取所有必需模块的副本。 该命令会将这些副本存储在本地缓存中。 只有当外部文件在本地缓存中可用时,才能生成 Bicep 文件。 通常不需要运行还原,因为它由生成进程自动触发。
若要将外部模块还原到本地缓存,该帐户必须具有正确的配置文件和权限以便访问注册表。 你可以在 Bicep 配置文件中设置配置文件和凭据优先级,以用于向注册表证明身份。
要使用“还原”命令,你必须拥有 Bicep CLI 版本 0.4.X 或更高版本。 此命令目前只可在直接调用 Bicep CLI 时使用。 它目前无法通过 Azure CLI 命令使用。
若要手动还原文件的外部模块,请使用:
az bicep restore --file <bicep-file> [--force]
提供的 Bicep 文件是想要部署的文件。 必须包含链接到注册表的模块。 例如,可以还原以下文件:
module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
name: 'storageDeploy'
params: {
storagePrefix: 'examplestg1'
}
}
本地缓存位于:
在 Windows 上
%USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>
在 Linux 上
/home/<username>/.bicep
在 Mac 上
~/.bicep
如果已缓存模块,则 restore
命令不会刷新缓存。 若要刷新缓存,可以从缓存中删除模块路径,或将 --force
开关与 restore
命令配合使用。
升级
upgrade
命令使用最新版本更新已安装的版本。 此命令只可通过 Azure CLI 使用。
az bicep upgrade
版本
version
命令返回已安装的版本。
az bicep version
该命令显示版本号。
Bicep CLI version 0.22.6 (d62b94db31)
若要通过 Bicep CLI 直接调用此命令,请使用:
bicep --version
如果尚未安装 Bicep CLI,则会看到一条错误消息,其中指出找不到 Bicep CLI。
后续步骤
若要了解如何部署 Bicep 文件,请参阅: