Help Center/ Object Storage Service/ API Reference/ Object APIs/ Basic Operations/ Modifying Object Metadata
Updated on 2026-05-26 GMT+08:00
View PDF
Share

Modifying Object Metadata

Function

Object metadata is a set of name-value pairs that describe the object and is used for object management. This API is used to add, modify, or delete metadata of objects in a bucket. For more information about object metadata, see Configuring, Editing, and Viewing Object Metadata.

Constraints

  • In a versioning-enabled bucket, you can only configure metadata for the latest version of an object, but not for historical versions.
  • Metadata cannot be configured for Archive or Deep Archive objects.
  • The total size of user-defined metadata is limited to 8 KB.
  • For the permissions required to configure, edit, or view object metadata, see Object Actions.

Authorization

To call this API, you must be the object owner or have the permission to modify object metadata. You are advised to use IAM or bucket policies for authorization. For details about OBS authorization methods, see Differences Between OBS Permissions Control Methods.

  • If you use IAM for authorization, you need to use either role/policy-based authorization or identity policy-based authorization and configure the required permissions:
    • If you use role/policy-based authorization (IAM v3 APIs in the old IAM version), you must have the obs:object:ModifyObjectMetadata permission. For details, see Creating a Custom IAM Policy.
    • If you use identity policy-based authorization (IAM v5 APIs in the new IAM version), you must have the obs:object:modifyObjectMetadata permission, as shown in the following table. For details, see Creating a Custom IAM Identity Policy.

      Action

      Access Level

      Resource Type (*: Required)

      Condition Key

      Alias

      Dependencies

      obs:object:modifyObjectMetadata

      Write

      object *

      g:EnterpriseProjectId

      -

      -

      -
      • obs:EpochTime
      • obs:SourceIp
      • obs:TlsVersion
      • obs:CustomDomain
  • If you use bucket policies for authorization, you must have the obs:object:ModifyObjectMetadata permission. For details, see Creating a Custom Bucket Policy.

URI

PUT /{object_key}

Calling Method

For details, see Calling APIs. Before calling this API, calculate the API signature and add it to the request.

You can debug this API in API Explorer.

Request Syntax

1
2
3
4
5
6
7
8
 
PUT /ObjectName?metadata HTTP/1.1 
Host: bucketname.obs.region.myhuaweicloud.com 
Content-Type: application/xml 
Content-Length: length
Authorization: authorization
Date: date
<Optional Additional Header> 
<object Content>

URI Parameters

Table 1 URI parameters

Parameter

Type

Mandatory

Description

versionId

String

No

Definition

Version ID of the object.

Constraints

N/A

Range

The value must contain 32 characters.

Default Value

N/A

Request Headers

OBS supports the six HTTP request headers: Cache-Control, Expires, Content-Encoding, Content-Disposition, Content-Type, and Content-Language. It saves these header values in the metadata of the object. When the object is downloaded or queried, the saved values are set for corresponding HTTP headers and returned to the client.

Table 2 Request headers

Header

Type

Mandatory

Description

x-obs-metadata-directive

String

Yes

Definition

Metadata operation directive.

Constraints

If you want to change the storage class of an object by modifying its metadata, x-obs-metadata-directive must be set to REPLACE_NEW.

Range

  • REPLACE_NEW: The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.
  • REPLACE: All original metadata is replaced by metadata specified in the request. Metadata that is not specified (except for x-obs-storage-class) is deleted.

Default Value

N/A

Cache-Control

String

No

Definition

It specifies the cache behavior of the web page when an object is downloaded.

Constraints

N/A

Range

See the Cache-Control values defined in HTTP.

Default Value

N/A

Content-Disposition

String

No

Definition

It specifies the name of an object when it is downloaded.

Constraints

N/A

Range

See the Content-Disposition values defined in HTTP.

Default Value

N/A

Content-Encoding

String

No

Definition

It specifies the content encoding format when an object is downloaded.

Constraints

N/A

Range

See the Content-Encoding values defined in HTTP.

Default Value

N/A

Content-Language

String

No

Definition

It specifies the content language format when an object is downloaded.

Constraints

N/A

Range

See the Content-Language values defined in HTTP.

Default Value

N/A

Content-Type

String

No

Definition

It specifies the file type of an object when it is downloaded.

Constraints

N/A

Range

For details about the common content types, see Common Content Types.

Default Value

N/A

Expires

String

No

Definition

It specifies the expiration time of a cached web page when an object is downloaded.

CAUTION:

This parameter is not used to set the object expiration time, which is set using x-obs-expires.

Constraints

N/A

Range

See the Expires values defined in HTTP.

Default Value

N/A

x-obs-website-redirect-location

String

No

Definition

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

In the following example, the request header sets the redirection to an object (anotherPage.html) in the same bucket:

x-obs-website-redirect-location:/anotherPage.html

In the following example, the request header sets the object redirection to an external URL:

x-obs-website-redirect-location:http://www.example.com/

Constraints

The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

Range

N/A

Default Value

N/A

x-obs-storage-class

String

No

Definition

Specifies the storage class of an object.

Example: x-obs-storage-class: STANDARD

Constraints

The value is case-sensitive.

Range

  • STANDARD
  • WARM
  • COLD
  • DEEP_ARCHIVE

Default Value

N/A

x-obs-meta-*

String

No

Definition

Custom metadata of the object. You can add a header starting with x-obs-meta- in the request to define metadata. The custom metadata will be returned in the response when you retrieve the object or query the object metadata.

Example: x-obs-meta-test: test metadata

Constraints

  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.

Range

N/A

Default Value

N/A

x-obs-expires

Integer

No

Definition

Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted.

Example: x-obs-expires:3

Constraints

The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.

Range

The value is an integer greater than 0.

Default Value

N/A

x-obs-tagging

String

No

Definition

An object's tag information in key-value pairs. Multiple tags can be added at the same time.

Example: x-obs-tagging:TagA=A&TagB&TagC

Constraints

  • If a tag key or value contains special characters, equal signs (=), or full-width characters, it must be URL-encoded.
  • If there is no equal sign (=) in a configuration, the tag value is considered left blank.

Range

N/A

Default Value

N/A

Request Elements

This request contains no elements.

Response Syntax

1
2
3
4
5
 
HTTP/1.1 status_code
Date: date
Content-Length: length
Etag: etag
Last-Modified: time

Response Headers

Table 3 Response headers

Header

Type

Description

x-obs-metadata-directive

String

Definition

Metadata operation directive.

Range

  • REPLACE_NEW: The metadata that has an existing value is replaced. A value is assigned to the metadata that does not have a value. The metadata that is not specified remains unchanged. Custom metadata is replaced.
  • REPLACE: All original metadata is replaced by metadata specified in the request. Metadata that is not specified (except for x-obs-storage-class) is deleted.

Default Value

N/A

Cache-Control

String

Definition

It specifies the cache behavior of the web page when an object is downloaded.

Constraints

If a request carries this header field, the response message must contain this header field.

Range

See the Cache-control values defined in HTTP.

Default Value

N/A

Content-Disposition

String

Definition

It specifies the name of an object when it is downloaded.

Constraints

If a request carries this header field, the response message must contain this header field.

Range

See the Content-Disposition values defined in HTTP.

Default Value

N/A

Content-Encoding

String

Definition

It specifies the content encoding format when an object is downloaded.

Constraints

If a request carries this header field, the response message must contain this header field.

Range

See the Content-Encoding values defined in HTTP.

Default Value

N/A

Content-Language

String

Definition

It specifies the content language format when an object is downloaded.

Constraints

If a request carries this header field, the response message must contain this header field.

Range

See the Content-Language values defined in HTTP.

Default Value

N/A

Expires

String

Definition

It specifies the expiration time of a cached web page when an object is downloaded.

Constraints

If a request carries this header field, the response message must contain this header field.

Range

See the Expires values defined in HTTP.

Default Value

N/A

x-obs-website-redirect-location

String

Definition

If the bucket is configured with website hosting, the request for obtaining the object can be redirected to another object in the bucket or an external URL.

In the following example, the request header sets the redirection to an object (anotherPage.html) in the same bucket:

x-obs-website-redirect-location:/anotherPage.html

In the following example, the request header sets the object redirection to an external URL:

x-obs-website-redirect-location:http://www.example.com/

Constraints

  • If a request carries this header field, the response message must contain this header field.
  • The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB.

Range

N/A

Default Value

N/A

x-obs-storage-class

String

Definition

It specifies the storage class of an object.

Constraints

  • If a request carries this header field, the response message must contain this header field.
  • The value is case-sensitive.

Range

  • STANDARD
  • WARM
  • COLD
  • DEEP_ARCHIVE

Default Value

N/A

x-obs-meta-*

String

Definition

Custom metadata of the object. You can add custom metadata headers that start with x-obs-meta- for easy object management. When you retrieve or query the metadata of the object, the added custom metadata headers will be returned in the response.

Constraints

  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8 KB. To measure the size, calculate the sum of bytes of all UTF-8 encoded keys and values.
  • The custom metadata keys are case-insensitive, but are stored in lowercase by OBS. The key values are case-sensitive.
  • Both custom metadata keys and their values must conform to US-ASCII standards. If non-ASCII or unrecognizable characters are required, they must be encoded and decoded in URL or Base64 on the client, because the server does not perform such operations.

Range

N/A

Default Value

N/A

x-obs-expires

Integer

Definition

Specifies when an object expires. It is measured in days.

Constraints

  • The value must be greater than the number of days that have passed since the object was created. For example, if the object was uploaded 10 days ago, you must specify a value greater than 10.
  • If a request carries this header field, the response message must contain this header field.

Range

The value is an integer greater than 0.

Default Value

N/A

Response Body

This response contains no elements.

Error Responses

No special errors. You can find all errors in Table 2.

Sample Request: Adding Metadata for an Object

Add the following metadata to the object: Content-Type:application/zip and x-obs-meta-test:meta.

1
2
3
4
5
6
7
8
9
 
PUT /object?metadata HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 14:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=
x-obs-metadata-directive:REPLACE_NEW
Content-Type:application/zip
x-obs-meta-test:meta

Sample Response: Adding Metadata for an Object

1
2
3
4
5
6
7
8
9
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3E4BB5905C41B6E65B6
Accept-Ranges: bytes
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSD3nAiTaBoeyt9oHp9vTYtXnLDmwV6D
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 0
x-obs-metadata-directive:REPLACE_NEW
x-obs-meta-test:meta

Sample Request: Editing Metadata of an Object

If metadata x-obs-meta-test:testmeta exists in the object and the value of x-obs-storage-class is WARM, change the metadata x-obs-meta-test of the object to newmeta and change x-obs-storage-class to COLD.

1
2
3
4
5
6
7
8
9
 
PUT /object?metadata HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 14:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=
x-obs-metadata-directive:REPLACE_NEW
x-obs-meta-test:newmeta
x-obs-storage-class:COLD

Sample Response: Editing Metadata of an Object

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3E4BB5905C41B6E65B6
Accept-Ranges: bytes
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSD3nAiTaBoeyt9oHp9vTYtXnLDmwV6D
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 0
x-obs-metadata-directive:REPLACE_NEW
x-obs-meta-test:newmeta
x-obs-storage-class:COLD

Sample Request: Deleting Metadata of an Object

Metadata x-obs-meta-test:newmeta and Content-Type:application/zip exist in the object, and delete x-obs-meta-test.

1
2
3
4
5
6
7
8
 
PUT /object?metadata HTTP/1.1
User-Agent: curl/7.29.0
Host: examplebucket.obs.region.myhuaweicloud.com
Accept: */*
Date: WED, 01 Jul 2015 14:24:33 GMT
Authorization: OBS H4IPJX0TQTHTHEBQQCEC:NxtSMS0jaVxlLnxlO9awaMTn47s=
x-obs-metadata-directive:REPLACE
Content-Type:application/zip

Sample Response: Deleting Metadata of an Object

1
2
3
4
5
6
7
8
 
HTTP/1.1 200 OK
Server: OBS
x-obs-request-id: 8DF400000163D3E4BB5905C41B6E65B6
Accept-Ranges: bytes
x-obs-id-2: 32AAAQAAEAABAAAQAAEAABAAAQAAEAABCSD3nAiTaBoeyt9oHp9vTYtXnLDmwV6D
Date: WED, 01 Jul 2015 04:19:21 GMT
Content-Length: 0
x-obs-metadata-directive:REPLACE

Using SDKs to Call APIs

You are advised to use OBS SDKs to call APIs. SDKs encapsulate APIs to simplify development. You can call SDK API functions to access OBS without manually calculating signatures.

Java

Python

C

Go

BrowserJS

.NET

Android

iOS

PHP

Node.js

Helpful Links

Parent Topic: Basic Operations