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

用于指定搜索结果排序顺序的可选字段。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.app createddata 范围，系统将忽略此字段。

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 Photo、Android 动态照片、全景图片、Photo Sphere 照片。

FeatureFilter

此过滤条件定义了媒体内容应具有的功能。

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

enum (Feature)

要包含在媒体内容搜索结果中的一组功能。组中的项是 OR 关系，可以匹配任何指定地图项。

特征

可用作过滤条件的一组功能。

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