Method: mediaItems.batchCreate

在使用者的 Google 相簿相片庫中建立一或多個媒體項目。

這是建立媒體項目的第二個步驟。如要進一步瞭解步驟 1，將原始位元組上傳到 Google 伺服器，請參閱上傳媒體。

這項呼叫會將媒體項目新增至資料庫。如果指定相簿 id，呼叫也會將媒體項目新增至相簿。每本相簿最多可包含 20,000 個媒體項目。根據預設，媒體項目會新增到媒體庫或相簿的結尾。

如果同時定義相簿 id 和位置，則系統會將媒體項目新增至指定位置的相簿。

如果呼叫中包含多個媒體項目，系統會將這些項目新增至指定位置。您無法在非擁有者的共享相簿中建立媒體項目時，無法放置該媒體項目。否則會導致 BAD REQUEST 錯誤。

HTTP 要求

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構：

JSON 表示法 
{
  "albumId": string,
  "newMediaItems": [
    {
      object (NewMediaItem)
    }
  ],
  "albumPosition": {
    object (AlbumPosition)
  }
}
欄位
albumId

string

新增媒體項目的專輯 ID。媒體項目也會新增至使用者的媒體庫。此為選填欄位。
newMediaItems[]

object (NewMediaItem)

必要欄位。要建立的媒體項目清單。每次呼叫最多 50 個媒體項目。
albumPosition

object (AlbumPosition)

找到新增媒體項目的相簿中的位置。如未指定，媒體項目會新增至相簿結尾 (根據預設值，也就是 LAST_IN_ALBUM)。如果已設定這個欄位且未指定 albumId，要求將會失敗。如果你設定欄位，但不是共享相簿的擁有者，這項要求也會失敗。

回應主體

已建立媒體項目清單。

如果成功，回應主體即會包含具有以下結構的資料：

JSON 表示法 
{
  "newMediaItemResults": [
    {
      object (NewMediaItemResult)
    }
  ]
}
欄位
newMediaItemResults[]

object (NewMediaItemResult)

僅供輸出。已建立媒體項目清單。

授權範圍

需要下列其中一種 OAuth 範圍：

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.appendonly
  • https://www.googleapis.com/auth/photoslibrary.sharing

NewMediaItem

使用者 Google 相簿帳戶中建立的新媒體項目。

JSON 表示法 
{
  "description": string,

  // Union field new_media_item_type can be only one of the following:
  "simpleMediaItem": {
    object (SimpleMediaItem)
  }
  // End of list of possible types for union field new_media_item_type.
}
欄位
description

string

媒體項目的說明。系統會在 Google 相簿應用程式的項目資訊專區中向使用者顯示這則評論 (長度必須少於 1000 個半形字元)。只加入使用者撰寫的文字。說明應提供背景資訊，並協助使用者瞭解媒體內容。請勿加入任何自動產生的字串，例如檔案名稱、標記和其他中繼資料。
聯集欄位 new_media_item_type。新的媒體項目可以有多種類型，取決於上傳路徑。目前支援的上傳作業只會使用簡單的媒體項目路徑。new_media_item_type 只能是下列其中一項：
simpleMediaItem

object (SimpleMediaItem)

透過隨附的 uploadToken 上傳的新媒體項目。

SimpleMediaItem

透過上傳權杖在 Google 相簿中建立的簡易媒體項目。

JSON 表示法 
{
  "uploadToken": string,
  "fileName": string
}
欄位
uploadToken

string

這個權杖用於識別上傳至 Google 的媒體位元組。
fileName

string

含有媒體項目副檔名的檔案名稱。使用者會在 Google 相簿中看到。如果設定了這個欄位，系統會忽略位元組上傳程序中指定的檔案名稱。檔案名稱 (包含副檔名) 不得超過 255 個半形字元。此為選填欄位。

NewMediaItemResult

建立新媒體項目的結果。

JSON 表示法 
{
  "uploadToken": string,
  "status": {
    object (Status)
  },
  "mediaItem": {
    object (MediaItem)
  }
}
欄位
uploadToken

string

用來建立這個新 (簡單) 媒體項目的上傳權杖。只有在媒體項目十分簡單，且需要一個上傳權杖時，系統才會填入資料。
status

object (Status)

如果建立這個媒體項目時發生錯誤，這個欄位會填入錯誤相關資訊。如要進一步瞭解這個欄位，請參閱狀態。
mediaItem

object (MediaItem)

使用上傳權杖建立的媒體項目。如果未發生錯誤且媒體項目成功建立，系統就會填入這個欄位。