このページは Cloud Translation API によって翻訳されました。

長時間実行オペレーションを管理する

長時間実行オペレーション（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}/download

FILE_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 サイト	未加工テキスト	text/raw	.txt
Google スライド	Microsoft PowerPoint	application/vnd.openxmlformats-officedocument.presentationml.presentation	.pptx
Google Vids	MP4	アプリケーション/mp4	.mp4
Jamboard	PDF	application/pdf	.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。

長時間実行オペレーションの詳細を取得する

長時間実行オペレーションとは、完了までに膨大な時間がかかる可能性があるメソッドの呼び出しです。通常、新しく作成されたダウンロードオペレーションは、特に 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 パラメータは、レスポンスの代替形式としてコンテンツのダウンロードがリクエストされていることをサーバーに伝えます。

Google ドキュメント、スプレッドシート、スライド、Vids のリビジョンは、alt=media URL で get() メソッドを使用してダウンロードすることはできません。一致しない場合、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`	Drive API を使用できません。これは一時的な状態である可能性が高く、指数バックオフで再試行することで解決できます。非べき等オペレーションの再試行が常に安全であるとは限りません。	指数バックオフを使用して再試行する。
15	`DATA_LOSS`	回復不能なデータの消失や破損。	システム管理者にお問い合わせください。データの損失や破損が発生した場合は、システム管理者からサポート担当者への連絡をおすすめします。
16	`UNAUTHENTICATED`	リクエストには、オペレーションのための有効な認証情報がありません。	問題を解決してから再試行してください。