直接および再開可能なメディア アップロード

このドキュメントでは、Java 用 Google API クライアント ライブラリを使用して直接または再開可能なメディア アップロードを使用する方法について説明します。

再開可能なメディア アップロード

サイズの大きいメディア ファイルをサーバーにアップロードする場合は、再開可能なメディア アップロードを使用して、ファイルをチャンクごとに送信します。Google API で生成されたライブラリには、再開可能なメディア アップロードを操作するための便利なメソッドが含まれています。

再開可能メディア アップロード プロトコルは、Google Drive API ドキュメントに記載されている再開可能なメディア アップロード プロトコルに類似しています。

プロトコル設計

次のシーケンス図は、再開可能メディア アップロード プロトコルの仕組みを示しています。

実装の詳細

主なクラスは MediaHttpUploader と MediaHttpProgressListener です。

サービス固有の生成されたライブラリのメソッドにディスカバリ ドキュメントに mediaUpload パラメータが含まれている場合は、これらのメソッド用に、InputStreamContent をパラメータとして受け取るコンビニエンス メソッドが作成されます。（Google API Discovery サービスでメディア アップロードを使用する方法については、メディア アップロードをご覧ください）。

たとえば、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 バージョンで導入されました。

再開可能なメディア アップロード プロトコルでは複数のリクエストでファイルをアップロードしますが、直接メディア アップロードではファイル全体が 1 つの HTTP リクエストでアップロードされます。直接アップロードを行うと、HTTP リクエストの数は少なくなりますが、大規模なアップロードで失敗する（接続エラーなど）可能性が高くなります。

ダイレクト メディア アップロードの使用方法は、前述の再開可能なメディア アップロードに関する説明と同じです。それに加えて、次の呼び出しで MediaHttpUploader にダイレクト アップロードのみを実行するように指示します。

mediaHttpUploader.setDirectUploadEnabled(true);