Partilhar via

Comandos CLI do Bicep

Este artigo descreve os comandos que pode usar na CLI do Bicep. Pode executar estes comandos usando a Azure CLI ou invocando diretamente os comandos da CLI do Bicep. Cada método requer um processo de instalação distinto. Para mais informações sobre instalações, consulte Azure CLI e Azure PowerShell.

Esta orientação mostra como executar os comandos na CLI do Azure CLI. Ao executar comandos no Azure CLI, inicie-os com az. Se não estiveres a usar o Azure CLI, executa os comandos sem az no início de cada um. Por exemplo, az bicep build torna-se bicep build, e az bicep version torna-se bicep --version.

compilação

O comando build converte um ficheiro de Bicep num modelo de Azure Resource Manager JSON (template ARM). Normalmente, não precisas de executar este comando porque ele corre automaticamente quando implementas um ficheiro Bicep. Executa-o manualmente quando quiseres ver o modelo JSON ARM criado a partir do teu ficheiro Bicep.

Usar qualquer uma das seguintes funcionalidades do Bicep permite automaticamente a geração de código da versão 2.0 da linguagem:

O exemplo seguinte converte um ficheiro Bicep chamado main.bicep para um template ARM chamado main.json. O novo ficheiro é criado no mesmo diretório do ficheiro Bicep:

bicep build main.bicep

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

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

O exemplo seguinte especifica o nome e a localização do ficheiro a criar:

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

Para imprimir o ficheiro no stdout, utilize:

bicep build main.bicep --stdout

Se o seu ficheiro Bicep incluir um módulo que faz referência a um registo externo, o comando build chama automaticamente restore. O restore comando obtém o arquivo do registro e o armazena no cache local.

Nota

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

Para evitar a restauração automática, use o --no-restore interruptor:

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

Para usar o switch --no-restore, deve ter Bicep CLI versão 0.4.X ou posterior.

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

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

construir-params

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

bicep build-params params.bicepparam

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

descompilar

O comando decompile converte um template JSON ARM num ficheiro Bicep:

bicep decompile main.json

Este comando cria um arquivo chamado main.bicep no mesmo diretório que main.json. Se main. bicep existe no mesmo diretório, use o switch --force para sobrescrever o ficheiro de Bicep existente.

Para mais informações sobre o uso deste comando, veja Decompile JSON ARM template to Bicep.

descompilar-params

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

bicep decompile-params 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 . Use --bicep-file para especificar o caminho para o ficheiro Bicep (relativamente ao ficheiro .bicepparam) que está referenciado na declaração using.

format

O comando format formata um ficheiro Bicep para que siga as convenções de estilo recomendadas. Pensa nele como um formador de código ou "mais bonito" para os teus ficheiros Bicep. Tem a mesma função do atalho SHIFT+ALT+F no Visual Studio Code.

bicep format main.bicep

generate-params

O comando generate-params constrói um ficheiro de parâmetros a partir do ficheiro Bicep dado e atualiza-o se existir um ficheiro de parâmetros existente.

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

Este comando cria um ficheiro de parâmetros de Bicep chamado main.bicepparam. O ficheiro de parâmetros contém todos os parâmetros do ficheiro Bicep, estejam ou não configurados com valores padrão.

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

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

instalar

O comando install adiciona a CLI Bicep ao teu ambiente local, e só está disponível através do Azure CLI. Para mais informações, consulte Instale Bicep ferramentas.

Para instalar a versão mais recente, use:

N/A

Para instalar uma versão específica, use o seguinte comando:

N/A

jsonrpc

O comando jsonrpc executa a CLI Bicep com uma interface JSON-RPC. Ao usar esta interface, pode interagir programaticamente com a saída estruturada. Também evita atrasos no arranque a frio ao compilar vários ficheiros. Esta configuração suporta a construção de bibliotecas para interagir programaticamente com ficheiros Bicep em linguagens não .NET.

O formato de fio para enviar e receber entrada e saída é delimitado por cabeçalhos. Utiliza a seguinte estrutura, onde \r e \n representam caracteres de retorno de carro e de avanç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

Os seguintes métodos estão disponíveis através da interface JSON-RPC:

  • bíceps/formato

    Formata um ficheiro Bicep.

    • O pedido:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "bicep/format",
  "params": {
    "path": "/path/to/file.bicep"
  }
}

    • A resposta:

      {
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "success": true,
    "diagnostics": [],
    "contents": "param foo string\n\nresource storage 'Microsoft.Storage/storageAccounts@2025-01-01' = {\n  name: 'mystorageaccount'\n  location: 'East US'\n}\n"
  }
}

      Em caso de sucesso, "success": true é devolvido, com conteúdos a contendo a Bicep fonte formatada. Sobre o fracasso, "success": false com diagnostics a descrição do fracasso.

  • bíceps/versão

    Devolve a versão do Bicep CLI.

    • O pedido:

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

    • A resposta:

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

Para os métodos disponíveis e órgãos de pedido e resposta, veja ICliJsonRpcProtocol.cs. Para um exemplo de estabelecer uma ligação JSONRPC e interagir programaticamente com Bicep ficheiros usando Node, veja 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 ligar a um pipe nomeado no macOS ou Linux:

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

Para ligar a um tubo nomeado no Windows:

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

Para mais exemplos, veja 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> é o número do soquete ao qual o cliente JSONRPC se conecta.

Para ligar a um soquete TCP:

bicep jsonrpc --socket 12345

Uso para stdin e stdout

Para executar a interface JSONRPC, use a seguinte sintaxe. Utilização stdin e stdout para mensagens:

bicep jsonrpc --stdio

fiapos

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

bicep lint main.bicep

Se o seu ficheiro Bicep incluir um módulo que faz referência a um registo externo, o comando lint chama automaticamente restore. O restore comando obtém o arquivo do registro e o armazena no cache local.

Nota

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

Para evitar a restauração automática, use o --no-restore interruptor:

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 comando list-versions devolve todas as versões disponíveis da CLI Bicep. Use este comando para ver se deseja atualizar ou instalar uma nova versão. Este comando só está disponível através da Azure CLI.

N/A

publicar

O publish comando adiciona um módulo a um registro. O registo de contentores do Azure deve existir, e a conta que publica no registo deve ter as permissões corretas. Para mais informações sobre a criação de um registo de módulos, consulte Use registo privado para Bicep módulos. Para publicar um módulo, a conta deve ter o perfil e as permissões corretas para acessar o registro. Pode configurar o perfil e a precedência de credenciais para autenticação no registo no ficheiro de configuração Bicep.

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

Deve ter Bicep CLI versão 0.14.X ou posterior para usar o comando publish e o parâmetro --documentationUri/-d.

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

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

Por exemplo:

bicep publish 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. Incremente a versão ao atualizar.

repor

Quando o teu ficheiro Bicep usa módulos que publicas num registo, o comando restore obtém cópias de todos os módulos necessários do registo. Ele armazena essas cópias em um cache local. Um ficheiro Bicep só pode ser construído quando os ficheiros externos estão disponíveis na 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. Pode configurar o perfil e a precedência de credenciais para autenticação no registo no ficheiro de configuração Bicep.

Para usar o comando restore, deve ter Bicep CLI versão 0.14.X ou posterior.

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

bicep restore <bicep-file>

O ficheiro Bicep que forneces é o ficheiro que queres implementar. 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'
  }
}

Encontras a cache local 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.

instantâneo

Ao usar Bicep CLI v0.41.2 ou mais recente, pode usar o comando snapshot para criar uma representação normalizada e determinística de uma implementação Bicep a partir de um ficheiro .bicepparam. Podes comparar este snapshot com snapshots posteriores para perceberes que alterações um refatorado causaria, sem implementar nada no Azure. Este comando é particularmente útil para:

  • Diferenças Visuais: Ver exatamente como uma refatoração (como mover código para um módulo) altera as definições de recursos subjacentes.
  • Expressões Complexas: Compreender a que uma string ou variável complexa realmente avalia antes da implementação.
  • Validação CI/CD: Detetação automática de alterações não intencionais na lógica da infraestrutura durante pull requests.

Criar um instantâneo

Este comando gera um .snapshot.json ficheiro. Este ficheiro é "normalizado", ou seja, remove ruído como os limites dos módulos para que possas focar-te nos próprios recursos.

bicep snapshot --mode overwrite <bicep-param-file>

O ficheiro JSON seguinte mostra um exemplo de snapshot:

{
  "predictedResources": [
    {
      "id": "[format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]",
      "type": "Microsoft.Storage/storageAccounts",
      "name": "stmyappstorage001",
      "apiVersion": "2025-01-01",
      "location": "eastus",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2"
    }
  ],
  "diagnostics": []
}

Validar alterações

Depois de criar um snapshot, execute o comando em modo validar. Compara o teu código de Bicep atual com o snapshot guardado e mostra uma diferença visual, tal como o comando what-if mas totalmente local.

bicep snapshot --mode validate <bicep-param-file>

Uma saída de exemplo é a seguinte:

PS C:\bicep> bicep snapshot --mode validate main.bicepparam
Snapshot validation failed. Expected no changes, but found the following:

Scope: <unknown>

  ~ [format('/subscriptions/{0}/resourceGroups/{1}/providers/Microsoft.Storage/storageAccounts/stmyappstorage001', subscription().subscriptionId, resourceGroup().name)]
    ~ apiVersion: "2025-01-01" => "2025-06-01"
    ~ sku.name:   "Standard_LRS" => "Standard_GRS"

"Validação de snapshot falhada" indica diferenças entre os dois snapshots.

O snapshot do Bicep CLI e o What-If apresentam estas diferenças:

Feature bicep snapshot az deployment group what-if
Execução Apenas Local (Offline) Baseado na cloud (Online)
Comparação Compara código com um ficheiro guardado Compara código vs. estado real do Azure
Velocidade Extremamente rápido Mais lento (requer chamadas de API)
Caso de uso Refatoração e testes lógicos Verificação final pré-desdobramento

Forneça contexto

Ao executar o snapshot do Bicep, a CLI realiza uma avaliação local do seu código. Como não comunica com o Azure, não pode "pedir" à cloud o seu ID de Subscrição ou o nome atual do Grupo de Recursos.

Se o teu código usar funções de ambiente (como subscription().id), o snapshot falhará ou devolverá marcadores de posição, a menos que forneças contexto específico através de argumentos da linha de controlo (CLI).

Para simular um ambiente real de implantação, pode passar as seguintes bandeiras:

Argumento Propósito Valor de Exemplo
--subscription-id Substitui o valor devolvido por subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Substitui o valor devolvido por resourceGroup().name my-production-rg
--location Define a localização padrão para deployment().location westeurope
--tenant-id Substitui o valor devolvido por tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Substitui o valor devolvido por managementGroup().name my-corp-mg 
bicep snapshot main.bicepparam \
  --subscription-id 00000000-0000-0000-0000-000000000000 \
  --resource-group my-temp-rg \
  --location eastus \
  --mode overwrite

actualização

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

N/A

versão

O version comando retorna a versão instalada:

bicep --version

Se não instalaste a CLI do Bicep, vês uma mensagem de erro a dizer que a CLI do Bicep não foi encontrada.

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

Bicep CLI version 0.29.45 (57a44c0230)

Próximos passos

Para saber mais sobre como implementar um ficheiro Bicep, veja:

  • Last updated on