管理長時間執行的作業

長時間執行的作業 (LRO) 是指 API 方法的完成時間比 API 回應所需的時間長。一般而言，在工作執行期間不要讓呼叫執行緒保持開啟，因為這會導致使用者體驗不佳。反之，最好將某些類型的承諾傳回給使用者，讓他們稍後回來查看。

每當您呼叫 files 資源的 download() 方法，透過 Drive API 或其用戶端程式庫下載檔案時，Google Drive 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. 啟動長時間執行作業：長時間執行作業開始，並管理下載程序。

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() 方法是下載 MP4 格式 Vids 檔案的唯一方式，通常最適合下載大多數影片檔案。

為 Google 文件或試算表產生的下載連結一開始會傳回重新導向。按一下新連結即可下載檔案。

向 download() 方法發出的要求應用於啟動 LRO，並發出擷取最終下載 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：資源鍵可協助保護檔案，避免遭到非預期存取。詳情請參閱「使用資源鍵存取透過連結共用的 Google 雲端硬碟檔案」。

• NAME：伺服器指派的名稱。

• DOWNLOAD_URI：檔案的最終下載 URI。

請注意，partialDownloadAllowed 欄位會指出是否允許部分下載。下載 Blob 檔案內容時為 True。

取得長時間執行作業的詳細資料

長時間執行的作業是指可能需要大量時間才能完成的方法呼叫。一般來說，新建立的下載作業一開始會處於待處理狀態 (done=null)，尤其是針對 Vids 檔案。

您可以使用 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 檔案的修訂內容，您必須在 revisions 資源上呼叫 get() 方法，並提供要下載的檔案 ID、修訂 ID 和 alt=media 網址參數。alt=media 網址參數會告訴伺服器，內容下載作業是以替代回應格式要求。

無法使用 get() 方法搭配 alt=media 網址下載 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 設計指南。

相關主題

• 下載及匯出檔案
• 管理檔案修訂版本