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 之后的行。pageToken 应为对 searchMediaItems 请求的响应中 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

过滤条件

可应用于媒体内容搜索的过滤条件。如果已指定多个过滤器选项，则这些过滤器彼此将是“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 相册应用中标为收藏的媒体内容。