Funções de data para Bicep

Este artigo descreve as funções do Bíceps para trabalhar com datas.

dateTimeAdicionar

dateTimeAdd(base, duration, [format])

Adiciona uma duração de tempo a um valor base. O formato ISO 8601 é esperado.

Espaço de nome: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Description
base	Sim	string	O valor datetime inicial para a adição. Use o formato de carimbo de data/hora ISO 8601.
duration	Sim	string	O valor de tempo a ser adicionado à base. Pode ser um valor negativo. Use o formato de duração ISO 8601.
format	Não	string	O formato de saída para o resultado de data e hora. Se não for fornecido, é utilizado o formato do valor base. Use cadeias de caracteres de formato padrão ou cadeias de caracteres de formato personalizado.

Valor devolvido

O valor datetime que resulta da adição do valor de duração ao valor base.

Observações

A dateTimeAdd função não leva anos bissextos em consideração, e P1Y deve ser interpretado como P365D, enquanto P1M deve ser interpretado como P30D. O seguinte arquivo Bicep mostra alguns exemplos:

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

No exemplo anterior, considerando 2023 como um ano não bissexto, o resultado da adição de um ano ao dia inicial do ano é 2024-01-01T00:00:00Z. Por outro lado, adicionar um ano ao dia inicial de 2024, um ano bissexto, resulta em 2024-12-31T00:00:00Z, não 2025-01-01T00:00:00Z, dado que um ano bissexto compreende 366 dias em vez de 365 dias. Além disso, a distinção entre anos bissextos e não bissextos torna-se evidente quando se adiciona um mês ao primeiro dia de fevereiro, levando a resultados variáveis no dia do mês.

Exemplos

O exemplo a seguir mostra diferentes maneiras de adicionar valores de tempo.

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

Quando o exemplo anterior é implantado com uma hora base de 2020-04-07 14:53:14Z, a saída é:

Nome	Tipo	valor
add3YearsOutput	String	07/04/2023 14:53:14
subtrair9DaysOutput	String	29/03/2020 14:53:14
add1HourOutput	String	07/04/2020 15:53:14

O próximo exemplo mostra como definir a hora de início para uma agenda de automação.

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)

Converte um valor inteiro de tempo de época em um datetime ISO 8601.

Espaço de nome: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Description
epochTime	Sim	número inteiro	A hora de época para converter em uma cadeia de caracteres datetime.

Valor devolvido

Uma cadeia de caracteres datetime ISO 8601.

Observações

Esta função requer Bicep CLI versão 0.5.X ou superior.

Exemplo

O exemplo a seguir mostra valores de saída para as funções de tempo de época.

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

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

A saída é:

Nome	Tipo	valor
datetimeValor	String	2023-05-02T15:16:13Z
epochValue	Int	1683040573

dateTimeToEpoch

dateTimeToEpoch(dateTime)

Converte uma cadeia de caracteres datetime ISO 8601 em um valor inteiro de tempo de época.

Espaço de nome: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Description
dateTime	Sim	string	A cadeia de caracteres datetime para converter em uma hora de época.

Valor devolvido

Um inteiro que representa o número de segundos a partir da meia-noite de 1º de janeiro de 1970.

Observações

Esta função requer Bicep CLI versão 0.5.X ou superior.

Exemplos

O exemplo a seguir mostra valores de saída para as funções de tempo de época.

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

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

A saída é:

Nome	Tipo	valor
datetimeValor	String	2023-05-02T15:16:13Z
epochValue	Int	1683040573

O próximo exemplo usa o valor de tempo de época para definir a expiração de uma chave em um cofre de chaves.

@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
      }
    }
  }
}

utcAgora

utcNow(format)

Retorna o valor datetime atual (UTC) no formato especificado. Se nenhum formato for fornecido, o formato ISO 8601 (yyyyMMddTHHmmssZ) será usado. Esta função só pode ser usada no valor padrão para um parâmetro.

Espaço de nome: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Description
format	Não	string	O valor codificado de URI para converter em uma cadeia de caracteres. Use cadeias de caracteres de formato padrão ou cadeias de caracteres de formato personalizado.

Observações

Você só pode usar essa função dentro de uma expressão para o valor padrão de um parâmetro. Usar essa função em qualquer outro lugar em um arquivo Bicep retorna um erro. A função não é permitida em outras partes do arquivo Bicep porque retorna um valor diferente cada vez que é chamada. Implantar o mesmo arquivo Bicep com os mesmos parâmetros não produziria os mesmos resultados de forma confiável.

Se você usar a opção para reverter o erro para uma implantação bem-sucedida anterior e a implantação anterior incluir um parâmetro que usa utcNow, o parâmetro não será reavaliado. Em vez disso, o valor do parâmetro da implantação anterior é reutilizado automaticamente na implantação de reversão.

Tenha cuidado ao reimplantar um arquivo Bicep que depende da função utcNow para um valor padrão. Quando você reimplanta e não fornece um valor para o parâmetro, a função é reavaliada. Se você quiser atualizar um recurso existente em vez de criar um novo, passe o valor do parâmetro da implantação anterior.

Valor devolvido

O valor datetime UTC atual.

Exemplos

O exemplo a seguir mostra formatos diferentes para o valor datetime.

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

A saída do exemplo anterior varia para cada implantação, mas será semelhante a:

Nome	Tipo	valor
utcSaída	string	20190305T175318Z
utcShortOutput	string	03/05/2019
utcCustomOutput	string	3 5

O próximo exemplo mostra como usar um valor da função ao definir um valor de tag.

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

Próximos passos

• Para obter uma descrição das seções em um arquivo Bicep, consulte Compreender a estrutura e a sintaxe dos arquivos Bicep.