对象存储 标量检索

一、授权说明

通过子账号使用时，需要在授权策略的 action 中添加 ci:DatasetSimpleQuery 权限。数据万象支持的所有操作接口请参见 CI action。

二、使用限制

·使用检索前需要先完成创建数据集。

·仅支持北京、上海、成都地域，即请求 Host 中 Region 仅支持填写为 ap-beijing、ap-shanghai、ap-chengdu。

·更多使用限制，详情请参见使用限制。

三、请求示例

POST /datasetquery/simple HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: <Auth String>Content-Length: <length>Content-Type: application/jsonAccept: application/json

注意：说明：

注意：Authorization: Auth String，详情请参见请求签名文档。

四、请求头

此接口仅使用公共请求头部，详情请参见公共请求头部文档。

五、请求体

{ "DatasetName": "test", "Query": { "Operation": "and", "SubQueries": [{ "Field": "ContentType", "Value": "image/jpeg", "Operation": "eq" }, { "Field": "Size", "Value": "1000", "Operation": "gt" } ] }, "Sort": "CustomId", "Order": "desc", "MaxResults": 100}

六、请求参数

参数名称	描述	类型	是否必选
DatasetName	数据集名称，同一个账户下唯一。可通过控制台或接口查询。	String	是
Query	简单查询参数条件，可自嵌套。	Container	否
Sort	排序字段列表。请参见标量检索表达式语法。多个排序字段可使用半角逗号（,）分隔，例如：Size,Filename。最多可设置5个排序字段。排序字段顺序即为排序优先级顺序。	String	否
Order	排序字段的排序方式。取值如下：asc：升序；desc（默认）：降序。规则如下：多个排序方式可使用半角逗号（,）分隔，例如：asc,desc。排序方式不可多于排序字段，即参数 Order 的元素数量需小于等于参数 Sort 的元素数量。例如 Sort 取值为 Size,Filename 时，Order 可取值为 asc,desc 或 asc。排序方式少于排序字段时，未排序的字段默认取值 asc。例如 Sort 取值为 Size,Filename，Order 取值为 asc 时，Filename 默认排序方式为 asc，即升序排列。	String	否
MaxResults	返回文件元数据的最大个数。取值范围为0 – 200。使用聚合参数时，该值表示返回分组的最大个数，取值范围为0 – 2000。不设置此参数或者设置为0时，则取默认值100。	Integer	否
NextToken	当绑定关系总数大于设置的 MaxResults 时，用于翻页的 token。从 NextToken 开始按字典序返回绑定关系信息列表。第一次调用此接口时，设置为空。	String	否
Aggregations	聚合字段信息列表。当你使用聚合查询时，仅返回聚合结果，不再返回匹配到的元信息列表。	Container Array	否
WithFields	仅返回特定字段的值，而不是全部已有的元信息字段。可用于降低返回的结构体大小。不填或留空则返回所有字段。	String Array	否

Query 节点内容：

参数名称	描述	类型	是否必选
Operation	操作运算符。枚举值：not：逻辑非。or：逻辑或。and：逻辑与。lt：小于。lte：小于等于。gt：大于。gte：大于等于。eq：等于。exist：存在性查询。prefix：前缀查询。match-phrase：字符串匹配查询。	String	是
SubQueries	子查询的结构体。只有当 Operations 为逻辑运算符（and、or、not）时，才能设置子查询条件。在逻辑运算符为 and/or/not 时，其 SubQueries 内描述的所有条件需符合父级设置的 and/or/not 逻辑关系。	Container Array	否
Field	字段名称。关于支持的字段，请参考标量检索表达式语法。	String	否
Value	查询的字段值。当 Operations 为逻辑运算符（and、or、not）时，该字段无效。	String	否

Aggregations 节点内容：

参数名称	描述	类型	是否必选
Field	字段名称。关于支持的字段，请参考标量检索表达式语法。	String	否
Operation	聚合字段的操作符。枚举值：min：最小值。max：最大值。average：平均数。sum：求和。count：计数。distinct：去重计数。group：分组计数，按照分组计数结果从高到低排序。	String	否

七、响应头

此接口仅返回公共响应头部，详情请参见公共响应头部文档。

八、响应体

{ "Aggregations": [], "Files": [{ "COSCRC64": "1111122455985959955", "COSStorageClass": "STANDARD", "CacheControl": "", "ContentType": "image/jpeg", "CreateTime": "2023-12-26T14:29:25.753167285+08:00", "CustomId": "002", "CustomLabels": { "age": "18", "level": "18" }, "DatasetName": "test", "ETag": "\\"21aeb337eb76df70dcb1e2618598****5\\"", "FileAccessTime": "", "FileModifiedTime": "2023-06-07T07:20:28Z", "Filename": "examplebucket-1250000000/test002.jpg", "MediaType": "image", "ObjectACL": "default", "Size": "10000", "URI": "cos://examplebucket-1250000000/test002.jpg", "UpdateTime": "2023-12-26T14:38:11.575077683+08:00" }, { "COSCRC64": "1111125831785959934", "COSStorageClass": "STANDARD", "CacheControl": "", "ContentType": "image/jpeg", "CreateTime": "2023-12-26T11:43:18.92077679+08:00", "CustomId": "001", "CustomLabels": { "age": "18", "level": "18" }, "DatasetName": "test", "ETag": "\\"21aeb337eb76df70dcb1e2618598****\\"", "FileModifiedTime": "2023-06-07T07:18:04Z", "Filename": "examplebucket-1250000000/test001.jpg", "MediaType": "image", "ObjectACL": "default", "Size": "20000", "URI": "cos://examplebucket-1250000000/test001.jpg", "UpdateTime": "2023-12-26T11:45:02.445509346+08:00" }], "NextToken": "aP+BAwEBDlF1ZXJ5TmV4dFRva2VuAf+CAAEGAQpTb3J0RmllbGRzAQwAAQtTZWFyY2hBZnRlcgH/hAABBU9yZGVyAQwAAQVBcHBpZAEMAAEDVWluAQwAAQtEYXRhc2V0TmFtZQEMAAAAHP+DAgEBDltdaW50ZXJmYWNlIHt9Af+EAAEQAAAj/4IBCEN1c3RvbUlkAQEGc3RyaW5nDAUAAzAwMQEEZG*****", "RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****"}

响应包体具体数据内容如下：

参数名称	类型	描述
Aggregations	Container Array	聚合字段信息列表。仅在请求的 Aggregations 不为空时返回。
Files	Container Array	文件信息列表。仅在请求的 Aggregations 为空时返回。
RequestId	String	请求 ID。
NextToken	String	翻页标记。当文件总数大于设置的 MaxResults 时，用于翻页的 token。符合条件的文件信息未全部返回时，此参数才有值。下一次列出文件信息时将此值作为 NextToken 传入，将后续的文件信息返回。

File 节点内容：

参数名称	类型	描述
COSCRC64	String	文件 CRC64值。
COSStorageClass	String	文件存储空间类型。
CacheControl	String	指定 Object 被下载时网页的缓存行为。该字段需要设置 COS Object HTTP 属性 Cache-Control。
ContentType	String	文件内容类型（MIME Type）。
CreateTime	String	元数据创建时间的时间戳，格式为 RFC3339Nano。
CustomId	String	该文件的自定义 ID。该文件索引到数据集后，作为该行元数据的属性存储，用于和你的业务系统进行关联、对应。你可以根据业务需求传入该值，例如将某个 URI 关联到你系统内的某个 ID。推荐传入全局唯一的值。
CustomLabels	Container	文件自定义标签列表。储存你业务自定义的键名、键值对信息，用于在查询时可以据此为筛选项进行检索。
DatasetName	String	数据集名称。
ETag	String	Object 生成时会创建相应的 ETag ，ETag 用于标识一个 Object 的内容。
FileModifiedTime	String	文件最近一次修改时间的时间戳，格式为 RFC3339Nano。
Filename	String	文件路径。
MediaType	String	文件媒体类型。枚举值：image：图片。other：其他。document：文档。archive：压缩包。audio：音频。video：视频。
ObjectACL	String	文件访问权限属性。
Size	Int	文件大小，单位为字节。
URI	String	资源标识字段，表示需要建立索引的文件地址。
UpdateTime	String	元数据修改时间的时间戳，格式为 RFC3339Nano。创建元数据后，如果未更新过元数据，则元数据修改时间的时间戳和元数据创建时间的时间戳相同。
ObjectId	String	对象唯一 ID。
ContentDisposition	String	指定 Object 被下载时的名称。需要设置 COS Object HTTP 属性 Content-Disposition。
ContentEncoding	String	指定该 Object 被下载时的内容编码格式。需要设置 COS Object HTTP 属性 Content-Encoding。
ContentLanguage	String	Object 内容使用的语言。需要设置 COS Object HTTP 属性 Content-Language。
ServerSideEncryption	String	加密算法,需要设置 x-cos-server-side-encryption。
COSUserMeta	Container	COS 自定义头部。储存你的业务在 cos object 上的键名、键值对信息，用于在查询时可以据此为筛选项进行检索。
COSTagging	Container	COS 自定义标签。储存你的业务在 cos object 上的自定义标签的键名、键值对信息，用于在查询时可以据此为筛选项进行检索。
COSTaggingCount	Int	COS 自定义标签的数量。

Aggregations 节点内容：

参数名称	类型	描述
Field	String	聚合字段名称。
Operation	String	聚合字段的聚合操作符。
Value	Float	聚合的统计结果。
Groups	Container Array	分组聚合的结果列表。仅在请求的 Aggregations 中存在 group 类型的 Operation 时才会返回。

Groups 节点内容：

参数名称	类型	描述
Value	String	分组聚合的值。
Count	Integer	分组聚合的总个数。

九、请求

POST /datasetquery/simple HTTP/1.1Host: <AppId>.ci.<Region>.myqcloud.comAuthorization: <Auth String>Content-Length: <length>Content-Type: application/jsonAccept: application/json{ "DatasetName": "test", "Query": { "Operation": "and", "SubQueries": [{ "Field": "ContentType", "Value": "image/jpeg", "Operation": "eq" }, { "Field": "Size", "Value": "1000", "Operation": "gt" } ] }, "Sort": "CustomId", "Order": "desc", "MaxResults": 100}

十、响应

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 645Date: Thu, 15 Jun 2023 07:59:50 GMTStatus: 200 OKx-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****{ "Aggregations": [], "Files": [{ "COSCRC64": "1111122455985959955", "COSStorageClass": "STANDARD", "CacheControl": "", "ContentType": "image/jpeg", "CreateTime": "2023-12-26T14:29:25.753167285+08:00", "CustomId": "002", "CustomLabels": { "age": "18", "level": "18" }, "DatasetName": "test", "ETag": "\\"21aeb337eb76df70dcb1e2618598****5\\"", "FileAccessTime": "", "FileModifiedTime": "2023-06-07T07:20:28Z", "Filename": "examplebucket-1250000000/test002.jpg", "MediaType": "image", "ObjectACL": "default", "Size": "10000", "URI": "cos://examplebucket-1250000000/test002.jpg", "UpdateTime": "2023-12-26T14:38:11.575077683+08:00" }, { "COSCRC64": "1111125831785959934", "COSStorageClass": "STANDARD", "CacheControl": "", "ContentType": "image/jpeg", "CreateTime": "2023-12-26T11:43:18.92077679+08:00", "CustomId": "001", "CustomLabels": { "age": "18", "level": "18" }, "DatasetName": "test", "ETag": "\\"21aeb337eb76df70dcb1e2618598****\\"", "FileModifiedTime": "2023-06-07T07:18:04Z", "Filename": "examplebucket-1250000000/test001.jpg", "MediaType": "image", "ObjectACL": "default", "Size": "20000", "URI": "cos://examplebucket-1250000000/test001.jpg", "UpdateTime": "2023-12-26T11:45:02.445509346+08:00" }], "NextToken": "aP+BAwEBDlF1ZXJ5TmV4dFRva2VuAf+CAAEGAQpTb3J0RmllbGRzAQwAAQtTZWFyY2hBZnRlcgH/hAABBU9yZGVyAQwAAQVBcHBpZAEMAAEDVWluAQwAAQtEYXRhc2V0TmFtZQEMAAAAHP+DAgEBDltdaW50ZXJmYWNlIHt9Af+EAAEQAAAj/4IBCEN1c3RvbUlkAQEGc3RyaW5nDAUAAzAwMQEEZG*****", "RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****"}

十一、请求

十二、响应

HTTP/1.1 200 OKContent-Type: application/jsonContent-Length: 645Date: Thu, 15 Jun 2023 07:59:50 GMTStatus: 200 OKx-cos-request-id: NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****{ "RequestId": "NWFjMzQ0MDZfOTBmYTUwXzZkZV8z****", "Aggregations": [{ "Field": "Filename", "Groups": [{ "Count": 1, "Value": "file001" }, { "Count": 1, "Value": "file002" }], "Operation": "group" }], "Files": [], "NextToken": ""}