Compartilhar via

comandos da CLI Bicep

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

Esta orientação mostra como executar os comandos no Azure CLI. Ao executar comandos no Azure CLI, inicie-os com az. Se você não estiver usando o Azure CLI, 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.

build

O comando build converte um arquivo Bicep em um modelo de Azure Resource Manager JSON (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 modelo do ARM JSON criado com base no arquivo Bicep.

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

O exemplo a seguir converte um arquivo de Bicep chamado main.bicep a um modelo do ARM chamado main.json. O novo arquivo é criado no mesmo diretório que o arquivo 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 a seguir especifica o nome e o local do arquivo a ser criado:

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

Para imprimir o arquivo para stdout, use:

bicep build main.bicep --stdout

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

Observação

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

Para impedir a restauração automática, use a opção --no-restore :

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

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

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.

build-params

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

bicep build-params 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 um modelo do ARM JSON em um arquivo Bicep:

bicep decompile main.json

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

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

decompile-params

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

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

format

O comando format formata um arquivo Bicep para que ele siga as convenções de estilo recomendadas. Pense nele como um formatador de código ou "mais bonito" para seus arquivos de Bicep. Ele tem a mesma função que o atalho SHIFT+ALT+F em Visual Studio Code.

bicep format main.bicep

generate-params

O comando generate-params cria um arquivo de parâmetros do arquivo de Bicep determinado e o atualiza se houver um arquivo de parâmetros existente.

bicep generate-params 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, configurado com valores padrão ou não.

bicep generate-params 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 comando install adiciona a CLI Bicep ao ambiente local e só está disponível por meio do Azure CLI. Para obter mais informações, consulte Instalar ferramentas de Bicep.

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. Usando essa interface, você pode interagir programaticamente com a saída estruturada. Você também evita atrasos de início frio ao compilar vários arquivos. Essa configuração dá suporte à criação de bibliotecas para interagir com arquivos Bicep programaticamente em idiomas não .NET.

O formato de fio para enviar e receber entrada e saída é delimitado por cabeçalho. Ele usa a seguinte estrutura, em que \r e \n representa caracteres de retorno de carro e feed 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

Os métodos a seguir estão disponíveis por meio da interface JSON-RPC:

  • bicep/format

    Formata um arquivo Bicep.

    • A solicitação:

      {
  "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"
  }
}

      Com o êxito, "success": true é retornado, com o conteúdo mantendo a fonte de Bicep formatada. Em caso de falha, "success": false com diagnostics a descrição da falha.

  • bicep/versão

    Retorna a versão da CLI do Bicep.

    • A solicitação:

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

    • A resposta:

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

Para obter os métodos disponíveis e os corpos de solicitação e resposta, 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 macOS ou 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

Para executar a interface JSONRPC, use a sintaxe a seguir. Use stdin e stdout para mensagens:

bicep jsonrpc --stdio

lint

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

bicep lint main.bicep

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

Observação

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

Para impedir a restauração automática, use a opção --no-restore :

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 Bicep. Use este comando para ver se você deseja atualizar ou instalar uma nova versão. Esse comando só está disponível por meio do Azure CLI.

N/A

publicar

O comando publish adiciona um módulo a um registro. O registro de contêiner 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 Use o 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 o perfil e a precedência de credencial para autenticação no registro no arquivo de configuração Bicep.

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

Você 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.

restauração

Quando o arquivo Bicep usa módulos que você publica 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 o profile e a precedência de credencial para autenticação no registro no arquivo de configuração Bicep.

Para usar o comando restore, você 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 arquivo Bicep fornecido é 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'
  }
}

Você encontra o cache local 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.

instantâneo

Usando Bicep CLI v0.41.2 ou mais recente, você pode usar o comando snapshot para criar uma representação determinística normalizada de uma implantação de Bicep de um arquivo .bicepparam. Você pode comparar esse instantâneo com instantâneos posteriores para entender quais alterações um refatorador causaria, sem implantar nada para Azure. Esse comando é particularmente útil para:

  • Diferenças visuais: ver exatamente como um refatorador (como mover código para um módulo) altera as definições de recurso subjacentes.
  • Expressões complexas: noções básicas sobre o que uma cadeia de caracteres complexa ou variável realmente avalia antes da implantação.
  • Validação de CI/CD: capturando automaticamente alterações não intencionais na lógica de infraestrutura durante solicitações de pull.

Criar um instantâneo

Esse comando gera um .snapshot.json arquivo. Esse arquivo é "normalizado", o que significa que ele remove ruídos como limites de módulo para que você possa se concentrar nos próprios recursos.

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

O arquivo JSON a seguir mostra um exemplo de instantâneo:

{
  "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 instantâneo, execute o comando no modo de validação. Ele compara o código Bicep atual com o instantâneo salvo e mostra uma diferença visual, assim como o comando what-if mas totalmente local.

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

Uma saída de exemplo se parece com:

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"

"Falha na validação de instantâneo" indica diferenças entre os dois instantâneos.

Bicep instantâneo da CLI e o what-if têm estas diferenças:

Característica bicep snapshot az deployment group what-if
Execução Somente local (offline) Baseado em nuvem (Online)
Comparação Compara código versus um arquivo salvo Compara código versus estado de Azure ao vivo
Velocidade Extremamente rápido Mais lento (requer chamadas à API)
Caso de uso Refatoração e teste lógico Verificação de pré-implantação final

Fornecer contexto

Ao executar Bicep instantâneo, a CLI executa uma avaliação local do código. Como ele não fala com Azure, ele não pode "pedir" à nuvem sua ID de Assinatura ou o nome atual do Grupo de Recursos.

Se o código usar funções de ambiente (como subscription().id), o instantâneo falhará ou retornará espaços reservados, a menos que você forneça um contexto específico por meio de argumentos da CLI.

Para simular um ambiente de implantação real, você pode passar os seguintes sinalizadores:

Argument Propósito Exemplo de valor
--subscription-id Substitui o valor retornado por subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Substitui o valor retornado por resourceGroup().name my-production-rg
--location Define o local padrão para deployment().location westeurope
--tenant-id Substitui o valor retornado por tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Substitui o valor retornado 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

atualização

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

N/A

versão

O version comando retorna sua versão instalada:

bicep --version

Se você não instalou a CLI do Bicep, verá uma mensagem de erro informando 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óximas etapas

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

  • Last updated on