Method: mediaItems.search

搜尋使用者 Google 相簿相片庫中的媒體項目。如未設定篩選器,系統會傳回使用者媒體庫中的所有媒體項目。如果已設定相簿,則會傳回指定相簿中的所有媒體項目。如果您指定了篩選器,系統就會列出符合使用者媒體庫篩選器的媒體項目。如果同時設定相簿和篩選器,要求會導致錯誤發生。

HTTP 要求

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

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

要求主體

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

JSON 表示法
{
  "albumId": string,
  "pageSize": integer,
  "pageToken": string,
  "filters": {
    object (Filters)
  },
  "orderBy": string
}
欄位
albumId

string

相簿的 ID。如果填入值,系統會列出指定相簿中的所有媒體項目。無法與任何篩選器一起設定。

pageSize

integer

回應中傳回的媒體項目數量上限。傳回的媒體項目可能少於指定數量。pageSize 的預設值為 25,上限為 100 個。

pageToken

string

取得下一頁結果的接續權杖。如果將這個類別加入要求,系統會傳回 pageToken 之後的資料列。pageToken 應為回應 searchMediaItems 要求回應的 nextPageToken 參數中傳回的值。

filters

object (Filters)

要套用至要求的篩選器。無法與 albumId 搭配使用。

orderBy

string

這是指定搜尋結果排序順序的選用欄位。只有在使用 dateFilter 時,orderBy 欄位才能發揮作用。如未指定這個欄位,結果就會依照 creationTime 最舊,最舊顯示。提供 MediaMetadata.creation_time 時,搜尋結果將按相反順序顯示,由舊到新排序。如要依先後順序顯示結果,方法是加入 desc 引數,如下所示:MediaMetadata.creation_time desc

可搭配此參數使用的唯一篩選器是 includeArchivedMediaexcludeNonAppCreatedData。不支援其他篩選器。

回應主體

符合搜尋參數的媒體項目清單。

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

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

object (MediaItem)

僅供輸出。符合搜尋參數的媒體項目清單。

nextPageToken

string

僅供輸出。使用此權杖取得下一組媒體項目。它是下次要求中有更多可用媒體項目且唯一可靠的指標。

授權範圍

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

  • https://www.googleapis.com/auth/photoslibrary
  • https://www.googleapis.com/auth/photoslibrary.readonly
  • https://www.googleapis.com/auth/photoslibrary.readonly.appcreateddata

篩選器

可套用至媒體項目搜尋的篩選條件。如果指定多個篩選器選項,系統會將這些選項視為 AND 並互相處理。

JSON 表示法
{
  "dateFilter": {
    object (DateFilter)
  },
  "contentFilter": {
    object (ContentFilter)
  },
  "mediaTypeFilter": {
    object (MediaTypeFilter)
  },
  "featureFilter": {
    object (FeatureFilter)
  },
  "includeArchivedMedia": boolean,
  "excludeNonAppCreatedData": boolean
}
欄位
dateFilter

object (DateFilter)

根據媒體項目建立日期篩選媒體項目。

contentFilter

object (ContentFilter)

根據媒體項目內容篩選媒體項目。

mediaTypeFilter

object (MediaTypeFilter)

根據媒體類型篩選媒體項目。

featureFilter

object (FeatureFilter)

根據媒體項目篩選媒體項目。

includeArchivedMedia

boolean

如果設定了這項政策,搜尋結果會包含使用者已封存的媒體項目。預設值為 false (不含已封存的媒體項目)。

excludeNonAppCreatedData

boolean

如果設定了這項政策,搜尋結果會排除並非由這個應用程式建立的媒體項目。預設值為 false (系統會傳回所有媒體項目)。如果使用 photoslibrary.readonly.appcreateddata 範圍,系統就會忽略這個欄位。

日期篩選器

這個篩選器定義了傳回媒體允許的日期範圍或日期範圍。您可以挑選一組特定日期和一組日期範圍。如果上傳的媒體項目未指定中繼資料的擷取日期,就不會在使用日期篩選器的查詢中傳回媒體項目。在這種情況下,Google 相簿伺服器上傳時間不會做為備用。

JSON 表示法
{
  "dates": [
    {
      object (Date)
    }
  ],
  "ranges": [
    {
      object (DateRange)
    }
  ]
}
欄位
dates[]

object (Date)

與媒體項目建立日期相符的日期清單。每個要求最多可包含 5 個日期。

ranges[]

object (DateRange)

與媒體項目建立日期相符的日期範圍清單。每個要求最多可包含 5 個日期範圍。

日期

代表整個日曆的日期。當只有重要月份和年份時,請將 day 設為 0,例如 2018 年 12 月。如果只有重要年份 (例如整個 2018 年),請將 daymonth 設為 0。如果只有重要日期和月份,請將 year 設為 0,例如週年或生日。

不支援:將所有值設為 0、只將 month 設為 0,或同時將 dayyear 都設為 0。

JSON 表示法
{
  "year": integer,
  "month": integer,
  "day": integer
}
欄位
year

integer

日期的年份。必須介於 1 到 9999 之間,如要指定不含年份的日期,請輸入 0。

month

integer

月份。必須是 1 到 12 之間的值,或是 0 才能指定不含月份和日期的年份。

day

integer

日。值必須介於 1 到 31 之間,且適用於年份和月份;如要指定非重要日期的年/月,則為 0。

日期範圍

用於定義日期範圍。兩個日期必須採用相同格式。詳情請參閱 Date

JSON 表示法
{
  "startDate": {
    object (Date)
  },
  "endDate": {
    object (Date)
  }
}
欄位
startDate

object (Date)

以上述其中一種格式顯示的開始日期 (在日期範圍範圍內)。

endDate

object (Date)

結束日期 (在日期範圍範圍內)。指定的格式必須與開始日期相同。

內容篩選器

這個篩選器可讓您根據內容類型傳回媒體項目。

您可以指定要納入的類別清單和/或要排除的類別清單。因此,每個清單中的類別都會以 OR 連結。

內容篩選器 includedContentCategories:[c1, c2, c3] 會取得包含 (c1 OR c2 或 c3) 的媒體項目。

內容篩選器 excludedContentCategories:[c1, c2, c3] 「不會」取得含有 (c1 OR c2 OR c3) 的媒體項目。

此外,您也可以加入某些類別,但排除其他類別,如以下範例所示:includedContentCategories:[c1, c2]、excludedContentCategories: [c3, c4]

上述範例會取得內含 (c1 OR c2) AND NOT (c3 OR c4) 的媒體項目,includedContentategories顯示的類別不能出現在excludedContentCategories中。

JSON 表示法
{
  "includedContentCategories": [
    enum (ContentCategory)
  ],
  "excludedContentCategories": [
    enum (ContentCategory)
  ]
}
欄位
includedContentCategories[]

enum (ContentCategory)

要納入媒體項目搜尋結果的類別組合。組合中的項目會以 OR 連接。每項要求最多只能有 10 個 includedContentCategories

excludedContentCategories[]

enum (ContentCategory)

不會納入媒體項目搜尋結果的類別組合。組合中的項目會以 OR 連接。每項要求最多只能有 10 個 excludedContentCategories

內容類別

這組預先定義的內容類別可供篩選。

列舉
NONE 預設內容類別。如果在篩選器中使用任何其他類別,系統會忽略這個類別。
LANDSCAPES 包含橫向的媒體項目。
RECEIPTS 包含收據的媒體項目。
CITYSCAPES 包含城市景觀的媒體項目。
LANDMARKS 包含地標的媒體項目。
SELFIES 自拍媒體項目。
PEOPLE 包含人物的媒體項目。
PETS 寵物包含的媒體項目。
WEDDINGS 婚禮的媒體項目。
BIRTHDAYS 生日的媒體項目。
DOCUMENTS 包含文件的媒體項目。
TRAVEL 旅遊期間拍攝的媒體項目。
ANIMALS 包含動物的媒體項目。
FOOD 包含食物的媒體項目。
SPORT 體育賽事的媒體項目。
NIGHT 夜間拍攝的媒體項目。
PERFORMANCES 來自成效的媒體項目。
WHITEBOARDS 包含白板的媒體項目。
SCREENSHOTS 螢幕截圖的媒體項目,
UTILITY 視為實用性的媒體項目,包括但不限於文件、螢幕截圖、白板等。
ARTS 包含藝術品的媒體項目。
CRAFTS 包含手工藝的媒體項目。
FASHION 與時尚相關的媒體項目。
HOUSES 包含房屋的媒體項目。
GARDENS 包含花園的媒體項目。
FLOWERS 包含花朵的媒體項目。
HOLIDAYS 節日拍攝的媒體項目。

媒體類型篩選器

這個篩選器會定義要傳回的媒體項目類型,例如影片或相片。系統僅支援一種媒體類型,

JSON 表示法
{
  "mediaTypes": [
    enum (MediaType)
  ]
}
欄位
mediaTypes[]

enum (MediaType)

要納入的媒體項目類型。這個欄位只能填入一種媒體類型。如果指定多個媒體類型,就會發生錯誤。

MediaType

可供搜尋的媒體類型組合。

列舉
ALL_MEDIA 視為未套用篩選器。包含所有媒體類型。
VIDEO 所有屬於影片的媒體項目。使用者使用 Google 相簿應用程式製作的電影也包括在內。
PHOTO 所有屬於相片的媒體項目。包括 .bmp、.gif、.ico、.jpg (和其他拼寫)、.tiff、.webp 和特殊相片類型 (例如 iOS 實景相片、Android 動態相片、全景相片、全景相片)。

特徵篩選器

這個篩選器定義了媒體項目應具備的功能。

JSON 表示法
{
  "includedFeatures": [
    enum (Feature)
  ]
}
欄位
includedFeatures[]

enum (Feature)

要納入媒體項目搜尋結果的一組功能。組合中的項目以 OR 表示,並可能符合任何指定的地圖項目。

特徵

可供篩選的功能組合。

列舉
NONE 視為未套用篩選器。具備所有功能。
FAVORITES 使用者在 Google 相簿應用程式中標示為收藏的媒體項目。