本頁面由 Cloud Translation API 翻譯而成。

管理長時間執行的作業

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

每當您呼叫 files 資源的 download() 方法，透過 Drive API 或其用戶端程式庫下載檔案時，Google 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 內容提出要求。
啟動長時間執行作業：長時間執行作業開始，並管理下載程序。
傳回待處理作業：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() 方法是下載 MP4 格式 Vids 檔案的唯一方法，通常適合下載大部分的影片檔案。

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

對 download() 方法發出的開始 LRO 要求，以及對擷取最終下載 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	圖片/png	.png
Google 表單	ZIP	應用程式/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	application/mp4	.mp4
Jamboard	PDF	應用程式/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：資源鍵可協助保護檔案，避免遭到非預期存取。詳情請參閱「使用資源鍵存取透過連結共用的 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');

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

您無法使用 get() 方法搭配 alt=media 網址，下載 Google 文件、試算表、簡報和 Vid 的修訂版本。否則會產生 fileNotDownloadable 錯誤。

alt=media 網址參數是 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`	要求中不含作業的有效驗證憑證。	未修正問題前請勿重試。

管理長時間執行的作業

流程總覽

下載檔案

預設 MIME 類型

下載回應

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

輪詢長時間執行的作業

方法呼叫

curl

下載修訂版本

排解 LRO 問題

相關主題