更新时间：2026-03-19 GMT+08:00
更新云服务器元数据 - UpdateServerMetadata
功能介绍
更新云服务器元数据。
- 如果元数据中没有待更新字段，则自动添加该字段。
- 如果元数据中已存在待更新字段，则直接更新字段值。
- 如果元数据中的字段不在请求参数中，则保持不变。
如果元数据中包含了敏感数据，您应当采取适当的措施来保护敏感数据，比如限制访问范围、加密等。
接口约束
云服务器状态（云服务器的OS-EXT-STS:vm_state属性）必须是active，stopped，paused或者suspended。
调试
您可以在API Explorer中调试该接口。
授权信息
账号具备所有API的调用权限，如果使用账号下的IAM用户调用当前API，该IAM用户需具备调用API所需的权限。
- 如果使用角色与策略授权，具体权限要求请参见权限和授权项。
- 如果使用身份策略授权，需具备如下身份策略权限。
|
授权项 |
访问级别 |
资源类型（*为必须） |
条件键 |
别名 |
依赖的授权项 |
|---|---|---|---|---|---|
|
ecs:cloudServers:updateMetadata |
write |
instance * |
- |
- |
iam:agencies:pass |
URI
POST /v1/{project_id}/cloudservers/{server_id}/metadata
|
参数 |
是否必选 |
描述 |
|---|---|---|
|
project_id |
是 |
参数解释： 项目ID。 获取方法请参见获取项目ID。 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 |
|
server_id |
是 |
参数解释： 云服务器ID。 约束限制： 不涉及 取值范围： 不涉及 默认取值： 不涉及 |
请求消息
|
参数 |
是否必选 |
参数类型 |
说明 |
|---|---|---|---|
|
metadata |
是 |
Object |
参数解释： 更新云服务器元数据。 可以通过元数据自定义键值对。系统预留键值对请参见表11。 约束限制： 如果元数据中包含了敏感数据，您应当采取适当的措施来保护敏感数据，比如限制访问范围、加密等。 取值范围：
默认取值： 不涉及 |
响应消息
|
参数 |
参数类型 |
说明 |
|---|---|---|
|
metadata |
Object |
参数解释： 用户自定义metadata键值对。 取值范围： 不涉及 |
请求示例
更新云服务器的元数据为自定义的键值对。
POST https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/metadata
{
"metadata": {
"key": "value"
}
}
响应示例
{
"metadata":{
"key":"value"
}
}
返回值
请参考通用请求返回值。
父主题： 元数据管理
