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

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

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

تُرجع الطريقة مورد operations إلى العميل. يمكنك استخدام المورد operations لجمع حالة طريقة واجهة برمجة التطبيقات بشكل غير متزامن من خلال الاستعلام عن العملية من خلال الطريقة get(). تلتزم عمليات LRO في Drive API بتصميم LRO في Google Cloud.

لمزيد من المعلومات، يُرجى الاطّلاع على العمليات التي تستغرق وقتًا طويلاً.

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

يوضّح الرسم البياني التالي الخطوات الأساسية لآلية عمل file.download.

الخطوات العامة لطريقة file.download
الشكل 1. الخطوات العامة لطريقة file.download

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

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

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

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

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

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

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

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

  9. عرض العملية المكتملة باستخدام معرّف الموارد المنتظم (URI) للتنزيل: بعد اكتمال طلب البحث التلقائي (LRO)، تعرض واجهة برمجة التطبيقات 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" أو "جداول بيانات Google" تهدف في البداية إلى إعادة التوجيه. انقر على الرابط الجديد لتنزيل الملف.

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

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

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

استبدِل FILE_ID بـ fileId للملف الذي تريد تنزيله.

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

إذا لم يتم ضبط نوع MIME عند تنزيل محتوى غير ملفّات نصية، يتم تحديد أنواع MIME التلقائية التالية:

نوع المستند التنسيق نوع MIME امتداد الملف
لغة برمجة تطبيقات Google JSON application/vnd.google-apps.script+json ‎.json
مستندات Google Microsoft Word application/vnd.openxmlformats-officedocument.wordprocessingml.document ‎.docx
رسومات Google PNG الصورة/png ‎.png
نماذج Google ZIP application/zip ‎.zip
جداول بيانات Google Microsoft Excel application/vnd.openxmlformats-officedocument.spreadsheetml.sheet ‎.xlsx
مواقع Google النصّ غير المنسَّق نص/خام ‎.txt
العروض التقديمية من Google Microsoft PowerPoint application/vnd.openxmlformats-officedocument.presentationml.presentation ‎.pptx
Google Vids MP4 application/mp4 ‎.mp4
Jamboard PDF application/pdf ‎.pdf

تنزيل الردّ

عند استدعاء الطريقة 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
  }
}

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

يُرجى العلم أنّ الحقل partialDownloadAllowed يشير إلى ما إذا كان تحميل ملف جزئي مسموحًا به. صحيح عند تنزيل محتوى ملف ملفّ أصغر.

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

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

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

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

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

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

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

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

يتم عرض بروتوكولات الطلبات هنا.

طلب إجراء

operations.get(name='NAME');

استبدِل NAME باسم العملية الذي حدّده الخادم كما هو موضح في الاستجابة لطلب الطريقة download().

curl

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

استبدِل NAME باسم العملية الذي حدّده الخادم كما هو موضح في الاستجابة لطلب الطريقة download().

يستخدم الأمر المسار /drive/v3/operations/NAME.

يُرجى العلم أنّه لا يتم عرض السمة 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" إلى الزيادة التلقائية لأرقام المراجعات. ومع ذلك، قد تتضمّن سلسلة الأرقام فواصل في حال حذف المراجعات، لذا يجب عدم الاعتماد على الأرقام التسلسلية لمحاولة استرداد المراجعات.

تحديد مشاكل عمليات إعادة التوجيه الدائمة وحلّها

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

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

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

الرمز تعداد الوصف الإجراء المقترح
1 CANCELLED تم إلغاء العملية، عادةً من قِبل المتصل. أعِد تنفيذ العملية.
2 UNKNOWN قد يتم عرض هذا الخطأ عندما تنتمي قيمة Status التي تمّ تلقّيها من مساحة عناوين أخرى إلى مساحة خطأ غير معروفة في مساحة العناوين هذه. إذا لم يعرض خطأ واجهة برمجة التطبيقات معلومات كافية، قد يتم تحويل الخطأ إلى هذا الخطأ. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
3 INVALID_ARGUMENT حدّد العميل وسيطة غير صالحة. يختلف هذا الخطأ عن FAILED_PRECONDITION. يشير الرمز INVALID_ARGUMENT إلى الوسيطات التي تتضمن مشاكل بغض النظر عن حالة النظام، مثل اسم ملف بتنسيق غير صحيح. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
4 DEADLINE_EXCEEDED انتهت المهلة قبل اكتمال العملية. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح. على سبيل المثال، قد يكون قد تأخّر وصول استجابة ناجحة من خادم لفترة طويلة بما يكفي لانتهاء المهلة. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
5 NOT_FOUND لم يتم العثور على بعض الكيانات المطلوبة، مثل مورد FHIR. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
6 ALREADY_EXISTS الكيان الذي حاول العميل إنشاؤه، مثل مثيل DICOM، متوفّر مسبقًا. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
7 PERMISSION_DENIED لا يملك المتصل الإذن لتنفيذ العملية المحدّدة. لا يشير رمز الخطأ هذا إلى أنّ الطلب صالح أو أنّ الكيان المطلوب متوفّر أو أنّه يستوفي الشروط المسبقة الأخرى. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
8 RESOURCE_EXHAUSTED تم استنفاد بعض الموارد، مثل الحصة لكل مشروع. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. قد تصبح الحصة متاحة بمرور الوقت.
9 FAILED_PRECONDITION تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها. على سبيل المثال، يكون الدليل الذي سيتم حذفه غير فارغ، أو يتم تطبيق عملية rmdir على عنصر غير دليل. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
10 ABORTED تم إلغاء العملية، عادةً بسبب مشكلة في التوافق، مثل تعذُّر التحقّق من التسلسل أو إلغاء المعاملة. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
11 OUT_OF_RANGE تمّت محاولة إجراء العملية بعد النطاق الصالح، مثل الانتقال إلى أو قراءة ما بعد نهاية الملف. على عكس الخطأ INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة قد يتم حلّها في حال تغيّر حالة النظام. لا تحاول إعادة المحاولة بدون حلّ المشكلة.
12 UNIMPLEMENTED لم يتم تنفيذ العملية أو أنها غير متاحة أو غير مفعّلة في Drive API. لا تحاول إعادة المحاولة.
13 INTERNAL الأخطاء الداخلية يشير ذلك إلى حدوث خطأ غير متوقّع في المعالجة على النظام الأساسي. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
14 UNAVAILABLE واجهة برمجة التطبيقات Drive API غير متاحة. من المرجّح أن يكون هذا ظرفًا عابرًا، ويمكن تصحيحه من خلال إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة العمليات غير الثابتة. يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
15 DATA_LOSS ثمة بيانات تالفة أو مفقودة ويتعذّر استرجاعها. يُرجى التواصل مع مشرف النظام. قد يحتاج مشرف النظام إلى التواصل مع ممثّل الدعم في حال حدوث فقدان للبيانات أو تلفها.
16 UNAUTHENTICATED لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة للعملية. لا تحاول إعادة المحاولة بدون حلّ المشكلة.