- HTTP 请求
- 请求正文
- 响应正文
- 授权范围
- 过滤条件
- DateFilter
- Date
- DateRange
- ContentFilter
- ContentCategory
- MediaTypeFilter
- MediaType
- FeatureFilter
- 功能
- 试试看!
搜索用户 Google 相册媒体库中的媒体内容。如果未设置过滤条件,则系统会返回用户媒体库中的所有媒体内容。如果设置了影集,则返回指定影集中的所有媒体内容。如果指定了过滤条件,系统会列出与用户媒体库中的过滤条件匹配的媒体内容。如果您同时设置了影集和过滤条件,则请求会导致错误。
HTTP 请求
POST https://photoslibrary.googleapis.com/v1/mediaItems:search
网址采用 gRPC 转码语法。
请求正文
请求正文中包含结构如下的数据:
JSON 表示法 |
---|
{
"albumId": string,
"pageSize": integer,
"pageToken": string,
"filters": {
object ( |
字段 | |
---|---|
albumId |
影集的标识符。如果填充,则列出指定影集中的所有媒体内容。无法同时设置此字段和任何过滤条件。 |
pageSize |
响应中要返回的媒体项数量上限。返回的媒体内容可能少于指定数量。 |
pageToken |
获得下一页结果的延续令牌。将此内容添加到请求中会返回 |
filters |
要应用于请求的过滤条件。不能与 |
orderBy |
用于指定搜索结果排序顺序的可选字段。 可与此参数搭配使用的其他过滤条件只有 |
响应正文
与搜索参数匹配的媒体内容列表。
如果成功,响应正文将包含结构如下的数据:
JSON 表示法 |
---|
{
"mediaItems": [
{
object ( |
字段 | |
---|---|
mediaItems[] |
仅供输出。与搜索参数匹配的媒体内容列表。 |
nextPageToken |
仅供输出。使用此令牌获取下一组媒体项。其存在是下一个请求中有更多媒体项可用的唯一可靠指标。 |
授权范围
需要以下 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 |
根据内容过滤媒体项。 |
mediaTypeFilter |
根据媒体类型过滤媒体项。 |
featureFilter |
根据功能过滤媒体项。 |
includeArchivedMedia |
如果设置了此字段,则结果会包含用户已归档的媒体内容。默认设置为 false(不包括已归档的媒体内容)。 |
excludeNonAppCreatedData |
如果设置此字段,则结果会排除并非由此应用创建的媒体内容。默认值为 false(系统会返回所有媒体内容)。如果使用 photoslibrary.readonly.app createddata 范围,系统将忽略此字段。 |
DateFilter
此过滤条件用于指定允许返回媒体的日期或日期范围。您可以选择一组具体日期和一组日期范围。如果上传的媒体内容没有指定媒体内容拍摄日期的元数据,则不会在使用日期过滤条件的查询中返回。在这种情况下,系统不会将 Google 相册服务器上传时间用作后备方案。
JSON 表示法 |
---|
{ "dates": [ { object ( |
字段 | |
---|---|
dates[] |
与媒体内容创建日期匹配的日期列表。每个请求最多可包含 5 个日期。 |
ranges[] |
与媒体项的创建日期相匹配的日期范围列表。每个请求最多可包含 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 |
日期。必须介于 1 到 9999 之间,如果为 0,则可以指定不带年份的日期。 |
month |
一年中的月。必须是 1 到 12 之间的数字,如果输入 0,则不指定月份和日期。 |
day |
某日。必须是 1 到 31 之间的数字,并且对年份和月份有效,如果指定了日期不重要的年/月,则为 0。 |
DateRange
定义日期范围。两个日期必须采用相同的格式。如需了解详情,请参阅 Date
。
JSON 表示法 |
---|
{ "startDate": { object ( |
字段 | |
---|---|
startDate |
采用上述某种格式的开始日期(包含在日期范围内)。 |
endDate |
结束日期(包含在范围中)。必须指定与开始日期相同的格式。 |
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 ( |
字段 | |
---|---|
includedContentCategories[] |
媒体内容搜索结果中包含的一组类别。该组中的项之间为 OR 关系。每个请求最多包含 10 个 |
excludedContentCategories[] |
媒体项搜索结果中不会包含的一组类别。该组中的项之间为 OR 关系。每个请求最多包含 10 个 |
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 ( |
字段 | |
---|---|
mediaTypes[] |
包含的媒体项的类型。此字段应仅填充一种媒体类型。如果您指定多种媒体类型,会导致错误。 |
MediaType
可搜索的媒体类型集。
枚举 | |
---|---|
ALL_MEDIA |
视为未应用任何过滤条件。包含所有媒体类型。 |
VIDEO |
被视为视频的所有媒体项。以及用户使用 Google 相册应用制作的电影。 |
PHOTO |
被视为照片的所有媒体项。包括 .bmp、.gif、.ico、.jpg(和其他拼写)、.tiff、.webp 和特殊类型的照片,如 iOS Live Photo、Android 动态照片、全景图片、Photo Sphere 照片。 |
FeatureFilter
此过滤条件定义了媒体内容应具有的功能。
JSON 表示法 |
---|
{
"includedFeatures": [
enum ( |
字段 | |
---|---|
includedFeatures[] |
要包含在媒体内容搜索结果中的一组功能。组中的项是 OR 关系,可以匹配任何指定地图项。 |
特征
可用作过滤条件的一组功能。
枚举 | |
---|---|
NONE |
视为未应用任何过滤条件。包含所有功能。 |
FAVORITES |
用户在 Google 相册应用中标记为收藏的媒体内容。 |