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

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

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

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

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

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

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

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

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

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

على سبيل المثال، تتوافق طريقة 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);