Funkcje daty dla szablonów usługi ARM

Artykuł
01/20/2024

W tym artykule opisano funkcje pracy z datami w szablonie usługi Azure Resource Manager (szablon usługi ARM).

Napiwek

Zalecamy Bicep , ponieważ oferuje te same możliwości co szablony usługi ARM, a składnia jest łatwiejsza w użyciu. Aby dowiedzieć się więcej, zobacz funkcje daty .

dateTimeAdd

dateTimeAdd(base, duration, [format])

Dodaje czas trwania do wartości podstawowej. Oczekiwano formatu ISO 8601.

W pliku Bicep użyj funkcji dateTimeAdd .

Parametry

Parametr	Wymagania	Type	Opis
base	Tak	string	Początkowa wartość daty/godziny dodawania. Użyj formatu znacznika czasu ISO 8601.
czas trwania	Tak	string	Wartość czasu, która ma zostać dodana do bazy. Może to być wartość ujemna. Użyj formatu czasu trwania ISO 8601.
format	Nie.	string	Format danych wyjściowych dla wyniku daty i godziny. Jeśli nie zostanie podana, zostanie użyty format wartości podstawowej. Użyj ciągów formatu standardowego lub ciągów formatu niestandardowego.

Wartość zwracana

Wartość daty/godziny, która wynika z dodania wartości czasu trwania do wartości podstawowej.

Uwagi

Funkcja dateTimeAdd nie bierze pod uwagę lat przestępnych, a P1Y należy interpretować jako P365D, podczas gdy P1M należy interpretować jako P30D. Poniższy kod json przedstawia kilka przykładów:

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

W poprzednim przykładzie, biorąc pod uwagę rok 2023 jako rok nieprzestąpny, wynik dodawania jednego roku do początkowego dnia roku to 2024-01-01T00:00:00Z. Z drugiej strony, dodanie jednego roku do dnia początkowego 2024 r., rok przestępny, powoduje 2024-12-31T00:00:00Z, a nie 2025-01-01T00:00:00Z, biorąc pod uwagę, że rok przestępny obejmuje 366 dni zamiast 365 dni. Ponadto rozróżnienie między latami przestępnym i nieskocznia staje się widoczne podczas dodawania jednego miesiąca do pierwszego dnia lutego, co prowadzi do różnych wyników dnia miesiąca.

Przykłady

Poniższy przykładowy szablon przedstawia różne sposoby dodawania wartości czasu.

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

Po wdrożeniu poprzedniego szablonu przy użyciu czasu podstawowego 2020-04-07 14:53:14Zdane wyjściowe to:

Nazwisko	Typ	Wartość
add3YearsOutput	String	4/7/2023 2:53:14
odejmowanie 9DaysOutput	String	29.03.2020 23:53:14
add1HourOutput	String	4/7/2020 17:53:14

W następnym przykładowym szablonie pokazano, jak ustawić godzinę rozpoczęcia harmonogramu automatyzacji.

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

Konwertuje wartość liczby całkowitej czasu epoki na wartość daty/godziny ISO 8601.

W Bicep użyj funkcji dateTimeFromEpoch .

Parametry

Parametr	Wymagania	Type	Opis
epochTime	Tak	int	Czas epoki, który ma być konwertowany na ciąg daty/godziny.

Wartość zwracana

Ciąg daty/godziny ISO 8601.

Przykład

W poniższym przykładzie przedstawiono wartości wyjściowe dla funkcji czasu epoki.

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

Dane wyjściowe to:

Nazwisko	Typ	Wartość
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	Int	1683040573

dateTimeToEpoch

dateTimeToEpoch(dateTime)

Konwertuje ciąg daty/godziny ISO 8601 na wartość całkowitą czasu epoki.

W Bicep użyj funkcji dateTimeToEpoch .

Parametry

Parametr	Wymagania	Type	Opis
Data i godzina	Tak	string	Ciąg daty/godziny, który ma być konwertowany na czas epoki.

Wartość zwracana

Liczba całkowita reprezentująca liczbę sekund od północy 1 stycznia 1970 roku.

Przykłady

W poniższym przykładzie przedstawiono wartości wyjściowe dla funkcji czasu epoki.

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

Dane wyjściowe to:

Nazwisko	Typ	Wartość
datetimeValue	String	2023-05-02T15:16:13Z
epochValue	Int	1683040573

W następnym przykładzie użyto wartości czasu epoki, aby ustawić wygaśnięcie klucza w magazynie kluczy.

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

Zwraca bieżącą wartość daty/godziny (UTC) w określonym formacie. Jeśli nie podano żadnego formatu, używany jest format ISO 8601 (yyyyMMddTHHmmssZ). Tej funkcji można używać tylko w wartości domyślnej parametru.

W Bicep użyj funkcji utcNow .

Parametry

Parametr	Wymagania	Type	Opis
format	Nie.	string	Zakodowana wartość identyfikatora URI do konwersji na ciąg. Użyj ciągów formatu standardowego lub ciągów formatu niestandardowego.

Uwagi

Tej funkcji można używać tylko w wyrażeniu dla wartości domyślnej parametru. Użycie tej funkcji w dowolnym miejscu w szablonie zwraca błąd. Funkcja nie jest dozwolona w innych częściach szablonu, ponieważ zwraca inną wartość za każdym razem, gdy jest wywoływana. Wdrożenie tego samego szablonu przy użyciu tych samych parametrów nie spowodowałoby niezawodnego wygenerowania tych samych wyników.

Jeśli używasz opcji wycofywania błędu do wcześniejszego pomyślnego wdrożenia, a wcześniejsze wdrożenie zawiera parametr, który używa utcNowparametru , parametr nie jest ponownie oceniany. Zamiast tego wartość parametru z wcześniejszego wdrożenia jest automatycznie ponownie wykorzystywana we wdrożeniu wycofywania.

Należy zachować ostrożność podczas ponownego wdrażania szablonu, który opiera się na utcNow funkcji dla wartości domyślnej. Po ponownym wdróżeniu i nie podaniu wartości parametru funkcja zostanie ponownie zceniona. Jeśli chcesz zaktualizować istniejący zasób, a nie utworzyć nowego, przekaż wartość parametru z wcześniejszego wdrożenia.

Wartość zwracana

Bieżąca wartość daty/godziny UTC.

Przykłady

Poniższy przykładowy szablon przedstawia różne formaty wartości daty/godziny.

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

Dane wyjściowe z poprzedniego przykładu różnią się w zależności od wdrożenia, ale będą podobne do następujących:

Nazwisko	Typ	Wartość
utcOutput	string	20190305T175318Z
utcShortOutput	string	03/05/2019
utcCustomOutput	string	3 5

W następnym przykładzie pokazano, jak używać wartości z funkcji podczas ustawiania wartości tagu.

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

Następne kroki

Aby zapoznać się z opisem sekcji w szablonie usługi ARM, zobacz Omówienie struktury i składni szablonów usługi ARM.

Funkcje daty dla szablonów usługi ARM

dateTimeAdd

Parametry

Wartość zwracana

Uwagi

Przykłady

dateTimeFromEpoch

Parametry

Wartość zwracana

Przykład

dateTimeToEpoch

Parametry

Wartość zwracana

Przykłady

Utcnow

Parametry

Uwagi

Wartość zwracana

Przykłady

Następne kroki

Dodatkowe zasoby