Функции файлов для Bicep

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

loadDirectoryFileInfo

loadDirectoryFileInfo(directoryPath, [searchPattern])

Загружает базовую информацию о файлах каталога в виде объекта Bicep. Функция загружает файлы во время компиляции, а не во время выполнения.

Пространство имен: sys.

Параметры

Параметр	Обязательно	Тип	Description
directoryPath	Да	струна	Путь относительно файла Bicep, вызывающего эту функцию. Вы можете использовать переменные, если они являются константами по времени компиляции, но параметры использовать нельзя.
searchPattern	нет	струна	Шаблон поиска, используемый при загрузке файлов. Эта схема может включать джокеры.

Возвращаемое значение

Массив объектов, каждый из которых представляет файл в каталоге. Каждый объект содержит следующие свойства:

Недвижимость	Тип	Description
baseName	струна	Имя файла.
Расширение	струна	Расширение файла.
relativePath	струна	Относительный путь к текущему шаблону.

Примеры

В следующем примере загружаются сведения о файле для всех файлов Bicep в каталоге ./modules/ .

var dirFileInfo = loadDirectoryFileInfo('./modules/', '*.bicep')

output dirFileInfoOutput object[] = dirFileInfo

Папка содержит только один файл с именем appService.bicep. Результат выглядит так:

[{"relativePath":"modules/appService.bicep","baseName":"appService.bicep","extension":".bicep"}]

loadFileAsBase64

loadFileAsBase64(filePath)

Загружает файл в виде строки base64.

Пространство имен: sys.

Параметры

Параметр	Обязательно	Тип	Description
filePath	Да	струна	Путь к загружению файла. Путь относительно развернутого Bicep-файла. Не удается включить переменные.

Замечания

Используйте эту функцию, когда у вас есть бинарный контент, который вы хотите включить в развертывание. Вместо того чтобы вручную кодировать файл в строку base64 и добавлять его в файл Bicep, загружайте файл с помощью этой функции. Файл загружается при компиляции Bicep-файла в шаблон JSON. Нельзя использовать переменные в пути к файлу, потому что компилятор не разрешает их при компиляции в шаблон. Во время развертывания шаблон JSON содержит содержимое файла как жестко закодированную строку.

Для этой функции требуется интерфейс командной строки Bicep версии 0.4.X или более поздней.

Максимальный допустимый размер файла составляет 96 КБ.

Возвращаемое значение

Файл в виде строки base64.

Примеры

Следующий пример загружает скрипт PowerShell в виде строки base64 и использует его вместе с расширением Custom Script Extension для виртуальной машины (VM).

param vmName string
param location string

resource vmExtension 'Microsoft.Compute/virtualMachines/extensions@2024-07-01' = {
  name: '${vmName}/CustomScriptExtension'
  location: location
  properties: {
    publisher: 'Microsoft.Compute'
    type: 'CustomScriptExtension'
    typeHandlerVersion: '1.10'
    autoUpgradeMinorVersion: true
    forceUpdateTag: 'true'
    protectedSettings: {
      commandToExecute: 'powershell.exe -ExecutionPolicy Unrestricted -Command "iex ""& { $([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(\'${loadFileAsBase64('vm-provisioning.ps1')}\'))) } -ParamX foo -ParamY bar"""'
    }
  }
}

Note

В этом примере параметр PowerShell -EncodedCommand не использован. -EncodedCommand ожидает команды, закодированной UTF-16LE. В этом примере вместо этого строка base64 передаётся в PowerShell и явно декодирует её как UTF-8 перед вызовом скрипта.

Файл скрипта загружается во время компиляции Bicep и встраивается в сгенерированный шаблон JSON в виде строки, закодированной в base64. Когда развертывание запускается, PowerShell декодирует строку и вызывает скрипт на виртуальной машине. Этот подход полезен при встраивании содержимого скрипта напрямую в commandToExecute, поскольку он избегает множества проблем с цитированием, побегом и новыми строками, которые могут возникнуть при многострочном содержимом скриптов.

Вы также можете закодировать встроенную многострочную строку и base64() передавать именованные параметры декодированному скрипту. Для получения дополнительной информации см. многострочный литерал.

var scriptContent = '''
param(
  [string] $Name
)

Write-Host "Hello $Name!"
'''

var scriptArgs = {
  Name: 'MyValue'
}

// Builds a string of the form '-ArgA ValA -ArgB ValB'
var argumentString = join(map(items(scriptArgs), i => '-${i.key} ${i.value}'), ' ')

var commandToExecute = 'powershell.exe -ExecutionPolicy Unrestricted -Command "iex \\"& { $([System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String(\'${base64(scriptContent)}\'))) } ${argumentString}\\""'

Note

Этот пример работает потому, что значение аргумента (MyValue) не содержит специальных символов. Простой join/map строитель не уходит и не цитирует значения. Он провалится, если какое-либо значение содержит пробелы (которые должны быть обернуты в кавычки), или одиночные кавычки, двойные кавычки или другие символы, специфические для парсера командной строки PowerShell (который нужно отклонять с replace()помощью ).

Для полного примера, который корректно обрабатывает булевые значения, целые числа, строки с полным выходом, массивы и объекты, см. раздел Create a Deployment Script с комплексными входами и выходами.

loadJsonContent

loadJsonContent(filePath, [jsonPath], [encoding])

Загружает указанный JSON-файл в виде объекта Any.

Пространство имен: sys.

Параметры

Параметр	Обязательно	Тип	Description
filePath	Да	струна	Путь к загружению файла. Путь относительно развернутого Bicep-файла. Не удается включить переменные.
jsonPath	нет	струна	Выражение JSONPath, указывающее, что загружается только часть файла.
encoding	нет	струна	Кодировка файла. Значение по умолчанию — utf-8. Доступны следующие варианты: iso-8859-1, , us-asciiutf-16, utf-16BEили utf-8.

Замечания

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

В VS Code IntelliSense доступен для свойств загруженного объекта. Например, можно создать файл со значениями для общего доступа ко многим файлам Bicep. Пример показан в этой статье.

Для этой функции требуется интерфейс командной строки Bicep версии 0.7.X или более поздней.

Максимальный допустимый размер файла составляет 1 048 576 символов, включая окончания строки.

Возвращаемое значение

Содержимое файла как объекта Any.

Примеры

В следующем примере создается JSON-файл, содержащий значения для группы безопасности сети.

{
  "description": "Allows SSH traffic",
  "protocol": "Tcp",
  "sourcePortRange": "*",
  "destinationPortRange": "22",
  "sourceAddressPrefix": "*",
  "destinationAddressPrefix": "*",
  "access": "Allow",
  "priority": 100,
  "direction": "Inbound"
}

Вы загружаете этот файл и преобразуете его в объект JSON. Объект используется для назначения значений ресурсу.

param location string = resourceGroup().location

var nsgconfig = loadJsonContent('nsg-security-rules.json')

resource newNSG 'Microsoft.Network/networkSecurityGroups@2025-01-01' = {
  name: 'example-nsg'
  location: location
  properties: {
    securityRules: [
      {
        name: 'SSH'
        properties: nsgconfig
      }
    ]
  }
}

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

loadYamlContent

loadYamlContent(filePath, [pathFilter], [encoding])

Загружает указанный ФАЙЛ YAML в виде объекта Any.

Пространство имен: sys.

Параметры

Параметр	Обязательно	Тип	Description
filePath	Да	струна	Путь к загружению файла. Путь относительно развернутого Bicep-файла. Не удается включить переменные.
pathFilter	нет	струна	Фильтр пути — это выражение JSONPath, указывающее, что загружается только часть файла.
encoding	нет	струна	Кодировка файла. Значение по умолчанию — utf-8. Доступны следующие варианты: iso-8859-1, , us-asciiutf-16, utf-16BEили utf-8.

Замечания

Используйте эту функцию, если у вас есть YAML-контент или минифицированный YAML-контент, который вы храните в отдельном файле. Вместо дублирования содержимого YAML в вашем файле Bicep используйте эту функцию для загрузки содержимого. Вы можете загрузить часть ФАЙЛА YAML, указав фильтр пути. Компилятор Bicep загружает файл при компиляции файла Bicep в шаблон YAML. Нельзя включать переменные в путь к файлу, потому что компилятор не может их разрешить при компиляции в шаблон. Во время развертывания шаблон YAML содержит содержимое файла как жестко закодированную строку.

В VS Code IntelliSense доступен для свойств загруженного объекта. Например, можно создать файл со значениями для общего доступа ко многим файлам Bicep. Пример показан в этой статье.

Для этой функции требуется интерфейс командной строки Bicep версии 0.16.X или более поздней.

Максимальный допустимый размер файла составляет 1 048 576 символов, включая окончания строки.

Возвращаемое значение

Содержимое файла как объекта Any.

Примеры

В следующем примере создается ФАЙЛ YAML, содержащий значения для группы безопасности сети.

description: "Allows SSH traffic"
protocol: "Tcp"
sourcePortRange: "*"
destinationPortRange: "22"
sourceAddressPrefix: "*"
destinationAddressPrefix: "*"
access: "Allow"
priority: 100
direction: "Inbound"

Вы загружаете этот файл и преобразуете его в объект JSON. Объект используется для назначения значений ресурсу.

param location string = resourceGroup().location

var nsgconfig = loadYamlContent('nsg-security-rules.yaml')

resource newNSG 'Microsoft.Network/networkSecurityGroups@2025-01-01' = {
  name: 'example-nsg'
  location: location
  properties: {
    securityRules: [
      {
        name: 'SSH'
        properties: nsgconfig
      }
    ]
  }
}

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

loadTextContent

loadTextContent(filePath, [encoding])

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

Пространство имен: sys.

Параметры

Параметр	Обязательно	Тип	Description
filePath	Да	струна	Путь к загружению файла. Путь относительно развернутого Bicep-файла. Он не может содержать переменные.
encoding	нет	струна	Кодировка файла. Значение по умолчанию — utf-8. Доступны следующие варианты: iso-8859-1, , us-asciiutf-16, utf-16BEили utf-8.

Замечания

Используйте эту функцию при наличии содержимого, хранящегося в отдельном файле. Вы можете загрузить содержимое, а не дублировать его в файле Bicep. Например, можно загрузить скрипт развертывания из файла. Файл загружается при компиляции Bicep-файла в шаблон JSON. Вы не можете включать переменные в путь к файлу, потому что они не разрешаются при компиляции в шаблон. Во время развертывания шаблон JSON содержит содержимое файла как жестко закодированную строку.

Чтобы загрузить JSON-файлы, используйте функцию loadJsonContent() .

Для этой функции требуется интерфейс командной строки Bicep версии 0.4.X или более поздней.

Максимальный допустимый размер файла составляет 131 072 символов, включая окончания строки.

Возвращаемое значение

Содержимое файла в виде строки.

Примеры

Следующий пример показывает, как загрузить скрипт из файла и использовать его для скрипта развертывания.

resource exampleScript 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: 'exampleScript'
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '/subscriptions/{sub-id}/resourcegroups/{rg-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{id-name}': {}
    }
  }
  properties: {
    azPowerShellVersion: '14.0'
    scriptContent: loadTextContent('myscript.ps1')
    retentionInterval: 'P1D'
  }
}

Дальнейшие шаги

Описание разделов в файле Bicep приведено в статье Общие сведения о структуре и синтаксисе файлов Bicep.