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

長時間実行オペレーション（LRO）は、API レスポンスに適した時間よりも完了に時間のかかる API メソッドです。通常、タスクの実行中に呼び出しスレッドを開いたままにしておくと、ユーザー エクスペリエンスが低下するため、開いたままにしておくことはできません。代わりに、なんらかの Promise をユーザーに返して、後で確認できるようにすることをおすすめします。

Google Drive API は、files リソースで download() メソッドを呼び出して、ドライブ API またはそのクライアント ライブラリを介してファイルのコンテンツをダウンロードするたびに、LRO を返します。

このメソッドは、operations リソースをクライアントに返します。operations リソースを使用して、get() メソッドでオペレーションをポーリングすることで、API メソッドのステータスを非同期で取得できます。Drive API の LRO は、 Google Cloud LRO 設計パターンに準拠しています。

詳細については、長時間実行オペレーションをご覧ください。

プロセスの概要

次の図は、file.download メソッドの仕組みの概要を示しています。

1. files.download を呼び出す: アプリが download() メソッドを呼び出すと、ファイルの Drive API ダウンロード リクエストが開始されます。詳細については、ファイルをダウンロードするをご覧ください。

2. 権限をリクエストする: このリクエストは、認証情報を Drive API に送信します。アプリで、まだ付与されていないユーザーの認証を使用して Drive API を呼び出す必要がある場合は、ログインを促すメッセージがユーザーに表示されます。また、認証の設定時に指定したスコープでアクセスをリクエストします。

3. ダウンロードを開始: Drive API リクエストが送信され、ファイルのダウンロードが開始されます。リクエストは、Google Vids または他の Google Workspace コンテンツに対して行うことができます。

4. LRO を開始する: 長時間実行オペレーションが開始され、ダウンロード プロセスが管理されます。

5. 保留中のオペレーションを返す: Drive API は、リクエストを行ったユーザーに関する情報と複数のファイル メタデータ フィールドを含む保留中のオペレーションを返します。

6. 初期の保留状態: アプリは、done=null の初期保留状態とともに保留中のオペレーションを受信します。これは、ファイルのダウンロードはまだ準備ができておらず、オペレーションのステータスが保留中であることを示します。

7. operations.get を呼び出して結果を確認する: アプリは推奨される間隔で get() を呼び出し、オペレーションの結果をポーリングして、長時間実行オペレーションの最新の状態を取得します。保留状態の done=false が返された場合、アプリはオペレーションが完了状態（done=true）を返すまでポーリングを続けます。ファイルが大きい場合は、複数回ポーリングする必要があります。詳細については、長時間実行オペレーションの詳細を取得するをご覧ください。

8. 保留中の状態を確認する: LRO から保留中の状態 done=true が返された場合、ファイルのダウンロードの準備ができており、オペレーション ステータスが完了したことを示します。

9. 完了したオペレーションをダウンロード 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 タイプが割り当てられます。

ダウンロード レスポンス

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');

curl -i -H \
      'Authorization: Bearer $(gcloud auth print-access-token)" \
      'https://googleapis.com/drive/v3/operations/NAME?alt=json'

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 ドキュメント、スプレッドシート、スライド、動画の変更版は、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 設計ガイドをご覧ください。

関連トピック

• ファイルをダウンロードしてエクスポートする
• ファイルのリビジョンを管理する