通过

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.cn/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 命令将 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`

有关更多示例，请参阅 C# 和 node.js。

用于 TCP 套接字

使用以下语法可作为 JSONRPC 客户端连接到现有 TCP 套接字。

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.cn/<module-path>:<tag> --documentationUri <documentation-uri>

例如：

az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.cn/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.cn/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

本地缓存位于：

  • 在 Windows 上

    %USERPROFILE%\.bicep\br\<registry-name>.azurecr.cn\<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 文件，请参阅：