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

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

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

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

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

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

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

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

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

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

  3. بدء التنزيل: يتم إرسال طلب إلى واجهة برمجة تطبيقات Drive لبدء تنزيل الملف. يمكن تقديم الطلب إلى 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 للتنزيل: بعد انتهاء عملية LRO، تعرض واجهة برمجة تطبيقات Drive عنوان 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 نص غير منسَّق text/raw ‎.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 يشير إلى ما إذا كان مسموحًا بالتنزيل الجزئي. تعرض القيمة True عند تنزيل محتوى ملف كائن ثنائي كبير.

الحصول على تفاصيل حول عملية تستغرق وقتًا طويلاً

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

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

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

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

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

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

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

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

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

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

الرمز Enum الوصف الإجراء المقترَح
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 لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة للعملية. لا تعِد المحاولة بدون حلّ المشكلة.