查询和统计数据集内文件，支持逻辑关系表达方式。
接口说明
-
请确保在使用该接口前，已充分了解智能媒体管理产品的收费方式和价格。
-
调用该接口前，请确保您已通过绑定方式（ CreateBinding ）或者主动索引（ IndexFileMeta 或者 BatchIndexFileMeta ）方式将文件索引到数据集（Dataset）中。
-
返回结果仅为示例，根据工作流模板配置不同，获取到的文件元数据信息的类别和包含的内容均有可能与示例不同。如果有疑问，请使用钉钉搜索钉钉群号 88490020073 加入钉钉群进行反馈。
使用限制
-
每次查询最多返回 100 个文件信息。
-
每次查询最多返回 2000 条聚合统计信息。
-
子查询条件最大支持设置 100 个。
-
子查询嵌套深度最多支持 5 层。
查询条件示例
- 如果要搜索 JPEG 格式的图片且图片尺寸大于 1000 像素，则 Query 填写示例如下：
{
"SubQueries":[
{
"Field":"ContentType",
"Value": "image/jpeg",
"Operation":"eq"
},
{
"Field":"ImageWidth",
"Value":"1000",
"Operation":"gt"
}
],
"Operation":"and"
}
- 如果要搜索
oss://examplebucket/path/中所有包含电视或音响标签的文件且该文件的大小大于 10 MB，则 Query 填写示例如下：
说明
这里
电视和音响是同一个文件的不同标签，在Labels字段中以两个独立对象的方式存在，请注意和下一个例子的区别。
{
"SubQueries": [
{
"Field": "URI",
"Value": "oss://examplebucket/path/",
"Operation": "prefix"
},
{
"Field": "Size",
"Value": "1048576",
"Operation": "gt"
},
{
"SubQueries": [
{
"Field": "Labels.LabelName",
"Value": "电视",
"Operation": "eq"
},
{
"Field": "Labels.LabelName",
"Value": "音响",
"Operation": "eq"
}
],
"Operation": "or"
}
],
"Operation": "and"
}
- 如果要排除人脸信息中有一个 36 岁以上的男性的文件，则 Query 填写示例如下：
说明
和上一个例子不同的是，这里要求某一个人脸同时满足 36 岁以上、男性两个条件，这和一张图片中有多个人脸，其中某个是男性，而其中另一个是 36 岁以上这个需求是不同的。在该请求中，需要使用
nested查询实现条件在同一个元素内同时满足的限制。
{
"Operation": "not",
"SubQueries": [{
"Operation": "nested",
"SubQueries": [{
"Operation": "and",
"SubQueries": [{
"Field": "Figures.Age",
"Operation": "gt",
"Value": "36"
}, {
"Field": "Figures.Gender",
"Operation": "eq",
"Value": "male"
}]
}]
}]
}
- 如果要搜索 JPEG 格式的图片且图片存在自定义标签和系统标签，则 Query 填写示例如下：
{
"SubQueries":[
{
"Field":"ContentType",
"Value": "image/jpeg",
"Operation":"eq"
},
{
"Field":"CustomLabels.test",
"Operation":"exist"
},
{
"Field":"Labels.LabelName",
"Operation":"exist"
}
],
"Operation":"and"
}
结合以上搜索条件，您还可以通过聚合操作实现不同数据的统计和分析，例如计算符合搜索条件的所有文件的大小总和、数量、平均值或者最值，统计所有符合搜索条件图片的尺寸分布情况。
调试
您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。
授权信息
下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：
- 操作：是指具体的权限点。
- 访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
- 资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用背景高亮的方式表示。
- 对于不支持资源级授权的操作，用
全部资源表示。
- 条件关键字：是指云产品自身定义的条件关键字。
- 关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。
| 操作 | 访问级别 | 资源类型 | 条件关键字 | 关联操作 |
|---|---|---|---|---|
| imm:SimpleQuery | list | *Dataset acs:imm:{#regionId}:{#accountId}:project/{#ProjectName}/dataset/{#DatasetName} |
| 无 |
请求参数
| 名称 | 类型 | 必填 | 描述 | 示例值 |
|---|---|---|---|---|
| NextToken | string | 否 | 当文件总数大于设置的 MaxResults 时，用于翻页的 token。 从 NextToken 开始按字典序返回文件信息列表。 第一次调用此接口时，设置为空。 | MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw== |
| MaxResults | integer | 否 |
| 10 |
| ProjectName | string | 是 | 项目名称，获取方式请参见创建项目。 | test-project |
| DatasetName | string | 是 | 数据集名称，获取方式请参见创建数据集。 | test-dataset |
| Query | SimpleQuery | 否 | 简单查询条件。请点击左侧链接查看详情。 | |
| Sort | string | 否 | 排序字段列表。请参考字段和操作符的支持列表。 说明
| Size,Filename |
| Order | string | 否 | 排序字段的排序方式。取值如下：
说明
| asc,desc |
| Aggregations | array<object> | 否 | 聚合字段信息列表。 注意 当您使用聚合查询时，仅返回聚合结果，不再返回匹配到的元信息列表。 | |
| object | 否 | 聚合字段信息的结构体。 | ||
| Field | string | 否 | 字段名称。关于支持的字段，请参见字段和操作符的支持列表。 | Size |
| Operation | string | 否 | 聚合字段的操作符。 枚举值：
| sum |
| WithFields | array | 否 | 仅返回特定字段的值，而不是全部已有的元信息字段。可用于降低返回的结构体大小。 不填或留空则返回所有字段。 | |
| string | 否 | 需要返回字段的字段名。支持 File 中列举支持的字段名。 | Filename | |
| WithoutTotalHits | boolean | 否 | 是否返回命中记录总数
|
返回参数
示例
正常返回示例
JSON格式
{
"NextToken": "MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==",
"RequestId": "2C5C1E0F-D8B8-4DA0-8127-EC32C771****",
"Files": [
{
"OwnerId": "102321002467****",
"ProjectName": "test-project",
"DatasetName": "test-dataset",
"ObjectType": "file",
"ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
"UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
"CreateTime": "2021-06-29T14:50:13.011643661+08:00",
"URI": "oss://test-bucket/test-object.jpg",
"OSSURI": "oss://examplebucket/sampleobject.jpg",
"Filename": "sampleobject.jpg",
"MediaType": "image",
"ContentType": "image/jpeg",
"Size": 1000,
"FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
"FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
"FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
"FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
"ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
"LatLong": "30.134390,120.074997",
"Timezone": "",
"Addresses": [
{
"Language": "zh-Hans",
"AddressLine": "中国浙江省杭州市余杭区文一西路969号",
"Country": "中国",
"Province": "浙江省",
"City": "杭州市",
"District": "余杭区",
"Township": "文一西路"
}
],
"TravelClusterId": "-",
"Orientation": 0,
"Figures": [
{
"FigureId": "868a9e74-cde5-4c7a-9013-28bb984****",
"FigureConfidence": 1,
"FigureClusterId": "Cluster-dbe72fec-b84c-4ab6-885b-3678e64****",
"FigureClusterConfidence": 1,
"FigureType": "face",
"Age": 29,
"AgeSD": 5,
"Gender": "female",
"GenderConfidence": 1,
"Emotion": "happiness",
"EmotionConfidence": 0.70784568786621,
"FaceQuality": 0.960875928401947,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
},
"Mouth": "close",
"MouthConfidence": 1,
"Beard": "none",
"BeardConfidence": 1,
"Hat": "none",
"HatConfidence": 1,
"Mask": "none",
"MaskConfidence": 1,
"Glasses": "none",
"GlassesConfidence": 0.8,
"Sharpness": 0.7,
"Attractive": 0.96,
"HeadPose": {
"Pitch": 18.385589599609375,
"Roll": 4.204030513763428,
"Yaw": 2.4945924282073975
}
}
],
"FigureCount": 10,
"Labels": [
{
"Language": "zh-Hans",
"LabelName": "椅子",
"LabelLevel": 2,
"LabelConfidence": 0.95,
"ParentLabelName": "家具",
"CentricScore": 0.877
}
],
"Title": "test",
"ImageWidth": 270,
"ImageHeight": 500,
"EXIF": "{\"Compression\":{\"value\":\"6\"},\"DateTime\":{\"value\":\"2020:08:19 17:11:11\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "欢迎使用智能媒体管理",
"Confidence": 0.8254936695098877,
"Boundary": {
"Width": 200,
"Height": 300,
"Left": 10,
"Top": 30,
"Polygon": [
{
"X": 10,
"Y": 10
}
]
}
}
],
"VideoWidth": 1080,
"VideoHeight": 1920,
"VideoStreams": [
{
"Index": 0,
"Language": "en",
"CodecName": "h264",
"CodecLongName": "H.264 / AVC / MPEG-4 AVC / MPEG-4 part 10",
"Profile": "High",
"CodecTimeBase": "1373627/83160000",
"CodecTagString": "avc1",
"CodecTag": "0x31637661",
"Width": 1280,
"Height": 720,
"HasBFrames": 2,
"SampleAspectRatio": "1:1",
"DisplayAspectRatio": "16:9",
"PixelFormat": "yuv420p",
"Level": 40,
"FrameRate": "25/1",
"AverageFrameRate": "25/1",
"TimeBase": "1/12800",
"StartTime": 0,
"Duration": 22.88,
"Bitrate": 5407765,
"FrameCount": 572,
"Rotate": "90",
"BitDepth": 8,
"ColorSpace": "bt709",
"ColorRange": "tv",
"ColorTransfer": "bt709",
"ColorPrimaries": "bt709"
}
],
"Subtitles": [
{
"Index": 2,
"Language": "en",
"CodecName": "mov_text",
"CodecLongName": "MOV text",
"CodecTagString": "tx3g",
"CodecTag": "0x67337874",
"StartTime": 0,
"Duration": 71.378,
"Bitrate": 74,
"Content": "欢迎",
"Width": 600,
"Height": 30
}
],
"AudioStreams": [
{
"Index": 1,
"Language": "en",
"CodecName": "aac",
"CodecLongName": "AAC (Advanced Audio Coding)",
"CodecTimeBase": "1/44100",
"CodecTagString": "mp4a",
"CodecTag": "0x6134706d",
"TimeBase": "1/48000",
"StartTime": 0.0235,
"Duration": 3.690667,
"Bitrate": 320087,
"FrameCount": 173,
"Lyric": "test",
"SampleFormat": "fltp",
"SampleRate": 48000,
"Channels": 2,
"ChannelLayout": "stereo"
}
],
"Artist": "Jane",
"AlbumArtist": "Jane",
"AudioCovers": [
{
"ImageWidth": 500,
"ImageHeight": 820,
"EXIF": "{\"FileSize\":{\"value\":\"29304\"},\"Format\":{\"value\":\"jpg\"}}",
"ImageScore": {
"OverallQualityScore": 0.736
},
"CroppingSuggestions": [
{
"AspectRatio": "2:3",
"Confidence": 0.742
}
],
"OCRContents": [
{
"Language": "zh-hans",
"Contents": "欢迎使用智能媒体管理",
"Confidence": 0.8254936695098877
}
]
}
],
"Composer": "Jane",
"Performer": "Jane",
"Language": "eng",
"Album": "FirstAlbum",
"PageCount": 5,
"ETag": "\"1D9C280A7C4F67F7EF873E28449****\"",
"CacheControl": "no-cache",
"ContentDisposition": "attachment; filename =test.jpg",
"ContentEncoding": "UTF-8",
"ContentLanguage": "zh-CN",
"AccessControlAllowOrigin": "https://aliyundoc.com",
"AccessControlRequestMethod": "PUT",
"ServerSideEncryptionCustomerAlgorithm": "SM4",
"ServerSideEncryption": "AES256",
"ServerSideDataEncryption": "SM4",
"ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
"OSSStorageClass": "Standard",
"OSSCRC64": "559890638950338001",
"ObjectACL": "default",
"ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
"OSSUserMeta": {
"key": "val"
},
"OSSTaggingCount": 2,
"OSSTagging": {
"key": "val"
},
"OSSExpiration": "2120-01-01T12:00:00.000Z",
"OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
"OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
"OSSObjectType": "Normal",
"CustomId": "\t\nmember-image-id-0001",
"CustomLabels": {
"MemberName": "Tim",
"Enabled": "True",
"ItemCount": "10"
},
"StreamCount": 1,
"ProgramCount": 1,
"FormatName": "mov",
"FormatLongName": "QuickTime / MOV",
"StartTime": 0,
"Bitrate": 13091201,
"Duration": 15.263,
"SemanticSimilarity": 0.855123,
"SemanticTypes": [
"content"
],
"Elements": [
{
"ElementContents": [
{
"Type": "text",
"Content": "文本片段",
"URL": "http://aliyun.com",
"TimeRange": [
0
]
}
],
"ObjectId": "",
"ElementType": "",
"SemanticSimilarity": 0,
"ElementRelations": [
{
"Type": "",
"ObjectId": ""
}
]
}
],
"SceneElements": [
{
"TimeRange": [
0
],
"FrameTimes": [
0
]
}
],
"OCRTexts": "阿里云IMM",
"FileStatus": "",
"Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
"SmartClusters": [
{
"SmartClusterId": "",
"Similarity": 0
}
],
"ObjectStatus": "Indexed",
"SequenceNumber": 3,
"ClusterStatus": {
"key": {
"key": [
""
]
}
},
"ClusterModifications": {
"key": {
"key": [
""
]
}
}
}
],
"Aggregations": [
{
"Field": "Size",
"Operation": "sum",
"Value": 200,
"Groups": [
{
"Value": "100",
"Count": 5
}
]
}
],
"TotalHits": 10
}错误码
访问错误中心查看更多错误码。
变更历史
| 变更时间 | 变更内容概要 | 操作 |
|---|---|---|
| 2023-11-22 | OpenAPI 入参发生变更 | 查看变更详情 |
| 2023-09-04 | OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2022-01-25 | OpenAPI 返回结构发生变更 | 查看变更详情 |
| 2021-06-15 | 新增 OpenAPI | 查看变更详情 |