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

影集的标识符。如果填充此字段，系统会列出指定影集中的所有媒体内容。无法同时设置该字段和任意过滤器。
pageSize

integer

响应中可返回的媒体项数量上限。返回的媒体内容数量可能会少于指定数量。pageSize 的默认值为 25，最大值为 100。
pageToken

string

获得下一页结果的延续令牌。将此属性添加到请求中，即可返回 pageToken 后面的行。在对 searchMediaItems 请求的响应中，pageToken 应该是 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
  • https://www.googleapis.com/auth/photoslibrary.readonly.originals

过滤条件

可应用于媒体内容搜索的过滤条件。如果指定了多个过滤条件选项，则系统会将这些选项视为“AND”，并且彼此之间是 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 Live Photos、Android 动态照片、全景图片、Photo Sphere 照片。

FeatureFilter

此过滤条件用于定义媒体内容应具备的功能。

JSON 表示法 
{
  "includedFeatures": [
    enum (Feature)
  ]
}
字段
includedFeatures[]

enum (Feature)

要包含在媒体项搜索结果中的功能集。组中的项通过 OR 进行组合，可以匹配任何指定的特征。

功能

可过滤的一组功能。

枚举
NONE 视为未应用任何过滤器。包含所有功能。
FAVORITES 用户在 Google 相册应用中标记为“收藏”的媒体内容。