上傳媒體內容

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

  1. 使用 uploads 端點，將媒體檔案的位元組上傳至 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 Photos Library API 支援可續傳的上傳作業。支援續傳的上傳作業可將媒體檔案分割成多個部分，然後一次上傳一個部分。

步驟 2：建立媒體項目

上傳媒體檔案的位元組後，您可以使用上傳權杖，在 Google 相簿中將這些檔案建立為媒體項目。上傳權杖的效期為建立當天起算的一天內。媒體項目一律會新增至使用者的媒體庫。媒體項目只能新增至應用程式建立的相簿。詳情請參閱「授權範圍」。

如要建立新的媒體項目，請呼叫 mediaItems.batchCreate 並指定 newMediaItems 清單。每個 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
  • 使用可續傳的上傳流程，在網路中斷時提高上傳作業的穩定性，並允許您續傳部分完成的上傳作業，藉此減少頻寬用量。從用戶端行動裝置上傳檔案，或上傳大型檔案時，這項設定就非常重要。

此外，請參考下列上傳程序各步驟的訣竅：上傳位元組，然後建立媒體項目。

上傳位元組數

  • 上傳位元組 (以擷取上傳權杖) 可以平行執行。
  • 請務必在每次上傳呼叫的X-Goog-Upload-Content-Type標頭中，設定正確的 MIME 類型。

建立媒體項目

  • 請勿為單一使用者平行呼叫 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.

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