Google Drive API 支援多種下載和匯出動作,如下表所示:
| 下載動作 |
|
||||
| 匯出動作 |
|
在 Drive API 中,Blob 檔案是指儲存在 Google 雲端硬碟中的任何原始二進位檔案 (例如圖片、影片和 PDF),而非 Google Workspace 文件。這與 JavaScript 的 Blob 物件無關。如要詳細瞭解這裡提及的檔案類型,包括 Blob 和 Google Workspace 檔案,請參閱「檔案類型」。
下載或匯出檔案內容前,請先確認使用者可以透過 files 資源的 capabilities.canDownload 欄位下載檔案。
本文的其餘部分會詳細說明如何執行這幾類下載和匯出動作。
下載 Blob 檔案內容
如要下載儲存在雲端硬碟的 Blob 檔案,請使用 files.get 方法,並提供要下載的檔案 ID 和 alt system 參數。
alt=media 參數會告知伺服器,要求下載內容做為替代回應格式。
alt 系統參數適用於所有 Google REST API。如果您使用 Drive API 用戶端程式庫,則不需要明確設定這項參數,因為用戶端程式庫方法會將 alt=media 參數新增至基礎 HTTP 要求。
下列程式碼範例說明如何使用 files.get 方法下載檔案:
Apps Script
/**
* Downloads a file from Drive.
* @param {string} fileId The ID of the file to download.
* @return {Blob} The file content as a Blob.
*/
function downloadFile(fileId) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '?alt=media';
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
Java
Python
Node.js
PHP
.NET
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
- FILE_NAME:輸出檔案的名稱。
從應用程式開始下載檔案時,必須使用允許讀取檔案內容的範圍授權。舉例來說,使用 drive.readonly.metadata 範圍的應用程式無權下載檔案內容。用戶端程式庫程式碼範例使用受限制的 drive 檔案範圍,可讓使用者查看及管理所有雲端硬碟檔案。如要進一步瞭解雲端硬碟範圍,請參閱「選擇 Google Drive API 範圍」。
具有owner權限 (適用於「我的雲端硬碟」檔案) 或organizer權限 (適用於共用雲端硬碟檔案) 的使用者,可以透過 DownloadRestrictionsMetadata 物件限制下載。詳情請參閱「禁止使用者下載、列印或複製你的檔案」。
如果檔案遭判定為濫用 (例如有害軟體),只有檔案擁有者可以下載。
此外,acknowledgeAbuse 查詢參數必須設為 true,表示使用者已確認下載潛在垃圾軟體或其他濫用檔案的風險。應用程式應在使用者使用這個查詢參數前,以互動方式向使用者發出警告。
存取記憶體中的檔案資料
如果應用程式必須直接在記憶體中存取檔案資料 (例如以位元組緩衝區的形式),而不是將資料儲存到本機磁碟,您可以調整用戶端程式庫要求或處理傳回的串流:
Node.js:Node.js 用戶端程式庫預設會以
Readable串流形式傳回檔案內容。如要將檔案儲存到本機磁碟,請按照下列步驟操作:const fs = require('fs'); const dest = fs.createWriteStream('/path/to/dest/file.ext'); const response = await service.files.get( { fileId, alt: 'media' }, { responseType: 'stream' } ); response.data .on('end', () => { console.log('Download complete.'); }) .on('error', (err) => { console.error('Error downloading file.', err); }) .pipe(dest);或者,如要直接在記憶體中以
ArrayBuffer形式傳回資料,而非以串流形式傳回,請在要求選項中設定responseType參數:const file = await service.files.get({ fileId, alt: 'media', }, { responseType: 'arraybuffer' }); // Convert the ArrayBuffer to a Node.js Buffer object. const buffer = Buffer.from(file.data);Python:下載 Blob 檔案的 Python 程式碼範例已將下載區塊寫入記憶體內
io.BytesIO()物件。如要存取原始位元組,請呼叫file.getvalue()。Java:下載 Blob 檔案的 Java 程式碼範例會使用
java.io.ByteArrayOutputStream,在記憶體中擷取下載的位元組。使用outputStream.toByteArray()存取原始位元組陣列。.NET:下載 Blob 檔案的 C# 程式碼範例會使用
System.IO.MemoryStream。使用stream.ToArray()存取基礎位元組陣列。Apps Script:下載 Blob 檔案的 Apps Script 程式碼範例會使用
response.getBlob()方法傳回Blob物件。使用getBytes()方法將其轉換為位元組陣列。
部分下載
部分下載是指只下載檔案的指定部分。您可以使用 Range 標頭搭配位元組範圍,指定要下載的檔案部分。例如:
Range: bytes=500-999
下載舊版 Blob 檔案內容
如要下載舊版 Blob 檔案的內容,請使用 revisions.get 方法,並提供要下載的檔案 ID、修訂版本 ID 和 alt system 參數。alt=media 參數會告知伺服器,要求下載內容做為替代回應格式。與 files.get 類似,revisions.get 方法也會接受 acknowledgeAbuse 查詢參數和 Range 標頭。
你只能下載標示為「永久保存」的 Blob 檔案內容修訂版本。如要下載修訂版本,請先將其設為「永久保留」。 詳情請參閱「指定要從自動刪除作業中排除的修訂版本」。
如要進一步瞭解如何下載修訂版本,請參閱「管理長時間執行的作業」。
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- REVISION_ID:要下載的修訂版本 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
- FILE_NAME:輸出檔案的名稱。
在瀏覽器中下載 Blob 檔案內容
如要透過瀏覽器下載儲存在雲端硬碟中的 Blob 檔案內容,而非透過 API,請使用 files 資源的 webContentLink 欄位。如果使用者有權下載檔案,系統會傳回下載檔案和內容的連結。您可以將使用者重新導向至這個網址,或提供可點選的連結。
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=webContentLink" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
更改下列內容:
- FILE_ID:要取得下載連結的檔案 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
使用長期執行的作業下載 Blob 檔案內容
如要使用長時間執行的作業 (LRO) 下載 Blob 檔案內容,請使用 files.download 方法,並提供要下載的檔案 ID。您可以選擇設定修訂版本的 ID。
這是下載 Google Vids 檔案的唯一方法。嘗試匯出 Google Vids 檔案時,收到 fileNotExportable 錯誤訊息。詳情請參閱「管理長時間執行的作業」。
curl
下列 curl 指令會啟動 LRO,並傳回 JSON 回應。如要下載檔案或輪詢這個 LRO,您必須使用傳回的 ID 提出另一項要求,才能取得內容網址。接著,您可以對該網址發出最終的 curl 要求,下載檔案。詳情請參閱「管理長時間執行的作業」。
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=video/mp4" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
匯出 Google Workspace 文件內容
如要匯出 Google Workspace 文件的位元組內容,請使用 files.export 方法,並提供要匯出的檔案 ID 和正確的 MIME 類型。匯出內容的大小上限為 10 MB。
下列程式碼範例說明如何使用 files.export 方法,以 PDF 格式匯出 Google Workspace 文件:
Apps Script
/**
* Exports a Google Workspace document.
* @param {string} fileId The ID of the file to export.
* @param {string} mimeType The MIME type to export to.
* @return {Blob} The exported content as a Blob.
*/
function exportPdf(fileId, mimeType) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '/export?mimeType=' + encodeURIComponent(mimeType);
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
Java
Python
Node.js
PHP
.NET
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=application/pdf" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME.pdf"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
- FILE_NAME:輸出檔案的名稱。
用戶端程式庫程式碼範例使用受限的 drive 範圍,可讓使用者查看及管理所有雲端硬碟檔案。如要進一步瞭解雲端硬碟範圍,請參閱「選擇 Google Drive API 範圍」。
程式碼範例也會將匯出 MIME 類型宣告為 application/pdf。如需各項 Google Workspace 文件支援的所有匯出 MIME 類型完整清單,請參閱「Google Workspace 文件匯出 MIME 類型」。
在瀏覽器中匯出 Google Workspace 文件內容
如要在瀏覽器中匯出 Google Workspace 文件內容,請使用 files 資源的 exportLinks 欄位。系統會根據文件類型,針對每個可用的 MIME 類型傳回下載檔案和內容的連結。您可以將使用者重新導向至網址,或提供可點選的連結。
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
更改下列內容:
- FILE_ID:要取得下載連結的檔案 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
在瀏覽器中匯出舊版 Google Workspace 文件內容
如要在瀏覽器中匯出 Google Workspace 文件的舊版內容,請使用 revisions.get 方法,並提供要下載的檔案 ID 和要產生匯出連結的修訂版本 ID,然後透過該連結執行下載作業。如果使用者有權下載檔案,系統就會傳回下載檔案和內容的連結。您可以將使用者重新導向至這個網址,或提供可點選的連結。
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- REVISION_ID:要下載的修訂版本 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。
使用長時間執行的作業匯出 Google Workspace 文件內容
如要使用長時間執行的作業 (LRO) 匯出 Google Workspace 文件內容,請使用 files.download 方法,並提供要下載的檔案 ID 和修訂版本 ID。詳情請參閱「管理長時間執行的作業」。
curl
下列 curl 指令會啟動 LRO,並傳回 JSON 回應。如要下載檔案或輪詢這個 LRO,您必須使用傳回的 ID 提出另一項要求,才能取得內容網址。接著,您就可以對該網址提出最終的 curl 要求,下載檔案。詳情請參閱「管理長時間執行的作業」。
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=MIME_TYPE&revisionId=REVISION_ID" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
更改下列內容:
- FILE_ID:要下載的檔案 ID。
- MIME_TYPE:要匯出的 MIME 類型。
- REVISION_ID:要下載的修訂版本 ID。
- ACCESS_TOKEN:授予 API 存取權的存取權杖。