مشغل المؤقت Azure Functions

مقالة
04/13/2022
قراءة خلال 13 دقائق

توضح هذه المقالة كيفية العمل مع مشغلات المؤقت في Azure Functions. مشغل المؤقت يتيح لك تشغيل وفقاً لجدولٍ زمني.

هذه معلومات مرجعية لمطوري Azure Functions. إذا كنت مستخدما جديدا لوظائف Azure، فابدأ بالموارد التالية:

Azure Functions developer reference.

قم بإنشاء وظيفتك الأولى.
C # مراجع المطور:

للحصول على معلومات عن كيفية تشغيل دالة يُشغِّلها المؤقت يدوياً، راجع تشغيل دالة لا يُشغِّلها HTTP يدوياً.

يتم توفير الدعم لهذا الربط تلقائيا في جميع بيئات التطوير. ليس عليك تثبيت الحزمة يدويا أو تسجيل الملحق.

توجد التعليمات البرمجية المصدر لحزمة ملحق المؤقت في مستودع GitHub azure-webjobs-sdk-extensions.

مثال

يوضح هذا المثال دالة C# تنفذ في كل مرة يكون فيها للدقائق قيمة قابلة للقسمة على خمسة. على سبيل المثال، عندما تبدأ الدالة في الساعة 18:55:00، يكون التنفيذ التالي في الساعة 19:00:00. TimerInfo يتم تمرير كائن إلى الدالة.

يمكن إنشاء الدالة C # باستخدام أحد أوضاع C # التالية:

مكتبة الفئة أثناء العملية: الدالة C# المترجمة التي يتم تشغيلها في نفس العملية مثل وقت تشغيل الوظائف.
مكتبة فئة العملية المعزولة: الدالة C # المترجمة التي يتم تشغيلها في عملية معزولة عن وقت التشغيل. مطلوب عملية معزولة لدعم وظائف C # التي تعمل على .NET 5.0.
البرنامج النصي C#: يستخدم بشكل أساسي عند إنشاء وظائف C# في مدخل Azure.

[FunctionName("TimerTriggerCSharp")]
public static void Run([TimerTrigger("0 */5 * * * *")]TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}");
}

[Function("TimerFunction")]
public static void Run([TimerTrigger("0 */5 * * * *")] TimerInfo timerInfo,
    FunctionContext context)
{
    var logger = context.GetLogger("TimerFunction");
    logger.LogInformation($"Function Ran. Next timer schedule = {timerInfo.ScheduleStatus.Next}");
}

يظهر المثال التالي ربط مشغل المؤقت في ملف function.json و دالة البرنامج النصي C#‎ التي تستخدم الربط. تكتب الدالة سجلاً يشير إلى ما إذا كان استدعاء هذه الدالة ناتجاً عن خطأ عند حدوث الجدولة. يُمرر الكائن TimerInfo إلى الدالة.

إليك بيانات الربط في ملف function.json:

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

إليك رمز البرنامج النصي C#‎:

public static void Run(TimerInfo myTimer, ILogger log)
{
    if (myTimer.IsPastDue)
    {
        log.LogInformation("Timer is running late!");
    }
    log.LogInformation($"C# Timer trigger function executed at: {DateTime.Now}" );  
}

تُشغَّل الدالة المثال التالي وتُنفَّذ كل خمس دقائق. التعليق التوضيحي على الدالة @TimerTrigger يُعرِّف الجدول باستخدام نفس تنسيق السلسلة باعتبارها تعبيرات CRON.

@FunctionName("keepAlive")
public void keepAlive(
  @TimerTrigger(name = "keepAliveTrigger", schedule = "0 */5 * * * *") String timerInfo,
      ExecutionContext context
 ) {
     // timeInfo is a JSON string, you can deserialize it to an object using your favorite JSON library
     context.getLogger().info("Timer is triggered: " + timerInfo);
}

يوضح المثال التالي ربط مشغل مؤقت في ملف function.json ورمز الدالة الذي يستخدم الربط، حيث يتم تمرير مثيل يمثل المؤقت إلى الدالة. تكتب الدالة سجلاً يشير إلى ما إذا كان استدعاء هذه الدالة ناتجاً عن خطأ عند حدوث الجدولة.

إليك بيانات الربط في ملف function.json:

{
    "schedule": "0 */5 * * * *",
    "name": "myTimer",
    "type": "timerTrigger",
    "direction": "in"
}

هنا تعليمة برمجية JavaScript:

module.exports = async function (context, myTimer) {
    var timeStamp = new Date().toISOString();

    if (myTimer.isPastDue)
    {
        context.log('Node is running late!');
    }
    context.log('Node timer trigger function ran!', timeStamp);   
};

فيما يلي رمز الدالة المؤقت في ملف run.ps1:

# Input bindings are passed in via param block.
param($myTimer)

# Get the current universal time in the default string format.
$currentUTCtime = (Get-Date).ToUniversalTime()

# The 'IsPastDue' property is 'true' when the current function invocation is later than scheduled.
if ($myTimer.IsPastDue) {
    Write-Host "PowerShell timer is running late!"
}

# Write an information log with the current time.
Write-Host "PowerShell timer trigger function ran! TIME: $currentUTCtime"

إليك رمز Python ، حيث يكون الكائن الذي تم تمريره إلى الدالة من نوع الكائن azure.functions.TimerRequest.

import datetime
import logging

import azure.functions as func


def main(mytimer: func.TimerRequest) -> None:
    utc_timestamp = datetime.datetime.utcnow().replace(
        tzinfo=datetime.timezone.utc).isoformat()

    if mytimer.past_due:
        logging.info('The timer is past due!')

    logging.info('Python timer trigger function ran at %s', utc_timestamp)

السمات

تستخدم كل من مكتبات C# العملية قيد المعالجة والعملية المعزولة السمة TimerTriggerAttribute لتحديد الدالة.

يستخدم البرنامج النصي C # بدلا من ذلك ملف تكوين function.json.

خاصية السمة	الوصف
جدولة	تعبير CRON أو قيمة TimeSpan. يمكن استخدام `TimeSpan` فقط لتطبيق الوظائف الذي يعمل على خطة خدمة التطبيقات. يمكنك وضع تعبير الجدول الزمني في إعداد تطبيق وتعيين هذه الخاصية إلى اسم إعداد التطبيق ملفوفا في % علامات، ك `%ScheduleAppSetting%`.
RunOnStartup	إذا `true`، تُستدعى الدالة عند بدء تشغيل وقت التشغيل. على سبيل المثال، يبدأ وقت التشغيل عندما ينشط تطبيق الوظائف بعد أن يصبح خاملاً بسبب عدم النشاط. عند إعادة تشغيل تطبيق الوظيفة بسبب تغييرات الوظيفة، وعندما يتم توسيع نطاق تطبيق الوظيفة. استخدمه بحذر. نادرا ما يجب تعيين RunOnStartup ، `true`خاصة في الإنتاج.
UseMonitor	تعيين إلى `true` أو `false` للإشارة إلى ما إذا كان يجب مراقبة الجدول. تستمر مراقبة الجدول في تكرار حدوث الجدول للمساعدة على ضمان الحفاظ على الجدول الزمني بصورةٍ صحيحةٍ حتى عند إعادة تشغيل مثيلات تطبيق الوظائف. في حالة عدم التعيين صراحةً، فسيكون الإعداد الافتراضي هو `true` للجداول التي لها فاصل زمني للتكرار أكبر من أو يساوي دقيقةً واحدةً. بالنسبة للجداول التي تُشغَّل أكثر من مرة في الدقيقة، يكون الإعداد الافتراضي هو `false`.

خاصية السمة	الوصف
جدولة	تعبير CRON أو قيمة TimeSpan. يمكن استخدام `TimeSpan` فقط لتطبيق الوظائف الذي يعمل على خطة خدمة التطبيقات. يمكنك وضع تعبير الجدول الزمني في إعداد تطبيق وتعيين هذه الخاصية إلى اسم إعداد التطبيق ملفوفا في % علامات، ك `%ScheduleAppSetting%`.
RunOnStartup	إذا `true`، تُستدعى الدالة عند بدء تشغيل وقت التشغيل. على سبيل المثال، يبدأ وقت التشغيل عندما ينشط تطبيق الوظائف بعد أن يصبح خاملاً بسبب عدم النشاط. عند إعادة تشغيل تطبيق الوظيفة بسبب تغييرات الوظيفة، وعندما يتم توسيع نطاق تطبيق الوظيفة. استخدمه بحذر. نادرا ما يجب تعيين RunOnStartup ، `true`خاصة في الإنتاج.
UseMonitor	تعيين إلى `true` أو `false` للإشارة إلى ما إذا كان يجب مراقبة الجدول. تستمر مراقبة الجدول في تكرار حدوث الجدول للمساعدة على ضمان الحفاظ على الجدول الزمني بصورةٍ صحيحةٍ حتى عند إعادة تشغيل مثيلات تطبيق الوظائف. في حالة عدم التعيين صراحةً، فسيكون الإعداد الافتراضي هو `true` للجداول التي لها فاصل زمني للتكرار أكبر من أو يساوي دقيقةً واحدةً. بالنسبة للجداول التي تُشغَّل أكثر من مرة في الدقيقة، يكون الإعداد الافتراضي هو `false`.

يستخدم البرنامج النصي C# ملف function.json للتكوين بدلا من السمات.

يشرح الجدول التالي خصائص تكوين الربط للبرنامج النصي C# الذي قمت بتعيينه في الملف function.json.

خاصية function.json	الوصف
النوع	يجب تعيين إلى "timerTrigger". تُعيَّن هذه الخاصية تلقائياً عندما تُنشئ المشغل في مدخل Azure.
⁧⁩direction⁧⁩	يجب تعيين إلى "في". تُعيَّن هذه الخاصية تلقائياً عندما تُنشئ المشغل في مدخل Azure.
⁧⁩الاسم⁧⁩	اسم المتغير الذي يمثل كائن المؤقت في التعليمات البرمجية للدالة.
جدول	تعبير CRON أو قيمة TimeSpan. يمكن استخدام `TimeSpan` فقط لتطبيق الوظائف الذي يعمل على خطة خدمة التطبيقات. يمكنك وضع تعبير الجدولة في أحد إعدادات التطبيق وتعيين هذه الخاصية إلى اسم إعداد التطبيق المُتضمَّن في علامات % ، كما في هذا المثال: "٪ScheduleAppSetting٪".
runOnStartup	إذا `true`، تُستدعى الدالة عند بدء تشغيل وقت التشغيل. على سبيل المثال، يبدأ وقت التشغيل عندما ينشط تطبيق الوظائف بعد أن يصبح خاملاً بسبب عدم النشاط. عند إعادة تشغيل تطبيق الوظيفة بسبب تغييرات الوظيفة، وعندما يتم توسيع نطاق تطبيق الوظيفة. استخدمه بحذر. نادرا ما يجب تعيين runOnStartup على `true`، خاصة في الإنتاج.
useMonitor	تعيين إلى `true` أو `false` للإشارة إلى ما إذا كان يجب مراقبة الجدول. تستمر مراقبة الجدول في تكرار حدوث الجدول للمساعدة على ضمان الحفاظ على الجدول الزمني بصورةٍ صحيحةٍ حتى عند إعادة تشغيل مثيلات تطبيق الوظائف. في حالة عدم التعيين صراحةً، فسيكون الإعداد الافتراضي هو `true` للجداول التي لها فاصل زمني للتكرار أكبر من أو يساوي دقيقةً واحدةً. بالنسبة للجداول التي تُشغَّل أكثر من مرة في الدقيقة، يكون الإعداد الافتراضي هو `false`.

تعليقات توضيحية

@TimerTrigger يعرف التعليق التوضيحي على الدالة schedule استخدام نفس تنسيق السلسلة مثل تعبيرات CRON. يدعم التعليق التوضيحي الإعدادات التالية:

التكوين

يشرح الجدول الآتي خصائص تكوين ربط البيانات التي عليك تعيينها في ملف function.json.

خاصية function.json	الوصف
النوع	يجب تعيين إلى "timerTrigger". تُعيَّن هذه الخاصية تلقائياً عندما تُنشئ المشغل في مدخل Azure.
⁧⁩direction⁧⁩	يجب تعيين إلى "في". تُعيَّن هذه الخاصية تلقائياً عندما تُنشئ المشغل في مدخل Azure.
⁧⁩الاسم⁧⁩	اسم المتغير الذي يمثل كائن المؤقت في التعليمات البرمجية للدالة.
جدول	تعبير CRON أو قيمة TimeSpan. يمكن استخدام `TimeSpan` فقط لتطبيق الوظائف الذي يعمل على خطة خدمة التطبيقات. يمكنك وضع تعبير الجدولة في أحد إعدادات التطبيق وتعيين هذه الخاصية إلى اسم إعداد التطبيق المُتضمَّن في علامات % ، كما في هذا المثال: "٪ScheduleAppSetting٪".
runOnStartup	إذا `true`، تُستدعى الدالة عند بدء تشغيل وقت التشغيل. على سبيل المثال، يبدأ وقت التشغيل عندما ينشط تطبيق الوظائف بعد أن يصبح خاملاً بسبب عدم النشاط. عند إعادة تشغيل تطبيق الوظيفة بسبب تغييرات الوظيفة، وعندما يتم توسيع نطاق تطبيق الوظيفة. استخدمه بحذر. نادرا ما يجب تعيين runOnStartup على `true`، خاصة في الإنتاج.
useMonitor	تعيين إلى `true` أو `false` للإشارة إلى ما إذا كان يجب مراقبة الجدول. تستمر مراقبة الجدول في تكرار حدوث الجدول للمساعدة على ضمان الحفاظ على الجدول الزمني بصورةٍ صحيحةٍ حتى عند إعادة تشغيل مثيلات تطبيق الوظائف. في حالة عدم التعيين صراحةً، فسيكون الإعداد الافتراضي هو `true` للجداول التي لها فاصل زمني للتكرار أكبر من أو يساوي دقيقةً واحدةً. بالنسبة للجداول التي تُشغَّل أكثر من مرة في الدقيقة، يكون الإعداد الافتراضي هو `false`.

عند التطوير محليا، أضف إعدادات التطبيق في الملف local.settings.json في Values المجموعة.

تنبيه

لا تقم بتعيين runOnStartup إلى true قيد الإنتاج. يؤدي استخدام هذا الإعداد إلى تنفيذ التعليمات البرمجية في أوقات غير متوقعة للغاية. في إعدادات إنتاج معينة، يمكن أن تؤدي عمليات التنفيذ الإضافية هذه إلى تكاليف أعلى بكثير للتطبيقات المستضافة في خطة الاستهلاك. على سبيل المثال، مع تمكين runOnStartup يُستدعى المشغل كلما وُسِّع تطبيق الوظائف خاصتك. تأكد من فهمك الكامل لسلوك التشغيل لدوالك قبل تمكين runOnStartup أثناء التشغيل.

راجع قسم المثال للحصول على أمثلة كاملة.

الاستخدام

عند استدعاء دالة مشغل مؤقت، يُمرر كائن مؤقت إلى الدالة. JSON التالي هو مثال على تمثيل كائن المؤقت.

{
    "Schedule":{
        "AdjustForDST": true
    },
    "ScheduleStatus": {
        "Last":"2016-10-04T10:15:00+00:00",
        "LastUpdated":"2016-10-04T10:16:00+00:00",
        "Next":"2016-10-04T10:20:00+00:00"
    },
    "IsPastDue":false
}

تكون الخاصية isPastDue هي true عندما يكون استدعاء الدالة الحالي متأخرًا عن الجدول الزمني. على سبيل المثال، قد يؤدي إعادة تشغيل تطبيق الوظائف إلى حدوث خطأ عند الاستدعاء.

تعبيرات NCRONTAB

تستخدم Azure Functions مكتبة NCronTab لتفسير تعبيرات NCRONTAB. تعبير NCRONTAB مشابه لتعبير CRON فيما عدا أنه يتضمن حقلاً سادسًا إضافيًا في البداية لاستخدامه من أجل دقة الوقت بالثواني:

{second} {minute} {hour} {day} {month} {day-of-week}

يمكن أن يحتوي كل حقل على أحد أنواع القيم التالية:

النوع	مثال	عندما أطلقت
قيمة محددة	`0 5 * * * *`	مرة كل ساعة من اليوم في الدقيقة الخامسة (5) من كل ساعة
كل القيم (`*`)	`0 * 5 * * *`	في كل دقيقة في الساعة، بدءًا من الساعة 5
نطاق (عامل تشغيل`-` )	`5-7 * * * * *`	ثلاث مرات في الدقيقة - في الثواني من 5 إلى 7 خلال كل دقيقة من كل ساعة من كل يوم
مجموعة من القيم (عامل تشغيل`,` )	`5,8,10 * * * * *`	ثلاث مرات في الدقيقة - عند الثواني 5 و8 و10 خلال كل دقيقة من كل ساعة من كل يوم
قيمة الفاصل الزمني (عامل التشغيل`/` )	`0 /5 * * *`	12 مرة في الساعة - في الثانية 0 من كل دقيقة خامسة من كل ساعة من كل يوم

لتحديد الأشهر أو الأيام، يمكنك استخدام القيم الرقمية أو الأسماء أو اختصارات الأسماء:

بالنسبة للأيام ، تكون القيم الرقمية من 0 إلى 6 حيث يبدأ 0 بيوم الأحد.
الأسماء باللغة الإنجليزية. على سبيل المثال: Monday، January.
الأسماء غير حساسة لحالة الأحرف.
يمكن اختصار الأسماء. ثلاثة أحرف هي طول الاختصار الموصى به. على سبيل المثال: Mon، Jan.

أمثلة NCRONTAB

فيما يلي بعض الأمثلة على تعبيرات NCRONTAB التي يمكنك استخدامها لتشغيل المؤقت في Azure Functions.

مثال	عندما أطلقت
`0 /5 * * *`	مرة كل خمس دقائق
`0 0 * * * *`	مرة واحدة في الجزء العلوي من كل ساعة
`0 0 /2 * *`	مرة كل ساعتين
`0 0 9-17 * * *`	مرة كل ساعة من 9 صباحاً حتي 5 مساءً
`0 30 9 * * *`	الساعة 9:30 صباحًا كل يوم
`0 30 9 * * 1-5`	الساعة 9:30 صباحًا في كل يوم من أيام الأسبوع
`0 30 9 * Jan Mon`	الساعة 9:30 صباحًا كل يوم اثنين من شهر يناير

ملاحظة

يدعم تعبير NCRONTAB تنسيق كلٍ من الحقل الخامس و الحقل السادس. موضع الحقل السادس هو قيمة للثواني تُوضَع في بداية التعبير.

المناطق الزمنية NCRONTAB

تشير الأرقام في تعبير CRON إلى وقت وتاريخ، وليس إلى فترة زمنية. على سبيل المثال، يشير 5 في الحقل hour إلى 5:00 صباحاً، وليس كل 5 ساعات.

المنطقة الزمنية الافتراضية المستخدمة مع تعبيرات CRON هي التوقيت العالمي المنسق (UTC). لجعل تعبير CRON الخاص بك يستند إلى منطقة زمنية أخرى، قم بإنشاء إعداد تطبيق لتطبيق الوظيفة الخاص بك باسم WEBSITE_TIME_ZONE.

تعتمد قيمة هذا الإعداد على نظام التشغيل والخطة التي يعمل عليها تطبيق الوظائف.

نظام التشغيل	الخطة	القيمة
Windows	الكل	اضبط القيمة على اسم المنطقة الزمنية المطلوبة كما هو موضح في السطر الثاني من كل زوج يعطيه الأمر Windows`tzutil.exe /L`
Linux	متميزة المخصصة.	قم بتعيين القيمة إلى اسم المنطقة الزمنية المطلوبة كما هو موضح في قاعدة بيانات tz.

ملاحظة

WEBSITE_TIME_ZONE غير مدعوم حاليا في خطة استهلاك Linux.

على سبيل المثال، التوقيت الشرقي في الولايات المتحدة (ممثلا ب Eastern Standard Time (Windows) أو America/New_York (Linux)) يستخدم حاليا التوقيت العالمي المنسق-05:00 خلال التوقيت القياسي والتوقيت العالمي المنسق-04:00 خلال التوقيت الصيفي. للحصول على مشغل مؤقت يطلق النار في الساعة 10:00 صباحا بالتوقيت الشرقي كل يوم، قم بإنشاء إعداد تطبيق لتطبيق الدالة الخاص بك باسم WEBSITE_TIME_ZONE، وقم بتعيين القيمة إلى Eastern Standard Time (Windows) أو America/New_York (Linux)، ثم استخدم تعبير NCRONTAB التالي:

"0 0 10 * * *"

عند استخدام WEBSITE_TIME_ZONE الوقت يتم ضبط التغييرات الزمنية في المنطقة الزمنية المحددة، بما في ذلك التوقيت الصيفي والتغييرات في التوقيت القياسي.

TimeSpan

يمكن استخدام TimeSpan فقط لتطبيق الوظائف الذي يعمل على خطة خدمة التطبيقات.

بخلاف تعبير CRON، تحدد القيمة TimeSpan الفاصل الزمني بين استدعاء كل دالة. عندما تكتمل إحدى الدوال بعد تشغيلها لفترةٍ أطول من الفاصل الزمني المحدد، يستدعي المؤقت الدالة على الفور مرةً أخرى.

مُعبراً عنه باعتباره سلسلة، يكون التنسيق TimeSpan هو hh:mm:ss عندما يكون hh أقل من 24. عندما يكون الرقمان الأولان 24 أو أكبر، يكون التنسيق dd:hh:mm. نضرب فيما يلي بعض الأمثلة:

مثال	وقت التشغيل
"01:00:00"	كل ساعة
"00:01:00"	كل دقيقة
"25:00:00"	كل 25 يوم
"1.00:00:00"	كل يوم

توسعة

في حالة توسعة تطبيق الوظائف إلى مثيلات متعددة، فسيُشغَّل مثيلٌ واحدٌ فقط لدالة تشغيل مؤقت عبر جميع المثيلات. لن يجري تشغيله مرةً أخرى إذا كان هناك استدعاء معلق لا يزال قيد التشغيل.

إذا كنت تشارك حسابات التخزين عبر تطبيقات الوظائف التي لم تُوزَّع في خدمة التطبيق، فقد تحتاج إلى تعيين معرف مضيف صراحةً لكل تطبيق.

إصدار الدوال	الإعداد
2.x (وإصدار أحدث)	متغير البيئة `AzureFunctionsWebHost__hostid`
1.x	`id` في host.json

يمكنك حذف قيمة التعريف أو تعيين تكوين تعريف كل تطبيق من تطبيقات الوظائف يدوياً إلى قيمة مختلفة.

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

إعادة محاولة السلوك

على عكس مشغل قائمة الانتظار، لا يعيد مُشغِّل المؤقت المحاولة بعد فشل إحدى الدوال. عندما تفشل دالة، لا تُستدعى مرةً أخرى حتى المرة التالية في الجدول الزمني.

استدعاء مشغل مؤقت يدوياً

يوفر مشغل المؤقت لـ Azure Functions خطاف ويب HTTP يمكن استدعاؤه لتشغيل الدالة يدويًا. يمكن أن يكون هذا مفيدًا للغاية في السيناريوهات التالية.

اختبار التكامل
تُبدَّل الفتحات باعتبارها جزءًا من اختبار التحقق من البناء أو نشاط الإحماء
التوزيع الأولي لدالةٍ ما لملء جدول ذاكرة التخزين المؤقت أو البحث في قاعدة بيانات على الفور

يُرجى الرجوع إلى تشغيل دالة لا يُشغِّلها HTTP يدوياً للحصول على تفاصيل عن كيفية استدعاء دالة يُشغِّلها المؤقت يدوياً.

استكشاف الأخطاء وإصلاحها

للحصول على معلومات عما يجب فعله عندما لا يعمل مُشغِّل المؤقت كما هو متوقع، راجع التحقيق في المشكلات والإبلاغ عنها مع عدم تنشيط الدوال المُشغَّلة بالمؤقت.

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

الانتقال إلى تشغيل سريع يستخدم مشغل مؤقت