مدیریت عملیات طولانی مدت

یک عملیات طولانی مدت (LRO) یک روش API است که تکمیل آن زمان بیشتری نسبت به زمان مناسب برای پاسخ API طول می‌کشد. معمولاً شما نمی‌خواهید نخ فراخوانی را در حین اجرای وظیفه باز نگه دارید زیرا تجربه کاربری ضعیفی را ارائه می‌دهد. در عوض، بهتر است نوعی promise را به کاربر برگردانید و به او اجازه دهید بعداً بررسی کند.

هر بار که متد download را روی منبع files فراخوانی می‌کنید تا محتوای یک فایل را از طریق API درایو یا کتابخانه‌های کلاینت آن دانلود کنید، API گوگل درایو یک LRO برمی‌گرداند.

این متد یک منبع operations را به کلاینت برمی‌گرداند. شما می‌توانید از منبع operations برای بازیابی ناهمگام وضعیت متد API با نمونه‌برداری از عملیات از طریق متد get استفاده کنید. LROها در Drive API از الگوی طراحی Google Cloud LRO پیروی می‌کنند.

برای اطلاعات بیشتر، به عملیات طولانی مدت مراجعه کنید.

مرور کلی فرآیند

نمودار زیر مراحل سطح بالای نحوه‌ی عملکرد متد file.download را نشان می‌دهد.

1. فراخوانی files.download : وقتی برنامه شما متد download را فراخوانی می‌کند، درخواست دانلود فایل از Drive API را اجرا می‌کند. برای اطلاعات بیشتر، به Download files مراجعه کنید.

2. درخواست مجوزها : این درخواست، اعتبارنامه‌های احراز هویت را به Drive API ارسال می‌کند. اگر برنامه شما نیاز به فراخوانی Drive API با استفاده از احراز هویت کاربری که هنوز اعطا نشده است، داشته باشد، از کاربر می‌خواهد که وارد سیستم شود. برنامه شما همچنین درخواست دسترسی با محدوده‌هایی را می‌کند که هنگام تنظیم احراز هویت مشخص می‌کنید.

3. شروع دانلود : یک درخواست از 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. بازگرداندن عملیات تکمیل‌شده به همراه آدرس دانلود : پس از اتمام عملیات LRO، Drive API آدرس دانلود را برمی‌گرداند و فایل اکنون در دسترس کاربر قرار دارد.

دانلود فایل‌ها

برای دانلود محتوا تحت یک عملیات طولانی مدت، از متد download روی منبع files استفاده کنید. این متد پارامترهای file_id ، mime_type و revision_id را دریافت می‌کند:

• الزامی. پارامتر مسیر file_id ، شناسه فایلی است که قرار است دانلود شود.

• اختیاری. پارامتر پرس‌وجوی mime_type نوع MIME مورد استفاده در روش را نشان می‌دهد. این پارامتر فقط هنگام دانلود محتوای رسانه‌ای غیر blob (مانند اسناد Google Workspace) در دسترس است. برای فهرست کاملی از انواع MIME پشتیبانی‌شده، به Export MIME types for Google Workspace documents مراجعه کنید.

  اگر نوع MIME تنظیم نشده باشد، سند Google Workspace با نوع MIME پیش‌فرض دانلود می‌شود. برای اطلاعات بیشتر، به انواع MIME پیش‌فرض مراجعه کنید.

• اختیاری. پارامتر کوئری revision_id ، شناسه‌ی ویرایش فایلی است که قرار است دانلود شود. این پارامتر فقط هنگام دانلود فایل‌های blob، Google Docs و Google Sheets در دسترس است. هنگام دانلود یک ویرایش خاص روی فایل‌های پشتیبانی نشده، کد خطای INVALID_ARGUMENT را برمی‌گرداند.

روش download تنها راه برای دانلود فایل‌های Vids با فرمت MP4 است و معمولاً برای دانلود اکثر فایل‌های ویدیویی مناسب‌تر است.

لینک‌های دانلود ایجاد شده برای Google Docs یا Sheets در ابتدا یک تغییر مسیر (ریدایرکت) برمی‌گردانند. برای دانلود فایل، روی لینک جدید کلیک کنید.

درخواست به روش download که LRO را آغاز می‌کند، و درخواست برای دریافت URI دانلود نهایی، هر دو باید از کلیدهای منبع استفاده کنند. برای اطلاعات بیشتر، به دسترسی به فایل‌های درایو لینک-اشتراک‌گذاری شده با استفاده از کلیدهای منبع مراجعه کنید.

پروتکل درخواست در اینجا نشان داده شده است.

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

به جای FILE_ID fileId فایلی که می‌خواهید دانلود کنید را قرار دهید.

انواع پیش‌فرض MIME

اگر هنگام دانلود محتوای غیر blob نوع 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 : یک کلید منبع به محافظت از فایل شما در برابر دسترسی ناخواسته کمک می‌کند. برای اطلاعات بیشتر، به دسترسی به فایل‌های درایو اشتراکی با لینک با استفاده از کلیدهای منبع مراجعه کنید.

• NAME : نامی که توسط سرور تعیین شده است.

• DOWNLOAD_URI : آدرس دانلود نهایی فایل.

توجه داشته باشید که فیلد partialDownloadAllowed نشان می‌دهد که آیا دانلود جزئی مجاز است یا خیر و هنگام دانلود محتوای فایل blob مقدار آن true است.

جزئیات مربوط به یک عملیات طولانی مدت را دریافت کنید

عملیات طولانی‌مدت، فراخوانی متدهایی هستند که ممکن است زمان قابل توجهی برای تکمیل شدن نیاز داشته باشند. معمولاً عملیات دانلود تازه ایجاد شده، در ابتدا در حالت انتظار ( done=null ) برگردانده می‌شوند، مخصوصاً برای فایل‌های Vids.

شما می‌توانید از منبع operations که Drive API ارائه می‌دهد، برای بررسی وضعیت پردازش LRO با وارد کردن نام منحصر به فرد اختصاص داده شده توسط سرور، استفاده کنید.

متد get آخرین وضعیت یک عملیات طولانی مدت را به صورت غیرهمزمان دریافت می‌کند. کلاینت‌ها می‌توانند از این متد برای نظرسنجی از نتیجه عملیات در فواصل زمانی توصیه شده توسط سرویس API استفاده کنند.

نظرسنجی از یک عملیات طولانی مدت

برای نمونه‌برداری از یک LRO موجود، متد get را مکرراً فراخوانی کنید تا عملیات تمام شود. بین هر درخواست نمونه‌برداری، مثلاً ۱۰ ثانیه، از یک backoff نمایی استفاده کنید.

یک LRO حداقل به مدت ۱۲ ساعت در دسترس است، اما در برخی موارد می‌تواند بیشتر نیز دوام بیاورد. این مدت زمان ممکن است تغییر کند و بسته به نوع فایل می‌تواند متفاوت باشد. پس از انقضای منبع، درخواست روش download جدید ضروری است.

هرگونه درخواستی برای get باید از کلیدهای منبع استفاده کند. برای اطلاعات بیشتر، به «دسترسی به فایل‌های درایو اشتراکی لینک‌شده با استفاده از کلیدهای منبع» مراجعه کنید.

پروتکل‌های درخواست در اینجا نشان داده شده‌اند.

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 با شناسه فایل مورد نظر برای دانلود، شناسه نسخه و پارامتر alt=media URL فراخوانی کنید. پارامتر alt=media URL به سرور می‌گوید که دانلود محتوا به عنوان یک فرمت پاسخ جایگزین درخواست شده است.

نمی‌توان با استفاده از متد get و آدرس alt=media نسخه‌های اصلاح‌شده‌ی فایل‌های Google Docs، Sheets، Slides و Vids را دانلود کرد. در غیر این صورت، خطای fileNotDownloadable ایجاد می‌شود.

پارامتر alt=media URL یک پارامتر سیستمی است که در تمام APIهای 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 Docs، Drawings و Slides به طور خودکار شماره‌های نسخه را افزایش می‌دهند. با این حال، اگر نسخه‌ها حذف شوند، ممکن است سری اعداد دارای فاصله باشند، بنابراین نباید برای بازیابی نسخه‌ها به شماره‌های متوالی تکیه کنید.

عیب‌یابی LROها

وقتی یک LRO از کار می‌افتد، پاسخ آن شامل یک کد خطای متعارف Google Cloud است.

جدول زیر هر کد خطا، کد وضعیت HTTP نگاشت شده، توضیحات و توصیه‌ای برای نحوه مدیریت کد خطا را نمایش می‌دهد. برای بسیاری از خطاها، اقدام توصیه شده این است که درخواست را دوباره با استفاده از exponential backoff امتحان کنید.

می‌توانید اطلاعات بیشتر در مورد این مدل خطا و نحوه کار با آن را در راهنمای طراحی API مطالعه کنید.

مباحث مرتبط

• دانلود و خروجی گرفتن از فایل‌ها