Comandos da CLI do Bicep

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: por meio da 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 comaz. Se você não estiver usando a CLI do Azure, execute os comandos sem az no início. Por exemplo, az bicep build torna-se bicep builde az bicep version se torna bicep --version.

compilar

O comando build converte um arquivo Bicep em um modelo do ARM (modelo do Azure Resource Manager). Normalmente, você não precisa executar esse comando porque ele é executado automaticamente quando você implanta um arquivo Bicep. Execute-o manualmente quando desejar ver o JSON do modelo do ARM criado com base no seu 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 da linguagem:

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

az bicep build --file main.bicep

O exemplo a seguir salva main.json em um diretório diferente.

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

O exemplo a seguir especifica o nome e a localização do arquivo a ser criado.

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

Para imprimir o arquivo para stdout, use:

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

Se o arquivo Bicep incluir um módulo que faz referência a um registro externo, o comando compilar chamará automaticamente restaurar. O comando restaurar obtém o arquivo do registro e o armazena no cache local.

Observação

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

Para não chamar o restaurar o automaticamente, use a opção --no-restore:

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

O processo de compilação com a opção --no-restore 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 comando build sem a opção --no-restore ou primeiro execute bicep restore.

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

build-params

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

az bicep build-params --file params.bicepparam

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

descompilar

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

az bicep decompile --file main.json

O comando cria um arquivo chamado main.bicep no mesmo diretório 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, confira Como descompilar o modelo do ARM JSON para Bicep.

decompile-params

O comando decompile-params 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

Esse 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 (em relação ao arquivo .bicepparam) que é referenciado na declaração using.

format

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

az bicep format --file main.bicep

generate-params

O comando generate-params cria um arquivo de parâmetros do arquivo Bicep especificado e atualiza se houver um arquivo parameters.json 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, configurados 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 comando install adiciona a CLI do Bicep ao seu ambiente local. Para obter mais informações, confira Instalar as ferramentas do Bicep. Esse comando só está disponível por meio 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. Essa configuração também dá suporte à criação de bibliotecas para interagir com arquivos Bicep programaticamente em non-.NET idiomas.

O formato de fio para envio e recebimento de 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 comprimento da cadeia de <message> caracteres, incluindo o .\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 obter os métodos e corpos de solicitação/resposta disponíveis, consulte ICliJsonRpcProtocol.cs. Para obter um exemplo de como estabelecer uma conexão JSONRPC e interagir 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 ao qual 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 se conectar 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 e stdout para mensagens.

bicep jsonrpc --stdio

lint

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

az bicep lint --file main.bicep

Se o seu 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 restaurar obtém o arquivo do registro e o armazena no cache local.

Observação

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

Para não chamar o restaurar o automaticamente, use a opção --no-restore:

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

O processo de lint com a chave --no-restore falha 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 comando lint sem a opção --no-restore ou primeiro execute bicep restore.

list-versions

O comando list-versions retorna todas as versões disponíveis da CLI do Bicep. Use este comando para ver se você deseja atualizar ou instalar uma nova versão. Esse comando só está disponível por meio 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 comando publish 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 as permissões e o perfil corretos para acessar o registro. Você pode configurar a precedência de 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 de publicação, você deve ter a CLI do Bicep versão 0.14.X ou superior. Para usar o parâmetro --documentationUri/-d, você deve ter a CLI 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 comando publish não reconhece os 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.

restaurar

Quando o arquivo Bicep usa módulos publicados em um registro, o comando restore 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, não é necessário executar a restauração, pois ela é disparada automaticamente pelo processo de compilação.

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

Para usar o comando de restauração, você deve ter a CLI do Bicep versão 0.4.X ou superior. No momento, esse comando só está disponível ao chamar a CLI do Bicep diretamente. Ele não está disponível no momento por meio do comando 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 se 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 comando restore não atualizará 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 a opção --force com o comando restore.

atualização

O comando upgrade atualiza sua versão instalada com a versão mais recente. Esse comando só está disponível por meio da CLI do Azure.

az bicep upgrade

version

O comando version retorna a sua versão instalada.

az bicep version

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

Bicep CLI version 0.22.6 (d62b94db31)

Para chamar esse comando diretamente pela CLI do Bicep, use:

bicep --version

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

Próximas etapas

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

Compartilhar via