إدراج الدوال في قائمة انتظار مع "مهام Cloud"

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

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

للتخفيف من هذه التعقيدات، يمكنك كتابة دالة قائمة انتظار مهام تحدد خيارات المهام الأساسية، مثل scheduleTime وdispatchDeadline، ثم تسلّم الدالة إلى قائمة انتظار في Cloud Tasks. تم تصميم بيئة Cloud Tasks خصيصًا لضمان التحكّم الفعّال في الازدحام وسياسات إعادة المحاولة لهذه الأنواع من العمليات.

تتكامل حزمة تطوير البرامج (SDK) من Firebase للإصدار Cloud Functions for Firebase 3.20.1 والإصدارات الأحدث مع الإصدار Firebase Admin SDK 10.2.0 والإصدارات الأحدث لدعم وظائف قائمة انتظار المهام.

يمكن أن يؤدي استخدام دوال قائمة انتظار المهام مع Firebase إلى فرض رسوم على Cloud Tasks المعالجة. يمكنك الاطّلاع على Cloud Tasks الأسعار لمزيد من المعلومات.

إنشاء دوال قائمة انتظار المهام

لاستخدام دوالّ قائمة انتظار المهام، اتّبِع سير العمل التالي:

1. اكتب دالة قائمة مهام باستخدام حزمة تطوير البرامج (SDK) الخاصة بـ Firebase من أجل Cloud Functions.
2. اختبِر الدالة عن طريق تشغيلها باستخدام طلب HTTP.
3. نفِّذ وظيفتك باستخدام واجهة سطر الأوامر Firebase. عند نشر دالة قائمة انتظار المهام للمرة الأولى، ستنشئ واجهة سطر الأوامر قائمة انتظار مهام في Cloud Tasks باستخدام الخيارات (الحدّ من المعدّل وإعادة المحاولة) المحدّدة في الرمز المصدر.
4. أضِف مهامًا إلى قائمة المهام التي تم إنشاؤها حديثًا، مع تمرير المَعلمات لإعداد جدول زمني للتنفيذ إذا لزم الأمر. يمكنك إجراء ذلك من خلال كتابة الرمز باستخدام Admin SDK ونشره على Cloud Functions for Firebase.

كتابة دوال قائمة انتظار المهام

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

ضبط وظائف قائمة انتظار المهام

تتضمّن وظائف قائمة انتظار المهام مجموعة فعّالة من إعدادات الضبط للتحكّم بدقة في حدود المعدّل وسلوك إعادة المحاولة لقائمة انتظار المهام:

exports.backupApod = functions
    .runWith( {secrets: ["NASA_API_KEY"]})
    .tasks.taskQueue({
      retryConfig: {
        maxAttempts: 5,
        minBackoffSeconds: 60,
      },
      rateLimits: {
        maxConcurrentDispatches: 6,
      },
    }).onDispatch(async (data) => {
index.js

• retryConfig.maxAttempts=5: تتم إعادة محاولة تنفيذ كل مهمة في قائمة انتظار المهام تلقائيًا 5 مرات كحد أقصى. يساعد ذلك في الحدّ من الأخطاء المؤقتة، مثل أخطاء الشبكة أو الانقطاع المؤقت للخدمة الخارجية التابعة.
• ‫retryConfig.minBackoffSeconds=60: تتم إعادة محاولة تنفيذ كل مهمة بعد 60 ثانية على الأقل من كل محاولة. ويوفّر ذلك مساحة كبيرة بين كل محاولة، ما يتيح لنا عدم استنفاد محاولات إعادة الإرسال الخمس بسرعة كبيرة.
• ‫rateLimits.maxConcurrentDispatch=6: يتم إرسال 6 مهام على الأكثر في وقت معيّن. يساعد ذلك في ضمان تدفّق ثابت للطلبات إلى الدالة الأساسية ويساعد في تقليل عدد المثيلات النشطة وعمليات التشغيل على البارد.

اختبار دوال قائمة انتظار المهام

في معظم الحالات، يكون محاكي Cloud Functions هو أفضل طريقة لاختبار وظائف قائمة انتظار المهام. راجِع مستندات Emulator Suite لمعرفة كيفية إعداد تطبيقك لمحاكاة وظائف قائمة انتظار المهام.

بالإضافة إلى ذلك، يتم عرض دوال قائمة انتظار المهام كدوال HTTP بسيطة في Firebase Local Emulator Suite. يمكنك اختبار دالة مهمة محاكية من خلال إرسال طلب HTTP POST مع حمولة بيانات بتنسيق JSON:

 # start the Firebase Emulators
 firebase emulators:start

 # trigger the emulated task queue function
 curl \
  -X POST                                            # An HTTP POST request...
  -H "content-type: application/json" \              # ... with a JSON body
  http://localhost:$PORT/$PROJECT_ID/$REGION/$NAME \ # ... to function url
  -d '{"data": { ... some data .... }}'              # ... with JSON encoded data

نشر دوال قائمة انتظار المهام

يمكنك نشر وظيفة قائمة المهام باستخدام واجهة سطر الأوامر في Firebase:

$ firebase deploy --only functions:backupApod

عند نشر دالة قائمة انتظار المهام للمرة الأولى، تنشئ واجهة سطر الأوامر قائمة انتظار مهام في Cloud Tasks مع خيارات (الحدّ من المعدّل وإعادة المحاولة) محدّدة في الرمز المصدر.

إذا واجهت أخطاء في الأذونات عند نشر الدوال، تأكَّد من منح أدوار إدارة الهوية وإمكانية الوصول (IAM) المناسبة للمستخدم الذي ينفّذ أوامر النشر.

إضافة وظائف قائمة انتظار المهام إلى قائمة الانتظار

يمكن إضافة دوال قائمة انتظار المهام إلى قائمة الانتظار في Cloud Tasks من بيئة خادم موثوقة، مثل Cloud Functions for Firebase، باستخدام Firebase Admin SDK لـ Node.js. إذا كنت جديدًا على Admin SDK، اطّلِع على إضافة Firebase إلى خادم للبدء.

في مسار نموذجي، ينشئ Admin SDK مهمة جديدة، ويضعها في قائمة الانتظار Cloud Tasks، ويضبط إعدادات المهمة:

exports.enqueueBackupTasks = functions.https.onRequest(
async (_request, response) => {
  const queue = getFunctions().taskQueue("backupApod");
  const enqueues = [];
  for (let i = 0; i <= 10; i += 1) {
    // Enqueue each task with i*60 seconds delay. Our task queue function
    // should process ~1 task/min.
    const scheduleDelaySeconds = i * 60 
    enqueues.push(
        queue.enqueue(
          { id: `task-${i}` },
          {
            scheduleDelaySeconds,
            dispatchDeadlineSeconds: 60 * 5 // 5 minutes
          },
        ),
    );
  }
  await Promise.all(enqueues);
  response.sendStatus(200);

});

• scheduleDelaySeconds: يحاول الرمز النموذجي توزيع تنفيذ المهام من خلال ربط تأخير لمدة N دقيقة بالمهمة رقم N. ويعني ذلك تشغيل مهمة واحدة تقريبًا في الدقيقة. يُرجى العِلم أنّه يمكنك أيضًا استخدام scheduleTime إذا كنت تريد أن يؤدي Cloud Tasks إلى تشغيل مهمة في وقت محدّد.
• dispatchDeadlineSeconds: الحد الأقصى للمدة التي Cloud Tasks سيتم الانتظار خلالها حتى تكتمل مهمة. ستعيد Cloud Tasks محاولة تنفيذ المهمة وفقًا لإعدادات إعادة المحاولة في قائمة الانتظار أو إلى أن يحين هذا الموعد النهائي. في المثال، تم ضبط قائمة الانتظار على إعادة محاولة تنفيذ المهمة 5 مرات كحد أقصى، ولكن يتم إلغاء المهمة تلقائيًا إذا استغرقت العملية بأكملها (بما في ذلك محاولات إعادة التنفيذ) أكثر من 5 دقائق.

تحديد المشاكل وحلّها

تفعيل تسجيل Cloud Tasks

تحتوي السجلّات من Cloud Tasks على معلومات تشخيصية مفيدة، مثل حالة الطلب المرتبط بمهمة. يتم إيقاف السجلات من Cloud Tasks تلقائيًا بسبب العدد الكبير من السجلات التي يمكن أن تنشئها في مشروعك. ننصحك بتفعيل سجلّات تصحيح الأخطاء أثناء تطوير وظائف قائمة المهام وتصحيح أخطائها بشكل نشط. اطّلِع على تفعيل التسجيل.

أذونات "إدارة الهوية وإمكانية الوصول"

قد تظهر أخطاء PERMISSION DENIED عند إضافة مهام إلى قائمة الانتظار أو عندما تحاول Cloud Tasks استدعاء دوال قائمة انتظار المهام. تأكَّد من أنّ مشروعك يتضمّن عمليات الربط التالية في إدارة الهوية وإمكانية الوصول (IAM):

• يجب أن يكون لدى الهوية المستخدَمة لإضافة المهام إلى قائمة الانتظار في Cloud Tasks إذن cloudtasks.tasks.create في خدمة "إدارة الهوية وإمكانية الوصول".

  في النموذج، هذا هو حساب الخدمة التلقائي App Engine

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member=serviceAccount:${PROJECT_ID}@appspot.gserviceaccount.com \
  --role=roles/cloudtasks.enqueuer

• يجب أن يكون لدى الهوية المستخدَمة لإضافة المهام إلى قائمة الانتظار في Cloud Tasks إذن باستخدام حساب الخدمة المرتبط بمهمة في Cloud Tasks.

  في النموذج، هذا هو حساب الخدمة التلقائي App Engine.

راجِع مستندات Google Cloud IAM للحصول على تعليمات حول كيفية إضافة حساب الخدمة التلقائي App Engine كمستخدم لحساب الخدمة التلقائي App Engine.

• يجب أن يكون لدى الهوية المستخدَمة لتفعيل وظيفة قائمة انتظار المهام إذن cloudfunctions.functions.invoke.

  في النموذج، هذا هو حساب الخدمة التلقائي App Engine

gcloud functions add-iam-policy-binding $FUNCTION_NAME \
  --region=us-central1 \
  --member=serviceAccount:${PROJECT_ID}@appspot.gserviceaccount.com \
  --role=roles/cloudfunctions.invoker