Bicep 的 Date 函式

發行項
03/22/2024

本文說明處理日期的 Bicep 函式。

dateTimeAdd

dateTimeAdd(base, duration, [format])

將持續時間加至基底值。預期為 ISO 8601 格式。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
base	Yes	string	要加上的開始日期時間值。使用 ISO 8601 時間戳記格式。
duration	Yes	string	要加至基底的時間值。可以是負數值。使用 ISO 8601 持續時間格式。
format	No	string	日期時間結果的輸出格式。如果未提供，則會使用基底值的格式。使用標準格式字串或自訂格式字串。

傳回值

將持續時間值加至基底值所產生的日期時間值。

備註

dateTimeAdd 函式不考慮閏年，P1Y 應解譯為 P365D，而 P1M 應解譯為 P30D。下列 Bicep 檔案示範一些範例：

output addOneYearNonLeap string = dateTimeAdd('2023-01-01 00:00:00Z', 'P1Y') //2024-01-01T00:00:00Z
output addOneYearLeap string = dateTimeAdd('2024-01-01 00:00:00Z', 'P1Y')  //2024-12-31T00:00:00Z

output addOneMonthNonLeap string = dateTimeAdd('2023-02-01 00:00:00Z', 'P1M') //2023-03-03T00:00:00Z
output addOneMonthLeap string = dateTimeAdd('2024-02-01 00:00:00Z', 'P1M') //2023-03-02T00:00:00Z

在上述範例中，由於 2023 並非閏年，因此 2023 年第一日加一年的結果為 2024-01-01T00:00:00Z。相反地，2024 年為閏年，一年有 366 天而非 365 天，因此第一日加一年的結果為 2024-12-31T00:00:00Z，而非 2025-01-01T00:00:00Z。此外，在二月第一日增加一個月時，由於閏年與非閏年的差異，二月份的天數也會因此出現不同結果。

範例

下列範例顯示加上時間值的不同方式。

param baseTime string = utcNow('u')

var add3Years = dateTimeAdd(baseTime, 'P3Y')
var subtract9Days = dateTimeAdd(baseTime, '-P9D')
var add1Hour = dateTimeAdd(baseTime, 'PT1H')

output add3YearsOutput string = add3Years
output subtract9DaysOutput string = subtract9Days
output add1HourOutput string = add1Hour

當前述範例是使用 2020-04-07 14:53:14Z 的基底時間部署時，輸出為：

名稱	類型	值
add3YearsOutput	String	4/7/2023 2:53:14 PM
subtract9DaysOutput	String	3/29/2020 2:53:14 PM
add1HourOutput	String	4/7/2020 3:53:14 PM

下一個範例顯示如何設定自動化排程的開始時間。

param omsAutomationAccountName string = 'demoAutomation'
param scheduleName string = 'demSchedule1'
param baseTime string = utcNow('u')

var startTime = dateTimeAdd(baseTime, 'PT1H')

...

resource scheduler 'Microsoft.Automation/automationAccounts/schedules@2022-08-08' = {
  name: concat(omsAutomationAccountName, '/', scheduleName)
  properties: {
    description: 'Demo Scheduler'
    startTime: startTime
    interval: 1
    frequency: 'Hour'
  }
}

dateTimeFromEpoch

dateTimeFromEpoch(epochTime)

將 Epoch 時間整數值轉換為 ISO 8601 日期時間。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
epochTime	Yes	int	要轉換成日期時間字串的 Epoch 時間。

傳回值

ISO 8601 日期時間字串。

備註

此函式需要 Bicep CLI 0.5.X 版或更高版本。

範例

下列範例顯示 Epoch 時間函式的輸出值。

param convertedEpoch int = dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

輸出如下：

名稱	類型	值
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	int	1683040573

dateTimeToEpoch

dateTimeToEpoch(dateTime)

將 ISO 8601 日期時間字串轉換為 Epoch 時間整數值。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
dateTime	Yes	string	要轉換成 Epoch 時間的日期時間字串。

傳回值

表示 1970 年 1 月 1 日午夜秒數的整數。

備註

此函式需要 Bicep CLI 0.5.X 版或更高版本。

範例

下列範例顯示 Epoch 時間函式的輸出值。

param convertedEpoch int = dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

輸出如下：

名稱	類型	值
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	int	1683040573

下一個範例會使用 epoch 時間值來設定金鑰保存庫中金鑰的到期日。

@description('The location into which the resources should be deployed.')
param location string = resourceGroup().location

@description('The Tenant Id that should be used throughout the deployment.')
param tenantId string = subscription().tenantId

@description('The name of the existing User Assigned Identity.')
param userAssignedIdentityName string

@description('The name of the resource group for the User Assigned Identity.')
param userAssignedIdentityResourceGroupName string

@description('The name of the Key Vault.')
param keyVaultName string  = 'vault-${uniqueString(resourceGroup().id)}'

@description('Name of the key in the Key Vault')
param keyVaultKeyName string = 'cmkey'

@description('Expiration time of the key')
param keyExpiration int = dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))

@description('The name of the Storage Account')
param storageAccountName string =  'storage${uniqueString(resourceGroup().id)}'


resource userAssignedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2018-11-30' existing = {
  scope: resourceGroup(userAssignedIdentityResourceGroupName)
  name: userAssignedIdentityName  
}

resource keyVault 'Microsoft.KeyVault/vaults@2021-10-01' = {
  name: keyVaultName
  location: location
  properties: {
    sku: {
      name: 'standard'
      family: 'A'
    }
    enableSoftDelete: true
    enablePurgeProtection: true
    enabledForDiskEncryption: true
    tenantId: tenantId
    accessPolicies: [
      {
        tenantId: tenantId
        permissions: {
          keys: [
            'unwrapKey'
            'wrapKey'
            'get'
          ]
        }
        objectId: userAssignedIdentity.properties.principalId
      }
    ]
  }
}

resource kvKey 'Microsoft.KeyVault/vaults/keys@2021-10-01' = {
  parent: keyVault
  name: keyVaultKeyName
  properties: {
    attributes: {
      enabled: true
      exp: keyExpiration
    }
    keySize: 4096
    kty: 'RSA'
  }
}

resource storage 'Microsoft.Storage/storageAccounts@2021-04-01' = {
  name: storageAccountName
  location: location
  sku: {
    name: 'Standard_LRS'
  }
  kind: 'StorageV2'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${userAssignedIdentity.id}': {}
    }
  }
  properties: {
    accessTier: 'Hot'
    supportsHttpsTrafficOnly: true
    minimumTlsVersion: 'TLS1_2'
    encryption: {
      identity: {
        userAssignedIdentity: userAssignedIdentity.id
      }
      services: {
         blob: {
           enabled: true
         }
      }
      keySource: 'Microsoft.Keyvault'
      keyvaultproperties: {
        keyname: kvKey.name
        keyvaulturi: endsWith(keyVault.properties.vaultUri,'/') ? substring(keyVault.properties.vaultUri,0,length(keyVault.properties.vaultUri)-1) : keyVault.properties.vaultUri
      }
    }
  }
}

utcNow

utcNow(format)

以指定的格式傳回目前的 (UTC) 日期時間值。如果未提供格式，則會使用 ISO 8601 (yyyyMMddTHHmmssZ) 格式。 此函式只能用於參數的預設值。

命名空間：sys (部分機器翻譯)。

參數

參數	必要	類型	描述
format	No	string	要轉換為字串的 URI 編碼值。使用標準格式字串或自訂格式字串。

備註

您只能在運算式內使用此函式，以取得參數的預設值。在 Bicep 檔案中的其他地方使用此函式會傳回錯誤。在 Bicep 檔案的其他部分不允許該函式，因為其會在每次呼叫時傳回不同的值。使用相同的參數部署相同的 Bicep 檔案，並不一定會產生相同的結果。

如果您使用發生錯誤時復原選項，以復原為稍早成功的部署，而稍早的部署包含使用 utcNow 的參數，則不會重新評估該參數。相反地，系統將會在復原部署中自動重複使用來自稍早部署的參數值。

重新部署依賴於 utcNow 函式以取得預設值的 Bicep 檔案時請小心。當您重新部署且未提供參數的值時，會重新評估該函式。如果您想更新現有的資源，而不是建立新的資源，請傳入來自先前部署的參數值。

傳回值

目前的 UTC 日期時間值。

範例

下列範例會顯示不同格式的日期時間值。

param utcValue string = utcNow()
param utcShortValue string = utcNow('d')
param utcCustomValue string = utcNow('M d')

output utcOutput string = utcValue
output utcShortOutput string = utcShortValue
output utcCustomOutput string = utcCustomValue

前述範例的輸出會隨著個別部署而有所不同，但會類似於：

名稱	類型	值
utcOutput	string	20190305T175318Z
utcShortOutput	string	03/05/2019
utcCustomOutput	string	3 5

下個範例示範如何在設定標記值時使用來自函式的值。

param utcShort string = utcNow('d')
param rgName string

resource myRg 'Microsoft.Resources/resourceGroups@2022-09-01' = {
  name: rgName
  location: 'westeurope'
  tags: {
    createdDate: utcShort
  }
}

output utcShortOutput string = utcShort

下一步

如需 Bicep 檔案中各區段的描述，請參閱了解 Bicep 檔案的結構和語法。

Bicep 的 Date 函式

dateTimeAdd

參數

傳回值

備註

範例

dateTimeFromEpoch

參數

傳回值

備註

範例

dateTimeToEpoch

參數

傳回值

備註

範例

utcNow

參數

備註

傳回值

範例

下一步

其他資源