Funções de data para modelos do ARM

Artigo
02/03/2024

Este artigo descreve as funções para trabalhar com datas no seu modelo do ARM (Azure Resource Manager).

Dica

Recomendamos o Bicep porque ele oferece as mesmas funcionalidades que os modelos do ARM e a sintaxe é mais fácil de usar. Para saber mais, confira as funções de data.

dateTimeAdd

dateTimeAdd(base, duration, [format])

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

No Bicep, use a função dateTimeAdd.

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 anos bissextos e P1Y deve ser interpretado como P365D, enquanto P1M deve ser interpretado como P30D. O json a seguir mostra alguns exemplos:

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "resources": [],
  "outputs": {
    "addOneYearNonLeap": {
      "type": "string",
      "value": "[dateTimeAdd('2023-01-01 00:00:00Z', 'P1Y')]"  //2024-01-01T00:00:00Z
    },
    "addOneYearLeap": {
      "type": "string",
      "value": "[dateTimeAdd('2024-01-01 00:00:00Z', 'P1Y')]"  //2024-12-31T00:00:00Z
    },
    "addOneMonthNonLeap": {
      "type": "string",
      "value": "[dateTimeAdd('2023-02-01 00:00:00Z', 'P1M')]"  //2023-03-03T00:00:00Z
    },
    "addOneMonthLeap": {
      "type": "string",
      "value": "[dateTimeAdd('2024-02-01 00:00:00Z', 'P1M')]"  //2024-03-02T00:00:00Z
    }
  }
}

No exemplo anterior, considerando 2023 como um ano não bissexto, o resultado de adicionar um ano ao dia inicial do ano será 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, visto que um ano bissexto consiste de 366 dias em vez de 365 dias. Além disso, a distinção entre anos bissextos e não bissextos torna-se evidente ao adicionar um mês ao primeiro dia de fevereiro, levando a diferentes resultados para o dia do mês.

Exemplos

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

{
  "$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": {
    "add3YearsOutput": {
      "value": "[variables('add3Years')]",
      "type": "string"
    },
    "subtract9DaysOutput": {
      "value": "[variables('subtract9Days')]",
      "type": "string"
    },
    "add1HourOutput": {
      "value": "[variables('add1Hour')]",
      "type": "string"
    }
  }
}

Quando o modelo 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 modelo de exemplo a seguir mostra como definir a hora de início de um agendamento do Automação do Azure.

{
  "$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": [
    ...
    {
      "type": "Microsoft.Automation/automationAccounts/schedules",
      "apiVersion": "2022-08-08",
      "name": "[concat(parameters('omsAutomationAccountName'), '/', parameters('scheduleName'))]",

      "properties": {
        "description": "Demo Scheduler",
        "startTime": "[variables('startTime')]",
        "interval": 1,
        "frequency": "Hour"
      }
    }
  ],
  "outputs": {
  }
}

dateTimeFromEpoch

dateTimeFromEpoch(epochTime)

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

No Bicep, use a função dateTimeFromEpoch.

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.

Exemplo

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "convertedEpoch": {
      "type": "int",
      "defaultValue": "[dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))]"
    }
  },
  "variables": {
    "convertedDatetime": "[dateTimeFromEpoch(parameters('convertedEpoch'))]"
  },
  "resources": [],
  "outputs": {
    "epochValue": {
      "type": "int",
      "value": "[parameters('convertedEpoch')]"
    },
    "datetimeValue": {
      "type": "string",
      "value": "[variables('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.

No Bicep, use a função dateTimeToEpoch.

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.

Exemplos

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

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "convertedEpoch": {
      "type": "int",
      "defaultValue": "[dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))]"
    }
  },
  "variables": {
    "convertedDatetime": "[dateTimeFromEpoch(parameters('convertedEpoch'))]"
  },
  "resources": [],
  "outputs": {
    "epochValue": {
      "type": "int",
      "value": "[parameters('convertedEpoch')]"
    },
    "datetimeValue": {
      "type": "string",
      "value": "[variables('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.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "metadata": {
    "_generator": {
      "name": "bicep",
      "version": "0.5.6.12127",
      "templateHash": "16023511331197397029"
    }
  },
  "parameters": {
    "location": {
      "type": "string",
      "defaultValue": "[resourceGroup().location]",
      "metadata": {
        "description": "The location into which the resources should be deployed."
      }
    },
    "tenantId": {
      "type": "string",
      "defaultValue": "[subscription().tenantId]",
      "metadata": {
        "description": "The Tenant Id that should be used throughout the deployment."
      }
    },
    "userAssignedIdentityName": {
      "type": "string",
      "metadata": {
        "description": "The name of the existing User Assigned Identity."
      }
    },
    "userAssignedIdentityResourceGroupName": {
      "type": "string",
      "metadata": {
        "description": "The name of the resource group for the User Assigned Identity."
      }
    },
    "keyVaultName": {
      "type": "string",
      "defaultValue": "[format('vault-{0}', uniqueString(resourceGroup().id))]",
      "metadata": {
        "description": "The name of the Key Vault."
      }
    },
    "keyVaultKeyName": {
      "type": "string",
      "defaultValue": "cmkey",
      "metadata": {
        "description": "Name of the key in the Key Vault"
      }
    },
    "keyExpiration": {
      "type": "int",
      "defaultValue": "[dateTimeToEpoch(dateTimeAdd(utcNow(), 'P1Y'))]",
      "metadata": {
        "description": "Expiration time of the key"
      }
    },
    "storageAccountName": {
      "type": "string",
      "defaultValue": "[format('storage{0}', uniqueString(resourceGroup().id))]",
      "metadata": {
        "description": "The name of the Storage Account"
      }
    }
  },
  "resources": [
    {
      "type": "Microsoft.KeyVault/vaults",
      "apiVersion": "2021-10-01",
      "name": "[parameters('keyVaultName')]",
      "location": "[parameters('location')]",
      "properties": {
        "sku": {
          "name": "standard",
          "family": "A"
        },
        "enableSoftDelete": true,
        "enablePurgeProtection": true,
        "enabledForDiskEncryption": true,
        "tenantId": "[parameters('tenantId')]",
        "accessPolicies": [
          {
            "tenantId": "[parameters('tenantId')]",
            "permissions": {
              "keys": [
                "unwrapKey",
                "wrapKey",
                "get"
              ]
            },
            "objectId": "[reference(extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, parameters('userAssignedIdentityResourceGroupName')), 'Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')), '2018-11-30').principalId]"
          }
        ]
      }
    },
    {
      "type": "Microsoft.KeyVault/vaults/keys",
      "apiVersion": "2021-10-01",
      "name": "[format('{0}/{1}', parameters('keyVaultName'), parameters('keyVaultKeyName'))]",
      "properties": {
        "attributes": {
          "enabled": true,
          "exp": "[parameters('keyExpiration')]"
        },
        "keySize": 4096,
        "kty": "RSA"
      },
      "dependsOn": [
        "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]"
      ]
    },
    {
      "type": "Microsoft.Storage/storageAccounts",
      "apiVersion": "2021-04-01",
      "name": "[parameters('storageAccountName')]",
      "location": "[parameters('location')]",
      "sku": {
        "name": "Standard_LRS"
      },
      "kind": "StorageV2",
      "identity": {
        "type": "UserAssigned",
        "userAssignedIdentities": {
          "[format('{0}', extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, parameters('userAssignedIdentityResourceGroupName')), 'Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName')))]": {}
        }
      },
      "properties": {
        "accessTier": "Hot",
        "supportsHttpsTrafficOnly": true,
        "minimumTlsVersion": "TLS1_2",
        "encryption": {
          "identity": {
            "userAssignedIdentity": "[extensionResourceId(format('/subscriptions/{0}/resourceGroups/{1}', subscription().subscriptionId, parameters('userAssignedIdentityResourceGroupName')), 'Microsoft.ManagedIdentity/userAssignedIdentities', parameters('userAssignedIdentityName'))]"
          },
          "services": {
            "blob": {
              "enabled": true
            }
          },
          "keySource": "Microsoft.Keyvault",
          "keyvaultproperties": {
            "keyname": "[parameters('keyVaultKeyName')]",
            "keyvaulturi": "[if(endsWith(reference(resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))).vaultUri, '/'), substring(reference(resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))).vaultUri, 0, sub(length(reference(resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))).vaultUri), 1)), reference(resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))).vaultUri)]"
          }
        }
      },
      "dependsOn": [
        "[resourceId('Microsoft.KeyVault/vaults', parameters('keyVaultName'))]",
        "[resourceId('Microsoft.KeyVault/vaults/keys', parameters('keyVaultName'), parameters('keyVaultKeyName'))]"
      ]
    }
  ]
}

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.

No Bicep, use a função utcNow.

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 modelo retorna um erro. A função não é permitida em outras partes do modelo porque ela retorna um valor diferente cada vez que é chamada. Implantar o mesmo modelo 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 modelo 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 modelo de exemplo a seguir mostra formatos diferentes para o valor datetime.

{
  "$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')]"
    }
  }
}

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.

{
  "$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": "2021-04-01",
      "name": "[parameters('rgName')]",
      "location": "westeurope",
      "tags": {
        "createdDate": "[parameters('utcShort')]"
      },
      "properties": {}
    }
  ],
  "outputs": {
    "utcShortOutput": {
      "type": "string",
      "value": "[parameters('utcShort')]"
    }
  }
}

Próximas etapas

Para obter uma descrição das seções de um modelo do ARM, confira Entender a estrutura e a sintaxe dos modelos do ARM.

Funções de data para modelos do ARM

dateTimeAdd

Parâmetros

Retornar valor

Comentários

Exemplos

dateTimeFromEpoch

Parâmetros

Retornar valor

Exemplo

dateTimeToEpoch

Parâmetros

Retornar valor

Exemplos

utcNow

Parâmetros

Comentários

Retornar valor

Exemplos

Próximas etapas

Recursos adicionais