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

選用欄位，用於指定搜尋結果的排序順序。orderBy 欄位只有在使用 dateFilter 時才能運作。如未指定這個欄位，結果會根據 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
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

篩選器

可套用至媒體項目搜尋的篩選器。如果指定多個篩選器選項，它們會彼此視為 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；如要指定不含日期的年份，請輸入 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)

媒體項目搜尋結果中要納入的類別組合。組合中的項目會以 OR 方式處理。每項要求最多可包含 10 個 includedContentCategories。
excludedContentCategories[]

enum (ContentCategory)

不應納入媒體項目搜尋結果的類別組合。集合中的項目會以 OR 運算，每項要求最多可包含 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 相簿應用程式中將媒體項目標示為收藏項目。