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

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

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

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

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

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

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

1. Call files.download : هنگامی که برنامه شما متد download() را فراخوانی می کند، درخواست دانلود Drive API را برای فایل اجرا می کند. برای اطلاعات بیشتر به دانلود فایل ها مراجعه کنید.

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

3. شروع دانلود : یک درخواست Drive API برای شروع دانلود فایل ارسال می شود. این درخواست می تواند به Google Vids یا برخی دیگر از محتوای Google Workspace ارسال شود.

4. شروع LRO : یک عملیات طولانی مدت شروع می شود و فرآیند دانلود را مدیریت می کند.

5. عملیات در انتظار بازگشت : Drive API یک عملیات معلق حاوی اطلاعات کاربر درخواست کننده و چندین فیلد فراداده فایل را برمی گرداند.

6. Initial pending state : برنامه شما عملیات در انتظار را به همراه یک حالت در انتظار اولیه done=null دریافت می کند. این نشان می‌دهد که فایل هنوز برای دانلود آماده نیست و وضعیت عملیات در حال تعلیق است.

7. فراخوانی operations.get و تأیید نتیجه : برنامه شما در فواصل زمانی توصیه شده برای نظرسنجی نتیجه عملیات و دریافت آخرین وضعیت یک عملیات طولانی مدت، تماس های get() را انجام می دهد. اگر حالت معلق done=false برگردانده شود، برنامه شما باید به نظرسنجی ادامه دهد تا زمانی که عملیات به حالت تکمیل شده ( done=true ) برگردد. برای فایل های بزرگ، انتظار داشته باشید که چندین بار نظرسنجی کنید. برای اطلاعات بیشتر، به دریافت جزئیات در مورد یک عملیات طولانی مدت مراجعه کنید.

8. بررسی وضعیت در انتظار : اگر حالت در انتظار done=true از LRO برگردانده شود، این نشان دهنده آماده بودن فایل برای دانلود و کامل بودن وضعیت عملیات است.

9. بازگشت عملیات تکمیل شده با دانلود URI : پس از اتمام LRO، Drive API URI دانلود را برمی گرداند و فایل اکنون در دسترس کاربر است.

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

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

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

• اختیاری. پارامتر query mime_type نشان دهنده نوع MIME است که روش باید استفاده کند. فقط هنگام بارگیری محتوای رسانه ای غیر حباب (مانند اسناد Google Workspace) در دسترس است. برای فهرست کامل انواع MIME پشتیبانی شده، صادرات انواع MIME برای اسناد Google Workspace را ببینید.

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

• اختیاری. پارامتر query 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 پیش فرض

اگر یک نوع 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 : URI نهایی دانلود برای فایل.

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

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

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

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

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

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

برای نظرسنجی یک LRO موجود، متد get() را به طور مکرر فراخوانی کنید تا زمانی که عملیات به پایان برسد. بین هر درخواست نظرسنجی از یک عقب‌نشینی نمایی مانند 10 ثانیه استفاده کنید.

LRO برای حداقل 12 ساعت در دسترس باقی می ماند، اما در برخی موارد می تواند مدت بیشتری باقی بماند. این مدت در معرض تغییر است و می تواند بین انواع فایل متفاوت باشد. پس از انقضای منبع، درخواست متد 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 برای دانلود آخرین نسخه استفاده کنید. این ویرایشی را واکشی می کند که با فراداده فایلی که قبلاً بازیابی کرده اید مطابقت دارد. برای دانلود داده‌های تمام نسخه‌های قبلی فایل که هنوز در فضای ابری ذخیره می‌شوند، می‌توانید با پارامتر fileId متد list() را در منبع revisions فراخوانی کنید. این همه revisionIds موجود در فایل را برمی گرداند.

برای دانلود محتوای ویرایش فایل‌های blob، باید متد get() را در منبع revisions با شناسه فایل برای دانلود، شناسه ویرایش و پارامتر URL alt=media فراخوانی کنید. پارامتر alt=media URL به سرور می گوید که دانلود محتوا به عنوان فرمت پاسخ جایگزین درخواست می شود.

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

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

عیب یابی LRO ها

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

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

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

موضوعات مرتبط

• فایل ها را دانلود و صادر کنید
• مدیریت ویرایش های فایل