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

篩選器

可套用至媒體項目搜尋的篩選器。如果指定多個篩選器選項，它們會彼此視為 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 相簿應用程式中標示為收藏的媒體項目。