Modifying Object Metadata

Functions

This operation modifies, deletes, or adds metadata to uploaded objects in a bucket.

Request Syntax

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

Request Parameters

Table 1 Request parameters

Parameter

Type

Mandatory (Yes/No)

Description

versionId

String

No

Explanation:

Version ID of the object.

Restrictions:

None

Value range:

The value must contain 32 characters.

Default value:

None

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 (Yes/No)

Description

x-obs-metadata-directive

String

Yes

Explanation:

Metadata operation directive.

Restrictions:

None

Value 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:

None

Cache-Control

String

No

Explanation:

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

Restrictions:

None

Value range:

See the Cache-Control values defined in HTTP.

Default value:

None

Content-Disposition

String

No

Explanation:

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

Restrictions:

None

Value range:

See the Content-Disposition values defined in HTTP.

Default value:

None

Content-Encoding

String

No

Explanation:

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

Restrictions:

None

Value range:

See the Content-Encoding values defined in HTTP.

Default value:

None

Content-Language

String

No

Explanation:

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

Restrictions:

None

Value range:

See the Content-Language values defined in HTTP.

Default value:

None

Content-Type

String

No

Explanation:

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

Restrictions:

None

Value range:

See the Content-Type values defined in HTTP.

Default value:

None

Expires

String

No

Explanation:

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.

Restrictions:

None

Value range:

See the Expires values defined in HTTP.

Default value:

None

x-obs-website-redirect-location

String

No

Explanation:

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/

Restrictions:

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

Value range:

None

Default value:

None

x-obs-storage-class

String

No

Explanation:

Specifies the storage class of an object.

Example: x-obs-storage-class: STANDARD

Restrictions:

The value is case-sensitive.

Value range:

  • STANDARD
  • WARM
  • COLD

Default value:

None

x-obs-meta-*

String

No

Explanation:

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

Restrictions:

  • The total size of all custom metadata cannot exceed 8K. 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.

Value range:

None

Default value:

None

x-obs-tagging

String

No

Explanation:

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

Restrictions:

  • 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.

Value range:

None

Default value:

None

Request Elements

This request involves 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 Additional response headers

Header

Type

Description

x-obs-metadata-directive

String

Explanation:

Metadata operation directive.

Value 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:

None

Cache-Control

String

Explanation:

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

Restrictions:

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

Value range:

See the Cache-control values defined in HTTP.

Default value:

None

Content-Disposition

String

Explanation:

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

Restrictions:

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

Value range:

See the Content-Disposition values defined in HTTP.

Default value:

None

Content-Encoding

String

Explanation:

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

Restrictions:

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

Value range:

See the Content-Encoding values defined in HTTP.

Default value:

None

Content-Language

String

Explanation:

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

Restrictions:

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

Value range:

See the Content-Language values defined in HTTP.

Default value:

None

Expires

String

Explanation:

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

Restrictions:

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

Value range:

See the Expires values defined in HTTP.

Default value:

None

x-obs-website-redirect-location

String

Explanation:

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/

Restrictions:

  • 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.

Value range:

None

Default value:

None

x-obs-storage-class

String

Explanation:

It specifies the storage class of an object.

Restrictions:

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

Value range:

  • STANDARD
  • WARM
  • COLD

Default value:

None

x-obs-meta-*

String

Explanation:

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.

Restrictions:

  • If a request carries this header field, the response message must contain this header field.
  • The total size of all custom metadata cannot exceed 8K. 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.

Value range:

None

Default value:

None

Response Elements

This response contains no elements.

Error Responses

No special error responses are returned. For details about error responses, see 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.example.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.example.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.example.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
Parent topic: Operations on Objects