上傳媒體項目包含兩個步驟:
- 使用上傳端點,將媒體檔案的位元組上傳至 Google 伺服器。這樣就會傳回可識別的上傳憑證 上傳的位元組。
- 使用 batchCreate 呼叫搭配上傳憑證,以便: 為使用者的 Google 相簿帳戶建立媒體項目。
以下步驟概述單一媒體項目的上傳程序。如果您是 上傳多個媒體項目 (非常可能適用於任何生產應用程式) 請參閱上傳影片的最佳做法,瞭解如何改善上傳內容的成效 效率。
事前準備
必要的授權範圍
如要將媒體項目上傳至使用者的媒體庫或相簿,需要有
photoslibrary.appendonly
範圍。如要進一步瞭解範圍,請參閱
授權範圍。
接受的檔案類型和大小
您可以上傳這個表格中列出的檔案類型。
媒體類型 | 接受的檔案類型 | 檔案大小上限 |
---|---|---|
相片 | AVIF、BMP、GIF、HEIC、ICO、JPG、PNG、TIFF、WEBP、部分 RAW 檔案。 | 200 MB |
影片 | 3GP、3G2、ASF、AVI、DIVX、M2T、M2TS、M4V、MKV、MMV、MOD、MOV、MP4、 MPG、MTS、TOD、WMV。 | 20 GB |
步驟 1:上傳位元組
使用上傳要求將位元組上傳至 Google。成功的上傳要求會以原始文字串的形式傳回上傳權杖。使用這些上傳項目
符記透過 batchCreate
呼叫建立媒體項目。
REST
請在 POST 要求標頭中加入下列欄位:
標頭欄位 | |
---|---|
Content-type |
請設為 application/octet-stream 。 |
X-Goog-Upload-Content-Type |
(建議使用) 設為上傳位元組的 MIME 類型。
常見的 MIME 類型包括 image/jpeg 、
image/png 和image/gif 。
|
X-Goog-Upload-Protocol |
請設為 raw 。 |
以下是 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/uploads Authorization: Bearer oauth2-token Content-type: application/octet-stream X-Goog-Upload-Content-Type: mime-type X-Goog-Upload-Protocol: raw
在要求主體中,包含檔案的二進位檔案:
media-binary-data
如果這個 POST 要求成功,則上傳憑證,格式如下:
原始文字字串的一組,做為回應主體傳回。製作媒體
項目,請在 batchCreate
呼叫中使用這些文字字串。
upload-token
建議的圖片檔案大小不超過 50 MB。大於 50 MB 的檔案 可能會出現效能問題
Google Photos Library API 支援續傳功能 上傳內容。支援續傳的上傳作業可讓您 將媒體檔案分成多個部分,然後一次上傳一個部分。
步驟 2:建立媒體項目
上傳媒體檔案的位元組後,即可建立媒體檔案做為媒體檔案。 Google 相簿中的項目。上傳憑證的有效期限為建立後的一天。媒體項目一律會新增至使用者的媒體庫。媒體項目只能新增至 您的相簿: 應用程式。詳情請參閱「授權」一文 範圍。
如要建立新的媒體項目,請呼叫
mediaItems.batchCreate
敬上
方法是指定 newMediaItems
清單每個 newMediaItem
都包含一張上傳作業
在 simpleMediaItem
中指定的符記,並視需要提供說明
向使用者顯示的圖表
說明欄位的字數上限為 1,000 個字元,而且只能包含 富含實質意義的文字例如「我們到公園玩耍」或「節慶晚餐」。請勿加入中繼資料,例如檔案名稱、程式輔助標記或其他自動產生的文字。
為達到最佳效能,請在單一呼叫中加入多個媒體項目,藉此減少必須對 mediaItems.batchCreate
發出的呼叫次數。一律等到
先前的要求已完成,再對同一個
內容。
您可以在使用者的媒體庫中建立一或多個媒體項目 指定說明和相應的上傳權杖:
REST
以下是 POST 要求標頭:
POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate Content-type: application/json Authorization: Bearer oauth2-token
要求主體應指定 newMediaItems
清單。
{ "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ] }
也可以將 albumId
和 albumPosition
指定
在相簿的特定位置插入媒體項目。
REST
{ "albumId": "album-id", "newMediaItems": [ { "description": "item-description", "simpleMediaItem": { "fileName": "filename", "uploadToken": "upload-token" } } , ... ], "albumPosition": { "position": "after-media-item", "relativeMediaItemId": "media-item-id" } }
如要進一步瞭解相簿位置,請參閱新增 充實。
商品建立回應
mediaItems.batchCreate
呼叫會傳回您嘗試建立的每個媒體項目結果。newMediaItemResults
清單會指出狀態和
包含要求的 uploadToken
。非零的狀態碼表示
錯誤。
REST
如果所有媒體項目都建立成功,要求會傳回
HTTP 狀態:200 OK
。如果無法建立部分媒體項目,要求會傳回 HTTP 狀態 207 MULTI-STATUS
,表示部分成功。
{ "newMediaItemResults": [ { "uploadToken": "upload-token", "status": { "message": "Success" }, "mediaItem": { "id": "media-item-id", "description": "item-description", "productUrl": "https://photos.google.com/photo/photo-path", "mimeType": "mime-type", "mediaMetadata": { "width": "media-width-in-px", "height": "media-height-in-px", "creationTime": "creation-time", "photo": {} }, "filename": "filename" } }, { "uploadToken": "upload-token", "status": { "code": 13, "message": "Internal error" } } ] }
如果成功新增項目,系統會傳回包含下列內容的 mediaItem
mediaItemId
、productUrl
和mediaMetadata
。若需更多資訊,請參閲
存取媒體項目。
如果媒體項目是影片,則必須先處理。mediaItem
在 mediaMetadata
包含 status
,用於說明處理程序
影片檔案的狀態新上傳的檔案會先傳回 PROCESSING
狀態,然後才會 READY
供使用。詳情請參閱「存取媒體項目」。
如果在這個呼叫期間發生錯誤,請按照最佳做法重試要求。個人中心 可能會想追蹤成功新增的項目 下一次要求時,移到相簿的正確位置上。如要 相關資訊,請參閱「建立 相簿。
傳回結果的順序一律會與上傳權杖相同 就會引發這個事件。
上傳最佳做法
下列最佳做法和資源有助於提升整體效率 上傳的影片:
- 遵循重試和錯誤處理的最佳方法 做法、維護 以下是一些注意事項:
- 使用支援續傳的流程 可讓您在網路服務中斷時更穩健地上傳 減少頻寬用量。這個 內容從用戶端行動裝置上傳,或在上傳時是很重要的 大型檔案。
至於上傳程序的各個步驟,也請考慮下列提示: 上傳位元組,然後建立媒體 項目。
上傳位元組
- 您可以並行上傳位元組 (用來擷取上傳權杖)。
- 請務必在每個上傳呼叫的
X-Goog-Upload-Content-Type
標頭中設定正確的 MIME 類型。
建立媒體項目
請勿為單一使用者同時呼叫
batchCreate
。- 針對每個使用者,逐一呼叫
batchCreate
(在 序列)。 - 為多位使用者,一律為每位使用者發出
batchCreate
呼叫 字詞。只同時呼叫「不同的使用者」。
- 針對每個使用者,逐一呼叫
加入越多
NewMediaItems
越好 每次呼叫batchCreate
以盡量減少通話總數 。您最多可以加入 50 個項目。設定有意義的說明文字 建立的相關名稱請勿加入中繼資料,例如 例如檔案名稱、程式輔助代碼 或其他自動產生 說明欄位中的值
範例逐步操作說明
本範例使用偽碼逐步說明如何為多位使用者上傳媒體項目。目的是大致列出上傳程序 (上傳原始檔案) 的兩個步驟 位元組和建立媒體項目) 和 詳細說明如何打造有效且有彈性的上傳機制 擷取及準備資料、針對特定領域進行預先訓練 調整指示、離線評估和整合
步驟 1:上傳原始位元組
首先請建立佇列,上傳所有媒體項目的原始位元組
使用者。追蹤每位使用者傳回的每個uploadToken
。請記住以下重點:
- 同時上傳執行緒的數量取決於您的作業數量 環境。
- 視需要重新排序上傳佇列。例如,您可以 根據每位使用者剩餘的上傳量, 使用者的整體進度或其他需求
虛擬程式碼
CREATE uploadQueue FROM users, filesToUpload // Upload media bytes in parallel. START multiple THREADS WHILE uploadQueue is not empty POP uploadQueue UPLOAD file for user GET uploadToken CHECK and HANDLE errors STORE uploadToken for user in uploadTokensQueue END
步驟 2:建立媒體項目
在步驟 1 中,您可以並行上傳多位使用者的多個位元組, 步驟 2 步驟 2 後,您一次只能為每位使用者進行一次呼叫。
虛擬程式碼
// For each user, create media items once 50 upload tokens have been // saved, or no more uploads are left per user. WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user // Calls can be made in parallel for different users, // but only make a single call per user at a time. START new thread for (this) user if there is no thread yet POP 50 uploadTokens from uploadTokensQueue for user CALL mediaItems.batchCreate with uploadTokens WAIT UNTIL batchCreate call has completed CHECK and HANDLE errors (retry as needed) DONE.
請繼續進行這個程序,直到所有上傳和媒體建立呼叫都完成為止。