Help Center/Elastic Cloud Server/API Reference/APIs/Metadata Management/Updating ECS Metadata
Updated on 2026-03-26 GMT+08:00
View PDF
Share

Updating ECS Metadata

Function

This API is used to update ECS metadata.

  • If the metadata does not contain the field to be updated, the field is automatically added.
  • If the metadata contains the field to be updated, the field value is automatically updated.
  • If the field in the metadata is not requested, the field value remains unchanged.

If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data.

Constraints

An ECS must be in active, stopped, paused, or suspended state, which is specified by OS-EXT-STS:vm_state.

Debugging

You can debug this API in API Explorer.

Authorization

Each account has all of the permissions required to call all APIs, but IAM users must have the required permissions specifically assigned.
  • If you are using role/policy-based authorization, see the required permissions in Permissions and Supported Actions.
  • If you are using identity policy-based authorization, the permissions listed below are required.

Action

Access Level

Resource Type (*: required)

Condition Key

Alias

Dependencies

ecs:cloudServers:updateMetadata

write

instance *

-

-

iam:agencies:pass

URI

POST /v1/{project_id}/cloudservers/{server_id}/metadata

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Definition

Specifies the project ID.

For details about how to obtain the ID, see Obtaining a Project ID.

Constraints

N/A

Range

N/A

Default Value

N/A

server_id

Yes

Definition

Specifies the ECS ID.

Constraints

N/A

Range

N/A

Default Value

N/A

Request

Table 2 Request parameters

Parameter

Mandatory

Type

Description

metadata

Yes

Map<String,String>

Definition

This API is used to update ECS metadata.

You can use metadata to customize key-value pairs. For details about reserved key-value pairs, see Table 11.

Constraints

If the metadata contains sensitive data, take appropriate measures to protect the sensitive data, for example, controlling access permissions and encrypting the data.

Range

  • A metadata key consists of 1 to 255 characters and can only contain uppercase letters, lowercase letters, digits, spaces, hyphens (-), underscores (_), colons (:), and periods (.).
  • A metadata value consists of a maximum of 255 characters.

Default Value

N/A

Response

Table 3 Parameter description

Parameter

Type

Description

metadata

Object

Definition

Specifies the user-defined metadata key-value pair.

Range

N/A

Example Request

Updated the metadata of an ECS with the user-defined metadata key-value pair.

POST https://{endpoint}/v1/{project_id}/cloudservers/{server_id}/metadata

{
    "metadata": {
        "key": "value"
    }
}

Example Response

{
    "metadata":{
        "key":"value"
    }
}

Returned Values

See Returned Values for General Requests.

Parent topic:Metadata Management