Google Drive API を使用すると、File の作成時または更新時にファイルデータをアップロードできます。フォルダなどのメタデータのみのファイルの作成方法については、メタデータのみのファイルを作成するをご覧ください。
アップロードには次の 3 種類があります。
シンプル アップロード(
uploadType=media): このアップロード タイプは、メタデータを提供せずに小さなメディア ファイル(5 MB 以下)を転送する場合に使用します。単純なアップロードを実行するには、単純なアップロードを実行するをご覧ください。マルチパート アップロード(
uploadType=multipart): 「このアップロード タイプを使用して、ファイルの説明を含むメタデータとともに、小さなファイル(5 MB 以下)を 1 回のリクエストで転送します。マルチパート アップロードを実行するには、マルチパート アップロードを実行するをご覧ください。再開可能なアップロード(
uploadType=resumable): このアップロード タイプは、サイズの大きなファイル(5 MB 超)や、モバイルアプリからファイルを作成する場合など、ネットワークが中断される可能性が高い場合に使用します。再開可能なアップロードは、アップロードごとに 1 つの HTTP リクエストを送信するだけで、サイズの小さなファイルでも利用できるため、ほとんどのアプリケーションに適しています。再開可能なアップロードを行うには、再開可能なアップロードを行うを参照してください。
Google API クライアント ライブラリは、これらのアップロードの少なくとも 1 つを実装します。各タイプの使用方法について詳しくは、クライアント ライブラリのドキュメントをご覧ください。
PATCH と PUT の使用状況
HTTP 動詞 PATCH はファイル リソースの部分的な更新をサポートし、HTTP 動詞 PUT はリソースの完全な置換をサポートします。PUT は、既存のリソースに新しいフィールドを追加するときに、互換性を損なう変更を導入する可能性があります。
ファイル リソースをアップロードする場合は、次のガイドラインを使用します。
- 再開可能なアップロードの初回リクエスト、または単純なアップロードまたはマルチパート アップロードの唯一のリクエストには、API リファレンスに記載されている HTTP 動詞を使用します。
- リクエストが開始されたら、再開可能なアップロードの後続のすべてのリクエストに
PUTを使用します。これらのリクエストは、呼び出されるメソッドに関係なくコンテンツをアップロードします。
シンプルなアップロードを実行する
シンプル アップロードを実行するには、uploadType=media を使用して files リソースの create メソッドを使用します。
次の例は、単純なアップロードを実行する方法を示しています。
HTTP
uploadType=mediaのクエリ パラメータを使用して、メソッドの /upload URI に対するPOSTリクエストを作成します。POST https://www.googleapis.com/upload/drive/v3/files?uploadType=mediaファイルのデータをリクエストの本文に追加します。
次の HTTP ヘッダーを追加します。
Content-Type: アップロードするオブジェクトの MIME メディア タイプに設定します。Content-Length: アップロードするバイト数に設定します。チャンク形式転送エンコードを使用する場合、このヘッダーは必要ありません。
リクエストを送信します。 リクエストが成功すると、サーバーは
HTTP 200 OKステータス コードとファイルのメタデータを返します。{HTTP}
シンプルなアップロードを実行すると、基本的なメタデータが作成され、MIME タイプや modifiedTime など、ファイルから一部の属性が推測されます。ファイルが小さく、ファイル メタデータが重要でない場合は、シンプルなアップロードを使用できます。
マルチパート アップロードを実行する
マルチパート アップロード リクエストを使用すると、同じリクエストでメタデータとデータをアップロードできます。送信するデータが小さく、接続が失敗したときにデータ全体を再度アップロードできる場合は、このオプションを使用します。
マルチパート アップロードを実行するには、uploadType=multipart を使用して files リソースの create メソッドを使用します。
マルチパート アップロードを実行する方法は次のとおりです。
Java
Python
Node.js
PHP
.NET
HTTP
uploadType=multipartのクエリ パラメータを使用して、メソッドの /upload URI に対するPOSTリクエストを作成します。POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipartリクエストの本文を作成します。本文の形式は multipart/related コンテンツ タイプ RFC 2387 に従います。本文には次の 2 つの部分が含まれます。
- メタデータ。メタデータは最初に配置し、
Content-Typeヘッダーをapplication/json;charset=UTF-8に設定する必要があります。ファイルのメタデータを JSON 形式で追加します。 - メディア。メディアは 2 番目に配置し、任意の MIME タイプの
Content-Typeヘッダーを指定する必要があります。ファイルのデータをメディア パーツに追加します。
最初の境界文字列の前に 2 個のハイフンを付けて、各部分を区別します。さらに、最後の境界文字列の後に 2 個のハイフンを追加します。
- メタデータ。メタデータは最初に配置し、
次のトップレベルの HTTP ヘッダーを追加します。
Content-Type。multipart/relatedに設定し、リクエストの各部分の識別に使用する境界文字列を含めます。例:Content-Type: multipart/related; boundary=foo_bar_bazContent-Length: リクエスト本文の総バイト数に設定します。
リクエストを送信します。
関連付けられたデータなしでメタデータ部分のみを作成または更新するには、POST リクエストまたは PATCH リクエストを標準リソース エンドポイント(https://www.googleapis.com/drive/v3/files)に送信します。リクエストが成功すると、サーバーは HTTP 200 OK ステータス コードとファイルのメタデータを返します。
ファイルを作成するときは、ファイルの name フィールドでファイル拡張子を指定する必要があります。たとえば、写真の JPEG ファイルを作成するときに、メタデータで "name": "photo.jpg" のようなものを指定できます。get メソッドの後続の呼び出しは、name フィールドで最初に指定された拡張機能を含む読み取り専用の fileExtension プロパティを返します。
再開可能なアップロードを実行する
再開可能なアップロードを使用すると、通信障害によってデータのフローが中断しても、アップロード オペレーションを再開できます。再開可能なアップロードでは、ネットワーク障害が発生した場合に大容量のファイルのアップロードを最初からやり直す必要がないため、使用する帯域幅を削減できます。
再開可能アップロードは、ファイルサイズが大きく異なる可能性がある場合や、リクエストに固定の時間制限がある場合(モバイル OS のバックグラウンド タスクや特定の App Engine リクエストなど)に便利です。アップロードの進行状況バーを表示する場合にも、再開可能なアップロードを使用できます。
再開可能なアップロードは、次の大まかな手順で構成されます。
- 最初のリクエストを送信し、再開可能セッション URI を取得します。
- データをアップロードし、アップロード状態をモニタリングします。
- (省略可)アップロードが中断された場合は、アップロードを再開します。
最初のリクエストを送信する
再開可能なアップロードを開始するには、uploadType=resumable を使用して files リソースの create メソッドを使用します。
HTTP
uploadType=resumableのクエリ パラメータを使用して、メソッドの /upload URI に対するPOSTリクエストを作成します。POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable開始リクエストが成功すると、
200 OKHTTP ステータス コードが返されます。また、再開可能なセッション URI を指定したLocationヘッダーも含まれます。HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0再開可能なセッション URI を保存して、ファイルデータをアップロードし、アップロード ステータスをクエリできるようにします。再開可能なセッションの URI は 1 週間後に期限切れになります。
ファイルにメタデータがある場合は、リクエストの本文に JSON 形式でメタデータを追加します。それ以外の場合には、リクエストの本文は空にしておきます。
次の HTTP ヘッダーを追加します。
X-Upload-Content-Type。省略できます。ファイルデータの MIME タイプに設定します。これは、後続のリクエストで転送されます。メタデータで、またはこのヘッダーを介してデータの MIME タイプが指定されていない場合、オブジェクトはapplication/octet-stream.として提供されます。X-Upload-Content-Length。省略できます。後続のリクエストで転送されるファイルデータのバイト数を設定します。Content-Type。ファイルにメタデータがある場合には必須です。application/json;charset=UTF-8に設定します。Content-Length。チャンク転送エンコードを使用しない場合は必須です。この開始リクエスト本文のバイト数を設定します。
リクエストを送信します。 セッション開始リクエストが成功すると、
200 OK HTTPステータス コードが返されます。また、再開可能なセッション URI を指定したLocationヘッダーも含まれます。再開可能なセッション URI を使用してファイルデータをアップロードし、アップロード ステータスを確認します。再開可能なセッションの URI は 1 週間後に期限切れになります。再開可能なセッションの URL をコピーして保存します。
コンテンツのアップロードに進みます。
コンテンツをアップロードする
再開可能なセッションでファイルをアップロードするには、2 つの方法があります。
- 1 つのリクエストでコンテンツをアップロードする: 1 つのリクエストでファイルをアップロードできる場合、1 つのリクエストに固定された時間制限がない場合、またはアップロードの進行状況インジケーターを表示する必要がない場合は、この方法を使用します。この方法は、リクエストの数が少なく、パフォーマンスが向上するため、最適です。
コンテンツを複数のチャンクでアップロードする: 1 つのリクエストで転送されるデータ量を削減する必要がある場合は、この方法を使用します。App Engine リクエストの一部のクラスのように、リクエストごとに固定の時間制限がある場合は、転送されるデータを減らす必要があることがあります。このアプローチは、アップロードの進行状況を示すカスタム インジケーターを提供する必要がある場合にも役立ちます。
HTTP - 単一リクエスト
- 再開可能なセッションの URI に
PUTリクエストを作成します。 - ファイルのデータをリクエストの本文に追加します。
- Content-Length HTTP ヘッダーを追加し、ファイルのバイト数に設定します。
- リクエストを送信します。 アップロード リクエストが中断された場合、または
5xxレスポンスを受け取った場合は、中断されたアップロードを再開するの手順に沿って対応してください。
HTTP - 複数のリクエスト
再開可能なセッションの URI に
PUTリクエストを作成します。リクエストの本文にチャンクのデータを追加します。サイズが 256 KB(256 x 1,024 バイト)の倍数になるようにチャンクを作成します(アップロードを完了する最後のチャックは除く)。アップロードを効率的に行うため、チャンクサイズはできるだけ大きくしてください。
次の HTTP ヘッダーを追加します。
Content-Length。現在のチャンクのバイト数を設定します。Content-Range: ファイルの何バイト目から何バイト目までをアップロードするかを設定します。たとえば、Content-Range: bytes 0-524287/2000000は、2, 000,000 バイトのファイルで先頭の 524,288 バイト(256 x 1,024 x 2)をアップロードすることを意味します。
リクエストを送信してレスポンスを処理します。アップロード リクエストが中断するか、
5xxレスポンスを受信したら、中断されたアップロードの再開の手順を行います。ファイルに残っているチャンクごとに手順 1 ~ 4 を繰り返します。レスポンスの
Rangeヘッダーを使用して、次のチャンクの開始位置を決定します。前のリクエストで送信したデータがすべてサーバーで受信されているとは限りません。
ファイル全体のアップロードが完了すると、200 OK または 201 Created レスポンスと、リソースに関連付けられたメタデータを受け取ります。
中断されたアップロードを再開する
レスポンスを受信する前にアップロード リクエストが終了した場合や、503
Service Unavailable レスポンスを受け取った場合は、中断されたアップロードを再開する必要があります。
HTTP
アップロードのステータスを取得するため、再開可能なセッションの URI に空の
PUTリクエストを作成します。ファイル内の現在の位置が不明であることを示す
Content-Rangeヘッダーを追加します。たとえば、ファイルの合計サイズが 2,000,000 バイトの場合は、Content-Rangeを*/2000000に設定します。ファイル全体のサイズがわからない場合は、Content-Rangeを*/*に設定します。リクエストを送信します。
レスポンスを処理します。
200 OKまたは201 Createdが返された場合、アップロードは完了しています。これ以上の操作は必要ありません。308 Resume Incompleteが返された場合、ファイルのアップロードを続行する必要があります。404 Not Foundレスポンスは、アップロード セッションが期限切れになったため、アップロードを最初からやり直す必要があることを示します。
308 Resume Incompleteが返された場合、レスポンスのRangeヘッダーを処理して、サーバーが受信したバイト数を特定します。レスポンスにRangeヘッダーがない場合、バイトは受信されていません。たとえば、Rangeヘッダーがbytes=0-42の場合、ファイルの先頭から 43 バイトを受信し、次にアップロードするチャンクは 44 バイトから始まることを意味します。これで、アップロードを再開する場所が確認できました。次のバイトからファイルのアップロードを続行します。送信するファイルの部分を示す
Content-Rangeヘッダーを含めます。たとえば、Content-Range: bytes 43-1999999は、44 バイト目から 2,000,000 バイト目までを送信することを示します。
メディア アップロード時のエラーへの対処
メディアをアップロードする際は、次のベスト プラクティスに沿ってエラーを処理してください。
5xxエラーの場合は、接続の中断が原因で失敗したアップロードを再開または再試行します。5xxエラーの処理について詳しくは、500、502、503、504 エラーを参照してください。403 rate limitエラーの場合は、アップロードを再試行します。403 rate limitエラーの処理について詳しくは、403 エラー:rateLimitExceededをご覧ください。- 再開可能なアップロード中に
4xxエラー(403を含む)が発生した場合は、アップロードを再開します。これらのエラーは、アップロード セッションが期限切れになったため、新しいセッション URI をリクエストして再開する必要があることを示します。アップロード セッションも、1 週間操作がないと期限切れになります。
Google ドキュメントにインポートするタイプ
ドライブでファイルを作成する際に、Google ドキュメントや Google スプレッドシートなどの Google Workspace ファイル形式に変換することがあります。たとえば、お気に入りのワープロで作成したドキュメントをドキュメントに変換して、その機能を利用したい場合などです。
ファイルを特定の Google Workspace ファイル形式に変換するには、ファイルを作成するときに Google Workspace mimeType を指定します。
CSV ファイルを Google Workspace スプレッドシートに変換する方法は次のとおりです。
Java
Python
Node.js
PHP
.NET
コンバージョンが利用可能かどうかを確認するには、ファイルを作成する前に about リソースの importFormats フィールドを確認します。サポートされている変換は、この配列で動的に利用できます。一般的なインポート形式は次のとおりです。
| 差出人 | 宛先 |
|---|---|
| Microsoft Word、OpenDocument テキスト、HTML、RTF、書式なしテキスト | Google ドキュメント |
| Microsoft Excel、OpenDocument スプレッドシート、CSV、TSV、プレーン テキスト | Google スプレッドシート |
| Microsoft PowerPoint、OpenDocument プレゼンテーション | Google スライド |
| JPEG、PNG、GIF、BMP、PDF | Google ドキュメント(ドキュメントに画像を埋め込む) |
| プレーン テキスト(特殊な MIME タイプ)、JSON | Google Apps Script |
update リクエスト中にメディアをアップロードしてドキュメント、スプレッドシート、スライドのファイルに変換すると、ドキュメントのコンテンツ全体が置き換えられます。
画像をドキュメントに変換すると、ドライブは光学式文字認識(OCR)を使用して画像をテキストに変換します。該当する BCP 47 言語コードを ocrLanguage パラメータで指定すると、OCR アルゴリズムの品質を向上させることができます。抽出されたテキストが、埋め込まれた画像の横に表示されます。
事前生成された ID を使用してファイルをアップロードする
Drive API を使用すると、リソースの作成、コピー、アップロードに使用できる事前生成されたファイル ID のリストを取得できます。詳細については、ファイルで使用する ID を生成するをご覧ください。
サーバーエラーやタイムアウトが原因でアップロードが失敗した場合は、事前に生成された ID を使用して安全に再試行できます。ファイル アクションが成功した場合、後続の再試行では 409 Conflict HTTP ステータス コード レスポンスが返され、重複するファイルは作成されません。
application/vnd.google-apps.drive-sdk と application/vnd.google-apps.folder の MIME タイプを除き、事前生成された ID は Google Workspace ファイルの作成ではサポートされていません。同様に、Google Workspace ファイル形式への変換を参照するアップロードもサポートされていません。
不明なファイル形式のインデックス登録可能なテキストを定義する
ユーザーはドライブの UI を使用してドキュメントのコンテンツを見つけることができます。また、files リソースの list メソッドと fullText フィールドを使用して、アプリのコンテンツを検索することもできます。詳しくは、ファイルとフォルダを検索するをご覧ください。
ドライブでは、テキスト ドキュメント、PDF、テキストを含む画像など、一般的なファイル形式が認識されると、検索用にドキュメントが自動的にインデックスに登録されます。アプリが他の種類のファイル(図面、動画、ショートカットなど)を保存する場合は、ファイルの contentHints.indexableText フィールドにインデックス可能なテキストを指定することで、検出可能性を高めることができます。
インデックス登録可能なテキストの詳細については、ファイル メタデータを管理するをご覧ください。