On this page

Functions
Request Syntax
Request Parameters
Request Headers
Request Elements
Response Syntax
Response Headers
Response Elements
Error Responses
Sample Request: Adding Metadata for an Object
Sample Response: Adding Metadata for an Object
Sample Request: Editing Metadata of an Object
Sample Response: Editing Metadata of an Object
Sample Request: Deleting Metadata of an Object
Sample Response: Deleting Metadata of an Object

Show all

Help Center/ Object Storage Service/ API Reference/ APIs/ Operations on Objects/ Modifying Object Metadata

Modifying Object Metadata

Updated on 2024-09-29 GMT+08:00

View PDF

Functions

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

Request Syntax

    
       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>

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

NOTE:

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, which is set using x-obs-expires. 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 DEEP_ARCHIVE 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 or decoded in URL or Base64 on the client, because the server does not perform such operations. Value range: None Default value: None
x-obs-expires	Integer	No	Explanation: Specifies when an object expires. It is measured in days. Once the object expires, it is automatically deleted. Example: x-obs-expires:3 Restrictions: 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. Value range: The value is an integer greater than 0. Default value: None

Request Elements

This request involves no elements.

Response Syntax

    
       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 DEEP_ARCHIVE 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 or decoded in URL or Base64 on the client, because the server does not perform such operations. Value range: None Default value: None
x-obs-expires	Integer	Explanation: Specifies when an object expires. It is measured in days. Restrictions: 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. Value range: The value is an integer greater than 0. 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.

    
       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

    
       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.

    
       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

    
       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.

    
       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

    
       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

Previous topic: Obtaining Object ACL Configuration

Next topic: Modifying an Object

Feedback

Was this page helpful?

Helpful Not helpful

Provide feedback

Thank you very much for your feedback. We will continue working to improve the documentation.See the reply and handling status in My Cloud VOC.

The system is busy. Please try again later.

Which of the following issues have you encountered?

Content is inconsistent with the product UI

Unclear descriptions

Lack of examples or code

Incorrect steps

Can't find what I need

Lack of best practices

Feedback (optional)

0/500

Select at least one type of issue, and enter your comments or suggestions.

Enter a maximum of 500 characters.

Submit Cancel

For any further questions, feel free to contact us through the chatbot.

Chatbot