本頁說明如何向 Google Photos Library API 提出支援續傳的上傳要求 宣告內容如因通訊問題導致資料傳輸過程遭到中斷，之後可透過此通訊協定繼續執行上傳作業。
如果您符合下列任一情況，請使用支援續傳的上傳選項：
- 你正在上傳大型檔案。
- 網路中斷或其他傳輸錯誤的可能性為 高 (例如您從行動應用程式上傳檔案)。
發生網路問題時，可續傳上傳功能也可以減少頻寬用量，因為您不需要從頭開始上傳大型檔案。
步驟 1：啟動上傳工作階段
請向 https://photoslibrary.googleapis.com/v1/uploads 傳送 POST 要求，啟動可續傳的上傳工作階段。使用支援續傳的上傳作業
請在此要求中傳回網址，然後上傳檔案。
POST 要求必須包含下列標頭：
| 標頭欄位 | |
|---|---|
Content-Length |
由於要求主體為空白，請將其設為 0。 |
X-Goog-Upload-Command |
請設為 start。 |
X-Goog-Upload-Content-Type |
設為檔案的 mime 類型，例如 image/jpeg。 |
X-Goog-Upload-Protocol |
請設為 resumable。 |
X-Goog-Upload-Raw-Size |
設定為檔案資料的位元組總數 已轉移。 |
以下是 POST 要求標頭：
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: bytes-of-file
步驟 2：儲存工作階段網址
如果成功，POST 要求會傳回 200 OK HTTP 狀態碼，包括
。
X-Goog-Upload-URL: url-to-make-uploads-to X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes
標頭欄位 x-goog-upload-chunk-granularity 包含用戶端傳送的所有資料區塊的位元組對齊和大小精細度。如果上傳
所有上傳作業都會以多個區塊執行，除了上次上傳，所有上傳作業外。
必須採用這個值的倍數也就是上傳檔案的位元組
必須對齊這個值。在最後一小段中，您可以上傳剩餘的位元組。
標頭欄位 X-Goog-Upload-URL 包含不重複的網址，必須透過所有剩餘要求才能完成上傳。請複製並儲存這個可續傳的工作階段網址，以便在後續的要求中使用。
步驟 3：上傳檔案
有兩種方式可以上傳檔案包含支援續傳的工作階段：
- 在單一要求中這種做法通常是最佳做法，因為它需要較少的要求，因此效能較佳。
-
分成多個片段。在這種方法中，上傳作業會透過分割資料，以多個要求進行。資料會以
x-goog-upload-chunk-granularity的倍數分割。如有必要，可以重試分割要求。如果符合以下描述，請使用這個方法：
- 您需要減少任一單一 請求。如果在報表設有固定時間限制的情況下 個別要求
- 您需要提供自訂指標來表示上傳內容 進度。
- 您必須知道何時可以安全捨棄資料。
單一請求
如何透過單一要求上傳檔案：
- 建立
POST要求至可續傳的工作階段網址。 - 將檔案資料新增至要求主體。
新增下列 HTTP 標頭：
Content-Length：設為 檔案。X-Goog-Upload-Command：設為upload, finalize。
傳送要求。
如果上傳要求中斷，或是你收到 5xx
請按照恢復
中斷上傳。
如果要求成功，您會在回應主體中收到 200 OK HTTP 狀態碼和上傳符記。建立
使用這個上傳憑證建立媒體項目。
多個區塊
如何分塊上傳檔案：
- 請對可續傳工作階段網址建立
POST要求。 -
將區塊的資料新增至要求主體。
除了完成上傳作業的最後一個區塊，其他區塊的大小都必須是可接受的區塊大小的倍數。保留 區塊的區塊越大，上傳效率越好
-
新增下列 HTTP 標頭：
Content-Length：設為 區塊X-Goog-Upload-Command：設為upload。針對最後一個區塊，請設為upload, finalize。X-Goog-Upload-Offset：設為應寫入位元組的偏移量。請注意，您必須上傳位元組 依序執行第一個偏移量是0。
- 傳送要求。
如果上傳要求中斷，或是你收到
5xx請按照恢復 中斷上傳。 - 針對檔案中剩餘的每個區塊重複執行這些步驟。
如果要求成功，您會在回應主體中收到 200 OK HTTP 狀態碼和上傳符記。建立
使用這個上傳憑證建立媒體項目。
範例
單一請求
以下範例顯示可續傳要求，可在單一要求中上傳 3,039,417 位元組的 JPEG 檔案。
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
回應會包含上傳網址和預期的區塊大小：
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
最終上傳要求：
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 3039417 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 0 [BYTES 0-4199999]
多個區塊
以下範例說明透過可續傳的要求
3,039,417 位元組 JPEG 檔案，分成多個區塊，透過可續傳工作階段
取得的網址和可接受的區塊大小精細程度。
這個範例使用 262,144 位元組的區塊大小，這是在初始化上傳工作階段時，在標頭欄位 x-goog-upload-chunk-granularity 中傳回的值。請注意，每次上傳都包含的位元組
是 262,144 的倍數
初始化上傳工作階段，接收上傳網址和區塊大小 如前一步驟所述：
POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: start X-Goog-Upload-Content-Type: image/jpeg X-Goog-Upload-Protocol: resumable X-Goog-Upload-Raw-Size: 3039417 [no body]
回應包含上傳網址和預期的區塊大小：
HTTP/1.1 200 OK X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable X-Goog-Upload-Chunk-Granularity: 262144
第一個區塊：
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 0 [BYTES 0-1048575]
第二個區塊：
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 1048576 X-Goog-Upload-Command: upload X-Goog-Upload-Offset: 1048576 [BYTES 1048576-2097151]
最後區塊：
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 942265 X-Goog-Upload-Command: upload, finalize X-Goog-Upload-Offset: 2097152 [BYTES 2097152-4200000]
繼續中斷的上傳作業
如果上傳要求中斷，或是您收到非 200 HTTP 狀態碼，請查詢伺服器，找出上傳成功的資料量。
以下是可續傳工作階段網址的 POST 要求。X-Goog-Upload-Command
應設為 query。
POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1 Content-Length: 0 X-Goog-Upload-Command: query
伺服器的回應包含 200 OK HTTP 狀態碼，以及
目前的上傳大小
HTTP/1.1 200 OK X-Goog-Upload-Status: active X-Goog-Upload-Size-Received: 100
然後，您可以從這個偏移處繼續上傳。除非您傳送了合併的上傳和完成指令，否則必須從伺服器提供的位移處繼續上傳，在這種情況下，您也可以從位移 0 處繼續上傳。
如果查詢指令的 HTTP 回應中出現 X-Goog-Upload-Status 標頭，且值並非 active，表示上傳作業已終止。