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

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

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

このメソッドは、クライアントに operations リソースを返します。operations リソースを使用して、 API メソッドのステータスを get メソッドでオペレーションをポーリングすることで、非同期で取得できます。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 を返し、ユーザーがファイルを利用できるようになります。

ファイルをダウンロードする

長時間実行オペレーションでコンテンツをダウンロードするには、download メソッドを files リソースで使用します。このメソッドは、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 メソッドは、Google Vids ファイルを MP4 形式でダウンロードする唯一の方法であり、通常はほとんどの動画ファイルのダウンロードに最適です。Google Vids ファイルをエクスポートしようとすると、 fileNotExportable エラーが発生します。

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 になります。

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

長時間実行オペレーションとは、完了までに膨大な時間がかかる可能性があるメソッドの呼び出しです。通常、新しく作成されたダウンロード オペレーションは、特に Google 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 ドキュメント、スプレッドシート、スライド、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 エラー コードが含まれます。

次の表に、各エラーコード、マッピングされた HTTP ステータス コード、説明、エラーコードの処理方法の推奨事項を示します。多くの エラーでは、指数 バックオフを使用してリクエストを再試行することが推奨される対応です。

このエラーモデルとその処理方法の詳細については、API 設計ガイドをご覧ください。

関連トピック

• ファイルをダウンロードしてエクスポートする