Method: mediaItems.list

針對指定裝置，傳回使用者設定的媒體來源所提供的背景媒體項目清單。

根據預設，listMediaItems 會提供 Ambient 體驗，從所有使用者設定的來源中傳回精選的媒體項目。

您也可以在要求中加入 mediaSourceId，從特定媒體來源擷取分頁項目清單，以便進行傳統篩選。

用戶端應用程式每部裝置每日最多可提出 240 次要求。

如果使用者未設定任何媒體來源，就會發生 FAILED_PRECONDITION 錯誤。

HTTP 要求

GET https://photosambient.googleapis.com/v1/mediaItems

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

查詢參數

參數
deviceId

string

必要欄位。這個裝置的專屬 ID。
mediaSourceId

string

(選用步驟) 如果是微光模式，請省略這個欄位。這項操作會從所有已設定的來源傳回精選媒體項目組合。傳回的項目數量會遵循您的 pageSize 要求，最多 100 個項目。如果指定了媒體來源，系統只會傳回該來源的項目。

id 必須是使用者為指定裝置選取的來源 (即 AmbientDevice.media_sources.id 之一)。

請注意，即使使用者選取 highlights 做為裝置的來源，系統也不支援 highlights。如果將這個欄位設為 highlights，系統會傳回 INVALID_ARGUMENT 錯誤。
pageSize

integer

(選用步驟) 要傳回的媒體項目數量上限。

服務會遵循您的 pageSize 要求，但傳回的項目可能少於指定的項目 (包括零個結果)。

如果未指定 pageSize 或設為 0，最多會傳回 50 個媒體項目。大於 100 的值會強制設為 100 這個最大允許值。如果提供負值，就會導致 INVALID_ARGUMENT 錯誤。
pageToken

string

(選用步驟) 從先前 mediaItems.list 呼叫收到的網頁權杖。提供此項目即可擷取後續網頁。

要求主體

要求主體必須為空白。

回應主體

對 mediaItems.list 方法的回應。

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

JSON 表示法 
{
  "mediaItems": [
    {
      object (AmbientMediaItem)
    }
  ],
  "nextPageToken": string
}
欄位
mediaItems[]

object (AmbientMediaItem)

裝置要顯示的微光媒體項目頁面。
nextPageToken

string

如果已設定，這個欄位可用於後續 mediaItems.list 呼叫中的 pageToken，用於擷取下一頁的項目。

如果省略這個欄位，不一定表示無法再擷取內容，而是後續內容頁面可能包含先前頁面已傳回的媒體項目。

授權範圍

需要下列 OAuth 範圍：

  • https://www.googleapis.com/auth/photosambient.mediaitems