直接和可续传的媒体上传

本文档介绍了如何在 Java 版 Google API 客户端库中使用直接上传和可续传的媒体上传。

可续传媒体上传

将大型媒体文件上传到服务器时，请使用可续传媒体上传逐个上传文件。Google API 生成的库包含与可续传媒体上传互动的便捷方法。

可续传媒体上传协议类似于 Google Drive API 文档中所述的可续传媒体上传协议。

协议设计

下面的序列图显示了可续传媒体上传协议的工作原理：

实现细节

我们主要关注 MediaHttpUploader 和 MediaHttpProgressListener。

如果服务专用库中的方法包含 Discovery 文档中的 mediaUpload 参数，则系统会为这些方法创建一种便捷方法，该方法接受 InputStreamContent 作为参数。（如需详细了解如何在 Google API Discovery Service 中使用媒体上传功能，请参阅媒体上传。）

例如，Drive API 的 insert 方法支持 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);
}

直接媒体上传

可续传媒体上传功能默认处于启用状态，不过您可以将其停用，并改用直接媒体上传功能（例如，如果您要上传小文件）。直接媒体上传是在 Java 版 Google API 客户端库的 1.9.0-beta 版本中引入的。

与使用多项请求上传文件的可续传媒体上传协议相反，直接媒体上传通过一个 HTTP 请求上传整个文件。执行直接上传会减少 HTTP 请求的数量，但会增加上传失败时发生的失败（例如连接失败）机会。

直接媒体上传的用途与上面提到的可续传媒体上传的用途相同，此外还有以下调用，告知 MediaHttpUploader 仅执行直接上传：

mediaHttpUploader.setDirectUploadEnabled(true);