用于 Azure 资源管理器模板的部署函数Deployment functions for Azure Resource Manager templates

资源管理器提供了以下函数,用于获取与当前部署相关的值:Resource Manager provides the following functions for getting values related to the current deployment:

若要从资源、资源组或订阅获取值,请参阅 Resource functions(资源函数)。To get values from resources, resource groups, or subscriptions, see Resource functions.

部署deployment

deployment()

返回有关当前部署操作的信息。Returns information about the current deployment operation.

返回值Return value

此函数返回部署期间传递的对象。This function returns the object that is passed during deployment. 根据部署对象是作为链接还是内联对象传递,所返回对象中的属性将有所不同。The properties in the returned object differ based on whether the deployment object is passed as a link or as an in-line object. 如果部署对象是以内联形式传递的(例如使用 Azure PowerShell 中的 -TemplateFile 参数指向本地文件时),所返回的对象采用以下格式:When the deployment object is passed in-line, such as when using the -TemplateFile parameter in Azure PowerShell to point to a local file, the returned object has the following format:

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

如果对象是以链接形式传递的(例如使用 -TemplateUri 参数指向远程对象时),所返回的对象采用以下格式:When the object is passed as a link, such as when using the -TemplateUri parameter to point to a remote object, the object is returned in the following format:

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

部署到 Azure 订阅而不是资源组时,返回对象包含 location 属性。When you deploy to an Azure subscription, instead of a resource group, the return object includes a location property. 部署本地模板或外部模板时包含 location 属性。The location property is included when deploying either a local template or an external template.

备注Remarks

可以根据父模板的 URI,使用 deployment() 链接到另一个模板。You can use deployment() to link to another template based on the URI of the parent template.

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

如果从门户中的部署历史记录重新部署模板,则该模板将部署为本地文件。If you redeploy a template from the deployment history in the portal, the template is deployed as a local file. 部署函数不返回 templateLink 属性。The templateLink property isn't returned in the deployment function. 如果模板依赖于 templateLink 来构建指向另一个模板的链接,请不要使用门户进行重新部署,If your template relies on templateLink to construct a link to another template, don't use the portal to redeploy. 而是使用最初部署模板时使用的命令。Instead, use the commands you used to originally deploy the template.

示例Example

下面的示例模板返回部署对象:The following example template returns the deployment object:

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

上面的示例返回下列对象:The preceding example returns the following object:

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

对于使用部署功能的订阅级别模板,请参阅订阅部署功能For a subscription-level template that uses the deployment function, see subscription deployment function. 它使用 az deployment createNew-AzDeployment 命令进行部署。It's deployed with either az deployment create or New-AzDeployment commands.

环境environment

environment()

返回有关用于部署的 Azure 环境的信息。Returns information about the Azure environment used for deployment.

返回值Return value

此函数返回当前 Azure 环境的属性。This function returns properties for the current Azure environment. 以下示例显示了全局 Azure 的属性。The following example shows the properties for global Azure. 主权云可能会返回略有不同的属性。Sovereign clouds may return slightly different properties.

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

示例Example

以下示例模板返回环境对象。The following example template returns the environment object.

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

前面的示例在部署到全局 Azure 时返回以下对象:The preceding example returns the following object when deployed to global Azure:

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

parametersparameters

parameters(parameterName)

返回一个参数值。Returns a parameter value. 指定的参数名称必须已在模板的 parameters 节中定义。The specified parameter name must be defined in the parameters section of the template.

parametersParameters

参数Parameter 必选Required 类型Type 说明Description
parameterNameparameterName Yes 字符串string 要返回的参数名称。The name of the parameter to return.

返回值Return value

指定的参数的值。The value of the specified parameter.

备注Remarks

通常情况下,使用参数来设置资源值。Typically, you use parameters to set resource values. 下面的示例将网站的名称设置为部署过程中传递的参数值。The following example sets the name of web site to the parameter value passed in during deployment.

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

示例Example

以下示例模板演示了 parameters 函数的简化用法。The following example template shows a simplified use of the parameters function.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-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": {
            "value": "[parameters('stringParameter')]",
            "type" : "string"
        },
        "intOutput": {
            "value": "[parameters('intParameter')]",
            "type" : "int"
        },
        "objectOutput": {
            "value": "[parameters('objectParameter')]",
            "type" : "object"
        },
        "arrayOutput": {
            "value": "[parameters('arrayParameter')]",
            "type" : "array"
        },
        "crossOutput": {
            "value": "[parameters('crossParameter')]",
            "type" : "string"
        }
    }
}

上面具有默认值的示例的输出为:The output from the preceding example with the default values is:

名称Name 类型Type Value
stringOutputstringOutput StringString option 1option 1
intOutputintOutput IntInt 11
objectOutputobjectOutput ObjectObject {"one": "a", "two": "b"}{"one": "a", "two": "b"}
arrayOutputarrayOutput ArrayArray [1, 2, 3][1, 2, 3]
crossOutputcrossOutput StringString option 1option 1

如需详细了解如何使用参数,请参阅 Azure 资源管理器模板中的参数For more information about using parameters, see Parameters in Azure Resource Manager template.

variablesvariables

variables(variableName)

返回变量的值。Returns the value of variable. 指定的变量名称必须已在模板的 variables 节中定义。The specified variable name must be defined in the variables section of the template.

parametersParameters

参数Parameter 必选Required 类型Type 说明Description
variableNamevariableName Yes StringString 要返回的变量名称。The name of the variable to return.

返回值Return value

指定的变量的值。The value of the specified variable.

备注Remarks

通常情况下,使用变量通过仅构造一次复杂值来简化模板。Typically, you use variables to simplify your template by constructing complex values only once. 下面的示例为存储帐户构造唯一的名称。The following example constructs a unique name for a storage account.

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

示例Example

以下示例模板返回了不同的变量值。The following example template returns different variable values.

{
    "$schema": "https://schema.management.azure.com/schemas/2015-01-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": {
            "value": "[variables('var1')]",
            "type" : "string"
        },
        "exampleOutput2": {
            "value": "[variables('var2')]",
            "type" : "array"
        },
        "exampleOutput3": {
            "value": "[variables('var3')]",
            "type" : "string"
        },
        "exampleOutput4": {
            "value": "[variables('var4')]",
            "type" : "object"
        }
    }
}

上面具有默认值的示例的输出为:The output from the preceding example with the default values is:

名称Name 类型Type Value
exampleOutput1exampleOutput1 StringString myVariablemyVariable
exampleOutput2exampleOutput2 ArrayArray [1, 2, 3, 4][1, 2, 3, 4]
exampleOutput3exampleOutput3 StringString myVariablemyVariable
exampleOutput4exampleOutput4 ObjectObject {"property1": "value1", "property2": "value2"}{"property1": "value1", "property2": "value2"}

如需详细了解如何使用变量,请参阅 Azure 资源管理器模板中的变量For more information about using variables, see Variables in Azure Resource Manager template.

后续步骤Next steps