قيود التعليمة البرمجية لوظيفة المنسق

Durable Functions هو أحد ملحقات Azure Functions التي تسمح لك بإنشاء تطبيقات تشير إلى الحالة. يمكنك استخدام وظيفة منسق لتنسيق عملية تنفيذ الوظائف الدائمة الأخرى داخل تطبيق الوظائف. وظائف المنسق هي وظائف موثوق بها تشير غلى الحالة وطويلة الأمد.

قيود التعليمة البرمجية للمنسق

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

استخدام APIs محددة

يوفر هذا المقطع بعض الإرشادات البسيطة التي تساعد على التأكد من أن التعليمات البرمجية محددة.

يمكن لوظائف المنسق استدعاء أي API في اللغات المستهدفة ذات الصلة. مع ذلك، من المهم أن تستدعي وظيفة المنسق فقط APIs المحددة. API المحددة هي API ترجع نفس القيمة التي يتم إدخالها، بغض النظر عن وقت أو عدد المرات التي يتم استدعاؤها.

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

إشعار

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

التواريخ والأوقات

تعد واجهات برمجة التطبيقات التي تُرجع التاريخ أو الوقت الحالي غير محددة ولا يجب استخدامها مطلقًا في وظائف المنسق. هذا لأن كل إعادة تشغيل لوظيفة منسق ستنتج قيمة مختلفة. يجب عليك بدلاً من ذلك استخدام واجهة برمجة التطبيقات المكافئة لـ Durable Functions للحصول على التاريخ أو الوقت الحالي، والذي يظل ثابتًا عبر عمليات الإعادة.

C#‎

لا تستخدم DateTime.NowوDateTime.UtcNow، أو ما يعادلها من واجهات برمجة التطبيقات للحصول على الوقت الحالي. يجب أيضًا تجنب فئات مثل Stopwatch. بالنسبة لوظائف المنسق قيد المعالجة.NET، استخدم IDurableOrchestrationContext.CurrentUtcDateTime الخاصية للحصول على الوقت الحالي. بالنسبة لوظائف المنسق المعزولة .NET، استخدم TaskOrchestrationContext.CurrentDateTimeUtc الخاصية للحصول على الوقت الحالي.

DateTime startTime = context.CurrentUtcDateTime;
// do some work
TimeSpan totalTime = context.CurrentUtcDateTime.Subtract(startTime);

جافا سكريبت

لا تستخدم واجهات برمجة التطبيقات مثل new Date() أو Date.now() للحصول على التاريخ والوقت الحاليين. بدلاً من ذلك، استخدمDurableOrchestrationContext.currentUtcDateTime.

// create a timer that expires 2 minutes from now
const expiration = moment.utc(context.df.currentUtcDateTime).add(2, "m");
const timeoutTask = context.df.createTimer(expiration.toDate());

Python

لا تستخدم datetime.now() وgmtime()، أو واجهات برمجة تطبيقات مشابهة للحصول على الوقت الحالي. بدلاً من ذلك، استخدمDurableOrchestrationContext.current_utc_datetime.

# create a timer that expires 2 minutes from now
expiration = context.current_utc_datetime + timedelta(seconds=120)
timeout_task = context.create_timer(expiration)

بوويرشيل

لا تستخدم cmdlets مثل Get-Date أو .NET APIs مثل [System.DateTime]::Now للحصول على الوقت الحالي. بدلاً من ذلك، استخدم$Context.CurrentUtcDateTime.

$expiryTime = $Context.Input.ExpiryTime
while ($Context.CurrentUtcDateTime -lt $expiryTime) {
    # do work
}

Java

لا تستخدم واجهات برمجة التطبيقات مثل LocalDateTime.now() أو Instant.now() للحصول على التاريخ والوقت الحاليين. بدلاً من ذلك، استخدمTaskOrchestrationContext.getCurrentInstant().

Instant startTime = ctx.getCurrentInstant();
// do some work
Duration totalTime  = Duration.between(startTime, ctx.getCurrentInstant());

GUIDs وUUIDs

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

C#‎

لا تستخدم واجهات برمجة التطبيقات مثل Guid.NewGuid() لإنشاء معرفات GUID عشوائية. بدلاً من ذلك، استخدم واجهة برمجة تطبيقات عنصر NewGuid() السياق لإنشاء GUID عشوائي آمن لإعادة تشغيل المنسق.

Guid randomGuid = context.NewGuid();

إشعار

GUIDs التي تم إنشاؤها باستخدام واجهات برمجة تطبيقات سياق التزامن هي من النوع 5 UUIDs.

جافا سكريبت

لا تستخدم uuid الوحدة النمطية أو crypto.randomUUID() الدالة لإنشاء UUIDs عشوائية. بدلاً من ذلك، استخدم الطريقة المضمنة في كائن السياق newGuid() لإنشاء GUID عشوائي آمن لإعادة تشغيل المنسق.

const randomGuid = context.df.newGuid();

إشعار

GUIDs التي تم إنشاؤها باستخدام واجهات برمجة تطبيقات سياق التزامن هي من النوع 5 UUIDs.

Python

لا تستخدم uuid الوحدة لإنشاء UUIDs عشوائية. بدلاً من ذلك، استخدم الطريقة المضمنة في كائن السياق new_guid() لإنشاء GUID عشوائي آمن لإعادة تشغيل المنسق.

randomGuid = context.new_guid()

إشعار

GUIDs التي تم إنشاؤها باستخدام واجهات برمجة تطبيقات سياق التزامن هي من النوع 5 UUIDs.

بوويرشيل

لا تستخدم cmdlets مثل New-Guid أو واجهات برمجة تطبيقات .NET مثل [System.Guid]::NewGuid() مباشرة في وظائف المنسق. بدلاً من ذلك، قم بإنشاء GUIDs عشوائية في وظائف النشاط وأعدها إلى وظائف المنسق.

Java

لا تستخدم java.util.UUID.randomUUID() أو أساليب مشابهة لإنشاء UUIDs جديدة مباشرة في وظائف المنسق. بدلاً من ذلك، قم بإنشاء GUIDs عشوائية في وظائف النشاط وأعدها إلى وظائف المنسق.

أعداد عشوائية

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

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

Bindings

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

متغيرات ثابتة

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

إشعار

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

متغيرات البيئة

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

الشبكة وHTTP

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

واجهات برمجة التطبيقات لحظر مؤشر الترابط

يمكن أن يتسبب حظر واجهات برمجة التطبيقات مثل "السكون" في حدوث مشكلات في الأداء والقياس لوظائف المنسق ويجب تجنبه. في خطة Azure Functions Consumption، يمكن أن تتسبب في تكبد رسوم غير لازمة على وقت التشغيل. استخدم بدائل لـ APIs الحظر عندما تكون متوفرة. على سبيل المثال، استخدم المؤقتات الدائمة لإنشاء تأخيرات آمنة لإعادة التشغيل ولا يتم احتسابها في وقت تنفيذ دالة منسق.

APIs غير المتزامنة

يجب ألا تبدأ التعليمات البرمجية للمنظم مطلقًا أي عملية غير متزامنة باستثناء تلك المحددة بواسطة كائن سياق مشغل التزامن. على سبيل المثال، لا يمكنك استخدام Task.Run وTask.Delay وHttpClient.SendAsyncفي .NET أو setTimeout وsetInterval في JavaScript. يجب أن تقوم وظيفة المنسق بجدولة العمل غير المتزامن فقط باستخدام واجهات برمجة تطبيقات Durable SDK، مثل جدولة وظائف النشاط. يجب إجراء أي نوع آخر من استدعاءات غير متزامنة داخل وظائف النشاط.

وظائف JavaScript غير المتزامنة

أعلن دائمًا عن وظائف منسق JavaScript كوظائف منشئ متزامن. يجب ألا تعلن عن وظائف منسق JavaScript لأن async وقت تشغيل Node.js لا يضمن أن الوظائف غير المتزامنة حتمية.

Python Coroutines

يجب ألا تعلن عن وظائف منسق Python على أنها coroutines. بمعنى آخر، لا تعلن أبدًا عن وظائف Python orchestrator مع async الكلمة الأساسية لأن دلالات coroutine لا تتوافق مع نموذج إعادة تشغيل الوظائف الدائمة. يجب أن تعلن دائمًا عن وظائف Python orchestrator كمنشئات، مما يعني أنه يجب أن تتوقع contextاستخدام APIyield بدلاً منawait.

واجهات برمجة تطبيقات مؤشر ترابط .NET

تقوم Durable Task Framework بتشغيل التعليمة البرمجية للمنسق على مؤشر ترابط أحادي ولا يمكن التفاعل مع أي مؤشرات ترابط أخرى. يمكن أن يؤدي تشغيل عمليات الاستمرارية غير المتزامنة على مؤشر ترابط تجمع العمال لتنفيذ التزامن إلى تنفيذ غير محدد أو حالات توقف تام. لهذا السبب، يجب ألا تستخدم وظائف المنظم أبدًا واجهات برمجة تطبيقات الترابط. على سبيل المثال، لا تستخدم ConfigureAwait(continueOnCapturedContext: false) أبدًا في دالة منسق. يضمن هذا تشغيل متابعة المهمة على وظيفة المنسق الأصلية SynchronizationContext.

إشعار

يحاول Durable Task Framework الكشف عن الاستخدام العرضي لمؤشرات الترابط غير المنسقة في وظائف المنسق. في حالة العثور على انتهاك، تطرح NonDeterministicOrchestrationException استثناءً. مع ذلك، لن يحدد سلوك الكشف هذا جميع الانتهاكات، ويجب ألا تعتمد عليه.

تعيين الإصدار

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

المهام الدائمة

إشعار

يصف هذا المقطع تفاصيل التنفيذ الداخلي لـ Durable Task Framework. يمكنك استخدام وظائف دائمة دون معرفة هذه المعلومات. الغرض منه فقط هو مساعدتك على فهم سلوك إعادة التشغيل.

يُشار أحيانا إلى المهام التي يمكن أن تنتظر بأمان في وظائف المنسق بأنها مهام دائمة. تنشئ Durable Task Framework هذه المهام وتديرها. ومن الأمثلة على ذلك المهام التي يتم إرجاعها بواسطة CallActivityAsyncو WaitForExternalEventو CreateTimer في وظائف منسق .NET.

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

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

سيساعدك وصف سلوك وقت التشغيل في هذا المقطع على فهم سبب عدم استخدام وظيفة التنسيق await أو yield في مهمة غير دائمة. يوجد سببان: أولهما أن مؤشر الترابط المرسِل لا يمكنه انتظار انتهاء المهمة وأي رد اتصال من قبل تلك المهمة من المحتمل أن يتلف حالة تتبع وظيفة المنسق. تتوفر بعض عمليات التحقق من وقت التشغيل لتسهيل الكشف عن هذه الانتهاكات.

لمعرفة المزيد حول كيفية تنفيذ Durable Task Framework وظائف المنسق، راجع التعليمات البرمجية المصدر لــ Durable Task على GitHub. تحديداً، راجع TaskOrchestrationExecutor.cs وTaskOrchestrationContext.cs.

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

تعرف على كيفية استدعاء التنسيقات الفرعية

تعرف على كيفية التعامل مع الإصدارات