команды cli Bicep

В этой статье описываются команды, которые можно использовать в Bicep CLI. Эти команды можно выполнить с помощью Azure CLI или непосредственного вызова команд командной строки Bicep. Для каждого метода требуется отдельный процесс установки. Дополнительные сведения о установках см. в разделе Azure CLI и Azure PowerShell.

В этом руководстве показано, как выполнять команды в Azure CLI. При выполнении команд в Azure CLI запустите их с az. Если вы не используете Azure CLI, выполните команды без az в начале каждого. Например, az bicep build становится bicep buildи az bicep version становится bicep --version.

сборка

Команда build преобразует файл Bicep в шаблон Azure Resource Manager JSON (шаблон ARM). Как правило, вам не нужно выполнять эту команду, так как она выполняется автоматически при развертывании Bicep файла. Запустите его вручную, если вы хотите увидеть шаблон ARM JSON, созданный из файла Bicep.

Использование любой из следующих функций Bicep автоматически включает создание кода версии 2.0:

В следующем примере преобразуется файл Bicep с именем main.bicep в шаблон ARM с именем main.json. Новый файл создается в том же каталоге, что и файл Bicep:

bicep build main.bicep

Следующий пример сохраняет main.json в другом каталоге:

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

В следующем примере указывается имя и расположение создаваемого файла:

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

Чтобы напечатать файл в stdout, используйте следующую команду:

bicep build main.bicep --stdout

Если файл Bicep содержит модуль, ссылающийся на внешний реестр, команда build автоматически вызывает restore. Команда restore получает файл из реестра и сохраняет его в локальном кэше.

Примечание.

Команда restore не обновляет кэш. Дополнительные сведения см. здесь.

Чтобы предотвратить автоматическое восстановление, используйте переключатель --no-restore :

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

Чтобы использовать параметр --no-restore, необходимо иметь Bicep CLI версии 0.4.X или более поздней версии.

Процесс сборки с параметром --no-restore завершается сбоем, если один из внешних модулей еще не кэширован:

The module with reference "br:exampleregistry.azurecr.io/bicep/modules/storage:v1" hasn't been restored.

При получении этой ошибки выполните команду без build переключателя или запустите --no-restorebicep restore сначала.

сборка-params

Команда build-params создает .bicepparam файл в файл параметров JSON:

bicep build-params params.bicepparam

Эта команда преобразует файл параметров params.bicepparam в файл параметров params.json JSON.

консоль

Команда console доступна в Bicep CLI версии 0.42.1 или более поздней версии. Он предоставляет интерактивную средуEval-Print цикла чтения (REPL) для выражений Bicep. Он позволяет экспериментировать с функциями и выражениями Bicep в интерактивном сеансе консоли, особенно полезно при разработке или тестировании логики Bicep, например выражений, функций и определяемых пользователем функций. Она поддерживает следующие функции:

  • Interactive Expression Evaluation: введите выражения Bicep и сразу увидите их вычисляющие результаты.
  • Объявления переменных: определение переменных с помощью синтаксиса выражения var name = синтаксис выражения и их повторное использование в последующих выражениях
  • Многострочный ввод: поддержка сложных многостроковых выражений с автоматическим обнаружением структурного завершения
  • Выделение синтаксиса: выделение синтаксиса в режиме реального времени для входных и выходных данных

Команда console имеет следующие ограничения:

  • Поддержка выражений, требующих Azure контекста, например resourceGroup()
  • Постоянное состояние между сеансами консоли не существует
  • Поддержка завершения не поддерживается

Чтобы запустить сеанс консоли Bicep, выполните следующую команду:

Чтобы выйти из консоли, нажмите ESC или используйте exit команду.

Примеры

Простые выражения

> 1 + 2
3

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

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

Объявления переменных

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

Многострочный выражения

Консоль автоматически обнаруживает, когда выражения являются структурны завершенными:

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

Сложные выражения

Лямбд
> 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'
  }
]
Определяемые пользователем типы и функции
> 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!'
]

Загрузка содержимого из файлов

консоль Bicep также поддерживает функции load*(). Каталог, из которого bicep console выполняется команда, используется в качестве текущего каталога при оценке функций.load*()

В следующем примере показано, как использовать loadDirectoryFileInfo() для загрузки сведений обо всех Bicep файлах в каталоге:

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

Перенаправление входных и выходных данных

Команда консоли поддерживает вычисление выражений, предоставляемых через пиппинг или перенаправление стандартных входных данных, включив такие сценарии, как:

  • Передача текста выражения через эхо
  • Создание скриптов, которые каналы выражений в консоли
  • Быстрое тестирование созданных или преобразованных фрагментов Bicep

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

Кроме того, поддерживается многострочный ввод:

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

Результат выглядит так: 'bar'.

Перенаправление выходных данных также поддерживается:

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

Выходные данные:

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

decompile

Команда decompile преобразует шаблон ARM JSON в файл Bicep:

bicep decompile main.json

Эта команда создает файл с именем main.bicep в том же каталоге, что и main.json. Если main. bicep существует в том же каталоге, используйте параметр --force для перезаписи существующего файла Bicep.

Дополнительные сведения об использовании этой команды см. в разделе Decompile JSON ARM-шаблон Bicep.

decompile-params

Команда decompile-params декомпилирует файл параметров JSON в .bicepparam файл параметров.

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

Эта команда декомпилирует файл параметров azuredeploy.parameters.json в файл azuredeploy.parameters.bicepparam . Используйте --bicep-file, чтобы указать путь к файлу Bicep (относительно файла .bicepparam/>), на который ссылается объявление using.

format

Команда format форматирует файл Bicep таким образом, чтобы он соблюдал рекомендуемые соглашения о стиле. Подумайте о нем как о форматировании кода или "более красивом" для Bicep файлов. Она имеет ту же функцию, что и ярлык SHIFT+ALT+F в Visual Studio Code.

bicep format main.bicep

generate-params

Команда generate-params создает файл параметров из заданного файла Bicep и обновляет его, если существует существующий файл параметров.

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

Эта команда создает файл параметров Bicep с именем main.bicepparam. Файл параметров содержит все параметры в файле Bicep, независимо от того, настроено ли значение по умолчанию.

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

Эта команда создает файл параметров с именем main.parameters.json. Файл параметров содержит только параметры без значений по умолчанию, настроенных в файле Bicep.

Установить

Команда install добавляет Bicep CLI в локальную среду и доступна только через Azure CLI. Дополнительные сведения см. в разделе Install Bicep tools.

Чтобы установить последнюю версию, выполните следующую команду:

Чтобы установить определенную версию, используйте следующую команду:

jsonrpc

Команда jsonrpc запускает интерфейс командной строки Bicep с интерфейсом JSON-RPC, обеспечивая быстрое программное взаимодействие с файлами Bicep. Подробные сведения об использовании, формате провода, доступных методах и параметрах подключения см. в разделе Bicep команда CLI jsonrpc.

lint

Команда lint возвращает ошибки и правило linter нарушения файла Bicep.

bicep lint main.bicep

Если файл Bicep содержит модуль, ссылающийся на внешний реестр, команда lint автоматически вызывает restore. Команда restore получает файл из реестра и сохраняет его в локальном кэше.

Примечание.

Команда restore не обновляет кэш. Дополнительные сведения см. здесь.

Чтобы предотвратить автоматическое восстановление, используйте переключатель --no-restore :

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

Процесс lint с коммутатором --no-restore завершается ошибкой, если один из внешних модулей еще не кэширован:

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

При возникновении этой ошибки выполните команду lint без параметра --no-restore либо сначала выполните bicep restore.

list-versions

Команда list-versions возвращает все доступные версии Bicep CLI. Используйте эту команду, чтобы узнать, требуется ли обновить или установить новую версию. Эта команда доступна только через Azure CLI.

N/A

публикация

Команда publish добавляет модуль в реестр. Реестр контейнеров Azure должен существовать, а публикация учетной записи в реестре должна иметь правильные разрешения. Дополнительные сведения о настройке реестра модулей см. в разделе Использовать частный реестр для модулей Bicep. Чтобы опубликовать модуль, учетная запись должна иметь правильный профиль и разрешения для доступа к реестру. Вы можете настроить приоритет профиля и учетных данных для проверки подлинности в реестре в файле конфигурации Bicep.

После публикации файла в реестре вы можете ссылаться на него в модуле.

Для использования команды < <>Bicep c1 /> />/c0>< версии 0.14.X или более поздней, чтобы использовать команду и параметр .

Чтобы опубликовать модуль в реестре, используйте следующее:

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

Например:

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

Команда publish не распознает псевдонимы, указанные в файле bicepconfig.json. Укажите полный путь модуля.

Предупреждение

Публикация в том же целевом объекте перезапишет старый модуль. Добавим версию при обновлении.

Восстановление

Когда файл Bicep использует модули, опубликованные в реестре, команда restore получает копии всех необходимых модулей из реестра. Эти копии помещаются в локальный кэш. Файл Bicep можно создать только в том случае, если внешние файлы доступны в локальном кэше. Обычно выполнение восстановления не требуется, так как он автоматически активируется процессом сборки.

Чтобы восстановить внешние модули в локальном кэше, учетная запись должна иметь правильный профиль и разрешения для доступа к реестру. Вы можете настроить приоритет проfile и учетных данных для проверки подлинности в реестре в файле конфигурации Bicep.

Чтобы использовать команду restore, требуется Bicep CLI версии 0.14.X или более поздней.

Чтобы вручную восстановить внешние модули для файла, используйте следующее:

bicep restore <bicep-file>

Предоставленный Bicep файл — это файл, который требуется развернуть. Он должен содержать модуль, связанный с реестром. Например, можно восстановить следующий файл:

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

Локальный кэш можно найти в:

  • На Windows

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

  • В Linux

    /home/<username>/.bicep

  • На Компьютере Mac

    ~/.bicep

Команда restore не обновляет кэш, если модуль уже кэширован. Чтобы обновить кэш, можно удалить путь модуля из кэша или использовать --force переключатель с restore помощью команды.

snapshot

С помощью Bicep CLI версии 0.41.2 или более поздней версии можно использовать команду snapshot для создания нормализованного детерминированного представления развертывания Bicep из файла .bicepparam. Вы можете сравнить этот моментальный снимок с последующими моментальными снимками, чтобы понять, какие изменения будут вызваны рефакторингом, не развертывая ничего в Azure. Эта команда особенно полезна для:

  • Визуальные диффы. Просмотр точного способа рефакторинга (например, перемещение кода в модуль) изменяет базовые определения ресурсов.
  • Сложные выражения: понимание того, что сложная строка или переменная фактически оценивается перед развертыванием.
  • Проверка CI/CD: автоматически перехватывает непредвиденные изменения в логике инфраструктуры во время запросов на вытягивание.

Создайте моментальный снимок

Эта команда создает .snapshot.json файл. Этот файл "нормализован" означает, что он удаляет шум, например границы модуля, чтобы сосредоточиться на самих ресурсах.

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

В следующем JSON-файле показан пример моментального снимка:

{
  "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": []
}

Проверка изменений

После создания моментального снимка выполните команду в режиме проверки. Он сравнивает текущий код Bicep с сохраненным моментальным снимком и отображает визуальный дифф, так же как и команду несколько если, но полностью локальную.

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

Пример выходных данных выглядит следующим образом:

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"

"Сбой проверки моментальных снимков" указывает на различия между двумя моментальными снимками.

Bicep моментальный снимок интерфейса командной строки и то, что имеет следующие различия:

Функция bicep snapshot az deployment group what-if
Выполнение Только локальный (автономный) Облачный (Онлайн)
Comparison Сравнивает код и сохраненный файл Сравнивает код и состояние динамического Azure
Скорость Очень быстро Медленнее (требуется вызовы API)
Вариант использования Рефакторинг и тестирование логики Окончательная проверка перед развертыванием

Предоставление контекста

При выполнении моментального снимка Bicep интерфейс командной строки выполняет локальную оценку кода. Так как он не разговаривает с Azure, он не может запрашивать облако для идентификатора подписки или текущего имени группы ресурсов.

Если код использует функции среды (например subscription().id), моментальный снимок завершится ошибкой или возвратом заполнителей, если только вы не предоставляете определенный контекст с помощью аргументов CLI.

Чтобы имитировать реальную среду развертывания, можно передать следующие флаги:

Аргумент Цель Пример значения
--subscription-id Заменяет возвращаемое значение subscription().subscriptionId 00000000-1111-2222-3333-444444444444
--resource-group Заменяет возвращаемое значение resourceGroup().name my-production-rg
--location Задает расположение по умолчанию для deployment().location westeurope
--tenant-id Заменяет возвращаемое значение tenant().tenantId 72f988bf-86f1-41af-91ab-2d7cd011db47
--management-group Заменяет возвращаемое значение 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

обновление

Команда upgrade обновляет установленную версию до последней версии. Эта команда доступна только через Azure CLI.

версия

Команда version возвращает установленную версию:

bicep --version

Если вы не установили интерфейс командной строки Bicep, появится сообщение об ошибке о том, что Bicep CLI не найден.

Команда показывает номер версии:

Bicep CLI version 0.29.45 (57a44c0230)

Следующие шаги

Дополнительные сведения о развертывании файла Bicep см. в следующем разделе:

  • Last updated on