直接和可续传的媒体上传

本文档介绍了如何通过适用于 Java 的 Google API 客户端库使用直接和可续传的媒体内容上传。

可续传媒体上传

将大型媒体文件上传到服务器时，请使用可续传媒体上传功能逐个分块发送文件。Google API 生成的库包含一些可以与可续传媒体上传交互的简便方法。

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

协议设计

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

实现细节

相关的主要类是 MediaHttpUploader 和 MediaHttpProgressListener。

如果服务专属的生成库中的方法在发现文档中包含 mediaUpload 参数，则系统会为这些方法创建一个使用 InputStreamContent 作为参数的便捷方法。（如需详细了解如何搭配 Google API 发现服务使用媒体上传，请参阅媒体上传。）

例如，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);