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

العملية الطويلة الأمد (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.

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

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

الرمز تعداد رمز حالة HTTP‬ الوصف الإجراء المقترَح
1 CANCELLED 499 Client Closed Request تم إلغاء العملية، وعادةً ما يتم ذلك من قِبل المتصل. أعِد تنفيذ العملية.
2 UNKNOWN 500 Internal Server Error قد يتم عرض هذا الخطأ عندما تنتمي قيمة Status تم تلقّيها من مساحة عناوين أخرى إلى مساحة خطأ غير معروفة في مساحة العناوين هذه. إذا لم يعرض خطأ واجهة برمجة التطبيقات معلومات كافية، قد يتم تحويل الخطأ إلى هذا الخطأ. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
3 INVALID_ARGUMENT 400 Bad Request حدّد العميل وسيطة غير صالحة. يختلف هذا الخطأ عن FAILED_PRECONDITION. يشير INVALID_ARGUMENT إلى وسيطات تسبّب مشاكل بغض النظر عن حالة النظام، مثل اسم ملف غير صالح. لا تعِد المحاولة بدون حلّ المشكلة.
4 DEADLINE_EXCEEDED 504 Gateway Timeout انتهت المهلة قبل أن تتمكّن العملية من الاكتمال. بالنسبة إلى العمليات التي تغيّر حالة النظام، قد يتم عرض هذا الخطأ حتى إذا اكتملت العملية بنجاح. على سبيل المثال، قد يتأخر الردّ الناجح من الخادم لفترة طويلة بما يكفي لانتهاء الموعد النهائي. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
5 NOT_FOUND 404 Not Found لم يتم العثور على بعض الكيانات المطلوبة، مثل مورد FHIR. لا تعِد المحاولة بدون حلّ المشكلة.
6 ALREADY_EXISTS 409 Conflict الكيان الذي حاول العميل إنشاءه، مثل مثيل DICOM، متوفّر مسبقًا. لا تعِد المحاولة بدون حلّ المشكلة.
7 PERMISSION_DENIED 403 Forbidden ليس لدى المتصل إذن لتنفيذ العملية المحدّدة. لا يعني رمز الخطأ هذا أنّ الطلب صالح أو أنّ العنصر المطلوب متوفّر أو أنّه يستوفي الشروط المسبقة الأخرى. لا تعِد المحاولة بدون حلّ المشكلة.
8 RESOURCE_EXHAUSTED 429 Too Many Requests تم استنفاد بعض الموارد، مثل الحصة المخصّصة لكل مشروع. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. قد تصبح الحصة متاحة بمرور الوقت.
9 FAILED_PRECONDITION 400 Bad Request تم رفض العملية لأنّ النظام ليس في الحالة المطلوبة لتنفيذها. على سبيل المثال، الدليل المطلوب حذفه غير فارغ، أو تم تطبيق عملية rmdir على عنصر ليس دليلاً. لا تعِد المحاولة بدون حلّ المشكلة.
10 ABORTED 409 Conflict تم إلغاء العملية، وعادةً ما يكون ذلك بسبب مشكلة في التزامن، مثل فشل عملية التحقّق من التسلسل أو إلغاء المعاملة. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
11 OUT_OF_RANGE 400 Bad Request تمت محاولة تنفيذ العملية بعد النطاق الصالح، مثل البحث أو القراءة بعد نهاية الملف. على عكس الخطأ INVALID_ARGUMENT، يشير هذا الخطأ إلى مشكلة يمكن حلّها إذا تغيّرت حالة النظام. لا تعِد المحاولة بدون حلّ المشكلة.
12 UNIMPLEMENTED 501 Not Implemented لم يتم تنفيذ العملية أو أنّها غير متاحة/مفعّلة في Drive API. لا تعِد المحاولة.
13 INTERNAL 500 Internal Server Error أخطاء داخلية يشير ذلك إلى حدوث خطأ غير متوقّع أثناء المعالجة في النظام الأساسي. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
14 UNAVAILABLE 503 Service Unavailable واجهة برمجة تطبيقات Drive غير متاحة. من المرجّح أنّ هذه الحالة عابرة، ويمكن تصحيحها من خلال إعادة المحاولة باستخدام خوارزمية الرقود الأسي الثنائي. يُرجى العِلم أنّه ليس من الآمن دائمًا إعادة محاولة تنفيذ العمليات غير المتكرّرة. أعِد المحاولة باستخدام خوارزمية الرقود الأسي الثنائي.
15 DATA_LOSS 500 Internal Server Error ثمة بيانات تالفة أو بيانات مفقودة ويتعذّر استرجاعها. يُرجى التواصل مع مشرف النظام. قد يحتاج مشرف النظام إلى التواصل مع أحد ممثلي فريق الدعم في حال فقدان البيانات أو تلفها.
16 UNAUTHENTICATED 401 Unauthorized لا يتضمّن الطلب بيانات اعتماد مصادقة صالحة للعملية. لا تعِد المحاولة بدون حلّ المشكلة.