管理長時間執行的作業

長時間執行的作業 (LRO) 是指 API 方法的完成時間比 API 回應所需的時間長。一般來說，您不應在任務執行期間保持呼叫執行緒開啟狀態，因為這會提供不佳的使用者體驗。建議您改為向使用者傳回某種承諾，讓他們稍後再查看。

每次在 files 資源上呼叫 download() 方法，透過 Google 雲端硬碟 API 或其用戶端程式庫下載檔案內容時，Google 雲端硬碟 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 文件、試算表、簡報和 Vid 的修訂版本。否則會產生 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 設計指南。

相關主題

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