Updating ECS Metadata

Function

This API is used to update ECS metadata.

  • If the metadata does not contain the target field, the field is automatically added.

  • If the metadata contains the target field, the field value is automatically updated.

  • If the field in the metadata is not requested, the field value remains unchanged.

Constraints

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

URI

POST /v2.1/{project_id}/servers/{server_id}/metadata

Table 1 describes the parameters in the URI.

Table 1 Parameter description

Parameter

Mandatory

Description

project_id

Yes

Specifies the project ID.

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

server_id

Yes

Specifies the ECS ID.

Request

Table 2 describes the request parameters.

Table 2 Request parameters

Parameter

Mandatory

Type

Description

metadata

Yes

Object

Specifies the user-defined metadata key-value pair.

For a metadata key:

It contains a maximum of 255 Unicode characters and cannot be left blank. A key can contain uppercase letters (A-Z), lowercase letters (a-z), digits (0-9), hyphens (-), underscores (_), colons (:), and periods (.).

For a metadata value:

A value contains a maximum of 255 Unicode characters.

Response

Table 3 describes the response parameters.

Table 3 Response parameters

Parameter

Type

Description

metadata

Object

Specifies the user-defined metadata key-value pair.

Example Request

Update the metadata of a specified ECS to the user-defined metadata key-value pair.

POST https://{endpoint}/v2.1/{project_id}/servers/{server_id}/metadata

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

Example Response

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

Returned Values

See Returned Values for General Requests.