上傳媒體內容

上傳媒體項目的程序分為兩個步驟：

  1. 使用上傳端點將媒體檔案的位元組上傳至 Google 伺服器。這會傳回上傳權杖，用於識別已上傳的位元組。
  2. 使用上傳權杖搭配 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 相簿 Library API 支援可繼續上傳的內容。支援續傳的上傳作業可讓您將媒體檔案分割成多個部分，然後一次上傳一個部分。

步驟 2：建立媒體項目

上傳媒體檔案的位元組後，您可以使用上傳符記，在 Google 相簿中建立媒體項目。上傳憑證的有效期限為建立後的一天。媒體項目一律會新增至使用者的媒體庫。媒體項目只能新增至應用程式建立的相簿。詳情請參閱「授權範圍」。

如要建立新的媒體項目，請指定 newMediaItems 清單，然後呼叫 mediaItems.batchCreate。每個 newMediaItem 都包含在 simpleMediaItem 中指定的上傳憑證，以及向使用者顯示的選用說明。

說明欄位的字元限制為 1000 個，且只能包含使用者建立的有意義文字。例如「我們到公園玩」或「節慶晚餐」。請勿加入中繼資料，例如檔案名稱、程式輔助標記或其他自動產生的文字。

為達到最佳效能，請在單一呼叫中加入多個媒體項目，藉此減少對 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 供使用。詳情請參閱「存取媒體項目」。

如果在這個呼叫期間發生錯誤，請按照最佳做法重試要求。您可能需要追蹤成功新增的項目，以便在下次要求期間，將圖片插入相簿的正確位置。詳情請參閱「建立相簿」。

系統一律會依照上傳符記提交的順序傳回結果。

上傳最佳做法

下列最佳做法和資源有助於提升上傳作業的整體效率：

  • 請遵循重試和錯誤處理最佳做法，並留意下列要點：
    • 如果配額用盡，或是因為頻繁發出太多呼叫而受到頻率限制，就可能會發生 429 錯誤。請務必在先前的請求完成前，不要為同一位使用者呼叫 batchCreate。
    • 429 錯誤需要等待 30s 秒以上的時間才能重試。重試要求時，請使用指數輪詢策略。
    • 當伺服器發生錯誤時，就會發生 500 錯誤。上傳時，很有可能是因為同時為同一使用者發出多次寫入呼叫 (例如 batchCreate)。請查看要求的詳細資料，並避免同時呼叫 batchCreate。
  • 使用支援續傳的流程，在網路發生中斷時，讓上傳作業更穩健，讓您能繼續完成部分完成的上傳作業，減少頻寬用量。從用戶端行動裝置上傳，或是上傳大型檔案時，這一點非常重要。

此外，請參考以下提示，瞭解上傳程序的各個步驟：上傳位元組，然後建立媒體項目。

上傳位元組

建立媒體項目

  • 請勿為單一使用者同時呼叫 batchCreate。

    • 針對每個使用者，逐一呼叫 batchCreate (依序呼叫)。
    • 如果有多位使用者，請務必為每位使用者依序呼叫 batchCreate。請只為不同的使用者並行呼叫。

  • 在每次呼叫 batchCreate 時，盡可能加入 NewMediaItems，以盡量減少需要發出的呼叫總數。最多可納入 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 中，您只能為每位使用者一次發出一個呼叫。

虛擬程式碼

// 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.

請繼續進行這個程序，直到所有上傳和媒體建立呼叫都完成為止。