Comandos da CLI do Bicep

Este artigo descreve os comandos que você pode usar na CLI do Bicep. Você pode executar esses comandos usando 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 sobre instalações, consulte CLI do Azure e Azure PowerShell.

Essas diretrizes mostram como executar os comandos na CLI do Azure. Ao executar comandos na CLI do Azure, inicie-os com az. Se você não estiver usando a CLI do Azure, execute os comandos sem az no início de cada um. Por exemplo, az bicep build torna-se bicep builde az bicep version se torna bicep --version.

compilar

O build comando converte um arquivo Bicep em um modelo JSON do Azure Resource Manager (modelo do 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 modelo JSON 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 da linguagem:

• tipos definidos pelo usuário
• funções definidas pelo usuário
• importações no momento da compilação
• recursos experimentais

O exemplo a seguir converte um arquivo bicep chamado main.bicep em um modelo do 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 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 chamará build restoreautomaticamente . O restore comando obtém o arquivo do registro e o armazena no cache local.

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" hasn't been restored.

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

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

build-params

O build-params comando cria um .bicepparam arquivo 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 decompile comando converte um modelo JSON ARM em um arquivo Bicep:

az bicep decompile --file main.json

Esse 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 Descompilar o modelo JSON ARM para o Bicep.

decompile-params

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

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 (relativo ao .bicepparam arquivo) referenciado using na declaração.

format

O format comando 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

Esse 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

Este 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 e só está disponível por meio da CLI do Azure. Para obter mais informações, confira Instalar as ferramentas do Bicep.

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 seguinte sintaxe 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 seguinte sintaxe para se conectar a um soquete TCP existente como um cliente JSONRPC:

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> é o número do soquete ao qual o cliente JSONRPC se conecta.

Para se conectar a um soquete TCP:

bicep jsonrpc --socket 12345

Uso para stdin e stdout

Use a seguinte sintaxe e stdin e stdout para mensagens para executar a interface JSONRPC:

bicep jsonrpc --stdio

lint

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

az bicep lint --file main.bicep

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

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.

Você deve ter a CLI do Bicep versão 0.14.X ou posterior para usar o publish comando e o --documentationUri/-d parâmetro.

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.

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, você deve ter a restore CLI do Bicep versão 0.14.X ou posterior. No momento, esse comando só está disponível ao chamar a CLI do Bicep diretamente. No momento, ele não está disponível por meio 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 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 --force opção com o restore comando.

upgrade

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 version comando retorna sua 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 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, consulte:

• Implantar – CLI do Azure
• Implantar - Azure PowerShell
• Implantar - Cloud Shell