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.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 相簿應用程式中將媒體項目標示為收藏項目。