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

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

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

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

تتوافق حزمة Firebase SDK للإصدار 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. انشر الدالة باستخدام واجهة سطر الأوامر (CLI) في 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 أفضل طريقة لاختبار وظائف قائمة انتظار المهام. يمكنك الاطّلاع على مستندات "مجموعة أدوات المحاكاة" للتعرّف على كيفية إعداد تطبيقك لمحاكاة دوال قائمة انتظار المهام.

بالإضافة إلى ذلك، يتم عرض دوال قائمة انتظار المهام كدوال 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

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

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

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

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

In a typical flow, the Admin SDK creates a new task, enqueues it in Cloud Tasks, and sets the configuration for the task:

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 إلى إذن إدارة الهوية وإمكانية الوصول (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 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