Funções de data para Bicep

Artigo
01/22/2024

Este artigo descreve as funções Bicep para trabalhar com dados.

dateTimeAdd

dateTimeAdd(base, duration, [format])

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

Namespace: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
base	Sim	string	O valor de data/hora de início para a adição. Use o formato de carimbo de data/hora ISO 8601.
duration	Sim	string	O valor temporal a ser adicionado à base. Pode ser um valor negativo. Use um 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, o formato do valor de base será usado. Use cadeias de caracteres de formato padrão ou cadeias de caracteres de formato personalizado.

Retornar valor

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

Comentários

A função dateTimeAdd não leva em consideração os anos bissextos, e P1Y deve ser interpretado como P365D, enquanto P1M deve ser interpretado como P30D. O arquivo Bicep a seguir 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 de início de 2024, um ano bissexto, resulta em 2024-12-31T00:00:00Z, e não 2025-01-01T00:00:00Z, já 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 se torna aparente quando se adiciona um mês ao primeiro dia de fevereiro, o que leva a resultados variados do dia do mês.

Exemplos

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

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

O exemplo a seguir mostra como definir a hora de início de um agendamento de Automação do Azure.

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 hora de época em um datetime ISO 8601.

Namespace: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
epochTime	Sim	INT	A hora da época a ser convertida em uma cadeia de caracteres de datetime.

Retornar valor

Uma cadeia de caracteres de datetime ISO 8601.

Comentários

Essa função requer a CLI do Bicep versão 0.5.X ou superior.

Exemplo

O exemplo a seguir mostra valores de saída para as funções de hora 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
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	int	1683040573

dateTimeToEpoch

dateTimeToEpoch(dateTime)

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

Namespace: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
dateTime	Sim	string	A cadeia de caracteres de datetime a ser convertida em uma hora de época.

Retornar valor

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

Comentários

Essa função requer a CLI do Bicep versão 0.5.X ou superior.

Exemplos

O exemplo a seguir mostra valores de saída para as funções de hora 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
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	int	1683040573

O exemplo a seguir usa o valor de hora da é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
      }
    }
  }
}

utcNow

utcNow(format)

Retorna o valor de datetime (UTC) atual no formato especificado. Se o formato não for fornecido, o formato ISO 8601 (yyyyMMddTHHmmssZ) será usado. Só é possível usar essa função no valor padrão de um parâmetro.

Namespace: sys.

Parâmetros

Parâmetro	Obrigatório	Type	Descrição
format	Não	string	O valor codificado em URI a ser convertido em uma cadeia de caracteres. Use cadeias de caracteres de formato padrão ou cadeias de caracteres de formato personalizado.

Comentários

Você só pode usar essa função em uma expressão do valor padrão de um parâmetro. O uso dela em qualquer outro lugar de um arquivo Bicep retorna um erro. A função não é permitida em outras partes do arquivo Bicep porque ela retorna um valor diferente cada vez que é chamada. Implantar o mesmo arquivo Bicep com os mesmos parâmetros não produziria os mesmos resultados com confiança.

Se você usar a opção para reverter um erro para 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 será utilizado automaticamente na implantação de reversão.

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

Retornar valor

O valor de 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 de acordo com cada implantação, mas será semelhante a:

Nome	Tipo	Valor
utcOutput	string	20190305T175318Z
utcShortOutput	string	05/03/2019
utcCustomOutput	string	3 5

O exemplo a seguir mostra como usar um valor da função ao definir um valor de marcação.

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óximas etapas

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

Funções de data para Bicep

dateTimeAdd

Parâmetros

Retornar valor

Comentários

Exemplos

dateTimeFromEpoch

Parâmetros

Retornar valor

Comentários

Exemplo

dateTimeToEpoch

Parâmetros

Retornar valor

Comentários

Exemplos

utcNow

Parâmetros

Comentários

Retornar valor

Exemplos

Próximas etapas

Recursos adicionais