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 相簿應用程式中，使用者可在該項目的資訊部分查看這項資訊。必須少於 1,000 個字元。只包含使用者撰寫的文字。說明應加入相關背景資訊，並協助使用者瞭解媒體。請勿加入任何自動產生的字串，例如檔案名稱、標記和其他中繼資料。
聯集欄位 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)

使用上傳憑證建立的媒體項目。如果未發生任何錯誤，且媒體項目建立成功，則會填入資料。