您可以使用 Google 雲端硬碟 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
查詢參數,針對方法的 /upload 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
,為方法的 /upload 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
標頭,表示系統未收到任何位元組。舉例來說,如果Range
標頭是bytes=0-42
,代表伺服器已接收檔案的前 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
欄位中提供可建立索引的文字,藉此提高檔案的曝光度。
如要進一步瞭解可建立索引的文字,請參閱「管理檔案中繼資料」。