ARM 模板的日期函数Date functions for ARM templates

资源管理器提供了以下可用于在 Azure 资源管理器 (ARM) 模板中处理日期的函数：Resource Manager provides the following functions for working with dates in your Azure Resource Manager (ARM) templates:

dateTimeAdddateTimeAdd

dateTimeAdd(base, duration, [format])

向基础值加上一个持续时间。Adds a time duration to a base value. 需要 ISO 8601 格式。ISO 8601 format is expected.

parametersParameters

参数Parameter 必须Required 类型Type 说明Description
basebase 是Yes stringstring 用于相加的起始日期/时间值。The starting datetime value for the addition. 使用 ISO 8601 时间戳格式。Use ISO 8601 timestamp format.
durationduration 是Yes stringstring 要与 base 相加的时间值。The time value to add to the base. 它可以是负值。It can be a negative value. 使用 ISO 8601 持续时间格式。Use ISO 8601 duration format.
formatformat 否No stringstring 日期时间结果的输出格式。The output format for the date time result. 如果未提供，则将使用 base 值的格式。If not provided, the format of the base value is used. 使用标准格式字符串或自定义格式字符串。Use either standard format strings or custom format strings.

返回值Return value

将 duration 值与 base 值相加后得到的日期/时间值。The datetime value that results from adding the duration value to the base value.

示例Examples

以下示例模板展示了增加时间值的各种方式。The following example template shows different ways of adding time values.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters":{
        "baseTime":{
            "type":"string",
            "defaultValue": "[utcNow('u')]"
        }
    },
    "variables": {
        "add3Years": "[dateTimeAdd(parameters('baseTime'), 'P3Y')]",
        "subtract9Days": "[dateTimeAdd(parameters('baseTime'), '-P9D')]",
        "add1Hour": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]"
    },
    "resources": [],
    "outputs": {
        "add3Years": {
            "value": "[variables('add3Years')]",
            "type": "string"
        },
        "subtract9Days": {
            "value": "[variables('subtract9Days')]",
            "type": "string"
        },
        "add1Hour": {
            "value": "[variables('add1Hour')]",
            "type": "string"
        },
    }
}

在 baseTime为 2020-04-07 14:53:14Z 的情况下部署上述模板时，输出为：When the preceding template is deployed with a base time of 2020-04-07 14:53:14Z, the output is:

名称Name 类型Type ValueValue
add3Yearsadd3Years StringString 4/7/2023 2:53:14 PM4/7/2023 2:53:14 PM
subtract9Dayssubtract9Days StringString 3/29/2020 2:53:14 PM3/29/2020 2:53:14 PM
add1Houradd1Hour StringString 4/7/2020 3:53:14 PM4/7/2020 3:53:14 PM

下一示例模板展示了如何设置自动化计划的开始时间。The next example template shows how to set the start time for an Automation schedule.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "omsAutomationAccountName": {
            "type": "string",
            "defaultValue": "demoAutomation",
            "metadata": {
                "description": "Use an existing Automation account."
            }
        },
        "scheduleName": {
            "type": "string",
            "defaultValue": "demoSchedule1",
            "metadata": {
                "description": "Name of the new schedule."
            }
        },
        "baseTime":{
            "type":"string",
            "defaultValue": "[utcNow('u')]",
            "metadata": {
                "description": "Schedule will start one hour from this time."
            }
        }
    },
    "variables": {
        "startTime": "[dateTimeAdd(parameters('baseTime'), 'PT1H')]"
    },
    "resources": [
        {
            "name": "[concat(parameters('omsAutomationAccountName'), '/', parameters('scheduleName'))]",
            "type": "microsoft.automation/automationAccounts/schedules",
            "apiVersion": "2015-10-31",
            "location": "chinaeast2",
            "tags": {
            },
            "properties": {
                "description": "Demo Scheduler",
                "startTime": "[variables('startTime')]",
                "isEnabled": "true",
                "interval": 1,
                "frequency": "hour"
            }
        }
    ],
    "outputs": {
    }
}

utcNowutcNow

utcNow(format)

以指定的格式返回当前的 (UTC) 日期时间值。Returns the current (UTC) datetime value in the specified format. 如果未提供格式，则使用 ISO 8601 (yyyyMMddTHHmmssZ) 格式。If no format is provided, the ISO 8601 (yyyyMMddTHHmmssZ) format is used. 此函数只能在参数的默认值中使用。This function can only be used in the default value for a parameter.

parametersParameters

参数Parameter 必须Required 类型Type 说明Description
formatformat 否No stringstring 要转换为字符串的 URI 编码值。The URI encoded value to convert to a string. 使用标准格式字符串或自定义格式字符串。Use either standard format strings or custom format strings.

备注Remarks

只能在表达式中对参数的默认值使用此函数。You can only use this function within an expression for the default value of a parameter. 在模板中的其他任何位置使用此函数都会返回错误。Using this function anywhere else in a template returns an error. 不允许在模板的其他部分使用该函数，因为每次调用该函数，都会返回不同的值。The function isn't allowed in other parts of the template because it returns a different value each time it's called. 使用相同的参数部署同一模板不能可靠地生成相同的结果。Deploying the same template with the same parameters wouldn't reliably produce the same results.

如果使用出错时回退选项回退到以前成功的部署，而以前的部署包含一个使用 utcNow 的参数，则不会重新评估该参数，If you use the option to rollback on error to an earlier successful deployment, and the earlier deployment includes a parameter that uses utcNow, the parameter isn't reevaluated. 而是在回滚部署中自动重复使用以前部署中的参数值。Instead, the parameter value from the earlier deployment is automatically reused in the rollback deployment.

重新部署依赖于 utcNow 函数提供默认值的模板时请保持谨慎。Be careful redeploying a template that relies on the utcNow function for a default value. 如果重新部署且不提供参数的值，则会重新评估该函数。When you redeploy and don't provide a value for the parameter, the function is reevaluated. 若要更新现有的资源而不是新建资源，请传入以前部署中的参数值。If you want to update an existing resource rather than create a new one, pass in the parameter value from the earlier deployment.

返回值Return value

当前的 UTC 日期时间值。The current UTC datetime value.

示例Examples

以下示例模板演示日期时间值的不同格式。The following example template shows different formats for the datetime value.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "utcValue": {
            "type": "string",
            "defaultValue": "[utcNow()]"
        },
        "utcShortValue": {
            "type": "string",
            "defaultValue": "[utcNow('d')]"
        },
        "utcCustomValue": {
            "type": "string",
            "defaultValue": "[utcNow('M d')]"
        }
    },
    "resources": [
    ],
    "outputs": {
        "utcOutput": {
            "type": "string",
            "value": "[parameters('utcValue')]"
        },
        "utcShortOutput": {
            "type": "string",
            "value": "[parameters('utcShortValue')]"
        },
        "utcCustomOutput": {
            "type": "string",
            "value": "[parameters('utcCustomValue')]"
        }
    }
}

上述示例的输出根据每个部署的不同而异，但类似于：The output from the preceding example varies for each deployment but will be similar to:

名称Name 类型Type ValueValue
utcOutpututcOutput stringstring 20190305T175318Z20190305T175318Z
utcShortOutpututcShortOutput stringstring 03/05/201903/05/2019
utcCustomOutpututcCustomOutput stringstring 3 53 5

以下示例演示在设置标记值时如何使用函数中的值。The next example shows how to use a value from the function when setting a tag value.

{
    "$schema": "https://schema.management.azure.com/schemas/2018-05-01/subscriptionDeploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "utcShort": {
            "type": "string",
            "defaultValue": "[utcNow('d')]"
        },
        "rgName": {
            "type": "string"
        }
    },
    "resources": [
        {
            "type": "Microsoft.Resources/resourceGroups",
            "apiVersion": "2018-05-01",
            "name": "[parameters('rgName')]",
            "location": "chinanorth",
            "tags":{
                "createdDate": "[parameters('utcShort')]"
            },
            "properties":{}
        }
    ],
    "outputs": {
        "utcShort": {
            "type": "string",
            "value": "[parameters('utcShort')]"
        }
    }
}

后续步骤Next steps