Функции развертывания для шаблонов ARM

Статья
06/26/2024

Resource Manager предоставляет следующие функции для получения значений, связанных с текущим развертыванием шаблона Azure Resource Manager (шаблон ARM):

deployment
среда
parameters
variables

Сведения о получении значений из ресурсов, групп ресурсов или подписки см. в разделе Функции для работы с ресурсами.

Совет

Мы рекомендуем использовать Bicep, так как он предоставляет те же возможности, что и шаблоны ARM, и имеет более простой синтаксис. Дополнительные сведения см. в описании функций развертывания.

развертывание

deployment()

Возвращает сведения о текущей операции развертывания.

В Bicep используйте функцию развертывания.

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

Эта функция возвращает объект, который передается во время развертывания. Свойства возвращаемого объекта различаются в зависимости от того, что вы делаете:

развертываете шаблон или спецификацию шаблона;
развертываете шаблон, который является локальным файлом, или развертываете шаблон, который является удаленным файлом, доступ к которому осуществляется через универсальный код ресурса (URI);
развертываете в группе ресурсов или развертываете в одной из других областей (подписка Azure, группа управления или клиент).

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

{
  "name": "",
  "properties": {
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

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

{
  "name": "",
  "properties": {
    "templateLink": {
      "uri": ""
    },
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

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

{
  "name": "",
  "properties": {
    "templateLink": {
      "id": ""
    },
    "template": {
      "$schema": "",
      "contentVersion": "",
      "parameters": {},
      "variables": {},
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

Если вы выполняете развертывание в подписке Azure, группе управления или клиенте, возвращаемый объект содержит свойство location, а не группу ресурсов. Свойство расположения включается при развертывании локального или внешнего шаблона. Формат будет следующим:

{
  "name": "",
  "location": "",
  "properties": {
    "template": {
      "$schema": "",
      "contentVersion": "",
      "resources": [],
      "outputs": {}
    },
    "templateHash": "",
    "parameters": {},
    "mode": "",
    "provisioningState": ""
  }
}

При развертывании шаблона deployment languageVersion 2.0 функция возвращает ограниченное подмножество свойств:

{
  "name": "",
  "location": "",
  "properties": {
    "template": {
      "contentVersion": ""
    },
    "templateLink": {
      "id": "",
      "uri": ""
    }
  }
}

Замечания

Вы можете использовать deployment() для ссылки на другой шаблон в зависимости от URI родительского шаблона.

"variables": {
  "sharedTemplateUrl": "[uri(deployment().properties.templateLink.uri, 'shared-resources.json')]"
}

Если вы повторно развертываете шаблон из журнала развертывания на портале, шаблон развернется в виде локального файла. Свойство templateLink не возвращается в функции развертывания. Если в шаблоне применяется templateLink для ссылки на другой шаблон, не используйте портал для повторного развертывания. Вместо этого используйте команды, с помощью которых вы развернули исходный шаблон.

Пример

В следующем примере возвращается объект развертывания.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "deploymentOutput": {
      "type": "object",
      "value": "[deployment()]"
    }
  }
}

В предыдущем примере возвращается следующий объект:

{
  "name": "deployment",
  "properties": {
    "template": {
      "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
      "contentVersion": "1.0.0.0",
      "resources": [],
      "outputs": {
        "deploymentOutput": {
          "type": "Object",
          "value": "[deployment()]"
        }
      }
    },
    "templateHash": "13135986259522608210",
    "parameters": {},
    "mode": "Incremental",
    "provisioningState": "Accepted"
  }
}

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

{
  "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {},
  "resources": [],
  "outputs": {
    "exampleOutput": {
      "type": "object",
      "value": "[deployment()]"
    }
  }
}

environment

environment()

Возвращает сведения о среде Azure, используемой для развертывания. Функция environment() не знает о конфигурациях ресурсов. Он может возвращать только один DNS-суффикс по умолчанию для каждого типа ресурса.

В Bicep используйте функцию среды.

Замечания

Чтобы просмотреть список зарегистрированных сред для вашей учетной записи, используйте az cloud list или Get-AzEnvironment.

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

Эта функция возвращает свойства для текущей среды Azure. В примере ниже показаны свойства для глобальной среды Azure. Национальные облака могут возвращать немного другие свойства.

{
  "name": "",
  "gallery": "",
  "graph": "",
  "portal": "",
  "graphAudience": "",
  "activeDirectoryDataLake": "",
  "batch": "",
  "media": "",
  "sqlManagement": "",
  "vmImageAliasDoc": "",
  "resourceManager": "",
  "authentication": {
    "loginEndpoint": "",
    "audiences": [
      "",
      ""
    ],
    "tenant": "",
    "identityProvider": ""
  },
  "suffixes": {
    "acrLoginServer": "",
    "azureDatalakeAnalyticsCatalogAndJob": "",
    "azureDatalakeStoreFileSystem": "",
    "azureFrontDoorEndpointSuffix": "",
    "keyvaultDns": "",
    "sqlServerHostname": "",
    "storage": ""
  }
}

Пример

В следующем примере шаблона возвращается объект среды:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "environmentOutput": {
      "type": "object",
      "value": "[environment()]"
    }
  }
}

В примере выше возвращается следующий объект при развертывании в глобальной среде Azure:

{
  "name": "AzureCloud",
  "gallery": "https://gallery.azure.com/",
  "graph": "https://graph.windows.net/",
  "portal": "https://portal.azure.com",
  "graphAudience": "https://graph.windows.net/",
  "activeDirectoryDataLake": "https://datalake.azure.net/",
  "batch": "https://batch.core.windows.net/",
  "media": "https://rest.media.azure.net",
  "sqlManagement": "https://management.core.windows.net:8443/",
  "vmImageAliasDoc": "https://raw.githubusercontent.com/Azure/azure-rest-api-specs/master/arm-compute/quickstart-templates/aliases.json",
  "resourceManager": "https://management.azure.com/",
  "authentication": {
    "loginEndpoint": "https://login.microsoftonline.com/",
    "audiences": [
      "https://management.core.windows.net/",
      "https://management.azure.com/"
    ],
    "tenant": "common",
    "identityProvider": "AAD"
  },
  "suffixes": {
    "acrLoginServer": ".azurecr.io",
    "azureDatalakeAnalyticsCatalogAndJob": "azuredatalakeanalytics.net",
    "azureDatalakeStoreFileSystem": "azuredatalakestore.net",
    "azureFrontDoorEndpointSuffix": "azurefd.net",
    "keyvaultDns": ".vault.azure.net",
    "sqlServerHostname": ".database.windows.net",
    "storage": "core.windows.net"
  }
}

parameters

parameters(parameterName)

Возвращает значение параметра. Указанное имя параметра должно быть определено в разделе параметров шаблона.

В Bicep можно ссылаться на параметры напрямую, используя их символьные имена.

Параметры

Параметр	Обязательное поле	Type	Описание
parameterName	Да	строка	Имя параметра, который требуется вернуть.

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

Значение указанного параметра.

Замечания

Как правило, параметры используются, чтобы задать значения ресурсов. В следующем примере значению параметра задается имя веб-сайта, переданное во время развертывания.

"parameters": {
  "siteName": {
    "type": "string"
  }
}, "resources": [
  {
    "type": "Microsoft.Web/Sites",
    "apiVersion": "2016-08-01",
    "name": "[parameters('siteName')]",
    ...
  }
]

Пример

В следующем примере показано упрощенное использование функции parameters.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "stringParameter": {
      "type": "string",
      "defaultValue": "option 1"
    },
    "intParameter": {
      "type": "int",
      "defaultValue": 1
    },
    "objectParameter": {
      "type": "object",
      "defaultValue": {
        "one": "a",
        "two": "b"
      }
    },
    "arrayParameter": {
      "type": "array",
      "defaultValue": [ 1, 2, 3 ]
    },
    "crossParameter": {
      "type": "string",
      "defaultValue": "[parameters('stringParameter')]"
    }
  },
  "variables": {},
  "resources": [],
  "outputs": {
    "stringOutput": {
      "type": "string",
      "value": "[parameters('stringParameter')]"
    },
    "intOutput": {
      "type": "int",
      "value": "[parameters('intParameter')]"
    },
    "objectOutput": {
      "type": "object",
      "value": "[parameters('objectParameter')]"
    },
    "arrayOutput": {
      "type": "array",
      "value": "[parameters('arrayParameter')]"
    },
    "crossOutput": {
      "type": "string",
      "value": "[parameters('crossParameter')]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
stringOutput	Строка	вариант 1
intOutput	Int	1
objectOutput	Object	{"one": "a", "two": "b"}
arrayOutput	Массив	[1, 2, 3]
crossOutput	Строка	вариант 1

Дополнительные сведения об использовании параметров см. в статье Параметры в шаблонах ARM.

переменные

variables(variableName)

Возвращает значение переменной. Указанное имя переменной должно быть определено в разделе переменных шаблона.

В Bicep можно ссылаться на переменные напрямую, используя их символьные имена.

Параметры

Параметр	Обязательное поле	Type	Описание
variableName	Да	Строка	Имя переменной, которую необходимо вернуть.

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

Значение указанной переменной.

Замечания

Как правило, переменные используются, чтобы упростить шаблон за счет создания сложных значений (единожды). В примере ниже создается уникальное имя для учетной записи хранения.

"variables": {
  "storageName": "[concat('storage', uniqueString(resourceGroup().id))]"
},
"resources": [
  {
    "type": "Microsoft.Storage/storageAccounts",
    "name": "[variables('storageName')]",
    ...
  },
  {
    "type": "Microsoft.Compute/virtualMachines",
    "dependsOn": [
      "[variables('storageName')]"
    ],
    ...
  }
],

Пример

Следующий пример возвращает разные значения переменных.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {},
  "variables": {
    "var1": "myVariable",
    "var2": [ 1, 2, 3, 4 ],
    "var3": "[ variables('var1') ]",
    "var4": {
      "property1": "value1",
      "property2": "value2"
    }
  },
  "resources": [],
  "outputs": {
    "exampleOutput1": {
      "type": "string",
      "value": "[variables('var1')]"
    },
    "exampleOutput2": {
      "type": "array",
      "value": "[variables('var2')]"
    },
    "exampleOutput3": {
      "type": "string",
      "value": "[variables('var3')]"
    },
    "exampleOutput4": {
      "type": "object",
      "value": "[variables('var4')]"
    }
  }
}

Выходные данные из предыдущего примера со значениями по умолчанию:

Имя.	Тип	значение
exampleOutput1	Строка	myVariable
exampleOutput2	Массив	[1, 2, 3, 4]
exampleOutput3	Строка	myVariable
exampleOutput4	Object	{"property1": "value1", "property2": "value2"}

Дополнительные сведения об использовании переменных см. в статье Переменные в шаблоне ARM.

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

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

Поделиться через

Функции развертывания для шаблонов ARM

развертывание

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

Замечания

Пример

environment

Замечания

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

Пример

parameters

Параметры

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

Замечания

Пример

переменные

Параметры

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

Замечания

Пример

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

Обратная связь

Дополнительные ресурсы