调用SimpleQuery接口查询和统计数据集内文件-智能媒体管理-阿里云

查询和统计数据集内文件，支持逻辑关系表达方式。

接口说明

请确保在使用该接口前，已充分了解智能媒体管理产品的收费方式和价格。
调用该接口前，请确保您已通过绑定方式（ 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	否	不传 Aggregations 参数查询文件时，表示返回文件的最大个数，取值范围为 0~100。传 Aggregations 参数进行聚合统计时，表示返回分组的最大个数，取值范围为 0~2000。不设置此参数或者设置为 0 时，则默认值为 100。	10
ProjectName	string	是	项目名称，获取方式请参见创建项目。	test-project
DatasetName	string	是	数据集名称，获取方式请参见创建数据集。	test-dataset
Query	SimpleQuery	否	简单查询条件。请点击左侧链接查看详情。
Sort	string	否	排序字段列表。请参考字段和操作符的支持列表。说明多个排序字段可使用半角逗号（,）分隔，例如：Size,Filename。最多可设置 5 个排序字段。排序字段顺序即为排序优先级顺序。	Size,Filename
Order	string	否	排序字段的排序方式。取值如下： asc：升序 desc（默认）：降序说明多个排序方式可使用半角逗号（,）分隔，例如：asc,desc。排序方式不可多于排序字段，即参数 Order 的元素数量需小于等于参数 Sort 的元素数量。例如 Sort 取值为 Size,Filename 时，Order 可取值为"asc,desc"。排序方式少于排序字段时，未排序的字段默认取值 desc。例如 Sort 取值为 Size,Filename，Order 取值为 asc 时，Filename 默认排序方式为 desc，即降序排列。	asc,desc
Aggregations	array<object>	否	聚合字段信息列表。注意当您使用聚合查询时，仅返回聚合结果，不再返回匹配到的元信息列表。
	object	否	聚合字段信息的结构体。
Field	string	否	字段名称。关于支持的字段，请参见字段和操作符的支持列表。	Size
Operation	string	否	聚合字段的操作符。枚举值： average：平均数。 min：最小值。 max：最大值。 count：计数。 distinct：去重计数。 sum：求和。 group：分组计数，按照分组计数结果从高到低排序。	sum
WithFields	array	否	仅返回特定字段的值，而不是全部已有的元信息字段。可用于降低返回的结构体大小。不填或留空则返回所有字段。
	string	否	需要返回字段的字段名。支持 File 中列举支持的字段名。	Filename
WithoutTotalHits	boolean	否	是否返回命中记录总数 true 不返回 TotalHits 字段 false 返回 TotalHits 字段

返回参数

名称	类型	描述	示例值
	object	响应结构体。
NextToken	string	当文件总数大于设置的 MaxResults 时，用于翻页的 token。下一次列出文件信息时以此值为 NextToken，将未返回的结果返回。当文件未全部返回时，此参数才有值。	MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
RequestId	string	请求 ID。	2C5C1E0F-D8B8-4DA0-8127-EC32C771****
Files	array	文件信息列表。仅在请求的 Aggregations 为空时返回。
Files	File	文件信息的结构体。
Aggregations	array<object>	聚合字段信息列表。仅在请求的 Aggregations 不为空时返回。
Aggregations	object	聚合字段信息结构体。
Field	string	聚合字段名称。	Size
Operation	string	聚合字段的聚合操作符。	sum
Value	double	聚合的统计结果。	200
Groups	array<object>	分组聚合的结果列表。仅在请求的 Aggregations 中存在 group 类型的 Operation 时才会返回。
Groups	object	分组聚合的结果。
Value	string	分组聚合的值。	100
Count	long	分组聚合的总个数。	5
TotalHits	long	命中的记录数。	10

示例

正常返回示例

JSON格式

{
  "NextToken": "MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==",
  "RequestId": "2C5C1E0F-D8B8-4DA0-8127-EC32C771****",
  "Files": [
    {
      "ProduceTime": "2021-06-29T14:50:13.011643661+08:00",
      "Timezone": "",
      "Artist": "Jane",
      "ObjectACL": "default",
      "FileStatus": "",
      "ContentType": "image/jpeg",
      "AccessControlRequestMethod": "PUT",
      "Size": 1000,
      "Album": "FirstAlbum",
      "ContentLanguage": "zh-CN",
      "OSSTagging": {
        "key": "val"
      },
      "Addresses": [
        {
          "Language": "zh-Hans",
          "AddressLine": "中国浙江省杭州市余杭区文一西路969号",
          "Country": "中国",
          "Province": "浙江省",
          "City": "杭州市",
          "District": "余杭区",
          "Township": "文一西路"
        }
      ],
      "StreamCount": 1,
      "CustomLabels": {
        "MemberName": "Tim",
        "Enabled": "True",
        "ItemCount": 10
      },
      "VideoHeight": 1920,
      "ImageWidth": 270,
      "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
        }
      ],
      "OSSStorageClass": "Standard",
      "SequenceNumber": 3,
      "MediaType": "image",
      "OSSDeleteMarker": "CAEQMhiBgIDXiaaB0BYiIGQzYmRkZGUxMTM1ZDRjOTZhNjk4YjRjMTAyZjhl****",
      "Insights": {
        "Video": {
          "Description": "无。",
          "Caption": "视频中展示了两个不同场景：一个是静止的白色盘子、黑色瓶子和透明玻璃杯，另一个是手拿着标有“YEZOLU”的洗发水瓶在浴室中缓慢上移。"
        },
        "Image": {
          "Caption": "无。",
          "Description": "图片中有一人，穿着深色西装外套，内搭白色衬衫。背景为渐变的浅蓝色至灰色。"
        }
      },
      "FormatLongName": "QuickTime / MOV",
      "ProgramCount": 1,
      "StartTime": 0,
      "Filename": "sampleobject.jpg",
      "Labels": [
        {
          "Language": "zh-Hans",
          "LabelName": "椅子",
          "LabelLevel": 2,
          "LabelConfidence": 0.95,
          "ParentLabelName": "家具",
          "CentricScore": 0.877
        }
      ],
      "Duration": 15.263,
      "Orientation": 0,
      "CroppingSuggestions": [
        {
          "AspectRatio": "2:3",
          "Confidence": 0.742,
          "Boundary": {
            "Width": 200,
            "Height": 300,
            "Left": 10,
            "Top": 30,
            "Polygon": [
              {
                "X": 10,
                "Y": 10
              }
            ]
          }
        }
      ],
      "EXIF": {
        "Compression": {
          "value": 6
        },
        "DateTime": {
          "value": "2020:08:19 17:11:11"
        }
      },
      "Performer": "Jane",
      "ImageHeight": 500,
      "PageCount": 5,
      "FigureCount": 10,
      "ImageScore": {
        "OverallQualityScore": 0.736
      },
      "ETag": "1D9C280A7C4F67F7EF873E28449****",
      "DatasetName": "test-dataset",
      "FileHash": "1d9c280a7c4f67f7ef873e28449dbe17",
      "CacheControl": "no-cache",
      "SmartClusters": [
        {
          "SmartClusterId": "",
          "Similarity": 0
        }
      ],
      "ClusterStatus": {
        "key": {
          "key": [
            ""
          ]
        }
      },
      "OSSVersionId": "CAEQNhiBgMDJgZCA0BYiIDc4MGZjZGI2OTBjOTRmNTE5NmU5NmFhZjhjYmY0****",
      "FileAccessTime": "2021-06-29T14:50:13.011643661+08:00",
      "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"
        }
      ],
      "ProjectName": "test-project",
      "VideoWidth": 1080,
      "AudioCovers": [
        {
          "ImageWidth": 500,
          "ImageHeight": 820,
          "EXIF": {
            "FileSize": {
              "value": 29304
            },
            "Format": {
              "value": "jpg"
            }
          },
          "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
                  }
                ]
              }
            }
          ]
        }
      ],
      "ContentEncoding": "UTF-8",
      "Elements": [
        {
          "ElementContents": [
            {
              "Type": "text",
              "Content": "文本片段",
              "URL": "http://aliyun.com",
              "TimeRange": [
                500
              ]
            }
          ],
          "ObjectId": "id1",
          "ElementType": "title - 标题； image - 图片 ； table - 表格 ； narrative-text - 正文",
          "SemanticSimilarity": 0.8,
          "ElementRelations": [
            {
              "Type": "child，parent",
              "ObjectId": "id1"
            }
          ]
        }
      ],
      "URI": "oss://test-bucket/test-object.jpg",
      "Reason": "[InternalError] The request has been failed due to some unknown error. status: 500, requestId: CC5ACFBD-BB7A-496D-A9D6-****",
      "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"
        }
      ],
      "ObjectStatus": "Indexed",
      "ObjectType": "file",
      "SceneElements": [
        {
          "TimeRange": [
            0
          ],
          "FrameTimes": [
            0
          ]
        }
      ],
      "ClusterModifications": {
        "key": {
          "key": [
            ""
          ]
        }
      },
      "ServerSideEncryptionKeyId": "9468da86-3509-4f8d-a61e-6eab1eac****",
      "OwnerId": "102321002467****",
      "FileModifiedTime": "2021-06-29T14:50:13.011643661+08:00",
      "Language": "eng",
      "FileCreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "SemanticTypes": [
        "content"
      ],
      "ServerSideEncryption": "AES256",
      "FormatName": "mov",
      "Composer": "Jane",
      "ObjectId": "75d5de2c50754e3dadd5c35dbca5f9949369e37eb342a73821f690c94c36c7f7",
      "CreateTime": "2021-06-29T14:50:13.011643661+08:00",
      "Title": "test",
      "TravelClusterId": "-",
      "OSSExpiration": "2120-01-01T12:00:00.000Z",
      "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,
          "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
          }
        }
      ],
      "ServerSideEncryptionCustomerAlgorithm": "SM4",
      "Bitrate": 13091201,
      "AlbumArtist": "Jane",
      "ContentMd5": "HZwoCnxPZ/fvhz4oRJ2+Fw==",
      "OCRTexts": "阿里云IMM",
      "ContentDisposition": "attachment; filename =test.jpg",
      "CustomId": "\t\nmember-image-id-0001",
      "UpdateTime": "2021-06-29T14:50:13.011643661+08:00",
      "OSSUserMeta": {
        "key": "val"
      },
      "OCRContents": [
        {
          "Language": "zh-hans",
          "Contents": "欢迎使用智能媒体管理",
          "Confidence": 0.8254936695098877
        }
      ],
      "AccessControlAllowOrigin": "https://aliyundoc.com",
      "OSSCRC64": 559890638950338000,
      "OSSTaggingCount": 2,
      "SemanticSimilarity": 0.855123,
      "OSSURI": "oss://examplebucket/sampleobject.jpg",
      "ServerSideDataEncryption": "SM4",
      "LatLong": "30.134390,120.074997",
      "OSSObjectType": "Normal"
    }
  ],
  "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	查看变更详情