comandos da CLI Bicep

Este artigo descreve os comandos que você pode usar na CLI do Bicep. Você pode executar esses comandos usando o CLI do Azure 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 CLI do Azure e Azure PowerShell.

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

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:

• 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 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

az bicep build --file main.bicep

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

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

az bicep build --file 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

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

Para imprimir o arquivo para stdout, use:

bicep build main.bicep --stdout

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 build chamará automaticamente restore. O restore comando obtém o arquivo do registro e o armazena no cache local.

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

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

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.

build-params

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

bicep build-params params.bicepparam

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.

consolar

O comando console está disponível em Bicep CLI v0.42.1 ou posterior. Ele fornece um ambiente de REPL (Loop deEval-Print de Leitura) interativo para expressões Bicep. Ele permite que você experimente Bicep funções e expressões em uma sessão de console interativa, especialmente útil ao criar ou testar Bicep lógica, como expressões, funções e funções definidas pelo usuário. Ele dá suporte aos seguintes recursos:

• Interactive Expression Evaluation: insira expressões Bicep e veja seus resultados avaliados imediatamente
• Declarações variáveis: definir variáveis usando 'var name = sintaxe de expressão e reutilizá-las em expressões subsequentes
• Entrada de várias linhas: suporte para expressões complexas de várias linhas com detecção automática de conclusão estrutural
• Realce da sintaxe: realce da sintaxe em tempo real para entrada e saída

O console comando tem estas limitações:

• Não há suporte para expressões que exigem Azure contexto, por exemplo, resourceGroup()
• Não há suporte para expressões de loop, por exemplo, [for i in range(0, x): i]
• Nenhum estado persistente entre sessões de console
• Sem suporte para conclusões

Use o seguinte comando para iniciar uma sessão de console Bicep:

bicep console

Para sair do console, pressione ESC ou use o exit comando.

Exemplos

Expressões simples

> 1 + 2
3

> 'Hello, ${'World!'}'
'Hello, World!'

> length(['a', 'b', 'c'])
3

Declarações de variável

> var myName = 'John'
> var greeting = 'Hello, ${myName}!'
> greeting
'Hello, John!'

Expressões de várias linhas

O console detecta automaticamente quando as expressões são concluídas estruturalmente:

> var config = {
  name: 'myApp'
  version: '1.0.0'
  settings: {
    debug: true
    timeout: 30
  }
}
> config.settings.debug
true

Expressões complexas

Lambdas

> var users = [
  { name: 'Alice', age: 30 }
  { name: 'Bob', age: 25 }
]
> map(users, user => user.name)
['Alice', 'Bob']

> filter(users, user => user.age > 26)
[
  {
    age: 30
    name: 'Alice'
  }
]

Funções e tipos definidos pelo usuário

> type PersonType = {
  name: string
  age: int
}
> func sayHi(person PersonType) string => 'Hello ${person.name}, you are ${person.age} years old!'
> var alice = {
  name: 'Alice'
  age: 30
}
> [ sayHi(alice), sayHi({ name: 'Bob', age: 25 })]
[
  'Hello Alice, you are 30 years old!'
  'Hello Bob, you are 25 years old!'
]

Carregando conteúdo de arquivos

Bicep console também dá suporte às funções load*(). O diretório do qual o bicep console comando é executado é usado como o diretório atual ao avaliar as load*() funções

O exemplo a seguir mostra como usar loadDirectoryFileInfo() para carregar informações sobre todos os arquivos Bicep em um diretório:

> loadDirectoryFileInfo('./modules/', '*.bicep')
[
  {
    relativePath: 'C:/Bicep/modules/appService.bicep'
    baseName: 'appService.bicep'
    extension: '.bicep'
  }
]

Redirecionamento de entrada/saída padrão e de tubulação

O comando do console dá suporte à avaliação de expressões fornecidas por meio de tubulação ou entrada padrão redirecionada, habilitando cenários como:

• Passando texto de expressão por meio de eco
• Compondo scripts que alimentam expressões no console
• Teste rápido de snippets de Bicep gerados ou transformados

Powershell:

# piped input
"parseCidr('10.144.0.0/20')" | bicep console

Bash:

# piped input
echo "parseCidr('10.144.0.0/20')" | bicep console
# stdin redirection from file content
bicep console < test.txt

Também há suporte para entrada de várias linhas:

"{
> foo: 'bar'
> }.foo" | bicep console

A saída é 'bar'.

Também há suporte para o redirecionamento de saída:

"toObject([{name:'Evie', age:4},{name:'Casper', age:3}], x => x.name)" | bicep console > output.json
more output.json

A saída é:

{
  Evie: {
    name: 'Evie'
    age: 4
  }
  Casper: {
    name: 'Casper'
    age: 3
  }
}

descompilar

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

bicep decompile main.json

az bicep decompile --file 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

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

az bicep format --file 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

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

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

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

Para instalar a versão mais recente, use:

az bicep install

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

az bicep install --version v0.37.4

jsonrpc

O comando jsonrpc inicia a CLI Bicep com uma interface JSON-RPC, permitindo interação programática rápida com arquivos Bicep. Para obter uso detalhado, formato de fio, métodos disponíveis e opções de conexão, consulte Bicep comando jsonrpc da CLI.

lint

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

bicep lint main.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 lint chamará automaticamente restore. O restore comando obtém o arquivo do registro e o armazena no cache local.

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

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

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 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 CLI do Azure.

az bicep list-versions

[
  "v0.37.4",
  "v0.36.177",
  "v0.36.1",
  "v0.35.1",
  "v0.34.44",
  "v0.34.1",
  "v0.33.93",
  "v0.33.13",
  "v0.32.4",
  "v0.31.92",
  "v0.31.34",
  "v0.30.23",
  "v0.30.3",
  "v0.29.47",
  "v0.29.45",
  "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"
]

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>

az bicep publish --file <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

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.

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>

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

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:

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:

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 CLI do Azure.

az bicep upgrade

versão

O version comando retorna sua versão instalada:

bicep --version

az bicep version

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:

• Deploy - CLI do Azure
• Deploy - Azure PowerShell
• Deploy - Cloud Shell