تحميلات الوسائط المباشرة والقابلة للاستئناف

يوضّح هذا المستند كيفية استخدام تحميلات الوسائط المباشرة والقابلة للاستئناف مع "مكتبة عميل Google API" للغة Java.

تحميل الوسائط القابلة للاستئناف

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

يشبه بروتوكول تحميل الوسائط القابلة للاستئناف بروتوكول تحميل الوسائط القابل للاستئناف الموضح في وثائق واجهة برمجة تطبيقات Google Drive.

تصميم البروتوكول

يوضّح مخطط التسلسل التالي آلية عمل بروتوكول تحميل الوسائط القابل للاستئناف:

تفاصيل التنفيذ

الفئات الرئيسية المثيرة للاهتمام هي MediaHttpUploader وMediaHttpProgressListener.

إذا كانت الطرق في المكتبات التي يتم إنشاؤها وفقًا للخدمة تحتوي على المعلَمة mediaUpload في مستند أثناء التصفّح، يتم إنشاء طريقة ملائمة للطرق التي تستخدم InputStreamContent كمعلمة. (لمزيد من المعلومات حول استخدام تحميل الوسائط مع خدمة Google APIs Discovery، يمكنك الاطّلاع على تحميل الوسائط.)

على سبيل المثال، تتيح طريقة 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-الإصدار التجريبي من مكتبة عملاء Google API لـ Java.

يحمّل الوسائط المباشرة الملف بأكمله في طلب HTTP واحد، على عكس بروتوكول تحميل الوسائط القابل للاستئناف والذي يحمّل الملف في طلبات متعددة. يؤدي إجراء تحميل مباشر إلى تقليل عدد طلبات HTTP، ولكنه يزيد من احتمالات تعذّر إتمامها (مثل حالات تعذُّر الاتصال) التي يمكن أن تحدث مع عمليات التحميل الكبيرة.

يتطابق استخدام التحميل المباشر للوسائط مع ما هو موضح أعلاه لتحميل الوسائط القابل للاستئناف، بالإضافة إلى المكالمة التالية التي تطلب من MediaHttpUploader إجراء عمليات تحميل مباشرة فقط:

mediaHttpUploader.setDirectUploadEnabled(true);