Comandos CLI do Bicep

Este artigo descreve os comandos que pode usar na CLI do Bicep. Pode executar estes 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 mais informações sobre instalações, consulte CLI do Azure e Azure PowerShell.

Esta orientação mostra como executar os comandos na CLI do CLI do Azure. Ao executar comandos no CLI do Azure, inicie-os com az. Se não estiveres a usar o CLI do Azure, 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:

• Tipos definidos pelo usuário
• funções definidas pelo utilizador
• Importações em tempo de compilação
• características experimentais

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

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 seguinte especifica o nome e a localização do ficheiro a criar:

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

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

Para imprimir o ficheiro no stdout, utilize:

bicep build main.bicep --stdout

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

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

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

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

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

az bicep build-params --file params.bicepparam

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

consola

O comando console está disponível em Bicep CLI v0.42.1 ou posterior. Fornece um ambiente interativo de Loop de LeituraEval-Print (REPL) para expressões Bicep. Permite-lhe experimentar funções e expressões do Bicep numa sessão interativa de consola, especialmente útil ao criar ou testar lógica do Bicep, como expressões, funções e funções definidas pelo utilizador. Suporta as seguintes funcionalidades:

• Avaliação Interativa de Expressão: Introduza Bicep expressões e veja imediatamente os seus resultados avaliados
• Declarações de Variáveis: Defina variáveis usando 'var name = sintaxe de expressão e reutilize-as em expressões subsequentes
• Multi-linha Input: Suporte para expressões complexas multi-linha com deteção automática de completude estrutural
• Realce de sintaxe: Realce de sintaxe em tempo real para entrada e saída

O console comando tem estas limitações:

• Não há suporte para expressões que exijam Azure contexto, por exemplo, resourceGroup()
• Não há suporte para expressões em loop for, por exemplo. [for i in range(0, x): i]
• Sem estado persistente entre as sessões da consola
• Sem suporte para completações

Use o seguinte comando para iniciar uma sessão na consola do Bicep:

bicep console

Para sair da consola, 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áveis

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

Expressões multi-linha

A consola deteta automaticamente quando as expressões estão estruturalmente completas:

> 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'
  }
]

Tipos e funções definidos pelo utilizador

> 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!'
]

Carregamento de conteúdo a partir de ficheiros

Bicep consola também suporta as funções load*(). O diretório a partir do qual o bicep console comando é executado é usado como diretório atual ao avaliar as load*() funções

O exemplo seguinte mostra como usar loadDirectoryFileInfo() para carregar informação sobre todos os ficheiros Bicep num diretório:

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

Tubagem e redirecionamento padrão de entrada/saída

O comando de consola suporta a avaliação de expressões fornecidas através de pipeline ou entrada padrão redirecionada, permitindo cenários como:

• Passagem de texto de expressão via eco
• Compor scripts que alimentam expressões para a consola
• Teste rápido de fragmentos 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 é suportada entrada multi-linha:

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

O resultado é 'bar'.

Também é suportada a redireção 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 template JSON ARM num ficheiro Bicep:

bicep decompile main.json

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

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

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

az bicep generate-params --file 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

az bicep generate-params --file 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 CLI do Azure. Para mais informações, consulte Instale Bicep ferramentas.

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 lança a CLI Bicep com uma interface JSON-RPC, permitindo uma rápida interação programática com ficheiros Bicep. Para uso detalhado, formato de fio, métodos disponíveis e opções de ligação, veja Bicep comando CLI jsonrpc.

fiapos

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

bicep lint main.bicep

az bicep lint --file 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.

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

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

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

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.

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>

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

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:

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:

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

az bicep upgrade

versão

O version comando retorna a 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óximos passos

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

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