调用 ListSmartClusters 接口列出指定 Dataset 下所有 SmartCluster,支持按聚类类型与规则类型过滤,支持分页。
注意事项
阿里云账号默认拥有列出 SmartCluster 的权限。如需通过 RAM 用户调用,请确保 RAM 用户拥有
oss:MetaQuery权限。本接口仅在 OpenMetaQuery 时配置了
RouteRule启用多 Dataset 路由的场景下可用。单次最多返回 200 条,默认 100 条。多于该数量时通过响应中的
NextToken翻页。建议在调用时显式指定
clusterType,以确保返回对应类型的聚类列表。未指定时,某些场景可能不返回特定类型的聚类。列表项默认包含完整字段(含
Rules),无需再单独调用 GetSmartCluster 拉取详情。
请求语法
POST /?metaQuery&action=listSmartClusters&datasetName=DatasetName HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue请求头
此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。
请求元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
datasetName | 字符串 | 是 | photos-2026 | 要列出 SmartCluster 的 Dataset 名。 |
maxResults | 整型 | 否 | 50 | 单次返回的最大条数,取值范围 1 到 200,默认 100。 |
nextToken | 字符串 | 否 | MTIzNDU2 | 分页令牌,首次调用不传,后续翻页时传入上一次返回的 |
clusterType | 字符串 | 否 | figure | 按聚类类型过滤。取值如下:
|
ruleTypes | 字符串 | 否 | face | 按规则类型过滤,多值时用英文逗号(
|
响应头
此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。
响应元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
ListSmartClustersResponse | 容器 | 是 | 不涉及 | 响应根元素。 子节点:SmartClusters、NextToken |
SmartClusters | 容器 | 是 | 不涉及 | SmartCluster 列表容器。 子节点:SmartCluster 父节点:ListSmartClustersResponse |
SmartCluster | 容器 | 否 | 不涉及 | 单个 SmartCluster 详情容器。详细字段见 SmartCluster 数据结构。 父节点:SmartClusters |
NextToken | 字符串 | 否 | MTIzNDU2 | 下一页的分页令牌。无更多结果时为空。 父节点:ListSmartClustersResponse |
示例
请求示例
首页请求:
POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&maxResults=50 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:00 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e翻页请求:
POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&maxResults=50&nextToken=MTIzNDU2 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:10 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e按聚类类型 + 规则类型过滤(只列 figure 类型且基于 face 规则的聚类):
POST /?metaQuery&action=listSmartClusters&datasetName=photos-2026&clusterType=figure&ruleTypes=face&maxResults=50 HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 13:00:20 GMT
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20260520/cn-hangzhou/oss/aliyun_v4_request,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e返回示例
HTTP/1.1 200 OK
x-oss-request-id: 64C8B6F4E7C5A3A8B9D6E7FA
Date: Wed, 20 May 2026 13:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<ListSmartClustersResponse>
<SmartClusters>
<SmartCluster>
<ObjectId>cluster-abc123def456</ObjectId>
<ClusterType>figure</ClusterType>
<Name>face-cluster-alice</Name>
<Description>Cluster faces matching Alice</Description>
<Rules>
<Rule>
<RuleType>face</RuleType>
<BaseURIs>oss://examplebucket/refs/alice.jpg</BaseURIs>
</Rule>
</Rules>
<CreateTime>2026-05-20T11:00:00.000+08:00</CreateTime>
<UpdateTime>2026-05-20T11:08:00.000+08:00</UpdateTime>
</SmartCluster>
<SmartCluster>
<ObjectId>cluster-xyz789</ObjectId>
<ClusterType>knowledge</ClusterType>
<Name>keyword-cluster-vehicles</Name>
<Rules>
<Rule>
<RuleType>keywords</RuleType>
<Keywords>car</Keywords>
<Keywords>truck</Keywords>
</Rule>
</Rules>
<CreateTime>2026-05-20T12:00:00.000+08:00</CreateTime>
<UpdateTime>2026-05-20T12:00:00.000+08:00</UpdateTime>
</SmartCluster>
</SmartClusters>
<NextToken>MTIzNDU2</NextToken>
</ListSmartClustersResponse>