调用 UpdateSmartCluster 接口更新指定 SmartCluster 的名称、描述、聚类规则或消息通知配置。
注意事项
阿里云账号默认拥有更新 SmartCluster 的权限。如需通过 RAM 用户更新,请确保 RAM 用户拥有
oss:MetaQuery权限。本接口仅在 OpenMetaQuery 时配置了
RouteRule启用多 Dataset 路由的场景下可用。可选参数(
name、description、rules、notification)至少需要传入一个,否则返回InvalidArgument(HTTP 400)。更新
rules后,系统会重新触发聚类计算,期间原聚类结果暂不可用,直到后台重算完成。聚类类型不可修改;如需切换类型,请先 DeleteSmartCluster 再 CreateSmartCluster。
修改后的
name在 Dataset 内仍需唯一,否则返回SmartClusterAlreadyExist(HTTP 409)。
请求语法
POST /?metaQuery&action=updateSmartCluster&datasetName=DatasetName&objectId=ObjectId HTTP/1.1
Host: BucketName.oss-cn-hangzhou.aliyuncs.com
Date: GMT Date
Authorization: SignatureValue请求头
此接口仅涉及公共请求头。更多信息,请参见公共请求头(Common Request Headers)。
请求元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
datasetName | 字符串 | 是 | photos-2026 | SmartCluster 所在的 Dataset 名。 |
objectId | 字符串 | 是 | cluster-abc123def456 | SmartCluster 的唯一 ID。 |
name | 字符串 | 否 | face-cluster-alice-v2 | 新的 SmartCluster 名,Dataset 内仍需唯一,长度最长 128 字符。 |
description | 字符串 | 否 | Updated description | 新的描述文本,长度最长 128 字符。 |
rules | SmartClusterRule 数组 | 否 | [{"RuleType":"face","BaseURIs":["oss://examplebucket/refs/alice2.jpg"]}] | 新的聚类规则数组。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。更新后会重新触发聚类计算。 子节点:SmartClusterRule |
SmartClusterRule | 容器 | 否 | 不涉及 | 单条聚类规则。 子节点:RuleType、BaseURIs、Keywords、Sensitivity 父节点:rules |
RuleType | 字符串 | 是 | face | 聚类规则类型。取值如下:
父节点:SmartClusterRule |
BaseURIs | 字符串数组 | 否 | ["oss://examplebucket/refs/alice2.jpg"] | 参考素材 OSS URI 列表,格式 父节点:SmartClusterRule |
Keywords | 字符串数组 | 否 | ["人物","车辆","建筑"] | 聚类关键词列表,RuleType 为 keywords 时必填。 父节点:SmartClusterRule |
Sensitivity | 浮点型 | 否 | 0.7 | 聚类灵敏度,取值范围 [0, 1],值越大匹配越严格。 父节点:SmartClusterRule |
notification | Notification 对象 | 否 | {"MNS":{"TopicName":"imm-cluster-notification"}} | 新的 MNS 消息通知配置。通过 URL Query String 传递时需 JSON 序列化并 URL 编码。 子节点:Notification |
Notification | 容器 | 否 | 不涉及 | 聚类任务消息通知配置。 子节点:MNS 父节点:notification |
MNS | 容器 | 否 | 不涉及 | MNS 通知配置。 子节点:TopicName 父节点:Notification |
TopicName | 字符串 | 否 | imm-cluster-notification | MNS 主题名称。 父节点:MNS |
响应头
此接口仅涉及公共响应头。更多信息,请参见公共响应头(Common Response Headers)。
响应元素
名称 | 类型 | 是否必选 | 示例值 | 描述 |
UpdateSmartClusterResponse | 容器 | 是 | 不涉及 | 响应根元素。 子节点:ObjectId |
ObjectId | 字符串 | 是 | cluster-abc123def456 | 被更新的 SmartCluster 唯一 ID,与请求参数 父节点:UpdateSmartClusterResponse |
示例
请求示例
POST /?metaQuery&action=updateSmartCluster&datasetName=photos-2026&objectId=cluster-abc123def456&description=Updated%20description HTTP/1.1
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
Date: Wed, 20 May 2026 12:00:00 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: 64C8B6F4E7C5A3A8B9D6E7F8
Date: Wed, 20 May 2026 12:00:01 GMT
Content-Type: application/xml
Server: AliyunOSS
<?xml version="1.0" encoding="UTF-8"?>
<UpdateSmartClusterResponse>
<ObjectId>cluster-abc123def456</ObjectId>
</UpdateSmartClusterResponse>