長時間実行オペレーション（LRO）は、API レスポンスに適した時間よりも完了に時間がかかる API メソッドです。通常、タスクの実行中に呼び出しスレッドを開いたままにすると、ユーザー エクスペリエンスが低下するため、避けるべきです。代わりに、ユーザーに何らかの Promise を返し、後で確認できるようにすることをおすすめします。
Google Drive API は、files リソースで download メソッドを呼び出して、Drive API またはそのクライアント ライブラリを介してファイルの内容をダウンロードするたびに、LRO を返します。
このメソッドは、クライアントに operations リソースを返します。operations リソースを使用すると、get メソッドでオペレーションをポーリングして、API メソッドのステータスを非同期で取得できます。Drive API の LRO は、 Google Cloud LRO 設計パターンに準拠しています。
詳細については、長時間実行オペレーションをご覧ください。
プロセスの概要
次の図は、file.download メソッドの仕組みの概要を示しています。
files.downloadを呼び出す: アプリがdownloadメソッドを呼び出すと、そのファイルの Drive API ダウンロード リクエストが開始されます。詳しくは、ファイルをダウンロードするをご覧ください。権限をリクエストする: リクエストは認証情報を Drive API に送信します。アプリで、まだ付与されていないユーザーの認証を使用して Drive API を呼び出す必要がある場合、ユーザーにログインを求めるメッセージが表示されます。アプリは、認証の設定時に指定したスコープを使用してアクセスを要求します。
ダウンロードを開始: ファイルのダウンロードを開始するために、Drive API リクエストが作成されます。リクエストは Google Vids または他の Google Workspace コンテンツに対して行われる可能性があります。
LRO を開始: 長時間実行オペレーションが開始され、ダウンロード プロセスが管理されます。
保留中のオペレーションを返す: Drive API は、リクエストを行うユーザーに関する情報と複数のファイル メタデータ フィールドを含む保留中のオペレーションを返します。
初期保留状態: アプリは、保留中のオペレーションと、
done=nullの初期保留状態を受け取ります。これは、ファイルがまだダウンロードの準備ができておらず、オペレーションのステータスが保留中であることを示します。operations.getを呼び出して結果を確認する: アプリは推奨される間隔でgetを呼び出して、オペレーションの結果をポーリングし、長時間実行オペレーションの最新の状態を取得します。done=falseの保留状態が返された場合、アプリはオペレーションが完了状態（done=true）を返すまでポーリングを続ける必要があります。大きなファイルの場合は、複数回のポーリングが想定されます。詳細については、長時間実行オペレーションの詳細を取得するをご覧ください。保留中の状態を確認する: LRO から
done=trueの保留中の状態が返された場合、これはファイルがダウンロードの準備ができており、オペレーション ステータスが完了していることを示します。ダウンロード URI を含む完了したオペレーションを返す: LRO が完了すると、Drive API はダウンロード URI を返し、ユーザーがファイルを利用できるようになります。
ファイルをダウンロードする
長時間実行オペレーションでコンテンツをダウンロードするには、files リソースで download メソッドを使用します。このメソッドは、file_id、mime_type、revision_id のクエリ パラメータを受け取ります。
必須。
file_idクエリ パラメータは、ダウンロードするファイルの ID です。省略可。
mime_typeクエリ パラメータは、メソッドが使用する MIME タイプを示します。これは、非 BLOB メディア コンテンツ（Google Workspace ドキュメントなど）をダウンロードする場合にのみ使用できます。サポートされている MIME タイプの完全なリストについては、Google Workspace ドキュメントのエクスポート MIME タイプをご覧ください。MIME タイプが設定されていない場合、Google Workspace ドキュメントはデフォルトの MIME タイプでダウンロードされます。詳細については、デフォルトの MIME タイプをご覧ください。
省略可。
revision_idクエリ パラメータは、ダウンロードするファイルのリビジョン ID です。この機能は、BLOB ファイル、Google ドキュメント、Google スプレッドシートをダウンロードする場合にのみ使用できます。サポートされていないファイルで特定のリビジョンをダウンロードすると、エラーコードINVALID_ARGUMENTを返します。
download メソッドは、Vids ファイルを MP4 形式でダウンロードする唯一の方法であり、通常はほとんどの動画ファイルのダウンロードに最適です。
Google ドキュメントまたはスプレッドシート用に最初に生成されたダウンロード リンクは、リダイレクトを返します。新しいリンクをクリックしてファイルをダウンロードします。
LRO を開始する download メソッドへのリクエストと、最終的なダウンロード URI を取得するリクエストの両方で、リソースキーを使用する必要があります。詳しくは、リソースキーを使用してリンク共有されたドライブ ファイルにアクセスするをご覧ください。
リクエスト プロトコルがここに表示されます。
POST https://www.googleapis.com/drive/v3/files/{FILE_ID}/downloadFILE_ID は、ダウンロードするファイルの fileId に置き換えます。
デフォルトの MIME タイプ
blob 以外のコンテンツをダウンロードするときに MIME タイプが設定されていない場合は、次のデフォルトの MIME タイプが割り当てられます。
| ドキュメントの種類 | 形式 | MIME タイプ | ファイル拡張子 |
|---|---|---|---|
| Google Apps Script | JSON | application/vnd.google-apps.script+json | .json |
| Google ドキュメント | Microsoft Word | application/vnd.openxmlformats-officedocument.wordprocessingml.document | .docx |
| Google 図形描画 | PNG | image/png | .png |
| Google フォーム | ZIP | application/zip | .zip |
| Google スプレッドシート | Microsoft Excel | application/vnd.openxmlformats-officedocument.spreadsheetml.sheet | .xlsx |
| Google サイト | Raw Text | text/raw | .txt |
| Google スライド | Microsoft PowerPoint | application/vnd.openxmlformats-officedocument.presentationml.presentation | .pptx |
| Google Vids | MP4 | application/mp4 | .mp4 |
| Jamboard | application/pdf |
ダウンロード レスポンス
download メソッドを呼び出すと、レスポンス本文は、長時間実行オペレーションを表すリソースで構成されます。通常、このメソッドはファイルの内容をダウンロードするためのリンクを返します。
{
"done": true,
"metadata": {
"@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileMetadata",
"resourceKey": "RESOURCE_KEY"
},
"name": "NAME",
"response": {
"@type": "type.googleapis.com/google.apps.drive.v3.DownloadFileResponse",
"downloadUri": "DOWNLOAD_URI",
"partialDownloadAllowed": false
}
}
この出力には次の値が含まれます。
RESOURCE_KEY: リソースキーは、ファイルが意図しないアクセスから保護されるようにします。詳細については、リソースキーを使用してリンク共有されたドライブ ファイルにアクセスするをご覧ください。
NAME: サーバー割り当て名。
DOWNLOAD_URI: ファイルの最終的なダウンロード URI。
partialDownloadAllowed フィールドは、部分ダウンロードが許可されているかどうかを示します。BLOB ファイルのコンテンツをダウンロードする場合は true。
長時間実行オペレーションの詳細を取得する
長時間実行オペレーションとは、完了までに膨大な時間がかかる可能性があるメソッドの呼び出しです。通常、新しく作成されたダウンロード オペレーションは、特に Google Vids ファイルの場合、最初は保留状態（done=null）で返されます。
Drive API が提供する operations リソースを使用して、サーバー割り当ての一意の名前を含めることで、処理 LRO のステータスを確認できます。
get メソッドは、長時間実行オペレーションの最新の状態を非同期で取得します。クライアントはこのメソッドを使用して、API サービスで推奨される間隔でオペレーションの結果をポーリングできます。
長時間実行オペレーションをポーリングする
使用可能な LRO をポーリングするには、オペレーションが完了するまで get メソッドを繰り返し呼び出します。各ポーリング リクエスト間で指数バックオフ（たとえば、10 秒）を使用します。
LRO は最低 12 時間使用できますが、場合によってはそれ以上存続することもあります。この期間は変更される可能性があり、ファイル形式によって異なる場合があります。リソースの有効期限が切れた場合は、新しい download メソッド リクエストが必要です。
get へのリクエストでは、リソースキーを使用する必要があります。詳しくは、リソースキーを使用してリンク共有されたドライブ ファイルにアクセスするをご覧ください。
リクエスト プロトコルがここに表示されます。
メソッド呼び出し
operations.get(name='NAME');
NAME は、download メソッド リクエストのレスポンスに示されているオペレーションのサーバー割り当て名に置き換えます。
curl
curl -i -H \
'Authorization: Bearer $(gcloud auth print-access-token)" \
'https://googleapis.com/drive/v3/operations/NAME?alt=json'
NAME は、download メソッド リクエストのレスポンスに示されているオペレーションのサーバー割り当て名に置き換えます。
このコマンドではパス /drive/v3/operations/NAME を使用します。
name は、download リクエストに対するレスポンスでのみ返されます。Drive API は List メソッドをサポートしていないため、この方法以外で取得することはできません。name の値が失われた場合は、download メソッド リクエストを再度呼び出して新しいレスポンスを生成する必要があります。
get リクエストからのレスポンスは、長時間実行オペレーションを表すリソースで構成されます。詳細については、ダウンロード レスポンスをご覧ください。
レスポンスに完了状態（done=true）が含まれている場合、長時間実行オペレーションは終了しています。
リビジョンをダウンロードする
files リソースの headRevisionId フィールドの値を使用して、最新のリビジョンをダウンロードできます。これにより、以前に取得したファイルのメタデータに対応するリビジョンが取得されます。クラウドにまだ保存されているファイルの以前のすべてのリビジョンのデータをダウンロードするには、fileId パラメータを使用して revisions リソースで list メソッドを呼び出します。これにより、ファイル内のすべての revisionIds が返されます。
BLOB ファイルの改訂コンテンツをダウンロードするには、ダウンロードするファイルの ID、改訂の ID、alt=media URL パラメータを指定して、revisions リソースで get メソッドを呼び出す必要があります。alt=media URL パラメータは、代替レスポンス形式としてコンテンツのダウンロードがリクエストされていることをサーバーに伝えます。
alt=media URL で get メソッドを使用しても、Google ドキュメント、スプレッドシート、スライド、Vids のリビジョンをダウンロードすることはできません。それ以外の場合は、fileNotDownloadable エラーが生成されます。
alt=media URL パラメータは、すべての Google REST API で使用できるシステム パラメータです。Drive API のクライアント ライブラリを使用する場合は、このパラメータを明示的に設定する必要はありません。
リクエスト プロトコルがここに表示されます。
GET https://www.googleapis.com/drive/v3/files/{FILE_ID}/revisions/{REVISION_ID}?alt=media次のように置き換えます。
- FILE_ID: ダウンロードするファイルの
fileId。 - REVISION_ID: ダウンロードするリビジョンの
revisionId。
Google ドキュメント、図形描画、スライドの版は、版番号が自動的に増分されます。ただし、リビジョンが削除されると、番号のシーケンスにギャップが生じる可能性があるため、連続した番号を使用してリビジョンを取得することは避けてください。
LRO のトラブルシューティング
LRO が失敗すると、レスポンスに正規の Google Cloud エラーコードが含まれます。
次の表に、各コードの原因と、コードの処理方法に関する推奨事項を示します。多くのエラーでは、指数バックオフを使用してリクエストを再試行することをおすすめします。
このエラーモデルとその処理方法について詳しくは、API 設計ガイドをご覧ください。
| コード | 列挙型 | 説明 | 推奨される対処方法 |
|---|---|---|---|
| 1 | CANCELLED |
オペレーションがキャンセルされました。通常、キャンセルは呼び出し元により行われます。 | オペレーションを再実行します。 |
| 2 | UNKNOWN |
別のアドレス空間から受信した Status 値がこのアドレス空間で不明なエラー空間に属している場合に、このエラーが返される可能性があります。API エラーから十分な情報が返されない場合、エラーがこのエラーに変換されている可能性があります。 |
指数バックオフを使用して再試行する。 |
| 3 | INVALID_ARGUMENT |
クライアントが無効な引数を指定しました。このエラーは FAILED_PRECONDITION とは異なります。INVALID_ARGUMENT は、ファイル名の形式が不適切など、システムの状態を問わず問題がある引数を示します。 |
問題を解決してから再試行します。 |
| 4 | DEADLINE_EXCEEDED |
オペレーションが完了する前に期限が切れました。システムの状態を変更するオペレーションの場合、オペレーションが正常に終了しても、このエラーが返されることがあります。たとえば、サーバーからの正常なレスポンスが期限切れになるほど遅延する場合もあります。 | 指数バックオフを使用して再試行します。 |
| 5 | NOT_FOUND |
リクエストされたエンティティ（FHIR リソースなど）が見つかりませんでした。 | 問題を解決してから再試行します。 |
| 6 | ALREADY_EXISTS |
クライアントが作成しようとしたエンティティ（DICOM インスタンスなど）はすでに存在します。 | 問題を解決してから再試行します。 |
| 7 | PERMISSION_DENIED |
呼び出し元には、指定されたオペレーションを実行する権限がありません。このエラーコードは、リクエストが有効であること、リクエストされたエンティティが存在すること、および他の事前条件が満たされていることを意味するものではありません。 | 問題を解決してから再試行します。 |
| 8 | RESOURCE_EXHAUSTED |
プロジェクトごとの割り当てなど、一部のリソースが枯渇しています。 | 指数バックオフを使用して再試行します。割り当ては時間の経過とともに使用可能になることがあります。 |
| 9 | FAILED_PRECONDITION |
システムがオペレーションの実行に必要な状態ではないため、オペレーションが拒否されました。たとえば、削除されるディレクトリが空でない、rmdir オペレーションがディレクトリ以外に適用されている状態です。 |
問題を解決してから再試行します。 |
| 10 | ABORTED |
オペレーションは、通常、シーケンサー チェックの失敗、またはトランザクションの中止などの同時実行の問題のために中止されています。 | 指数バックオフを使用して再試行します。 |
| 11 | OUT_OF_RANGE |
オペレーションが、ファイルの終わりを超えたシークまたは読み取りなど、有効な範囲を超えて試行されました。INVALID_ARGUMENT とは異なり、このエラーは、システムの状態が変化すれば修正できる可能性のある問題を示しています。 |
問題を解決してから再試行します。 |
| 12 | UNIMPLEMENTED |
オペレーションが実装されていないか、Drive API でサポートされていないか、有効にされていません。 | 再試行しないでください。 |
| 13 | INTERNAL |
内部エラー。これは、基盤となるシステムで処理中に予期しないエラーが発生したことを示します。 | 指数バックオフを使用して再試行します。 |
| 14 | UNAVAILABLE |
ドライブ API が利用できません。これは、指数バックオフで再試行することで解決できる可能性が高い一時的な状態です。非べき等オペレーションの再試行が常に安全であるとは限りません。 | 指数バックオフを使用して再試行する。 |
| 15 | DATA_LOSS |
回復不能なデータの消失や破損。 | システム管理者にお問い合わせください。データの損失や破損が発生した場合は、システム管理者からサポート担当者に連絡することをおすすめします。 |
| 16 | UNAUTHENTICATED |
リクエストには、オペレーションのための有効な認証情報がありません。 | 問題を解決してから再試行します。 |