تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

الخطوات العامة لطريقة file.download — **الشكل 1.** الخطوات المفصّلة لطريقة file.download

استدعاء files.download: عندما يستدعي تطبيقك الطريقة download()، يؤدي ذلك إلى بدء طلب تنزيل الملف من خلال Drive API. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة تنزيل الملفات.
طلب الأذونات: يُرسِل الطلب بيانات اعتماد المصادقة إلى واجهة برمجة التطبيقات Drive API. إذا كان تطبيقك يتطلّب طلب بيانات من واجهة برمجة التطبيقات Drive API باستخدام مصادقة مستخدم لم يتم منحها بعد، سيُطلب من المستخدم تسجيل الدخول. يطلب تطبيقك أيضًا الوصول باستخدام النطاقات التي تحدّدها عند إعداد المصادقة.
بدء التنزيل: يتم إرسال طلب إلى Drive API لبدء تنزيل الملف. يمكن تقديم الطلب إلى Google Vids أو أي محتوى آخر في Google Workspace.
بدء LRO: تبدأ عملية طويلة الأمد وتدير عملية التنزيل.
عرض عملية في انتظار المراجعة: تعرض واجهة برمجة التطبيقات Drive API عملية في انتظار المراجعة تحتوي على معلومات عن المستخدم الذي يقدّم الطلب والعديد من حقول البيانات الوصفية للملف.
الحالة الأولية في انتظار المراجعة: يتلقّى تطبيقك العملية التي في انتظار المراجعة مع حالة أولية في انتظار المراجعة هي done=null. يشير ذلك إلى أنّ الملف ليس جاهزًا للتنزيل بعد وأنّ حالة العملية في انتظار المراجعة.
استدعاء operations.get والتحقّق من النتيجة: يستدعي تطبيقك get() في المُدد الزمنية المُقترَحة لفحص نتيجة العملية والحصول على أحدث حالة لعملية طويلة الأمد. إذا تم إرجاع حالة done=false المعلَّقة، يجب أن يستمر تطبيقك في الاستطلاع إلى أن تعرض العملية الحالة المكتملة (done=true). وبالنسبة إلى الملفات الكبيرة، من المتوقَّع إجراء الاستطلاع عدة مرات. لمزيد من المعلومات، يُرجى الاطّلاع على الحصول على تفاصيل عن عملية تتعذّر إكمالها.
التحقّق من حالة الانتظار: إذا تم عرض حالة done=true المعلَّقة من LRO، يشير ذلك إلى أنّ الملف جاهز للتنزيل وأنّ حالة العملية قد اكتملت.
عرض العملية المكتملة باستخدام معرّف الموارد المنتظم (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 وطلب استرجاع معرّف الموارد المنتظم (URI) النهائي للتنزيل، يجب استخدام مفتاحَي الموارد. لمزيد من المعلومات، يُرجى الاطّلاع على الوصول إلى ملفات 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	التطبيق/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
  }
}

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

RESOURCE_KEY: يساعد مفتاح المصدر في حماية ملفك من الوصول غير المقصود. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى ملفات Drive المشترَكة باستخدام رابط باستخدام مفاتيح الموارد.
NAME: الاسم الذي خصّصه الخادم
DOWNLOAD_URI: معرّف الموارد المنتظم (URI) النهائي لتنزيل الملف

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

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

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

يمكنك استخدام مورد operations الذي توفِّره واجهة برمجة تطبيقات Drive للتحقّق من حالة المعالجة 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. إذا كنت تستخدم مكتبة عملاء لواجهة برمجة التطبيقات 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 وحلّها

عند تعذُّر تشغيل 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 غير متاحة. من المرجّح أن يكون هذا ظرفًا عابرًا، ويمكن تصحيحه من خلال إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. تجدر الإشارة إلى أنّه ليس من الآمن دائمًا إعادة محاولة العمليات غير الفعّالة.	يعيد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
15	`DATA_LOSS`	تلف أو فقدان بيانات غير قابل للإصلاح.	يُرجى التواصل مع مشرف النظام. قد يحتاج مشرف النظام إلى التواصل مع أحد ممثّلي فريق الدعم في حال حدوث فقدان للبيانات أو تلفها.
16	`UNAUTHENTICATED`	لا يحتوي الطلب على بيانات اعتماد مصادقة صالحة للعملية.	لا تحاول إعادة المحاولة بدون حلّ المشكلة.