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

管理長時間執行的作業

長時間執行的作業 (LRO) 是指完成時間較長，不適合做為 API 回應的 API 方法。一般來說，您不希望在工作執行時保持呼叫執行緒開啟，因為這樣會導致使用者體驗不佳。比較好的做法是向使用者傳回某種 Promise，讓他們稍後再回來查看。

每次在 files 資源上呼叫 download 方法，透過 Drive API 或其用戶端程式庫下載檔案內容時，Google Drive API 都會傳回 LRO。

這個方法會將 operations 資源傳回給用戶端。您可以透過 operations 資源，使用 get 方法輪詢作業，以非同步方式擷取 API 方法的狀態。Drive API 中的 LRO 遵循 Google Cloud LRO 設計模式。

詳情請參閱「長時間執行的作業」。

流程總覽

下圖顯示 file.download 方法的運作方式。

file.download 方法的高階步驟。 — **圖 1.** 檔案下載方法的高階步驟。

呼叫 files.download：應用程式呼叫 download 方法時，會啟動檔案的雲端硬碟 API 下載要求。詳情請參閱「下載檔案」。
要求權限：要求會將驗證憑證傳送至 Drive API。如果應用程式需要使用尚未授予的使用者驗證呼叫 Drive API，系統會提示使用者登入。應用程式也會要求存取您在設定驗證時指定的範圍。
開始下載：系統會提出 Drive API 要求，開始下載檔案。要求可能與 Google Vids 或其他 Google Workspace 內容有關。
啟動長時間執行的作業：長時間執行的作業開始，並管理下載程序。
傳回待處理作業：Google 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 類型，系統會以預設 MIME 類型下載 Google Workspace 文件。詳情請參閱「預設 MIME 類型」。
(選用步驟) revision_id 查詢參數是要下載的檔案修訂版本 ID。這項功能僅適用於下載 Blob 檔案、Google 文件和 Google 試算表。下載不支援檔案的特定修訂版本時，系統會傳回錯誤代碼 INVALID_ARGUMENT。

download 方法是下載 MP4 格式 Vids 檔案的唯一方式，通常最適合下載大多數影片檔案。

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

啟動 LRO 的 download 方法要求，以及擷取最終下載 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：資源金鑰可協助保護檔案，避免遭到未經授權的存取。詳情請參閱「使用資源金鑰存取透過連結共用的雲端硬碟檔案」。
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 路徑。

請注意，只有在 download 要求的回應中，才會傳回 name。由於 Drive API 不支援 List 方法，因此無法透過其他方式擷取。如果遺失 name 值，您必須再次呼叫 download 方法要求，產生新的回應。

get 要求的相關回應會包含代表長時間執行作業的資源。詳情請參閱「下載回覆」。

如果回應包含完成狀態 (done=true)，表示長時間執行的作業已完成。

下載修訂版本

您可以使用 files 資源中的 headRevisionId 欄位值，下載最新修訂版本。這會擷取與您先前擷取檔案的中繼資料相符的修訂版本。如要下載檔案所有先前修訂版本的資料 (仍儲存在雲端)，請使用 fileId 參數，對 revisions 資源呼叫 list 方法。這會傳回檔案中的所有 revisionIds。

如要下載 Blob 檔案的修訂內容，您必須在 revisions 資源上呼叫 get 方法，並提供要下載的檔案 ID、修訂版本 ID 和 alt=media 網址參數。alt=media 網址參數會告知伺服器，要求以替代回應格式下載內容。

使用 alt=media URL 的 get 方法時，無法下載 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 設計指南。

程式碼	列舉	說明	建議採取的行動
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`	雲端硬碟 API 無法使用。這很可能是暫時性問題，可透過指數輪詢重試來解決。請注意，重試非等冪作業並不一定安全。	以指數輪詢方式重試。
15	`DATA_LOSS`	無法復原的資料遺失或損毀。	請與系統管理員聯絡。如果發生資料遺失或損毀的情況，系統管理員可能需要與支援代表聯絡。
16	`UNAUTHENTICATED`	要求中不含作業的有效驗證憑證。	未修正問題前請勿重試。

下載及匯出檔案