إضافة وظائف إلى قائمة الانتظار باستخدام Cloud Tasks (الجيل الأول)

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

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

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

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

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

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

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

  1. اكتب دالة قائمة انتظار مهام باستخدام حزمة Firebase SDK لـ Cloud Functions.
  2. اختبِر الدالة عن طريق تشغيلها باستخدام طلب HTTP.
  3. انشر الدالة باستخدام Firebase CLI. عند نشر دالة قائمة انتظار المهام للمرة الأولى، ستنشئ واجهة سطر الأوامر قائمة انتظار مهام في 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 مع الخيارات (الحدّ الأقصى لمعدّل الطلبات وإعادة المحاولة) المحدّدة في رمز المصدر.

إذا واجهتك أخطاء في الأذونات عند نشر الدوال، تأكَّد من أنّ أدوار 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 تحاول استدعاء دوال قائمة انتظار المهام. تأكَّد من أنّ مشروعك يتضمّن عمليات الربط التالية في "إدارة الهوية وإمكانية الوصول":

  • تحتاج الهوية المستخدَمة لوضع المهام في قائمة الانتظار إلى إذن 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.

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