ファイルをアップロードする

Drive APIは、Fileリソースを createする、あるいは updateするとき、あなたが、ファイルデータをアップロードできるようにします。

メディアをアップロードするとき、特別な URIを使用します。 メディアのアップデートをサポートする方法には、次の 2つの URIエンドポイントがあります:

• /upload URI、それは、メディア用です。 /uploadエンドポイントの形式は、/upload接頭辞を伴う標準的なリソース URIです。 メディアデータ自体を転送するとき、この URIを使用します。 例: POST /upload/drive/v3/files。
• 標準的なリソース URI、それは、メタデータ用です。 もしリソースが任意のデータフィールドを含んでいるならば、それらのフィールドは、アップロードされたファイルを説明するメタデータを格納するために使用されます。 メタデータの値を作成あるいは更新したとき、この URIを使用することができます。 例: POST /drive/v3/files。

アップロードのタイプ

実行することができるアップロードは、3種類あります:

• シンプルアップロード: uploadType=media。 小さなファイル(5MB以下)の素早い転送のために。 シンプルアップロードを実行するには、シンプルアップロードを実行するを参照してください。

• マルチパートアップロード: uploadType=multipart。 小さなファイル(5MB以下)、およびファイルを説明するメタデータの素早い転送のため、それは、単一のリクエストがすべてです。 マルチパートアップロードを実行するには、マルチパートアップロードを実行するを参照してください。

• 再開可能なアップロード: uploadType=resumable。 より信頼性の高い転送のために、大きなファイルを用いる場合には特に重要です。 再開可能なアップロードは、ほとんどのアプリケーションのためのグッドチョイスです、なぜなら、それらは、アップロードごとに 1つの追加の HTTPリクエストのコストで小さなファイルのために動作するからです。 再開可能なアップロードを実行するには、再開可能なアップロードを実行するを参照してください。

ほとんどの Goolge APIクライアントライブラリは、少なくとも 1つのメソッドを実装しています。 それぞれのメソッドの使用方法についての詳細については、クライアントライブラリのドキュメントを参照してください。

シンプルアップロードを実行する

シンプルアップロードは、ファイルをアップロードするための最も簡単な方法です。 次の場合に、このオプションを使用してください:

• 接続が失敗した場合、ファイルは、その全体を再びアップロードするのに十分に小さいです。
• 送信するメタデータがありません。 別のリクエストにて、ファイルのためのメタデータを送信する計画がある場合、あるいは、利用可能なメタデータががない場合、これが当てはまるかもしれません。

もしファイルのためにメタデータを提供する必要があるならば、代わりに、マルチパートアップロードあるいは再開可能なアップロードを使用することができます。

より大きなファイル(5MB以上)、あるいは、信頼性の低いネットワーク接続の場合は、再開可能なアップロードを使用してください。

次の例は、クライアントライブラリを使用して画像をアップロードする方法を示しています:

File fileMetadata = new File();
fileMetadata.setName("photo.jpg");
java.io.File filePath = new java.io.File("files/photo.jpg");
FileContent mediaContent = new FileContent("image/jpeg", filePath);
File file = driveService.files().create(fileMetadata, mediaContent)
    .setFields("id")
    .execute();
System.out.println("File ID: " + file.getId());

file_metadata = {'name': 'photo.jpg'}
media = MediaFileUpload('files/photo.jpg',
                        mimetype='image/jpeg')
file = drive_service.files().create(body=file_metadata,
                                    media_body=media,
                                    fields='id').execute()
print 'File ID: %s' % file.get('id')

$fileMetadata = new Google_Service_Drive_DriveFile(array(
    'name' => 'photo.jpg'));
$content = file_get_contents('files/photo.jpg');
$file = $driveService->files->create($fileMetadata, array(
    'data' => $content,
    'mimeType' => 'image/jpeg',
    'uploadType' => 'multipart',
    'fields' => 'id'));
printf("File ID: %s\n", $file->id);

var fileMetadata = new File()
{
    Name = "photo.jpg"
};
FilesResource.CreateMediaUpload request;
using (var stream = new System.IO.FileStream("files/photo.jpg",
                        System.IO.FileMode.Open))
{
    request = driveService.Files.Create(
        fileMetadata, stream, "image/jpeg");
    request.Fields = "id";
    request.Upload();
}
var file = request.ResponseBody;
Console.WriteLine("File ID: " + file.Id);

file_metadata = {
    name: 'photo.jpg'
}
file = drive_service.create_file(file_metadata,
                                 fields: 'id',
                                 upload_source: 'files/photo.jpg',
                                 content_type: 'image/jpeg')
puts "File Id: #{file.id}"
file_metadata = {}
file = drive_service.update_file(id,
                                 file_metadata,
                                 fields: 'id',
                                 upload_source: 'files/photo.jpg',
                                 content_type: 'image/jpeg')
puts "File Id: #{file.id}"

var fileMetadata = {
  'name': 'photo.jpg'
};
var media = {
  mimeType: 'image/jpeg',
  body: fs.createReadStream('files/photo.jpg')
};
drive.files.create({
  resource: fileMetadata,
  media: media,
  fields: 'id'
}, function (err, file) {
  if (err) {
    // Handle error
    console.error(err);
  } else {
    console.log('File Id: ', file.id);
  }
});

NSData *fileData = [[NSFileManager defaultManager] contentsAtPath:@"files/photo.jpg"];

GTLRDrive_File *metadata = [GTLRDrive_File object];
metadata.name = @"photo.jpg";

GTLRUploadParameters *uploadParameters = [GTLRUploadParameters uploadParametersWithData:fileData
                                                                               MIMEType:@"image/jpeg"];
uploadParameters.shouldUploadWithSingleRequest = TRUE;
GTLRDriveQuery_FilesCreate *query = [GTLRDriveQuery_FilesCreate queryWithObject:metadata
                                                               uploadParameters:uploadParameters];
query.fields = @"id";
[driveService executeQuery:query completionHandler:^(GTLRServiceTicket *ticket,
                                                     GTLRDrive_File *file,
                                                     NSError *error) {
    if (error == nil) {
        NSLog(@"File ID %@", file.identifier);
    } else {
        NSLog(@"An error occurred: %@", error);
    }
}];

シンプルアップロードのリクエストを送信する

シンプルアップロードを使用するには:

1. メソッドの /upload URIへの POSTリクエストを作成します。 既存のファイルを更新するには、PUTを使用します。

2. クエリパラメータ uploadType=media を追加します。

   例えば:

   POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media

3. リクエストボディにファイルのデータを追加します。

4. 次の HTTPヘッダを追加します。

   • Content-Type。 アップロードされるオブジェクトの MIMEメディアタイプをセットします。
   • Content-Length。 アップロードしているバイト数をセットします。 この見出しは、chunked transfer encodingを使用している場合には、必要ありません。

5. リクエストを送信します。

例: シンプルアップロードリクエストを送信する

次の例は、シンプルアップロードリクエストを示しています:

POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media HTTP/1.1
Content-Type: image/jpeg
Content-Length: [NUMBER_OF_BYTES_IN_FILE]
Authorization: Bearer [YOUR_AUTH_TOKEN]

[JPEG_DATA]

もしリクエストが成功したならば、サーバは、ファイルのメタデータとともに、HTTP 200 OKステータスコードを返します。

HTTP/1.1 200
Content-Type: application/json

{
  "name": "myObject"
}

エラー処理については、エラーを処理するを参照してください。

マルチパートアップロードを実行する

マルチパートアップロードのリクエストは、あなたに、アップロードするデータと一緒にメタデータを送信できるようにします。 接続が失敗した場合に、もし、送信しているデータが、その全体を再びアップロードするのに十分小さいならば、このオプションを使用します。

もしあなたのファイルがメタデータを持っていなければ、代わりに、シンプルアップロードを使用してください。 より大きなファイル(5MB以上)、あるいは、信頼性の低いネットワーク接続の場合は、代わりに、再開可能なアップロードを使用してください。

マルチパートアップロードのリクエストを送信する

マルチパートアップロードを使用するには:

1. メソッドの /upload URIへの POSTリクエストを作成します。 既存のファイルを更新するには、PUTを使用します。

2. クエリパラメータ uploadType=multipart を追加します。

   例えば:

   POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart

3. リクエストのボディを作成します。 multipart/relatedコンテンツタイプ [RFC 2387] に従って、ボディをフォーマットします、それは、2つの部分を含んでいます:

   1. メタデータ部分。 最初に来なければならず、application/json; charset=UTF-8 がセットされた Content-Typeヘッダを持っていなければなりません。 ファイルのメタデータを、この部分に、JSON形式で追加します。
   2. メディア部分。 2番目に来なければならず、Content-Typeヘッダを持っていなければなりません、それは、任意の MIMEタイプを持つかもしれません。 ファイルのデータを、この部分に追加します。

   それぞれの部分を境界文字列を用いて識別します、それは、2つのハイフンが前についています。 さらに、最後の境界文字列の後に、2つのハイフンを追加します。

4. 次のトップレベルの HTTPヘッダを追加します:

   • Content-Type。 multipart/relatedにセットし、リクエストの異なる部分を識別するために使用している境界文字列を含みます。 例えば: Content-Type: multipart/related; boundary=foo_bar_baz
   • Content-Length。 リクエストボディ内のバイト数の合計をセットします。

5. リクエストを送信します。

例: マルチパートアップロードのリクエストを送信する

次の例は、マルチパートアップロードのリクエストを示しています:

POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: [NUMBER_OF_BYTES_IN_ENTIRE_REQUEST_BODY]

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "name": "myObject"
}

--foo_bar_baz
Content-Type: image/jpeg

[JPEG_DATA]
--foo_bar_baz--

もしリクエストが成功したならば、サーバは、ファイルのメタデータとともに、HTTP 200 OKステータスコードを返します:

HTTP/1.1 200
Content-Type: application/json

{
  "name": "myObject"
}

エラー処理については、エラーを処理するを参照してください。

再開可能なアップロードを実行する

このプロトコルは、通信エラーがデータのフローを中断した後、アップロード操作を再開できるようにします。 次の場合に、このオプションを使用します:

• 大きなファイルを転送している。
• ネットワークの中断や幾つかのその他の送信障害の可能性が高い(例えば、モバイルアプリからファイルをアップロードしている場合)。

さらには、再開可能なアップロードは、ネットワークに障害があるとき、あなたの帯域幅の使用量を減らすことができます、なぜならば、大きなファイルのアップロードを最初から再スタートする必要がないからです。

もし信頼性の高いネットワーク接続で小さなファイルを送信しているならば、代わりに、シンプルアップロードあるいは マルチパートアップロードを使用することができます。

リクエスト URIについて学ぶ

メディアをアップロードするとき、特別な URIを使用します。 実際、メディアのアップロードをサポートするメソッドは、2つの URIエンドポイントを持っています:

• メディアのための /upload URI。 /uploadエンドポイントの形式は、/upload接頭辞を伴う、標準的なリソース URIです。 メディアデータ自体を転送するとき、この URIを使用します。 例: POST /upload/drive/v3/files。
• メタデータのための、標準的なリソース URI。 もしリソースが任意のデータフィールドを含んでいるならば、これらのフィールドは、アップロードされたファイルを説明するメタデータを格納するために使用されます。 メタデータの値を作成あるいは更新するとき、この URIを使用することができます。 例: POST /drive/v3/files。

再開可能なアップロードのセッションを開始する

再開可能なアップロードのセッションを開始するには:

1. メソッドの /upload URIへのリクエストを作成します。 新しいファイルを作成するには、POSTを使用します。 既存のファイルを更新するには、PUTを使用します。

2. クエリパラメータ uploadType=resumable を追加します。

   例えば:

   POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable

   あるいは:

   PUT https://www.googleapis.com/upload/drive/v3/files/[FILE_ID]?uploadType=resumable

3. もしファイルのメタデータを持っているならば、JSON形式にて、リクエストボディにメタデータを追加します。 それ以外の場合は、リクエストボディを空のままにします。

4. 次の HTTPヘッダを追加します:

   • X-Upload-Content-Type。 オプション。 ファイルデータの MIMEタイプをセットします、それは、後続のリクエストにて転送されるでしょう。 もしデータの MIMEタイプがメタデータ内で、あるいは、このヘッダを介して指定されていなければ、オブジェクトは、application/octet-streamとして提供されるでしょう。
   • X-Upload-Content-Length。 オプション。 ファイルデータのバイト数をセットします、それは、後続のリクエストにて転送されるでしょう。
   • Content-Type。 ファイルのメタデータを持っている場合は、必須。 application/json; charset=UTF-8にセットします。
   • Content-Length。 chunked transfer encodingを使用していない限り、必須。 この最初のリクエストのボディ内のバイト数をセットします。

5. リクエストを送信します。

例: 再開可能なアップロードのセッションを開始する

次の例は、新しいファイルをアップロードするために再開可能なセッションを開始する方法を示しています:

POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "myObject"
}

次のセクションでは、レスポンスを処理する方法について説明しています。

再開可能なセッション URIを保存する

もしセッション開始リクエストが成功したならば、応答は 200 OK HTTPステータスコードを含んでいます。 さらに、それは、再開可能なセッション URIを指定する Locationヘッダを含んでいます。 ファイルデータをアップロードし、アップロード状態をクエリするには、再開可能なセッション URIを使用します。

再開可能なセッション URIをコピーし保存することで、後続のリクエストのためにそれを使用することができます。

例: 再開可能なセッション URIを保存する

次の例は、再開可能なセッション URIを含むレスポンスを示しています。

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

ファイルをアップロードする

再開可能なセッションを用いてファイルをアップロードするには、次の 2つの方法があります:

1. 単一のリクエストにて。 このアプローチは、通常、ベストです、なぜなら、それはより少ないリクエストを必要とし、より良いパフォーマンスを持つからです。
2. 複数のチャンクにて。 次の場合に、このアプローチを使用します:
   • 任意の単一のリクエストにて転送されるデータの量を減らす必要があります。 Google App Engineのリクエストの特定のクラスにも当てはまるように、個々のリクエストに一定の時間制限があるとき、これを行う必要があるかもしれません。
   • アップロードの進行状況を示す、カスタマイズされたインジケータを提供する必要があります。

例: ファイルをアップロードする

PUT https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

[BYTES 0-1999999]

PUT https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

[BYTES 0-524287]

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

中断されたアップロードを再開する

もしアップロードリクエストがレスポンスを受信する前に終了したならば、あるいは、もし 503 Service Unavailableレスポンスを受け取ったならば、中断されたアップロードを再開する必要があります。 これを行うには：

1. アップロード状態をリクエストするために、再開可能なセッション URIへの空の PUTリクエストを作成します。

2. ファイル内の現在の位置が不明であることを示す Content-Rangeヘッダを追加します。

   例えば、あなたのファイル長さの合計が 2,000,000バイトの場合、Content-Rangeに */2000000をセットします。

   もし完全なファイルサイズを知らなければ、Content-Rangeに */*をセットします。

3. リクエストを送信します。

4. レスポンスを処理します。

   • 200 OKあるいは 201 Createdレスポンスは、アップロードが完了し、それ以上のアクションが必要ないことを示しています。
   • 308 Resume Incompleteレスポンスは、ファイルをアップロードすることを続ける必要があることを示しています。
   • 404 Not Foundレスポンスは、アップロードセッションが失効し、アップロードが最初から再スタートされる必要があることを示します。

5. もし 308 Resume Incompleteレスポンスを受信したならば、レスポンスの Rangeヘッダを処理します、それは、サーバがこれまでどのバイトを受信したかを指定しています。 まだバイトをまったく受信していない場合、レスポンスは、Rangeヘッダを持たないでしょう。

   例えば、bytes=0-42の Rangeヘッダは、ファイルの最初の 43バイトが受信されrたことを示しています。

6. 今や、アップロードを再開するための場所を知ったので、残りのデータを送信することによって、あるいは次のチャンクを送信することによって、のいずれかで、ファイルをアップロードすることを続けます。 ファイルのどの部分を送信しているかを示す、Content-Rangeヘッダを含んでいます。

   例えば、Content-Range: bytes 43-1999999/2000000 は、43から 1,999,999までのバイトを送信していることを示します。

例: 中断されたアップロードを再開する

次の例は、アップロード状態のためのリクエストを示しています:

PUT https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

サーバのレスポンスは、これまでにファイルの最初の 43バイトを受信したことを示す Rangeヘッダを使用します:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-42

それから、43バイトから開始する、ファイルの残りのバイトを送信することによって、アップロードを再開するためのリクエストを送信することができます:

PUT https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

[BYTES 43-1999999]

エラーを処理する

メディアをアップロードするとき、エラー処理に関連する以下のベストプラクティスに従ってください:

• 接続の中断、あるいは任意の 5xxエラーのために失敗したアップロードを、再開あるいはリトライします、それは、次を含みます:
  • 500 Internal Server Error
  • 502 Bad Gateway
  • 503 Service Unavailable
  • 504 Gateway Timeout
• 403レート制限エラーのために失敗したアップロードを、再開あるいはリトライします。
• アップロードリクエストを再開あるいはリトライするとき、任意の 403あるいは 5xxサーバエラーが返された場合、指数バックオフ戦略を使用します。 これらのエラーは、サーバが過負荷になった場合に発生する可能性があります。 指数バックオフは、大量のリクエストあるいは重いネットワークトラフィックがあるとき、これらの種類の問題を緩和するのに役立つ可能性があります。
• (再開可能なアップロードのみ) チャンクを再開あるいはアップロードしようとした後、404 Not Foundエラーが受信された場合、アップロードを再スタートしてください。 これは、アップロードセッションが失効し、最初から再スタートされなければならないことを示しています。 アップロードセッションは、1週間の非アクティブの後に失効します。

詳細については、APIエラーを処理するを参照してください。

Google Docsタイプをインポートする

Google Drive内にファイルを作成するとき、ファイルの mimeTypeプロパティを指定することによって、幾つかのタイプのファイルを、Google Docs、Sheets、あるいは Slidesドキュメントに変換することができます。 次のサンプルは、スプレッドシートとして CSVファイルをアップロードする方法を示しています:

File fileMetadata = new File();
fileMetadata.setName("My Report");
fileMetadata.setMimeType("application/vnd.google-apps.spreadsheet");

java.io.File filePath = new java.io.File("files/report.csv");
FileContent mediaContent = new FileContent("text/csv", filePath);
File file = driveService.files().create(fileMetadata, mediaContent)
    .setFields("id")
    .execute();
System.out.println("File ID: " + file.getId());

file_metadata = {
    'name': 'My Report',
    'mimeType': 'application/vnd.google-apps.spreadsheet'
}
media = MediaFileUpload('files/report.csv',
                        mimetype='text/csv',
                        resumable=True)
file = drive_service.files().create(body=file_metadata,
                                    media_body=media,
                                    fields='id').execute()
print 'File ID: %s' % file.get('id')

$fileMetadata = new Google_Service_Drive_DriveFile(array(
    'name' => 'My Report',
    'mimeType' => 'application/vnd.google-apps.spreadsheet'));
$content = file_get_contents('files/report.csv');
$file = $driveService->files->create($fileMetadata, array(
    'data' => $content,
    'mimeType' => 'text/csv',
    'uploadType' => 'multipart',
    'fields' => 'id'));
printf("File ID: %s\n", $file->id);

var fileMetadata = new File()
{
    Name = "My Report",
    MimeType = "application/vnd.google-apps.spreadsheet"
};
FilesResource.CreateMediaUpload request;
using (var stream = new System.IO.FileStream("files/report.csv",
                        System.IO.FileMode.Open))
{
    request = driveService.Files.Create(
        fileMetadata, stream, "text/csv");
    request.Fields = "id";
    request.Upload();
}
var file = request.ResponseBody;
Console.WriteLine("File ID: " + file.Id);

file_metadata = {
    name: 'My Report',
    mime_type: 'application/vnd.google-apps.spreadsheet'
}
file = drive_service.create_file(file_metadata,
                                 fields: 'id',
                                 upload_source: 'files/report.csv',
                                 content_type: 'text/csv')
puts "File Id: #{file.id}"

var fileMetadata = {
  'name': 'My Report',
  'mimeType': 'application/vnd.google-apps.spreadsheet'
};
var media = {
  mimeType: 'text/csv',
  body: fs.createReadStream('files/report.csv')
};
drive.files.create({
  resource: fileMetadata,
  media: media,
  fields: 'id'
}, function (err, file) {
  if (err) {
    // Handle error
    console.error(err);
  } else {
    console.log('File Id:', file.id);
  }
});

NSData *fileData = [[NSFileManager defaultManager] contentsAtPath:@"files/report.csv"];

GTLRDrive_File *metadata = [GTLRDrive_File object];
metadata.name = @"My Report";
metadata.mimeType = @"application/vnd.google-apps.spreadsheet";

GTLRUploadParameters *uploadParameters = [GTLRUploadParameters uploadParametersWithData:fileData
                                                                               MIMEType:@"text/csv"];
uploadParameters.shouldUploadWithSingleRequest = TRUE;
GTLRDriveQuery_FilesCreate *query = [GTLRDriveQuery_FilesCreate queryWithObject:metadata
                                                               uploadParameters:uploadParameters];
query.fields = @"id";
[driveService executeQuery:query completionHandler:^(GTLRServiceTicket *ticket,
                                                     GTLRDrive_File *file,
                                                     NSError *error) {
    if (error == nil) {
        NSLog(@"File ID %@", file.identifier);
    } else {
        NSLog(@"An error occurred: %@", error);
    }
}];

サポートされる変換は、About resource'sの importFormats配列にて動的に利用可能で、次を含んでいます:

Google Doc、Sheet、あるいは Slideへの updateリクエスト中のメディアをアップロードし、変換するとき、ドキュメントのフルなコンテンツが置換されるでしょう。

画像を変換しているとき、ocrLanguageパラメータにて、適切な BCP 47言語コードを指定することによって、OCRアルゴリズムの品質を改善させることができます。 抽出されたテキストは、組み込まれた画像と一緒に Google Docsドキュメントに表示されるでしょう。

事前生成された IDを使用してアップロードする

Drive APIは、リソースをアップロードし作成するために使用されることができる、事前に生成されたファイル IDのリストを取得できるようにします。 アップロードおよびファイル作成リクエストは、ファイルのメタデータ内の idフィールドをセットすることによって、これらの事前生成された IDを含むことができます。

不確定なサーバエラーあるいはタイムアウトの場合、事前に生成された IDを用いて、安全にアップロードをリトライすることができます。 もしファイルが正常に作成されたならば、後続のリトライは、重複したファイルを作成する代わりに、HTTP 409エラーを返します。

備考: 事前生成された IDは、ネイティブの Google Documentの作成ではサポートされていません、あるいは、ネイティブの Google Document形式への変換がリクエストされたとき、アップロードします。