文档

SimpleQuery - 简单查询

更新时间:

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

接口说明

  • 请确保在使用该接口前,已充分了解智能媒体管理产品的收费方式和价格

  • 调用该接口前,请确保您已通过绑定方式( CreateBinding )或者主动索引( IndexFileMeta 或者 BatchIndexFileMeta )方式将文件索引到数据集(Dataset)中。

  • 返回结果仅为示例,根据工作流模板配置不同,获取到的文件元数据信息的类别和包含的内容均有可能与示例不同。如果有疑问,请使用钉钉搜索钉钉群号 31690030817 加入钉钉群进行反馈。

使用限制

  • 每次查询最多返回 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暂无授权信息透出。

请求参数

名称类型必填描述示例值
NextTokenstring

当文件总数大于设置的 MaxResults 时,用于翻页的 token。

从 NextToken 开始按字典序返回文件信息列表。

第一次调用此接口时,设置为空。

MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
MaxResultsinteger
  • 不传 Aggregations 参数查询文件时,表示返回文件的最大个数,取值范围为 0~100。

  • 传 Aggregations 参数进行聚合统计时,表示返回分组的最大个数,取值范围为 0~2000。

  • 不设置此参数或者设置为 0 时,则默认值为 100。

10
ProjectNamestring

项目名称,获取方式请参见创建项目

test-project
DatasetNamestring

数据集名称,获取方式请参见创建数据集

test-dataset
QuerySimpleQuery

简单查询条件。请点击左侧链接查看详情。

Sortstring

排序字段列表。请参考字段和操作符的支持列表

说明
  • 多个排序字段可使用半角逗号(,)分隔,例如:Size,Filename。
  • 最多可设置 5 个排序字段。
  • 排序字段顺序即为排序优先级顺序。
  • Size,Filename
    Orderstring

    排序字段的排序方式。取值如下:

    • asc:升序

    • desc(默认):降序

    说明
  • 多个排序方式可使用半角逗号(,)分隔,例如:asc,desc。
  • 排序方式不可多于排序字段,即参数 Order 的元素数量需小于等于参数 Sort 的元素数量。例如 Sort 取值为 Size,Filename 时,Order 可取值为 desc 或 asc。
  • 排序方式少于排序字段时,未排序的字段默认取值 asc。例如 Sort 取值为 Size,Filename,Order 取值为 asc 时,Filename 默认排序方式为 asc,即升序排列。
  • asc,desc
    Aggregationsobject []

    聚合字段信息列表。

    注意 当您使用聚合查询时,仅返回聚合结果,不再返回匹配到的元信息列表。

    Fieldstring

    字段名称。关于支持的字段,请参见字段和操作符的支持列表

    Size
    Operationstring

    聚合字段的操作符。

    枚举值:
    • average平均数
    • min最小值
    • max最大值
    • count计数
    • distinct去重计数
    • sum求和
    • group分组计数,按照分组计数结果从高到低排序
    sum
    WithFieldsarray

    仅返回特定字段的值,而不是全部已有的元信息字段。可用于降低返回的结构体大小。

    不填或留空则返回所有字段。

    string

    需要返回字段的字段名。支持 File 中列举支持的字段名。

    Filename
    WithoutTotalHitsboolean

    是否返回命中记录总数

    • true 不返回 TotalHits 字段
    • false 返回 TotalHits 字段

    返回参数

    名称类型描述示例值
    object

    响应结构体。

    NextTokenstring

    当文件总数大于设置的 MaxResults 时,用于翻页的 token。

    下一次列出文件信息时以此值为 NextToken,将未返回的结果返回。

    当文件未全部返回时,此参数才有值。

    MTIzNDU2Nzg6aW1tdGVzdDpleGFtcGxlYnVja2V0OmRhdGFzZXQwMDE6b3NzOi8vZXhhbXBsZWJ1Y2tldC9zYW1wbGVvYmplY3QxLmpwZw==
    RequestIdstring

    请求 ID。

    2C5C1E0F-D8B8-4DA0-8127-EC32C771****
    Filesarray

    文件信息列表。仅在请求的 Aggregations 为空时返回。

    File

    文件信息的结构体。

    Aggregationsobject []

    聚合字段信息列表。仅在请求的 Aggregations 不为空时返回。

    Fieldstring

    聚合字段名称。

    Size
    Operationstring

    聚合字段的聚合操作符。

    sum
    Valuedouble

    聚合的统计结果。

    200
    Groupsobject []

    分组聚合的结果列表。仅在请求的 Aggregations 中存在 group 类型的 Operation 时才会返回。

    Valuestring

    分组聚合的值。

    100
    Countlong

    分组聚合的总个数。

    5
    TotalHitslong

    命中的记录数。

    10

    示例

    正常返回示例

    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": 1,
              "LabelConfidence": 1,
              "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,
          "SemanticTypes": [
            ""
          ],
          "Elements": [
            {
              "ElementContents": [
                {
                  "Type": "",
                  "Content": "",
                  "URL": ""
                }
              ]
            }
          ],
          "OCRTexts": ""
        }
      ],
      "Aggregations": [
        {
          "Field": "Size",
          "Operation": "sum",
          "Value": 200,
          "Groups": [
            {
              "Value": "100",
              "Count": 5
            }
          ]
        }
      ],
      "TotalHits": 10
    }

    错误码

    访问错误中心查看更多错误码。

    变更历史

    变更时间变更内容概要操作
    2023-11-22OpenAPI 入参发生变更看变更集
    变更项变更内容
    入参OpenAPI 入参发生变更
      新增入参:WithoutTotalHits
    2023-09-04OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更
    2022-01-25OpenAPI 返回结构发生变更看变更集
    变更项变更内容
    出参OpenAPI 返回结构发生变更
    2021-06-15新增 OpenAPI看变更集
    • 本页导读 (1)
    文档反馈