Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

執行支援續傳的上傳作業

總覽

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

如要瞭解如何在 Google Cloud CLI 和用戶端程式庫中使用支援續傳的上傳作業，請參閱「工具和 API 如何使用支援續傳的上傳作業」。

必要的角色

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

如要上傳包含物件保留鎖定的檔案，請要求管理員授予您 bucket 的 Storage 物件管理員 (roles/storage.objectAdmin) IAM 角色。
在其他情況下，請要求管理員授予您 bucket 的 Storage 物件使用者 (roles/storage.objectUser) IAM 角色。

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

所需權限

storage.objects.create
storage.objects.delete

只有在上傳作業會覆寫現有物件時，才需要這項權限。

storage.objects.setRetention
- 只有在上傳內容包含物件保留鎖定時，才需要這項權限。

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

如要瞭解如何授予 bucket 角色，請參閱「在 bucket 上設定及管理 IAM 政策」。

啟動支援續傳的上傳作業工作階段

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

JSON API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
您也可以建立 JSON 檔案，其中包含要為上傳物件設定的中繼資料。舉例來說，下列 JSON 檔案會將要上傳的物件 contentType 中繼資料設為 image/png：
```
{
    "contentType": "image/png"
}
```

使用 cURL 呼叫 JSON API，並傳送 POST 物件要求：

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 是要上傳物件的 bucket 名稱。例如：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

儲存續傳工作階段 URI，該 URI 位於 POST 物件要求回應的 location 標頭中。

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

注意： 請謹慎共用可續傳工作階段 URI，因為任何人都能使用該 URI 將資料上傳至目標 bucket，不需進一步驗證。

XML API

安裝並初始化 gcloud CLI，以便為 Authorization 標頭產生存取權杖。
使用 cURL 呼叫 XML API，並傳送內文空白的 POST 物件要求：
```
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 是要上傳物件的 bucket 名稱。例如：my-bucket。
- OBJECT_NAME 是要為物件指定的網址編碼名稱。例如 pets/dog.png，網址編碼為 pets%2Fdog.png。
如果您已啟用跨源資源共享，則應在此要求和後續上傳要求中加入 Origin 標頭。

如果成功，回應會包含 201 狀態訊息。
儲存續傳工作階段 URI，該 URI 位於 POST 物件要求回應的 location 標頭中。

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

注意： 請謹慎共用可續傳工作階段 URI，因為任何人都能使用該 URI 將資料上傳至目標 bucket，不需進一步驗證。

上傳資料

啟動支援續傳的上傳作業後，您可以透過兩種方式上傳物件資料：

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

單一區塊上傳

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

JSON API

使用 cURL 呼叫 JSON API，並傳送 PUT 物件要求：
```
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

使用 cURL 呼叫 XML API，並傳送 PUT 物件要求：
```
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

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

區塊大小應為 256 KiB (256 x 1024 位元組) 的倍數，除非是完成上傳作業的最後一個區塊。區塊越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要權衡。建議區塊大小至少為 8 MiB。
使用 cURL 呼叫 JSON API，並傳送 PUT 物件要求：
```
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 標頭。
針對要上傳的其餘資料區塊，重複上述步驟，並使用每個回應的 Range 標頭中包含的上限值，決定每個後續區塊的起始位置。請勿假設伺服器收到任何指定要求中傳送的所有位元組。

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

XML API

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

區塊大小應為 256 KiB (256 x 1024 位元組) 的倍數，除非是完成上傳作業的最後一個區塊。區塊越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要權衡。建議區塊大小至少為 8 MiB。
使用 cURL 呼叫 XML API，並傳送 PUT 物件要求：
```
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 標頭。
針對要上傳的其餘資料區塊，重複上述步驟，並使用每個回應的 Range 標頭中包含的上限值，決定每個後續區塊的起始位置。請勿假設伺服器收到任何指定要求中傳送的所有位元組。

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

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

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

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

JSON API

使用 cURL 呼叫 JSON API，並傳送 PUT 物件要求：
```
curl -i -X PUT \
    -H "Content-Length: 0" \
    -H "Content-Range: bytes */OBJECT_SIZE" \
    "SESSION_URI"
```
其中：
- OBJECT_SIZE 是物件中的位元組總數。如果不知道物件的完整大小，請將這個值設為 *。
- SESSION_URI 是您啟動支援續傳的上傳作業時，Location 標頭中傳回的值。

XML API

使用 cURL 呼叫 XML API，並傳送 PUT 物件要求：
```
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

查看支援續傳的上傳作業狀態。
儲存狀態檢查回應中 Range 標頭的最大值。如果回應沒有 Range 標頭，表示 Cloud Storage 尚未保留任何位元組，您應從頭開始上傳。
請確認您要上傳的物件資料，是從 Range 標頭中上限值後方的位元組開始。
如果中斷的要求包含前置字串為 X-Goog-Meta- 的標頭，請在要求中加入這些標頭，以便繼續上傳。
使用 cURL 呼叫 JSON API，並傳送 PUT 物件要求，從 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 是您在目前要求中上傳的位元組數。舉例來說，如果上傳總大小為 20000000 的物件，但在上傳 0-42 個位元組後中斷，則上傳其餘物件時，UPLOAD_SIZE_REMAINING 應為 19999957。
- NEXT_BYTE 是您在步驟 2 中儲存的值之後的下一個整數。舉例來說，如果 42 是步驟 2 中的上限值，則 NEXT_BYTE 的值為 43。
- LAST_BYTE 是這項 PUT 要求中包含的結尾位元組。舉例來說，如要完成上傳總大小為 20000000 的物件，LAST_BYTE 的值應為 19999999。
- TOTAL_OBJECT_SIZE 是上傳物件的總大小。例如，20000000。如果不知道物件的完整大小，請將這個值設為 *。
- SESSION_URI 是您啟動支援續傳的上傳作業時，Location 標頭中傳回的值。

XML API

查看支援續傳的上傳作業狀態。
儲存狀態檢查回應中 Range 標頭的最大值。如果回應沒有 Range 標頭，表示 Cloud Storage 尚未保留任何位元組，您應從頭開始上傳。
請確認您要上傳的物件資料，是從 Range 標頭中上限值後方的位元組開始。
使用 cURL 呼叫 XML API，並使用 PUT 物件要求，從 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 是您在目前要求中上傳的位元組數。舉例來說，如果上傳總大小為 20000000 的物件，但在上傳 0-42 個位元組後中斷，則上傳其餘物件時，UPLOAD_SIZE_REMAINING 應為 19999957。
- 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

使用 cURL 呼叫 JSON API，並傳送 DELETE 要求：
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
其中：
- SESSION_URI 是您啟動支援續傳的上傳作業時，Location 標頭中傳回的值。

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

XML API

使用 cURL 透過 DELETE 要求呼叫 XML API：
```
curl -i -X DELETE -H "Content-Length: 0" \
  "SESSION_URI"
```
其中：
- SESSION_URI 是您啟動支援續傳的上傳作業時，Location 標頭中傳回的值。

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

失敗處理機制

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

執行支援續傳的上傳作業 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

必要的角色

所需權限

啟動支援續傳的上傳作業工作階段

JSON API

XML API

上傳資料

單一區塊上傳

JSON API

XML API

多區塊上傳

JSON API

XML API

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

JSON API

XML API

繼續執行中斷的上傳作業

JSON API

XML API

取消上傳

JSON API

XML API

失敗處理機制

後續步驟

執行支援續傳的上傳作業