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

要在回應中傳回的媒體項目數量上限。傳回的媒體項目數量可能少於指定數量。預設值為 25，最大值為 100。pageSize
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

篩選器

可套用至媒體項目搜尋的篩選器。如果指定多個篩選器選項，它們會彼此視為 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

如果設為 true，結果就會排除非由此應用程式建立的媒體項目。預設值為 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 相簿應用程式中將媒體項目標示為收藏項目。