執行支援續傳的上傳作業

總覽

本頁說明如何在 Cloud Storage JSON 和 XML API 中發出可續傳的上傳要求。如因通訊問題導致資料傳輸過程遭到中斷，之後可透過此通訊協定繼續執行上傳作業。

如要瞭解如何在 Google Cloud CLI 和用戶端程式庫中使用可續傳上傳功能，請參閱「工具和 API 如何使用可續傳上傳功能」。

必要的角色

如要取得執行可恢復上傳作業所需的權限，請要求管理員授予您下列其中一個角色：

  • 如要上傳的內容包含物件保留鎖定，請要求管理員授予您 bucket 的 Storage 物件管理員 (roles/storage.objectAdmin) IAM 角色。

  • 在其他情況下，請要求管理員授予您值區的「儲存空間物件使用者」(roles/storage.objectUser) IAM 角色。

這些預先定義的角色具備將物件上傳至各自案例的 bucket 所需的權限。如要查看確切的必要權限，請展開「必要權限」部分：

所需權限

  • storage.objects.create
  • storage.objects.delete
    • 只有在上傳作業會覆寫現有物件時，才需要這項權限。
  • storage.objects.setRetention
    • 只有在上傳內容包含物件保留鎖定時，才需要這項權限。

您也可以透過其他預先定義的角色或自訂角色取得這些權限。

如要瞭解如何授予值區角色，請參閱「搭配值區使用 IAM」。

啟動可續傳的上傳工作階段

如要啟動可續傳的上傳工作階段，請按照下列步驟操作：

JSON API

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. (選用) 建立 JSON 檔案，其中包含要上傳物件的 中繼資料。舉例來說，下列 JSON 檔案會設定要上傳至 image/png 的物件 contentType 中繼資料：

    {
    "contentType": "image/png"
}

  3. 使用 cURL 透過 POST 物件要求呼叫 JSON API：

    curl -i -X POST --data-binary @METADATA_LOCATION \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -H "Content-Length: INITIAL_REQUEST_LENGTH" \
    "https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o?uploadType=resumable&name=OBJECT_NAME"

    其中：

    • METADATA_LOCATION 是 JSON 檔案的本機路徑，其中包含您在上一個步驟中指定的選用中繼資料。如果未納入中繼資料檔案，請排除這項檔案，以及 --data-binary @ 和 Content-Type 標頭。
    • INITIAL_REQUEST_LENGTH 是這項初始要求主體中的位元組數，例如 79。
    • BUCKET_NAME 是您要向其上傳物件的值區名稱。例如：my-bucket。
    • OBJECT_NAME 是您要給予物件的網址編碼名稱。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。如果您在步驟 2 的物件中繼資料檔案中加入 name，則不需要執行這項操作。

    如果您已啟用跨來源資源共用，也應在這次和後續的上傳要求中加入 Origin 標頭。

    您可以新增至要求的選用標頭包括 X-Upload-Content-Type 和 X-Upload-Content-Length。

    如果成功，回應會包含 200 狀態碼，且類似以下內容：

    HTTP/2 200 
content-type: text/plain; charset=utf-8
x-guploader-uploadid: ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
location: https://storage.googleapis.com/upload/storage/v1/b/my-bucket/o?uploadType=resumable&name=cat-pic.jpeg&upload_id=ABgVH8_jqDHM_KOvNAJCx73r9v5fINktk9U-pXana1szCM5803tlJ7CKsRbDxkyYCrfEiNqzcZ6B7DfoDtc-bdzpH-SpVTAMEO9EQV34qG0-0yk
date: Mon, 07 Jul 2025 14:57:21 GMT
vary: Origin
vary: X-Origin
cache-control: no-cache, no-store, max-age=0, must-revalidate
expires: Mon, 01 Jan 1990 00:00:00 GMT
pragma: no-cache
content-length: 0
server: UploadServer
alt-svc: h3=":443"; ma=2592000,h3-29=":443"; ma=2592000

  4. 儲存 POST 物件要求回應的 location 標頭中提供的可續傳工作階段 URI。

    後續要求會使用這個 URI 上傳物件資料。

XML API

  1. 安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。

  2. 使用 cURL 透過主體空白的 POST 物件要求呼叫 XML API：

    curl -i -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Length: 0" \
    -H "Content-Type: OBJECT_CONTENT_TYPE" \
    -H "x-goog-resumable: start" \
    "https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME"

    其中：

    • OBJECT_CONTENT_TYPE 是物件的內容類型。例如 image/png。如果未指定內容類型，Cloud Storage 系統會將物件的 Content-Type 中繼資料設為 application/octet-stream。
    • BUCKET_NAME 是您要向其上傳物件的值區名稱。例如：my-bucket。
    • OBJECT_NAME 是您要給予物件的網址編碼名稱。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。

    如果您已啟用跨來源資源共用，也應在這次和後續的上傳要求中加入 Origin 標頭。

    如果成功，回應會包含 201 狀態訊息。

  3. 儲存 POST 物件要求回應的location 標頭中提供的可續傳工作階段 URI。

    後續要求會使用這個 URI 上傳物件資料。

上傳資料

啟動可續傳上傳作業後，有兩種方式可以上傳物件資料：

  • 單一區塊：這種做法通常是最佳選擇，因為需要的請求較少，因此效能較佳。
  • 分成多個區塊：如果需要減少單一要求中傳輸的資料量，例如個別要求有固定時間限制，或上傳開始時不知道上傳總大小，請使用這個方法。

單一區塊上傳

如要以單一區塊上傳資料，請執行下列操作：

JSON API

  1. 使用 cURL 透過 PUT 物件要求呼叫 JSON API：

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_LOCATION 是物件的本機路徑。例如：Desktop/dog.png。
    • OBJECT_SIZE 是物件中的位元組數。例如：20000000。
    • SESSION_URI 是您啟動可續傳上傳作業時，location 標頭中傳回的值。

    您可以視需要加入以 X-Goog-Meta- 為前置字元的標頭，在要求中為物件新增自訂中繼資料。

XML API

  1. 使用 cURL 透過 PUT 物件要求呼叫 XML API：

    curl -i -X PUT --data-binary @OBJECT_LOCATION \
    -H "Content-Length: OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_LOCATION 是物件的本機路徑。例如：Desktop/dog.png。
    • OBJECT_SIZE 是物件中的位元組數。例如：20000000。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

如果上傳作業完全完成，您會收到 200 OK 或 201 Created 回應，以及與資源相關聯的所有中繼資料。

如果上傳要求中斷，或是收到 5xx 回應，請按照「繼續執行中斷的上傳作業」一節所述的程序進行。

上傳多個區塊

如要以多個區塊上傳資料，請按照下列步驟操作：

JSON API

  1. 從要上傳的整體資料建立資料區塊。

    區塊大小應為 256 KiB (256 x 1024 位元組) 的倍數，但會完成上傳作業的最後一個區塊除外。通常來說，區塊越大，上傳速度就越快，但請注意，速度和記憶體用量之間會有所取捨。建議至少使用 8 MiB 的區塊大小。

  2. 使用 cURL 透過 PUT 物件要求呼叫 JSON API：

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • CHUNK_LOCATION 是目前上傳區塊的本機路徑。
    • CHUNK_SIZE 是您在目前要求中上傳的位元組數。例如：8388608。
    • CHUNK_FIRST_BYTE 是您要上傳的區塊在整個物件中的起始位元組。
    • CHUNK_LAST_BYTE 是您要上傳的區塊在整個物件中的結尾位元組。
    • TOTAL_OBJECT_SIZE 是您要上傳的物件總大小。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

    例如 Content-Range 是 Content-Range: bytes 0-8388607/20000000。如要進一步瞭解這個標頭，請參閱 Content-Range。

    如果要求成功，伺服器會傳回 308 Resume Incomplete。回應包含 Range 標頭。

  3. 針對要上傳的每個剩餘資料區塊，重複上述步驟，並使用每個回應的 Range 標頭中包含的上限值，決定每個後續區塊的開始位置；請勿假設伺服器已收到任何指定要求中傳送的所有位元組。

    您也可以在可續傳上傳作業的最終要求中，加入以 X-Goog-Meta- 為前置字元的要求標頭，為物件新增自訂中繼資料。

XML API

  1. 從要上傳的整體資料建立資料區塊。

    區塊大小應為 256 KiB (256 x 1024 位元組) 的倍數，但會完成上傳作業的最後一個區塊除外。通常來說，區塊越大，上傳速度就越快，但請注意，速度和記憶體用量之間會有所取捨。建議至少使用 8 MiB 的區塊大小。

  2. 使用 cURL 透過 PUT 物件要求呼叫 XML API：

    curl -i -X PUT --data-binary @CHUNK_LOCATION \
    -H "Content-Length: CHUNK_SIZE" \
    -H "Content-Range: bytes CHUNK_FIRST_BYTE-CHUNK_LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • CHUNK_LOCATION 是目前上傳區塊的本機路徑。
    • CHUNK_SIZE 是您在目前要求中上傳的位元組數。例如：8388608。
    • CHUNK_FIRST_BYTE 是您要上傳的區塊在整個物件中的起始位元組。
    • CHUNK_LAST_BYTE 是您要上傳的區塊在整個物件中的結尾位元組。
    • TOTAL_OBJECT_SIZE 是您要上傳的物件總大小。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

    例如 Content-Range 是 Content-Range: bytes 0-8388607/20000000。如要進一步瞭解這個標頭，請參閱 Content-Range。

    如果要求成功，伺服器會傳回 308 Resume Incomplete。回應包含 Range 標頭。

  3. 針對要上傳的每個剩餘資料區塊，重複上述步驟，並使用每個回應的 Range 標頭中包含的上限值，決定每個後續區塊的開始位置；請勿假設伺服器已收到任何指定要求中傳送的所有位元組。

上傳完成後，您會收到 200 OK 或 201 Created 回應，以及與資源相關聯的所有中繼資料。

如果任何區塊上傳作業中斷，或是收到 5xx 回應，您應重新傳送中斷的區塊，或從中斷處繼續上傳。

查看支援續傳的上傳作業狀態

如果可續傳的上傳作業中斷，或不確定上傳作業是否完成，可以檢查上傳狀態：

JSON API

  1. 使用 cURL 透過 PUT 物件要求呼叫 JSON API：

    curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_SIZE 是物件中的位元組總數。如果您不知道物件的完整大小，請使用 * 做為這個值。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

XML API

  1. 使用 cURL 透過 PUT 物件要求呼叫 XML API：

    curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • OBJECT_SIZE 是物件中的位元組總數。如果您不知道物件的完整大小，請使用 * 做為這個值。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

如果收到 200 OK 或 201 Created 回應，表示上傳作業已完成，不需採取任何行動。

308 Resume Incomplete 回應表示您需要繼續上傳資料。

  • 如果 Cloud Storage 尚未保存任何位元組，308 回應就不會包含 Range 標頭。在這種情況下，您應從頭開始上傳。
  • 否則，308 回應會包含 Range 標頭，指出 Cloud Storage 目前已儲存哪些位元組。繼續上傳中斷的檔案時，請使用這個值。

繼續執行中斷的上傳作業

如果上傳要求在收到回應前就終止，或者您收到 503 或 500 回應，那麼就需要從中斷處繼續處理上傳作業。如要繼續處理中斷的上傳作業，請按照下列步驟操作：

JSON API

  1. 檢查可續傳上傳作業的狀態。

  2. 將狀態檢查回應中包含的 Range 標頭上限值儲存起來。如果回應沒有 Range 標頭，表示 Cloud Storage 尚未保存任何位元組，您應從頭上傳。

  3. 請確認即將上傳的物件資料，是從 Range 標頭中上限值後方的位元組開始。

  4. 如果中斷的要求包含以 X-Goog-Meta- 為前置字元標頭，請在要求中加入這些標頭，以繼續上傳。

  5. 使用 cURL 透過 PUT 物件要求呼叫 JSON API，該要求會從 Range 標頭中值的下一個位元組開始擷取：

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • PARTIAL_OBJECT_LOCATION 是要上傳的剩餘資料本機路徑。
    • UPLOAD_SIZE_REMAINING 是您在目前要求中上傳的位元組數。舉例來說，如果上傳物件時中斷，且已上傳 0 到 42 個位元組，則上傳其餘部分時，UPLOAD_SIZE_REMAINING 會是 19999957，且物件總大小為 20000000。
    • NEXT_BYTE 是您在步驟 2 中儲存的值之後的下一個整數。舉例來說，如果 42 是步驟 2 中的上限值，則 NEXT_BYTE 的值為 43。
    • LAST_BYTE 是這項 PUT 要求中包含的結尾位元組。舉例來說，如要完成上傳總大小為 20000000 的物件，LAST_BYTE 的值為 19999999。
    • TOTAL_OBJECT_SIZE 是您要上傳的物件總大小。例如：20000000。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

XML API

  1. 檢查可續傳上傳作業的狀態。

  2. 儲存狀態檢查回應中包含的 Range 標頭上限值。如果回應沒有 Range 標頭，表示 Cloud Storage 尚未保存任何位元組，您應從頭上傳。

  3. 請確認即將上傳的物件資料，是從 Range 標頭中上限值後方的位元組開始。

  4. 使用 cURL 透過 PUT 物件要求呼叫 XML API，並從 Range 標頭中的值後方位元開始擷取：

    curl -i -X PUT --data-binary @PARTIAL_OBJECT_LOCATION \
    -H "Content-Length: UPLOAD_SIZE_REMAINING" \
    -H "Content-Range: bytes NEXT_BYTE-LAST_BYTE/TOTAL_OBJECT_SIZE" \
    "SESSION_URI"

    其中：

    • PARTIAL_OBJECT_LOCATION 是要上傳的剩餘資料本機路徑。
    • UPLOAD_SIZE_REMAINING 是您在目前要求中上傳的位元組數。舉例來說，如果上傳物件時中斷，且已上傳 0 到 42 個位元組，則上傳其餘部分時，UPLOAD_SIZE_REMAINING 會是 19999957，且物件總大小為 20000000。
    • NEXT_BYTE 是您在步驟 2 中儲存的值之後的下一個整數。舉例來說，如果 42 是步驟 2 中的上限值，則 NEXT_BYTE 的值為 43。
    • LAST_BYTE 是這項 PUT 要求中包含的結尾位元組。舉例來說，如要完成上傳總大小為 20000000 的物件，LAST_BYTE 的值為 19999999。
    • TOTAL_OBJECT_SIZE 是您要上傳的物件總大小。例如：20000000。
    • SESSION_URI 是您啟動可續傳上傳作業時，Location 標頭中傳回的值。

只要工作階段 URI 仍有效，你就能視需要多次繼續上傳。工作階段 URI 會在一週後失效。資料上傳成功後，Cloud Storage 會以 200 OK 或 201 created 狀態碼回應。

取消上傳

如要取消未完成的續傳上傳作業，並防止系統對該作業採取任何進一步動作，請按照下列步驟操作：

JSON API

  1. 使用 cURL 透過 DELETE 要求呼叫 JSON API：

    curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    其中：

如果成功，回應會包含 499 狀態碼。日後嘗試查詢或繼續上傳作業時，系統會傳回 4xx 回應。

XML API

  1. 使用 cURL 透過 DELETE 要求呼叫 XML API：

    curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"

    其中：

如果成功，回應會包含 204 狀態碼，日後查詢或繼續上傳的嘗試也會產生 204 回應。

失敗處理

在極少數情況下，由於 bucket 的權限已變更，或最終上傳物件的完整性檢查偵測到不符，因此要求繼續中斷上傳作業可能會失敗，並顯示無法重試的「4xx」錯誤。如果發生這種情況，請啟動新的續傳上傳作業工作階段，然後重試上傳。

後續步驟