إدارة العمليات طويلة المدى

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

تعرض Google Drive API عملية طويلة الأمد في كل مرة تستدعي فيها الطريقة download في المورد files لتنزيل محتوى ملف، سواء من خلال Drive API أو مكتبات البرامج.

يعرض الإجراء مورد operations للعميل. يمكنك استخدام مورد operations لاسترداد حالة طريقة واجهة برمجة التطبيقات بشكل غير متزامن من خلال التحقّق من العملية باستخدام طريقة get. تلتزم العمليات الطويلة الأمد في Drive API بنمط تصميم العمليات الطويلة الأمد في Google Cloud.

لمزيد من المعلومات، يُرجى الاطّلاع على العمليات الطويلة الأمد.

نظرة عامة على العملية

يوضّح المخطّط التالي الخطوات العامة لطريقة عمل الدالة file.download.

1. استدعاء files.download: عندما يستدعي تطبيقك طريقة download، يُطلق طلب تنزيل الملف من Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على تنزيل الملفات.

2. طلب الأذونات: يرسل الطلب بيانات اعتماد المصادقة إلى Drive API. إذا كان تطبيقك يتطلّب استدعاء Drive API باستخدام مصادقة مستخدم لم يتم منحها بعد، سيطلب التطبيق من المستخدم تسجيل الدخول. يطلب تطبيقك أيضًا إذن الوصول باستخدام نطاقات تحدّدها عند إعداد المصادقة.

3. بدء التنزيل: يتم إرسال طلب إلى Drive API لبدء تنزيل الملف. يمكن تقديم الطلب إلى Google Vids أو بعض محتوى Google Workspace الآخر.

4. بدء عملية طويلة الأمد: تبدأ عملية طويلة الأمد وتدير عملية التنزيل.

5. إرجاع عملية معلّقة: تعرض واجهة برمجة التطبيقات Drive API عملية معلّقة تتضمّن معلومات عن المستخدم الذي يرسل الطلب وعدة حقول للبيانات الوصفية للملف.

6. حالة "في انتظار المراجعة" الأولية: يتلقّى تطبيقك العملية المعلّقة مع حالة "في انتظار المراجعة" الأولية done=null. يشير ذلك إلى أنّ الملف غير جاهز للتنزيل بعد وأنّ حالة العملية معلّقة.

7. طلب operations.get والتحقّق من النتيجة: يطلب تطبيقك get على فترات زمنية منتظمة تنصح بها الخدمة للتحقّق من نتيجة العملية والاطّلاع على أحدث حالة لعملية طويلة. إذا تم عرض الحالة المعلقة done=false، يجب أن يواصل تطبيقك طلب البيانات إلى أن تعرض العملية الحالة المكتملة (done=true). بالنسبة إلى الملفات الكبيرة، من المتوقّع أن يتم طلب البيانات عدة مرات. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على تفاصيل حول عملية تستغرق وقتًا طويلاً.

8. التحقّق من حالة "في انتظار المراجعة": إذا تم عرض حالة done=true "في انتظار المراجعة" من عملية LRO، يشير ذلك إلى أنّ الملف جاهز للتنزيل وأنّ حالة العملية مكتملة.

9. إرجاع العملية المكتملة مع معرّف الموارد المنتظم (URI) للتنزيل: بعد اكتمال العملية الطويلة الأمد، تعرض Drive API معرّف الموارد المنتظم (URI) للتنزيل، ويصبح الملف متاحًا للمستخدم.

تنزيل الملفات

لتنزيل المحتوى ضمن عملية طويلة الأمد، استخدِم طريقة download في المورد files. تتلقّى الطريقة مَعلمات file_id وmime_type وrevision_id:

• الحقل مطلوب. تمثّل مَعلمة المسار file_id رقم تعريف الملف المطلوب تنزيله.

• اختياريّ. تشير مَعلمة طلب البحث mime_type إلى نوع MIME الذي يجب أن تستخدمه الطريقة. لا تتوفّر هذه الميزة إلا عند تنزيل محتوى وسائط غير ثنائي كبير (مثل مستندات Google Workspace). للحصول على قائمة كاملة بأنواع MIME المتوافقة، يُرجى الاطّلاع على تصدير أنواع MIME لمستندات Google Workspace.

  إذا لم يتم ضبط نوع MIME، سيتم تنزيل مستند Google Workspace بنوع MIME تلقائي. لمزيد من المعلومات، يُرجى الاطّلاع على أنواع MIME التلقائية.

• اختياريّ. مَعلمة طلب البحث revision_id هي رقم تعريف النسخة السابقة من الملف التي سيتم تنزيلها. لا تتوفّر هذه الميزة إلا عند تنزيل ملفات blob و"مستندات Google" و"جداول بيانات Google". تعرض رمز الخطأ INVALID_ARGUMENT عند تنزيل نسخة معدَّلة معيّنة من ملفات غير متوافقة.

طريقة download هي الطريقة الوحيدة لتنزيل ملفات Vids بتنسيق MP4، وهي عادةً الأنسب لتنزيل معظم ملفات الفيديو. إذا حاولت تصدير ملفات Google Vids، ستتلقّى رسالة الخطأ fileNotExportable.

تؤدي الروابط التي تم إنشاؤها لتنزيل ملفات "مستندات Google" أو "جداول بيانات Google" في البداية إلى إعادة توجيه. انقر على الرابط الجديد لتنزيل الملف.

يجب أن يستخدم كل من طلب طريقة download الذي يبدأ عملية LRO وطلب جلب عنوان URI النهائي للتنزيل مفاتيح الموارد. لمزيد من المعلومات، يُرجى الاطّلاع على الوصول إلى ملفات Drive التي تمت مشاركتها باستخدام رابط من خلال مفاتيح الموارد.

يظهر هنا بروتوكول الطلب.

POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/download

استبدِل FILE_ID بمعرّف fileId الخاص بالملف الذي تريد تنزيله.

أنواع MIME التلقائية

إذا لم يتم ضبط نوع MIME عند تنزيل محتوى غير كائن ثنائي كبير الحجم، سيتم تعيين أنواع MIME التلقائية التالية:

تنزيل الردّ

عند استدعاء طريقة download، يتألف نص الاستجابة من مورد يمثّل عملية طويلة الأمد. تعرض الطريقة عادةً رابطًا لتنزيل محتوى الملف.

{
  "done": true,
  "metadata": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
    "resourceKey": "RESOURCE_KEY"
  },
  "name": "NAME",
  "response": {
    "@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
    "downloadUri": "DOWNLOAD_URI",
    "partialDownloadAllowed": false
  }
}

يتضمّن هذا الناتج القيم التالية:

• RESOURCE_KEY: يساعد مفتاح المورد في حماية ملفك من الوصول غير المقصود. لمزيد من المعلومات، يُرجى الاطّلاع على الوصول إلى ملفات Drive التي تمت مشاركتها باستخدام رابط من خلال مفاتيح الموارد.

• NAME: الاسم الذي يحدّده الخادم

• ‫DOWNLOAD_URI: معرّف الموارد المنتظم (URI) النهائي لتنزيل الملف.

يُرجى العِلم أنّ الحقل partialDownloadAllowed يشير إلى ما إذا كان مسموحًا بإجراء تنزيل جزئي، ويكون true عند تنزيل محتوى ملف كائن ثنائي كبير.

الحصول على تفاصيل حول عملية طويلة الأمد

العمليات الطويلة الأمد هي استدعاءات طرق قد تستغرق وقتًا طويلاً لإكمالها. عادةً، يتم عرض عمليات التنزيل التي تم إنشاؤها حديثًا في البداية في حالة "في انتظار المراجعة" (done=null)، خاصةً بالنسبة إلى ملفات Vids.

يمكنك استخدام مورد operations الذي توفّره واجهة برمجة التطبيقات Drive API للتحقّق من حالة عملية LRO من خلال تضمين الاسم الفريد الذي يحدّده الخادم.

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

التحقّق من حالة عملية تستغرق وقتًا طويلاً

للاستقصاء عن حالة عملية LRO متاحة، عليك استدعاء الطريقة get بشكل متكرّر إلى أن تنتهي العملية. استخدِم رقودًا أسيًا ثنائيًا بين كل طلبات الاقتراع، مثل 10 ثوانٍ.

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

يجب استخدام مفاتيح الموارد في أي طلبات موجّهة إلى get. لمزيد من المعلومات، يُرجى الاطّلاع على الوصول إلى ملفات Drive التي تمت مشاركتها باستخدام رابط من خلال مفاتيح الموارد.

تظهر هنا بروتوكولات الطلبات.

operations.get(name='NAME');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

يُرجى العِلم أنّه لا يتم عرض name إلا في الرد على طلب download. لا تتوفّر طريقة أخرى لاستردادها لأنّ واجهة Drive API لا تتيح استخدام طريقة list. في حال فقدان قيمة name، عليك إنشاء استجابة جديدة من خلال إعادة طلب طريقة download.

تتألف الاستجابة من طلب get من مورد يمثّل عملية تستغرق وقتًا طويلاً. لمزيد من المعلومات، يُرجى الاطّلاع على تنزيل الرد.

عندما تتضمّن الاستجابة حالة مكتملة (done=true)، تكون العملية الطويلة قد انتهت.

تنزيل نسخة معدَّلة

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

لتنزيل محتوى المراجعة لملفات blob، يجب استدعاء طريقة get في المرجع revisions مع معرّف الملف المطلوب تنزيله ومعرّف المراجعة ومعلَمة عنوان URL alt=media. تُعلم مَعلمة عنوان URL alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كتنسيق استجابة بديل.

لا يمكن تنزيل مراجعات "مستندات Google" و"جداول بيانات Google" و"العروض التقديمية من Google" وVids باستخدام طريقة get مع عنوان URL alt=media. بخلاف ذلك، سيتم إنشاء الخطأ fileNotDownloadable.

مَعلمة عنوان URL alt=media هي مَعلمة نظام متاحة في جميع واجهات Google REST API. إذا كنت تستخدم مكتبة برامج للوصول إلى Drive API، لن تحتاج إلى ضبط هذه المَعلمة بشكل صريح.

يظهر هنا بروتوكول الطلب.

GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media

غيِّر القيم في السلسلة على الشكل التالي:

• FILE_ID: fileId للملف الذي تريد تنزيله
• REVISION_ID: revisionId هو رقم تعريف النسخة التي تريد تنزيلها.

تزيد مراجعات "مستندات Google" و"رسومات Google" و"العروض التقديمية من Google" أرقام المراجعات تلقائيًا. ومع ذلك، قد تتضمّن سلسلة الأرقام فجوات إذا تم حذف المراجعات، لذا لا يجب الاعتماد على الأرقام المتسلسلة لاسترداد المراجعات.

تحديد المشاكل في عمليات الإطلاق الإقليمية المحدودة وحلّها

عندما يتعذّر تنفيذ عملية طويلة الأمد، يتضمّن الرد رمز خطأ أساسيًا في Google Cloud.

يعرض الجدول التالي كل رمز خطأ ورمز حالة HTTP المرتبط به ووصفًا واقتراحًا حول كيفية التعامل مع رمز الخطأ. في حال حدوث العديد من الأخطاء، ننصحك بإعادة محاولة الطلب باستخدام التراجع الدليلي.

يمكنك الاطّلاع على مزيد من المعلومات حول نموذج الخطأ هذا وكيفية التعامل معه في دليل تصميم واجهة برمجة التطبيقات.

مواضيع ذات صلة

• تنزيل الملفات وتصديرها