Comandos da CLI do Bíceps

Artigo
12/06/2024

Este artigo descreve os comandos que você pode usar na CLI do Bicep. Você tem duas opções para executar esses comandos: utilizando a CLI do Azure ou invocando diretamente os comandos da CLI do Bicep. Cada método requer um processo de instalação distinto. Para obter mais informações, consulte Instalar a CLI do Azure e Instalar o Azure PowerShell.

Este artigo mostra como executar os comandos na CLI do Azure. Ao executar a CLI do Azure, você inicia os comandos com az. Se você não estiver usando a CLI do Azure, execute os comandos sem az no início do comando. Por exemplo, az bicep build torna-se bicep build, e az bicep version torna-se bicep --version.

build

O build comando converte um arquivo Bicep em um modelo do Azure Resource Manager (modelo ARM). Normalmente, você não precisa executar esse comando porque ele é executado automaticamente quando você implanta um arquivo Bicep. Execute-o manualmente quando quiser ver o JSON de modelo ARM criado a partir do arquivo Bicep.

O uso de qualquer um dos seguintes recursos do Bicep habilita automaticamente a geração de código da versão 2.0 do idioma:

O exemplo a seguir converte um arquivo Bicep chamado main.bicep em um modelo ARM chamado main.json. O novo arquivo é criado no mesmo diretório que o arquivo Bicep.

az bicep build --file main.bicep

O próximo exemplo salva main.json em um diretório diferente.

az bicep build --file main.bicep --outdir c:\jsontemplates

O próximo exemplo especifica o nome e o local do arquivo a ser criado.

az bicep build --file main.bicep --outfile c:\jsontemplates\azuredeploy.json

Para imprimir o ficheiro no stdout, utilize:

az bicep build --file main.bicep --stdout

Se o arquivo Bicep incluir um módulo que faça referência a um registro externo, o comando build chamará automaticamente a restauração. O comando restore obtém o arquivo do registro e o armazena no cache local.

Nota

O comando restore não atualiza o cache. Para obter mais informações, consulte restaurar.

Para não chamar a restauração automaticamente, use o --no-restore switch:

az bicep build --no-restore <bicep-file>

O processo de compilação com o --no-restore switch falhará se um dos módulos externos ainda não estiver armazenado em cache:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Quando você receber esse erro, execute o build comando sem a --no-restore opção ou execute bicep restore primeiro.

Para usar o switch, você deve ter a --no-restore CLI do Bicep versão 0.4.X ou superior.

construir-params

O build-params comando cria um arquivo .bicepparam em um arquivo de parâmetros JSON.

az bicep build-params --file params.bicepparam

Este comando converte um arquivo de parâmetros params.bicepparam em um arquivo de parâmetros JSON params.json .

descompilar

O decompile comando converte o modelo ARM JSON em um arquivo Bicep.

az bicep decompile --file main.json

O comando cria um arquivo chamado main.bicep no mesmo diretório que main.json. Se main.bicep existir no mesmo diretório, use a opção --force para substituir o arquivo Bicep existente.

Para obter mais informações sobre como usar esse comando, consulte Descompilando o modelo ARM JSON para Bicep.

descompilar-params

O decompile-params comando descompila um arquivo de parâmetros JSON para um arquivo de parâmetros .bicepparam .

az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/main.bicep

Este comando descompila um arquivo de parâmetros azuredeploy.parameters.json em um arquivo azuredeploy.parameters.bicepparam . --bicep-file especifica o caminho para o arquivo Bicep (relativo ao arquivo .bicepparam) referenciado using na declaração.

format

O format comando formata um arquivo Bicep. Ele tem a mesma função que o SHIFT+ALT+F atalho no Visual Studio Code.

az bicep format --file main.bicep

generate-params

O generate-params comando constrói um arquivo de parâmetros a partir do arquivo Bicep fornecido, atualiza se houver um arquivo de parâmetros existente.

az bicep generate-params --file main.bicep --output-format bicepparam --include-params all

O comando cria um arquivo de parâmetros Bicep chamado main.bicepparam. O arquivo de parâmetros contém todos os parâmetros no arquivo Bicep, configurado com valores padrão ou não.

az bicep generate-params --file main.bicep --outfile main.parameters.json

O comando cria um arquivo de parâmetros chamado main.parameters.json. O arquivo de parâmetros contém apenas os parâmetros sem valores padrão configurados no arquivo Bicep.

instalar

O install comando adiciona a CLI do Bicep ao seu ambiente local. Para obter mais informações, consulte Instalar ferramentas do Bicep. Este comando só está disponível através da CLI do Azure.

Para instalar a versão mais recente, use:

az bicep install

Para instalar uma versão específica:

az bicep install --version v0.3.255

jsonrpc

O jsonrpc comando permite executar a CLI do Bicep com uma interface JSON-RPC, permitindo a interação programática com saída estruturada e evitando atrasos de inicialização a frio ao compilar vários arquivos. Esta configuração também suporta a criação de bibliotecas para interagir com arquivos Bicep programaticamente em non-.NET idiomas.

O formato de fio para enviar e receber entrada/saída é delimitado por cabeçalho, usando a seguinte estrutura, onde \r e \n representam caracteres de retorno de carro e alimentação de linha:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n

<length> é o <message> comprimento da cadeia de caracteres, incluindo o trailing \r\n\r\n.
<message> é a mensagem JSON bruta.

Por exemplo:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

A mensagem a seguir mostra um exemplo para a versão do Bicep.

A entrada:

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "bicep/version",
  "params": {}
}

A saída:

{
  "jsonrpc": "2.0",
  "id": 0,
  "result": {
    "version": "0.24.211"
  }
}

Para os métodos disponíveis e organismos de pedido/resposta, ver ICliJsonRpcProtocol.cs. Para obter um exemplo de estabelecimento de uma conexão JSONRPC e interação com arquivos Bicep programaticamente usando o Node, consulte jsonrpc.test.ts.

Uso para pipe nomeado

Use a sintaxe a seguir para se conectar a um pipe nomeado existente como um cliente JSONRPC.

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> é um pipe nomeado existente para conectar o cliente JSONRPC.

Para se conectar a um pipe nomeado no OSX/Linux :

bicep jsonrpc --pipe /tmp/bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock

Para se conectar a um pipe nomeado no Windows :

bicep jsonrpc --pipe \\.\pipe\\bicep-81375a8084b474fa2eaedda1702a7aa40e2eaa24b3.sock`

Para obter mais exemplos, consulte C# e node.js.

Uso para soquete TCP

Use a sintaxe a seguir para se conectar a um soquete TCP existente como um cliente JSONRPC.

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> é um número de soquete ao qual conectar o cliente JSONRPC.

Para conectar-se a um soquete TCP

bicep jsonrpc --socket 12345

Uso para stdin e stdout

Use a sintaxe a seguir para executar a interface JSONRPC usando stdin & stdout para mensagens.

bicep jsonrpc --stdio

fiapos

O lint comando retorna os erros e as violações da regra linter de um arquivo Bicep.

az bicep lint --file main.bicep

Se o arquivo Bicep incluir um módulo que faça referência a um registro externo, o comando lint chamará automaticamente a restauração. O comando restore obtém o arquivo do registro e o armazena no cache local.

Nota

O comando restore não atualiza o cache. Para obter mais informações, consulte restaurar.

Para não chamar a restauração automaticamente, use o --no-restore switch:

az bicep lint --no-restore <bicep-file>

O processo lint com o --no-restore switch falhará se um dos módulos externos ainda não estiver armazenado em cache:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Quando você receber esse erro, execute o lint comando sem a --no-restore opção ou execute bicep restore primeiro.

lista-versões

O list-versions comando retorna todas as versões disponíveis da CLI do Bicep. Use este comando para ver se deseja atualizar ou instalar uma nova versão. Este comando só está disponível através da CLI do Azure.

az bicep list-versions

O comando retorna uma matriz de versões disponíveis.

[
  "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"
]

publicar

O publish comando adiciona um módulo a um registro. O registro de contêiner do Azure deve existir e a publicação da conta no registro deve ter as permissões corretas. Para obter mais informações sobre como configurar um registro de módulo, consulte Usar registro privado para módulos Bicep. Para publicar um módulo, a conta deve ter o perfil e as permissões corretas para acessar o registro. Você pode configurar a precedência de perfil e credencial para autenticação no registro no arquivo de configuração do Bicep.

Depois de publicar o arquivo no registro, você pode fazer referência a ele em um módulo.

Para usar o comando publishing, você deve ter a CLI do Bicep versão 0.14.X ou superior. Para usar o parâmetro, você deve ter a-d --documentationUri/CLI do Bicep versão 0.14.X ou superior.

Para publicar um módulo em um registro, use:

az bicep publish --file <bicep-file> --target br:<registry-name>.azurecr.io/<module-path>:<tag> --documentationUri <documentation-uri>

Por exemplo:

az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

O publish comando não reconhece aliases especificados em um arquivo bicepconfig.json . Forneça o caminho completo do módulo.

Aviso

A publicação no mesmo destino substitui o módulo antigo. Recomendamos que você incremente a versão ao atualizar.

restore

Quando o arquivo Bicep usa módulos que são publicados em um registro, o restore comando obtém cópias de todos os módulos necessários do registro. Ele armazena essas cópias em um cache local. Um arquivo Bicep só pode ser criado quando os arquivos externos estão disponíveis no cache local. Normalmente, a execução da restauração não é necessária, pois ela é acionada automaticamente pelo processo de compilação.

Para restaurar módulos externos para o cache local, a conta deve ter o perfil e as permissões corretas para acessar o registro. Você pode configurar a precedência de perfil e credencial para autenticação no registro no arquivo de configuração do Bicep.

Para usar o comando restore, você deve ter a CLI do Bicep versão 0.4.X ou superior. Atualmente, esse comando só está disponível ao chamar a CLI do Bicep diretamente. No momento, ele não está disponível por meio do comando da CLI do Azure.

Para restaurar manualmente os módulos externos de um arquivo, use:

az bicep restore --file <bicep-file> [--force]

O arquivo Bicep que você fornece é o arquivo que você deseja implantar. Ele deve conter um módulo que vincula a um registro. Por exemplo, você pode restaurar o seguinte arquivo:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

O cache local é encontrado em:

No Windows

%USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

No Linux
```
/home/<username>/.bicep
```
No Mac
```
~/.bicep
```

O restore comando não atualiza o cache se um módulo já estiver armazenado em cache. Para atualizar o cache, você pode excluir o caminho do módulo do cache ou usar o --force switch com o restore comando.

atualizar

O upgrade comando atualiza a versão instalada com a versão mais recente. Este comando só está disponível através da CLI do Azure.

az bicep upgrade

versão

O version comando retorna a versão instalada.

az bicep version

O comando mostra o número da versão.

Bicep CLI version 0.22.6 (d62b94db31)

Para chamar esse comando diretamente através da CLI do Bicep, use:

bicep --version

Se a CLI do Bicep não tiver sido instalada, você encontrará uma mensagem de erro informando que a CLI do Bicep não foi encontrada.

Próximos passos

Para saber mais sobre como implantar um arquivo Bicep, consulte:

Partilhar via