您可以透過 Google Drive API,在建立或更新 File
時上傳檔案資料。如要進一步瞭解如何建立僅含結構描述的檔案 (例如資料夾),請參閱「建立僅含結構描述的檔案」。
您可以執行三種類型的上傳作業:
簡易上傳 (
uploadType=media
):使用這個上傳類型,在不需提供中繼資料的情況下傳輸小型媒體檔案 (5 MB 以下)。如要執行簡易上傳,請參閱「執行簡易上傳」一文。多部分上傳 (
uploadType=multipart
):"使用這類上傳類型,即可在單一要求中傳送小型檔案 (5 MB 以下) 和描述檔案的中繼資料。如要執行多部分上傳作業,請參閱「執行多部分上傳作業」。支援續傳的上傳作業 (
uploadType=resumable
):這個上傳類型適用於大型檔案 (超過 5 MB) 和很可能發生網路中斷的情況 (例如透過行動應用程式建立檔案)。支援續傳的上傳作業也對多數應用程式而言是不錯的選擇,因為這類上傳作業也能以最低的費用處理每次上傳作業額外處理一次 HTTP 要求的情況。如要執行支援續傳的上傳作業,請參閱「執行支援續傳的上傳作業」。
Google API 用戶端程式庫至少會實作其中一種上傳類型。如要進一步瞭解如何使用各類型,請參閱用戶端程式庫說明文件。
使用 PATCH
與 PUT
提醒一下,HTTP 動詞 PATCH
支援部分檔案資源更新,而 HTTP 動詞 PUT
則支援完整資源取代。請注意,當您在現有資源中新增欄位時,PUT
可能會引入重大變更。
上傳檔案資源時,請遵循下列規範:
- 針對可續傳上傳作業的初始要求,或針對簡單或多部分上傳作業的唯一要求,請使用 API 參考資料中記錄的 HTTP 動詞。
- 要求開始後,請針對所有後續要求使用
PUT
進行可續傳上傳。無論呼叫的方法為何,這些要求都會上傳內容。
執行簡易上傳作業
如要執行簡單的上傳作業,請使用 files.create
方法搭配 uploadType=media
。
以下說明如何執行簡單的上傳作業:
HTTP
使用
uploadType=media
的查詢參數,對方法的 /上傳 URI 建立POST
要求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
將檔案資料新增至要求主體。
請新增下列 HTTP 標頭:
Content-Type
:請設為要上傳的物件 MIME 媒體類型。Content-Length
:請設定為要上傳的位元組數。如果您使用區塊傳輸編碼,則不需要這個標頭。
傳送要求。如果要求成功,伺服器會傳回
HTTP 200 OK
狀態碼,以及檔案的中繼資料。{HTTP}
執行簡單的上傳作業時,系統會建立基本中繼資料,並從檔案推斷出部分屬性,例如 MIME 類型或 modifiedTime
。如果檔案較小且檔案中繼資料不重要,您可以使用簡易上傳功能。
執行多部分上傳作業
多部分上傳要求可讓您在同一項要求中上傳中繼資料和資料。如果您要傳送的資料小到足以在連線失敗時再完整上傳一次,請使用這個選項。
如要執行多部分上傳作業,請使用 files.create
搭配 files.create
方法。uploadType=multipart
以下顯示如何執行多部分上傳作業:
Java
Python
Node.js
PHP
.NET
HTTP
使用查詢參數
uploadType=multipart
,針對方法的 /upload URI 建立POST
要求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
建立要求的主體。依據內含兩個部分的多部分/相關內容類型 RFC 2387 設定主體格式:
- 中繼資料。中繼資料必須先位於,且
Content-Type
標頭必須設為application/json;
charset=UTF-8
。以 JSON 格式新增檔案的中繼資料。 - 媒體:媒體必須放在第二個位置,且必須具有任何 MIME 類型的
Content-Type
標頭。將檔案資料新增至媒體部分。
使用邊界字串 (在前兩個連字號之後) 識別每個部分。此外,請在最後一個邊界字串後方加上兩個連字號。
- 中繼資料。中繼資料必須先位於,且
新增下列頂層 HTTP 標頭:
Content-Type
:請設為multipart/related
,並加入用來辨識要求各部分的邊界字串。例如:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
:設為要求主體中的位元組總數。
傳送要求。
如要建立或更新中繼資料部分,而不上傳相關聯的資料,請將 POST
或 PATCH
要求傳送至標準資源端點:https://www.googleapis.com/drive/v3/files
如果要求成功,伺服器會傳回 HTTP 200 OK
狀態碼,以及檔案的中繼資料。
建立檔案時,應在檔案的 name
欄位中指定檔案副檔名。舉例來說,建立相片 JPEG 檔案時,您可以在中繼資料中指定類似 "name": "photo.jpg"
。後續對 files.get
的呼叫會傳回唯讀 fileExtension
屬性,其中包含最初在 name
欄位中指定的擴充功能。
執行支援續傳的上傳作業
支援續傳的上傳作業可讓您在通訊失敗中斷資料流後,繼續執行上傳作業。由於您不需要從頭開始上傳大型檔案,因此如果網路故障,支援續傳的上傳作業也可以降低頻寬用量。
當您的檔案大小可能極大,或要求設有固定的時間限制 (例如行動作業系統背景工作及某些 App Engine 要求) 時,支援續傳的上傳作業就非常實用。您也可以在需要顯示上傳進度列的情況下使用可續傳上傳功能。
支援續傳的上傳作業包含數個高階步驟:
- 傳送初始要求,並擷取可續傳的工作階段 URI。
- 上傳資料並監控上傳狀態。
- (選用) 如果上傳作業受到干擾,請繼續進行上傳作業。
傳送初始要求
如要啟動支援續傳的上傳作業,請使用 uploadType=resumable
搭配 files.create
方法。
HTTP
使用
uploadType=resumable
的查詢參數,對方法的 /上傳 URI 建立POST
要求:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
如果啟動要求成功,回應會包含
200 OK
HTTP 狀態碼。此外,它還包含指定可續傳工作階段 URI 的Location
標頭:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
儲存可續傳的工作階段 URI,以便上傳檔案資料並查詢上傳狀態。續傳工作階段 URI 會在一週後失效。
如果您有檔案的中繼資料,請以 JSON 格式將中繼資料新增至要求主體。否則,請將要求主體留空。
請新增下列 HTTP 標頭:
X-Upload-Content-Type
。選填。請將此屬性設為檔案資料的 MIME 類型,該類型會在後續要求中傳輸。如果中繼資料或此標頭中未指定資料的 MIME 類型,系統會以application/octet-stream.
提供物件。X-Upload-Content-Length
(選用)。請將其設為要在後續要求中傳輸的檔案資料位元組數。Content-Type
:如果您有檔案的中繼資料,就必須提供這個屬性。設為application/json;
charset=UTF-8
。Content-Length
:除非使用區塊傳輸編碼,否則為必要屬性。設定為這項初始要求主體中的位元組數。
傳送要求。如果工作階段啟動要求成功,回應會包含
200 OK HTTP
狀態碼。此外,回應還包含指定可續傳工作階段 URI 的Location
標頭。使用支援續傳的工作階段 URI 上傳檔案資料,並查詢上傳狀態。支援續傳的工作階段 URI 會在一週後失效。複製並儲存可續傳的工作階段網址。
前往上傳內容頁面。
上傳內容
您可以透過兩種方式上傳可暫停的工作階段檔案:
- 在單一要求中上傳內容:如果檔案可在單一要求中上傳,且單一要求沒有固定的時間限制,或您不需要顯示上傳進度指標,請使用此方法。這種方法最適合用於因為需要較少要求,且可增進效能。
將內容分為多個區塊上傳:如果您必須減少任何單一要求中傳輸的資料量,請使用此方法。當個別要求有固定的時間限制時,您可能需要減少傳輸的資料量,某些類別的 App Engine 要求就是這種情況。如果您需要提供自訂指標來顯示上傳進度,此方法也很實用。
HTTP - 單一要求
- 建立可續傳工作階段 URI 的
PUT
要求。 - 將檔案資料新增至要求主體。
- 新增 Content-Length HTTP 標頭,並設為檔案中的位元組數。
- 傳送要求。如果上傳要求中斷,或是您收到
5xx
回應,請按照「繼續執行中斷的上傳作業」一節所述的程序操作。
HTTP - 多個要求
建立可續傳工作階段 URI 的
PUT
要求。將區塊的資料新增至要求主體。大小以 256 KB (256 x 1024 位元組) 的倍數建立區塊,但完成上傳作業的最終區塊除外。請盡可能將區塊大小設為較大,以便提高上傳效率。
請新增下列 HTTP 標頭:
Content-Length
:請設定為目前區塊中的位元組數。Content-Range
:設為顯示上傳檔案中的位元組。舉例來說,Content-Range: bytes 0-524287/2000000
會顯示您上傳 2,000,000 位元組檔案中的前 524,288 個位元組 (256 x 1024 x 2)。
傳送要求,並處理回應。如果上傳要求中斷,或是您收到
5xx
回應,請按照「繼續執行中斷的上傳作業」一節的程序操作。針對檔案中保留的每個區塊重複執行步驟 1 到 4。請使用回應中的
Range
標頭,決定下一個區塊要從哪裡開始。請勿假設伺服器已收到在前一個要求中傳送的所有位元組。
完整檔案上傳完畢後,您會收到 200 OK
或 201 Created
回應,並附上與資源相關聯的所有中繼資料。
繼續執行中斷的上傳作業
如果上傳要求在收到回應前就終止,或者您收到 503
Service Unavailable
回應,就必須繼續處理中斷的上傳作業。
HTTP
如要要求上傳狀態,請對可繼續的工作階段 URI 建立空白的
PUT
要求。新增
Content-Range
標頭,指出目前在檔案中的位置不明。舉例來說,如果檔案總長度為 2,000,000 個位元組,請將Content-Range
設為*/2000000
。如果您不知道檔案的完整大小,請將Content-Range
設為*/*
。傳送要求。
處理回應:
200 OK
或201 Created
回應表示上傳作業已完成,無須進一步採取行動。308 Resume Incomplete
回應表示您必須繼續上傳檔案。404 Not Found
回應表示上傳工作階段已逾期,必須從頭開始上傳。
如果您收到
308 Resume Incomplete
回應,請處理回應的Range
標頭,判斷伺服器已收到哪些位元組。如果回應沒有Range
標頭,表示系統未收到任何位元組。例如,bytes=0-42
的Range
標頭表示已收到檔案的前 43 個位元組,且下一個要上傳的區塊的開頭都是位元組 44。現在您已知道繼續上傳的位置,請繼續從下一個位元組開始上傳檔案。加入
Content-Range
標頭,指出您要傳送檔案的哪個部分。舉例來說,Content-Range: bytes 43-1999999
表示您傳送位元組 44 到 2,000,000。
處理媒體上傳錯誤
上傳媒體時,請按照下列最佳做法處理錯誤:
- 針對
5xx
錯誤,請繼續或重新執行因連線中斷而失敗的上傳作業。如要進一步瞭解如何處理5xx
錯誤,請參閱「500、502、503、504 錯誤」。 - 如果發生
403 rate limit
錯誤,請重試上傳。如要進一步瞭解如何處理403 rate limit
錯誤,請參閱「403 錯誤:rateLimitExceeded
」。 - 如果在可續傳上傳作業期間發生任何
4xx
錯誤 (包括403
),請重新啟動上傳作業。這些錯誤表示上傳工作階段已逾期,必須透過要求新的工作階段 URI 重新啟動。上傳工作階段也會在閒置一週後失效。
匯入至 Google 文件類型
在 Google 雲端硬碟中建立檔案時,您可能會想要將檔案轉換成 Google Workspace 檔案類型,例如 Google 文件或試算表。例如,您可能想將文件從慣用的文書處理工具轉換為文件,以便利用 Google 文件的功能。
如要將檔案轉換為特定 Google Workspace 檔案類型,請在建立檔案時指定 Google Workspace mimeType
。
以下說明如何將 CSV 檔案轉換為 Google Workspace 試算表:
Java
Python
Node.js
PHP
.NET
如要查看是否可進行轉換,請在建立檔案前檢查 about
資源的 importFormats
陣列。這個陣列會動態提供支援的轉換。常見的匯入格式包括:
寄件者 | 收件者 |
---|---|
Microsoft Word、OpenDocument Text、HTML、RTF、純文字 | Google 文件 |
Microsoft Excel、OpenDocument 試算表、CSV、TSV、純文字 | Google 試算表 |
Microsoft PowerPoint、OpenDocument 簡報 | Google 簡報 |
JPEG、PNG、GIF、BMP、PDF | Google 文件 (在文件中嵌入圖片) |
純文字 (特殊 MIME 類型)、JSON | Google Apps Script |
當您在 update
要求期間上傳並轉換媒體至 Google 文件、試算表或簡報檔案時,系統會取代文件的完整內容。
將圖片轉換為 Google 文件時,Google 雲端硬碟會使用光學字元辨識 (OCR) 技術,將圖片轉換為文字。您可以在 ocrLanguage
參數中指定適用的 BCP 47 語言代碼,藉此提升 OCR 演算法的品質。擷取的文字會顯示在文件中,並與嵌入的圖片並列。
使用預先產生的 ID 上傳檔案
Drive API 可讓您擷取預先產生的檔案 ID 清單,用於上傳及建立資源。上傳和檔案建立要求可使用這些預先產生的 ID。在檔案中繼資料中設定 id
欄位。
如要建立預先產生的 ID,請呼叫 files.generateIds
,並指定要建立的 ID 數量。
如果發生未明確的伺服器錯誤或逾時,您可以使用預先產生的 ID 安全地重新嘗試上傳。如果檔案已成功建立,後續重試會傳回 HTTP 409
錯誤,且不會建立重複的檔案。
為不明檔案類型定義可建立索引的文字
使用者可以使用雲端硬碟 UI 找出文件內容。您也可以使用 files.list
和 fullText
欄位,搜尋應用程式中的內容。詳情請參閱「搜尋檔案和資料夾」。
雲端硬碟會在辨識檔案類型時,自動為文件建立索引,以利搜尋,包括文字文件、PDF、含文字的圖片和其他常見類型。如果應用程式儲存其他類型的檔案 (例如繪圖、影片和捷徑),您可以在檔案的 contentHints.indexableText
欄位中提供可建立索引的文字,藉此提高檔案的曝光度。
如要進一步瞭解可建立索引的文字,請參閱「管理檔案中繼資料」。