بارگذاری‌های رسانه مستقیم و قابل‌ازسرگیری

این سند نحوه استفاده از بارگذاری‌های رسانه مستقیم و قابل‌ازسرگیری را با «کتابخانه کارخواه Google API» برای Java شرح می‌دهد.

بارگذاری رسانه ازسرگرفتنی

وقتی فایل رسانه‌ای بزرگی را در سرور بارگذاری می‌کنید، از بارگذاری رسانه قابل‌ازسرگیری استفاده کنید تا فایل را تکه‌تکه ارسال کنید. کتابخانه‌های تولیدشده Google API حاوی روش‌های راحتی برای تعامل با بارگذاری رسانه ازسرگرفتنی است.

پروتکل بارگذاری رسانه ازسرگرفتنی مشابه پروتکل بارگذاری رسانه ازسرگرفتنی است که در سند Google Drive API شرح داده شده است.

طراحی پروتکل

نمودار توالی زیر نحوه عملکرد پروتکل بارگذاری رسانه ازسرگرفتنی را نشان می‌دهد:

جزئیات پیاده‌سازی

کلاس‌های اصلی موردنظر عبارت‌اند از MediaHttpUploader و MediaHttpProgressListener.

اگر روش‌های موجود در کتابخانه‌های تولیدشده مختص سرویس حاوی پارامتر mediaUpload در سند اکتشاف باشند، روش راحتی برای این روش‌ها ایجاد می‌شود که InputStreamContent را به‌عنوان پارامتر می‌گیرد. (برای اطلاعات بیشتر درباره استفاده از بارگذاری رسانه با Google APIs Discovery Service، به بارگذاری رسانه مراجعه کنید.)

برای مثال، روش insert از Drive API از mediaUpload پشتیبانی می‌کند و می‌توانید از کد زیر برای بارگذاری فایل استفاده کنید:

class CustomProgressListener implements MediaHttpUploaderProgressListener {
  public void progressChanged(MediaHttpUploader uploader) throws IOException {
    switch (uploader.getUploadState()) {
      case INITIATION_STARTED:
        System.out.println("Initiation has started!");
        break;
      case INITIATION_COMPLETE:
        System.out.println("Initiation is complete!");
        break;
      case MEDIA_IN_PROGRESS:
        System.out.println(uploader.getProgress());
        break;
      case MEDIA_COMPLETE:
        System.out.println("Upload is complete!");
    }
  }
}

File mediaFile = new File("/tmp/driveFile.jpg");
InputStreamContent mediaContent =
    new InputStreamContent("image/jpeg",
        new BufferedInputStream(new FileInputStream(mediaFile)));
mediaContent.setLength(mediaFile.length());

Drive.Files.Insert request = drive.files().insert(fileMetadata, mediaContent);
request.getMediaHttpUploader().setProgressListener(new CustomProgressListener());
request.execute();

همچنین می‌توانید از ویژگی بارگذاری رسانه قابل‌ازسرگیری بدون کتابخانه‌های تولیدشده مختص سرویس استفاده کنید. به‌عنوان مثال:

File mediaFile = new File("/tmp/Test.jpg");
InputStreamContent mediaContent =
    new InputStreamContent("image/jpeg",
        new BufferedInputStream(new FileInputStream(mediaFile)));
mediaContent.setLength(mediaFile.length());


MediaHttpUploader uploader = new MediaHttpUploader(mediaContent, transport, httpRequestInitializer);
uploader.setProgressListener(new CustomProgressListener());
HttpResponse response = uploader.upload(requestUrl);
if (!response.isSuccessStatusCode()) {
  throw GoogleJsonResponseException(jsonFactory, response);
}

بارگذاری مستقیم رسانه

بارگذاری رسانه قابل ازسرگیری به‌طور پیش‌فرض فعال است، اما می‌توانید آن را غیرفعال کنید و به‌جای آن از بارگذاری مستقیم رسانه استفاده کنید، مثلاً اگر درحال بارگذاری یک فایل کوچک هستید. بارگذاری مستقیم رسانه در نسخه 1.9.0-beta از کتابخانه کارخواه Google API برای Java معرفی شد.

بارگذاری مستقیم رسانه کل فایل را در یک درخواست HTTP بارگذاری می‌کند، برخلاف پروتکل بارگذاری رسانه قابل‌ازسرگیری که فایل را در چندین درخواست بارگذاری می‌کند. انجام بارگذاری مستقیم تعداد درخواست‌های HTTP را کاهش می‌دهد اما احتمال خرابی‌ها (مانند خرابی‌های اتصال) را که ممکن است با بارگذاری‌های بزرگ رخ دهد، افزایش می‌دهد.

استفاده از بارگذاری مستقیم رسانه همانند آنچه در بالا برای بارگذاری رسانه ازسرگرفتنی توضیح داده شد است، به‌علاوه فراخوانی زیر که به MediaHttpUploader می‌گوید فقط بارگذاری‌های مستقیم را انجام دهد:

mediaHttpUploader.setDirectUploadEnabled(true);