وظائف التاريخ لـ Bicep

  • مقالة

توضح هذه المقالة وظائف Bicep للتعامل مع التواريخ.

dateTimeAdd

dateTimeAdd(base, duration, [format])

إضافة مدة زمنية إلى قيمة أساسية. يُتوقع تنسيق ISO 8601.

مساحة الاسم: sys.

المعلمات

المعلمة‬ المطلوب نوع ‏‏الوصف
الأساس ‏‏نعم‬ سلسلة قيمة البداية والتاريخ والوقت للإضافة. استخدم تنسيق الطابع الزمني ISO 8601 .
المدة ‏‏نعم‬ سلسلة القيمة الزمنية المراد إضافتها إلى القاعدة. يمكن أن تكون قيمة سالبة. استخدم تنسيق المدة ISO 8601 .
format لا سلسلة تنسيق الإخراج لنتيجة التاريخ والوقت. إذا لم يتم توفيره، فسيتم استخدام تنسيق القيمة الأساسية. استخدم إما سلاسل ذات تنسيق قياسي أو سلاسل تنسيق مخصص .

قيمة الإرجاع

قيمة التاريخ والوقت التي تنتج عن إضافة قيمة المدة إلى القيمة الأساسية.

ملاحظات

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 كسنة غير كبيسة، فإن نتيجة إضافة سنة واحدة إلى اليوم الأولي من السنة هي 2024-01-01T00:00:00Z. وعلى العكس من ذلك، تؤدي إضافة سنة واحدة إلى يوم بداية عام 2024، وهي سنة كبيسة، إلى 2024-12-31T00:00:00Z، وليس 2025-01-01T00:00:00Z، نظرا لأن السنة الكبسة تتكون من 366 يوما بدلا من 365 يوما. وعلاوة على ذلك، يصبح التمييز بين السنوات الكبسة وغير الكبسة واضحا عند إضافة شهر واحد إلى اليوم الأول من شهر فبراير، مما يؤدي إلى نتائج مختلفة في اليوم من الشهر.

الأمثلة

يوضح المثال التالي طرقًا مختلفة لإضافة قيم الوقت.

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، يكون الناتج:

Name نوع القيمة‬
add3YearsOutput السلسلة‬ 4/7/2023 2:53:14 مساءً
subtract9DaysOutput السلسلة‬ 29/3/2020 2:53:14 مساءً
add1HourOutput السلسلة‬ 7/4/2020 03:53:14 مساءً

يوضح المثال التالي كيفية تعيين وقت البدء لجدول Automation.

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)

يحول قيمة عدد صحيح لوقت زمني إلى تاريخ ISO 8601.

مساحة الاسم: sys.

المعلمات

المعلمة‬ المطلوب نوع ‏‏الوصف
epochTime ‏‏نعم‬ العدد الصحيح وقت epoch للتحويل إلى سلسلة التاريخ والوقت.

قيمة الإرجاع

سلسلة التاريخ والوقت ISO 8601.

ملاحظات

تتطلب هذه الدالة إصدار Bicep CLI 0.5.X أو أعلى.

مثال

يوضح المثال التالي قيم الإخراج لدوال وقت الفترة.

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

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

تكون النتيجة:

Name نوع القيمة‬
datetimeValue السلسلة‬ 2023-05-02T15:16:13Z
epochValue Int 1683040573

dateTimeToEpoch

dateTimeToEpoch(dateTime)

يحول سلسلة التاريخ والوقت ISO 8601 إلى قيمة عدد صحيح لوقت epoch.

مساحة الاسم: sys.

المعلمات

المعلمة‬ المطلوب نوع ‏‏الوصف
dateTime ‏‏نعم‬ سلسلة سلسلة التاريخ والوقت للتحويل إلى وقت epoch.

قيمة الإرجاع

عدد صحيح يمثل عدد الثواني من منتصف الليل يوم 1 يناير 1970.

ملاحظات

تتطلب هذه الدالة إصدار Bicep CLI 0.5.X أو أعلى.

الأمثلة

يوضح المثال التالي قيم الإخراج لدوال وقت الفترة.

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

var convertedDatetime = dateTimeFromEpoch(convertedEpoch)

output epochValue int = convertedEpoch
output datetimeValue string = convertedDatetime

تكون النتيجة:

Name نوع القيمة‬
datetimeValue السلسلة‬ 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 لا سلسلة قيمة URI المشفرة المراد تحويلها إلى سلسلة. استخدم إما سلاسل ذات تنسيق قياسي أو سلاسل تنسيق مخصص .

ملاحظات

لا يمكنك استخدام هذه الوظيفة إلّا داخل تعبير للقيمة الافتراضية للمعامل. يؤدي استخدام هذه الوظيفة في أي مكان آخر في ملف Bicep إلى إرجاع خطأ. الوظيفة غير مسموح بها في أجزاء أخرى من ملف Bicep لأنها ترجع قيمة مختلفة في كل مرة يتم استدعاؤها. لن يؤدي توزيع نفس ملف Bicep مع نفس المعلمات إلى الحصول على نفس النتائج بشكل موثوق به.

إذا كنت تستخدم الخيار للتراجع عن الخطأ لتوزيع الناجح السابق، وكان التوزيع السابق يتضمن معلمة تستخدم utcNow، فلن تتم إعادة تقييم المعلمة. بدلاً من ذلك، تتم إعادة استخدام قيمة المعلمة من التوزيع السابق تلقائيًا في توزعالعودة إلى الحالة السابقة.

كن حذرًا عند إعادة توزيع ملف Bicep الذي يعتمد على وظيفة utcNow لقيمة افتراضية. عند إعادة النشر وعدم توفير قيمة للمعامل، تتم إعادة تقييم الوظيفة. إذا كنت تريد تحديث مورد موجود بدلاً من إنشاء مورد جديد، فمرر قيمة المعلمة من التوزيع السابق.

قيمة الإرجاع

القيمة الحالية للتاريخ والوقت بالتوقيت العالمي المتفق عليه.

الأمثلة

يوضح المثال التالي تنسيقات مختلفة لقيمة التاريخ والوقت.

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

يختلف الإخراج من المثال السابق لكل عملية توزيع ولكنه سيكون مشابهًا لـ:

Name نوع القيمة‬
خرج التوقيت العالمي المتفق عليه سلسلة 20190305T175318Z
utcShortOutput سلسلة 05/03/2019
utcCustomOutput سلسلة 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

الخطوات التالية