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)

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