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_baz
Content-Length
: リクエスト本文の総バイト数に設定します。
リクエストを送信します。
関連するデータなしでメタデータ部分のみを作成または更新するには、POST
リクエストまたは PATCH
リクエストを標準リソース エンドポイント(https://www.googleapis.com/drive/v3/files
)に送信します。リクエストが成功すると、サーバーから HTTP 200 OK
ステータス コードとファイルのメタデータが返されます。
ファイルを作成するときに、ファイルの name
フィールドにファイル拡張子を指定する必要があります。たとえば、写真の JPEG ファイルを作成する場合は、メタデータに "name": "photo.jpg"
のような値を指定します。その後の files.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 OK
HTTP ステータス コードが返されます。また、再開可能なセッション 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 Workspace ファイル形式に変換することをおすすめします。たとえば、お気に入りのワード プロセッサのドキュメントを Google ドキュメントに変換して、その機能を活用したい場合があります。
ファイルを特定の Google Workspace ファイル形式に変換するには、ファイルを作成するときに Google Workspace mimeType
を指定します。
次の手順では、CSV ファイルを Google Workspace シートに変換する方法について説明します。
Java
Python
Node.js
PHP
.NET
変換が利用可能かどうかを確認するには、ファイルを作成する前に about
リソースの importFormats
配列を確認します。サポートされているコンバージョンは、この配列で動的に利用できます。一般的なインポート形式は次のとおりです。
From | 終了日 |
---|---|
Microsoft Word、OpenDocument Text、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)を使用して画像をテキストに変換します。ocrLanguage
パラメータで該当する BCP 47 言語コードを指定すると、OCR アルゴリズムの品質を向上させることができます。抽出されたテキストが、埋め込まれた画像の横にドキュメントに表示されます。
事前に生成された ID を使用してファイルをアップロードする
Drive API を使用すると、リソースのアップロードと作成に使用される事前生成されたファイル ID のリストを取得できます。アップロード リクエストとファイル作成リクエストでは、これらの事前生成 ID を使用できます。ファイル メタデータの id
フィールドを設定します。
事前生成された ID を作成するには、作成する ID の数を指定して files.generateIds
を呼び出します。
サーバーエラーやタイムアウトが原因で原因が特定できない場合は、事前に生成された ID を使用してアップロードを安全に再試行できます。ファイルが正常に作成された場合、その後の再試行は HTTP 409
エラーを返します。重複するファイルは作成されません。
不明なファイル形式のインデックス登録テキストを定義する
ユーザーはドライブの UI を使用してドキュメントのコンテンツを検索できます。files.list
と fullText
フィールドを使用して、アプリ内のコンテンツを検索することもできます。詳しくは、ファイルとフォルダを検索するをご覧ください。
ドライブは、テキスト ドキュメント、PDF、テキストを含む画像など、一般的なファイル形式を認識すると、検索用にドキュメントを自動的にインデックスに登録します。アプリが他の種類のファイル(描画、動画、ショートカットなど)を保存する場合は、ファイルの contentHints.indexableText
フィールドにインデックス登録可能なテキストを指定することで、検出可能性を高めることができます。
インデックス登録可能なテキストの詳細については、ファイル メタデータを管理するをご覧ください。