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


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

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

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

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

يمكن أن يؤدي استخدام دوال قائمة المهام مع 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 CLI:

$ firebase deploy --only functions:backupApod

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

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

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

يمكن إضافة دوال "قائمة انتظار المهام" إلى 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 على معلومات تشخيصية مفيدة، مثل حالة الطلب المرتبط بمهمة. تكون السجلات الواردة من Cloud Tasks غير مفعّلة تلقائيًا بسبب العدد الكبير من السجلات التي يمكن أن تُنشئها في مشروعك. ننصحك بتفعيل سجلّات تصحيح الأخطاء أثناء تطوير وظائف قائمة المهام وتصحيح أخطائها بشكل نشط. اطّلِع على مقالة تفعيل logging.

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

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

  • إنّ الهوية المستخدَمة لإدراج المهام في قائمة انتظار "Cloud Tasks" بحاجة إلى إذن "إدارة الهوية وإمكانية الوصول" (IAM) 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 للحصول على تعليمات حول كيفية إضافة حساب الخدمة التلقائي App Engine بصفته مستخدمًا لحساب الخدمة التلقائي App Engine.

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