本頁說明如何向 Google Photos Library API 提出支援續傳的上傳要求 宣告內容此通訊協定可讓您繼續執行上傳作業 導致資料流動中斷。
如果您符合下列任一情況,請使用支援續傳的上傳選項:
- 你正在上傳大型檔案。
- 網路中斷或其他傳輸錯誤的可能性為 高 (例如您從行動應用程式上傳檔案)。
在有網路的情況下,支援續傳的上傳作業也能減少頻寬用量 匯入作業失敗,因為您不需要從 自訂機器學習模型 但不想花時間從頭調整機器學習參數
步驟 1:啟動上傳工作階段
傳送 POST 要求,以啟動支援續傳的上傳工作階段:
https://photoslibrary.googleapis.com/v1/uploads
。使用此要求中傳回的可續傳上傳網址,上傳檔案。
POST 要求必須包含下列標頭:
標頭欄位 | |
---|---|
Content-Length |
要求主體為 0 ,因此請設為 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
,表示上傳
已經終止。