Comandos de la CLI de Bicep

Artículo
11/12/2024

En este artículo se describen los comandos que puede usar en la CLI de Bicep. Tiene dos opciones para ejecutar estos comandos: mediante el uso de la CLI de Azure o mediante la invocación directa de comandos de la CLI de Bicep. Cada método requiere un proceso de instalación distinto. Para más información, consulte Instalación de la CLI de Azure e Instalar Azure PowerShell.

En este artículo se muestra cómo ejecutar los comandos en la CLI de Azure. Cuando se ejecuta a través de la CLI de Azure, se inician los comandos con az. Si no usa la CLI de Azure, ejecute los comandos sin az al principio del comando. Por ejemplo, az bicep build se convierte en bicep build y az bicep version se convierte en bicep --version.

build

El comando build convierte un archivo de Bicep en una plantilla de Azure Resource Manager (plantilla de ARM). Normalmente, no es necesario ejecutar este comando, ya que se ejecuta automáticamente al implementar un archivo de Bicep. Ejecútelo manualmente cuando quiera ver el JSON de la plantilla de ARM que se crea a partir del archivo de Bicep.

El uso de cualquiera de las siguientes características de Bicep habilita automáticamente la generación de código de la versión 2.0 del lenguaje:

En el ejemplo siguiente se convierte un archivo de Bicep denominado main.bicep en una plantilla de ARM denominada main.json. El nuevo archivo se crea en el mismo directorio que el archivo de Bicep.

az bicep build --file main.bicep

En el ejemplo siguiente se guarda main.json en otro directorio.

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

En el ejemplo siguiente se especifica el nombre y la ubicación del archivo que se va a crear.

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

Para imprimir el archivo en stdout, use:

az bicep build --file main.bicep --stdout

Si el archivo Bicep incluye un módulo que hace referencia a un registro externo, el comando de compilación llama automáticamente a restore. El comando restore obtiene el archivo del registro y lo almacena en la memoria caché local.

Nota:

El comando restore no actualiza la caché. Para más información, consulte Comando restore.

Para no llamar a la restauración automáticamente, use el modificador --no-restore:

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

Se produce un error en el proceso de compilación con el modificador --no-restore si uno de los módulos externos aún no está almacenado en caché:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Cuando reciba este error, ejecute el comando build sin el modificador --no-restore o ejecute bicep restore primero.

Para usar el modificador --no-restore, debe tener la CLI de Bicep versión 0.4.X o posterior.

build-params

El comando build-params compila un archivo .bicepparam en un archivo de parámetros JSON.

az bicep build-params --file params.bicepparam

Este comando convierte un archivo de parámetros params.bicepparam en un archivo de parámetros JSON params.json.

decompile

El comando decompile convierte el JSON de la plantilla de ARM en un archivo de Bicep.

az bicep decompile --file main.json

El comando crea un archivo llamado main.bicep en el mismo directorio que main.json. Si main.bicep existe en el mismo directorio, use el modificador --force para sobrescribir el archivo Bicep existente.

Para más información sobre el uso de este comando, consulte Descompilación de JSON de plantilla de ARM en Bicep.

decompile-params

El comando decompile-params descompila un archivo de parámetros JSON en un archivo de parámetros .bicepparam.

az bicep decompile-params --file azuredeploy.parameters.json --bicep-file ./dir/main.bicep

Este comando descompila un archivo de parámetros azuredeploy.parameters.json en un archivo azuredeploy.parameters.bicepparam. --bicep-file especifica la ruta de acceso al archivo de Bicep (en relación con el archivo .bicepparam) al que se hace referencia en la declaración using.

format

El comando format da formato a un archivo de Bicep. Tiene la misma función que el acceso directo SHIFT+ALT+F en Visual Studio Code.

az bicep format --file main.bicep

generate-params

El comando generate-params compila el archivo de parámetros desde el archivo Bicep especificado y lo actualiza si hay un archivo parameters.json existente.

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

El comando crea un archivo de parámetros de Bicep denominado main.bicepparam. El archivo de parámetros contiene todos los parámetros del archivo Bicep, tanto si están configurados con valores predeterminados como si no.

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

El comando crea un archivo de parámetros denominado main.parameters.json. El archivo de parámetros solo contiene los parámetros sin valores predeterminados configurados en el archivo Bicep.

instalar

El comando install agrega la CLI de Bicep al entorno local. Para más información, consulte Instalación de herramientas de Bicep. Este comando solo está disponible a través de la CLI de Azure.

Para instalar la versión más reciente, use:

az bicep install

Para instalar una versión específica:

az bicep install --version v0.3.255

jsonrpc

El jsonrpc comando permite ejecutar la CLI de Bicep con una interfaz JSON-RPC, lo que permite la interacción mediante programación con la salida estructurada y evitar retrasos de arranque en frío al compilar varios archivos. Esta configuración también admite la creación de bibliotecas para interactuar con archivos de Bicep mediante programación en non-.NET idiomas.

El formato de cable para enviar y recibir entradas y salidas está delimitado por encabezados, utilizando la siguiente estructura, donde \r y \n representan caracteres de retorno de carro y avance de línea:

Content-Length: <length>\r\n\r\n<message>\r\n\r\n

<length> es la longitud de la <message> cadena, incluido el final \r\n\r\n.
<message> es el mensaje JSON sin formato.

Por ejemplo:

Content-Length: 72\r\n\r\n{"jsonrpc": "2.0", "id": 0, "method": "bicep/version", "params": {}}\r\n\r\n

En el mensaje siguiente se muestra un ejemplo de la versión de Bicep.

La entrada:

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

Salida:

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

Para los métodos disponibles y cuerpos de solicitud/respuesta, consulte ICliJsonRpcProtocol.cs. Para obtener un ejemplo de establecimiento de una conexión JSONRPC e interacción con archivos de Bicep mediante programación mediante node, consulte jsonrpc.test.ts.

Uso de canalización con nombre

Use la siguiente sintaxis para conectarse a una canalización con nombre existente como un cliente JSONRPC.

bicep jsonrpc --pipe <named_pipe>`

<named_pipe> es una canalización con nombre existente a la que conectar el cliente JSONRPC.

Para conectarse a una canalización con nombre en OSX/Linux:

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

Para conectarse a una canalización con nombre en Windows :

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

Para obtener más ejemplos, consulte C# y node.js.

Uso del socket TCP

Use la siguiente sintaxis para conectarse a un socket TCP existente como un cliente JSONRPC.

bicep jsonrpc --socket <tcp_socket>

<tcp_socket> es un número de socket al que conectar el cliente JSONRPC.

Para conectarse a un socket TCP

bicep jsonrpc --socket 12345

Uso de stdin y stdout

Use la siguiente sintaxis para ejecutar la interfaz JSONRPC mediante stdin & stdout para los mensajes.

bicep jsonrpc --stdio

lint

El comando lint devuelve los errores y las infracciones de la regla de linter de un archivo de Bicep.

az bicep lint --file main.bicep

Si el archivo de Bicep incluyera un módulo que hiciese referencia a un registro externo, el comando de lint llamará automáticamente a restore. El comando restore obtiene el archivo del registro y lo almacena en la memoria caché local.

Nota:

El comando restore no actualiza la caché. Para más información, consulte Comando restore.

Para no llamar a la restauración automáticamente, use el modificador --no-restore:

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

Se produce un error en el proceso de lint con el modificador --no-restore si uno de los módulos externos aún no está almacenado en caché:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" has not been restored.

Cuando reciba este error, ejecute el comando lint sin el modificador --no-restore o ejecute bicep restore primero.

list-versions

El comando list-versions devuelve todas las versiones disponibles de la CLI de Bicep. Use este comando para ver si quiere actualizar o instalar una nueva versión. Este comando solo está disponible a través de la CLI de Azure.

az bicep list-versions

El comando devuelve una matriz de versiones disponibles.

[
  "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

El comando publish agrega un módulo a un registro. El registro de contenedor de Azure debe existir y la cuenta que se publica en el registro debe tener los permisos correctos. Para obtener más información sobre cómo configurar un registro de módulo, consulte Uso del registro privado para módulos de Bicep. Para publicar un módulo, la cuenta debe tener el perfil y los permisos correctos para acceder al registro. Puede configurar el perfil y la precedencia de credenciales para la autenticación en el registro en el archivo de configuración de Bicep.

Después de publicar el archivo en el registro, puede hacer referencia a él en un módulo.

Para usar el comando publish, debe tener la CLI de Bicep versión 0.14.X o posterior. Para usar el parámetro --documentationUri/-d, debe tener la CLI de Bicep versión 0.14.X o posterior.

Para publicar un módulo en un registro, use:

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

Por ejemplo:

az bicep publish --file storage.bicep --target br:exampleregistry.azurecr.io/bicep/modules/storage:v1 --documentationUri https://www.contoso.com/exampleregistry.html

El comando publish no reconoce los alias especificados en un archivo bicepconfig.json. Proporcione la ruta de acceso completa del módulo.

Advertencia

La publicación en el mismo destino sobrescribe el módulo anterior. Se recomienda incrementar la versión al actualizar.

Restauración

Cuando el archivo Bicep usa módulos publicados en un registro, el comando restore obtiene copias de todos los módulos necesarios del registro. Almacena esas copias en una caché local. Un archivo Bicep solo se puede crear cuando los archivos externos están disponibles en la memoria caché local. Normalmente, la ejecución de la restauración no es necesaria, ya que el proceso de compilación la desencadena automáticamente.

Para restaurar módulos externos en la caché local, la cuenta debe tener el perfil y los permisos correctos para acceder al registro. Puede configurar el perfil y la precedencia de credenciales para la autenticación en el registro en el archivo de configuración de Bicep.

Para usar el comando restore, debe tener la CLI de Bicep versión 0.4.X o posterior. Este comando solo está disponible actualmente al llamar directamente a la CLI de Bicep. Actualmente no está disponible a través de un comando de la CLI de Azure.

Para restaurar manualmente los módulos externos de un archivo, use:

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

El archivo Bicep que proporcione es el archivo que desea implementar. Debe contener un módulo que se vincula a un registro. Por ejemplo, puede restaurar el siguiente archivo:

module stgModule 'br:exampleregistry.azurecr.io/bicep/modules/storage:v1' = {
  name: 'storageDeploy'
  params: {
    storagePrefix: 'examplestg1'
  }
}

La caché local se encuentra en:

En Windows

%USERPROFILE%\.bicep\br\<registry-name>.azurecr.io\<module-path\<tag>

En Linux
```
/home/<username>/.bicep
```
En Mac
```
~/.bicep
```

El comando restore no actualiza la caché si un módulo ya está almacenado en caché. Para actualizar la caché, puede eliminar de ella la ruta de acceso del módulo o usar el modificador --force con el comando restore.

upgrade

El comando upgrade actualiza la versión instalada a la versión más reciente. Este comando solo está disponible a través de la CLI de Azure.

az bicep upgrade

version

El comando version devuelve la versión instalada.

az bicep version

El comando muestra el número de versión.

Bicep CLI version 0.22.6 (d62b94db31)

Para llamar a este comando directamente a través de la CLI de Bicep, use:

bicep --version

Si la CLI de Bicep no se hubiera instalado, encontrará un mensaje de error indicando que no se encontró la misma.

Pasos siguientes

Para información sobre la implementación de un archivo de Bicep, consulte:

Compartir a través de