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。

這個參數只能搭配 includeArchivedMedia 和 excludeNonAppCreatedData 使用。不支援其他篩選器。

回應主體

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

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

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 範圍，則系統會忽略這個欄位。

DateFilter

這個篩選器會定義回傳媒體可設定的日期或日期範圍。您可以選擇某一組日期和一組日期範圍。如果上傳的媒體項目沒有指定擷取媒體項目的日期，則無法使用日期篩選器的查詢傳回。在這種情況下，系統不會將 Google 相簿伺服器上傳時間當做備用方案。

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

object (Date)

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

object (DateRange)

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

日期

代表整個日曆日期。如果只有年份和月份重要，例如整個 2018 年 12 月，請將 day 設為 0。如果只有一年如此重要，例如整個 2018 年，請將 day 和 month 設為 0。如果只有日期和月份重要 (例如週年或生日)，請將 year 設為 0。

不支援：將所有值設為 0、僅將 month 設為 0，或同時將 day 和 year 設為 0。

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

integer

日期。必須為 1 到 9999 或 0，才能指定不含年份的日期。
month

integer

一年中的月份。必須介於 1 到 12 之間；如要指定不含月和日的年份，請輸入 1 至 0。
day

integer

日。值必須介於 1 至 31 之間，且有效的年份和月份。如果指定的年份/月份不重要，這個值必須為 0。

DateRange

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

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

object (Date)

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

object (Date)

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

ContentFilter

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

您可以指定要納入的類別清單和/或要排除的類別清單。在每份清單中，這些類別會以 OR 合併。

內容篩選器 includedContentCategories: [c1, c2, c3] 會取得包含 (c1 OR c2 OR 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)

要納入媒體項目搜尋結果的類別組合。組合中的項目會以「或」方式呈現。每個要求最多只能有 10 個includedContentCategories。
excludedContentCategories[]

enum (ContentCategory)

不會納入媒體項目搜尋結果的一組類別。組合中的項目會以「或」方式呈現。每個要求最多只能有 10 個excludedContentCategories。

ContentCategory

此為一組預先定義的內容類別，可供您進行篩選。

列舉
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 假日拍攝的媒體項目。

MediaTypeFilter

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

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

enum (MediaType)

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

MediaType

可搜尋的媒體類型組合。

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

FeatureFilter

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

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

enum (Feature)

要納入媒體項目搜尋結果的一組功能。組合中的項目具有 OR 類型，且可能符合任何指定的功能。

功能

可篩選的功能組合。

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