本頁面說明如何透過 REST 通訊協定，向 Google Photos Library API 提出支援續傳的上傳要求。此通訊協定可讓您在通訊失敗導致資料流動後繼續上傳作業。
如果您是使用用戶端程式庫的開發人員，請注意，某些用戶端程式庫提供原生支援支援續傳上傳作業。
在下列情況下，請使用支援續傳的上傳選項：
- 您正在上傳大型檔案。
- 網路中斷或其他傳輸失敗的可能性很高 (例如從行動應用程式上傳檔案)。
支援續傳的上傳作業在網路故障時，也可以減少頻寬用量，因為這樣您就不必從頭開始上傳大型檔案。
步驟 1：啟動上傳工作階段
傳送 POST 要求至 https://photoslibrary.googleapis.com/v1/uploads，以啟動支援續傳的上傳工作階段。使用這項要求中傳回的支援續傳上傳網址上傳檔案。
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，則表示上傳作業已終止。