執行支援續傳的上傳作業

JSON API

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

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

   {
       "contentType": "image/png"
   }

3. 使用 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.s3nsapis.fr/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

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

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

XML API

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

2. 使用 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.s3nsapis.fr/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 狀態訊息。

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

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

JSON API

1. 使用 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

1. 使用 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 標頭中傳回的值。

JSON API

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

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

2. 使用 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 標頭。

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

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

XML API

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

   區塊大小應為 256 KiB (256 x 1024 位元組) 的倍數，除非是完成上傳作業的最後一個區塊。區塊越大，上傳速度通常越快，但請注意，速度和記憶體用量之間需要權衡。建議區塊大小至少為 8 MiB。

2. 使用 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 標頭。

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

JSON API

1. 使用 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

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 標頭中傳回的值。

JSON API

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

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

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

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

5. 使用 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

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

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

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

4. 使用 cURL 呼叫 XML API，並使用 PUT Object 要求，在 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 標頭中傳回的值。

JSON API

1. 使用 cURL 呼叫 JSON API，並傳送 DELETE 要求：

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

   其中：

   • SESSION_URI 是您啟動支援續傳的上傳作業時，Location 標頭中傳回的值。

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

XML API

1. 使用 cURL 呼叫 XML API，並傳送 DELETE 要求：

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

   其中：

   • SESSION_URI 是您啟動支援續傳的上傳作業時，在 Location 標頭中傳回的值。

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