Modifying Object Metadata (SDK for Python)

Function

Object metadata is a set of name-value pairs that describe the object and is used for object management.

Currently, only the system-defined metadata can be modified.

System-defined metadata consists of system-controlled metadata and user-controlled metadata. The kind of metadata like Last-Modified is controlled by the system and cannot be modified. However, the kind of metadata configured for objects such as ContentLanguage can be modified by calling APIs.

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

Restrictions

To configure object metadata, you must be the bucket owner or have the required permission (obs:object:ModifyObjectMetaData in IAM or ModifyObjectMetaData in a bucket policy). For details, see Introduction to OBS Access Control, IAM Custom Policies, and Configuring an Object Policy.
The mapping between OBS regions and endpoints must comply with what is listed in Regions and Endpoints.
If versioning is enabled for a bucket, you can set metadata for objects of the latest version, but cannot set metadata for objects of historical versions.
You cannot set metadata for Archive objects.

Method

ObsClient.setObjectMetadata(bucketName, objectKey, metadata, headers, versionId)

Request Parameters

**Table 1** List of request parameters
Parameter	Type	Mandatory (Yes/No)	Description
bucketName	str	Yes	Explanation: Bucket name Restrictions: A bucket name must be unique across all accounts and regions. A bucket name: Must be 3 to 63 characters long and start with a digit or letter. Lowercase letters, digits, hyphens (-), and periods (.) are allowed. Cannot be formatted as an IP address. Cannot start or end with a hyphen (-) or period (.). Cannot contain two consecutive periods (..), for example, my..bucket. Cannot contain periods (.) and hyphens (-) adjacent to each other, for example, my-.bucket or my.-bucket. If you repeatedly create buckets of the same name in the same region, no error will be reported and the bucket properties comply with those set in the first creation request. Default value: None
objectKey	str	Yes	Explanation: Object name. An object is uniquely identified by an object name in a bucket. An object name is a complete path that does not contain the bucket name. For example, if the address for accessing the object is examplebucket.obs.ap-southeast-1.myhuaweicloud.com/folder/test.txt, the object name is folder/test.txt. Value range: The value must contain 1 to 1,024 characters. Default value: None
metadata	dict	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. Restrictions: The custom metadata cannot exceed 8 KB. To measure the custom metadata, sum the number of bytes in the UTF-8 encoding of each key and value. The custom metadata keys are case insensitive, but are stored in lowercase in 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. Default value: None
headers	SetObjectMetadataHeader	No	Explanation: Request headers for configuring object metadata. For details, see Table 2.
versionId	str	No	Explanation: Object version ID, for example, G001117FCE89978B0000401205D5DC9A Value range: The value must contain 32 characters. Default value: None

**Table 2** SetObjectMetadataHeader
Parameter	Type	Mandatory (Yes/No)	Description
removeUnset	bool	No	Explanation: Used to set the metadata operation indicator Value range: True: The metadata operation indicator is REPLACE. REPLACE uses the complete header carried in the current request to replace the original one and deletes the metadata that is not specified. False: The metadata operation indicator is REPLACE_NEW. REPLACE_NEW replaces the metadata that already has a value, assigns a value to the metadata that does not have a value, and retains the metadata that is not specified. Default value: False
location	str	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. The request is redirected to object anotherPage.html in the same bucket: WebsiteRedirectLocation:/anotherPage.html The request is redirected to an external URL http://www.example.com/: WebsiteRedirectLocation:http://www.example.com/ OBS obtains the specified value from the header and stores it in the object metadata WebsiteRedirectLocation. Restrictions: The value must start with a slash (/), http://, or https:// and cannot exceed 2 KB. OBS only supports redirection for objects in the root directory of a bucket. Default value: None
cacheControl	str	No	Explanation: Cache-Control header in the response. It specifies the cache behavior of the web page when an object is downloaded. Default value: None
contentDisposition	str	No	Explanation: Content-Disposition header in the response It specifies the name of an object when it is downloaded. Default value: None
contentEncoding	str	No	Explanation: Content-Encoding header in the response It specifies the content encoding format when an object is downloaded. Default value: None
contentLanguage	str	No	Explanation: Content-Language header in the response It specifies the content language format when an object is downloaded. Default value: None
contentType	str	No	Explanation: Content-Type header in the response. It specifies the file type of an object when it is downloaded. Default value: None
expires	str	No	Explanation: Expires header in the response. It specifies the cache expiration time of the web page when the object is downloaded. CAUTION: This parameter cannot be used to configure the expiration time of an object. To configure the object expiration time, see Setting an Object Expiration Time (SDK for Python). Default value: None
storageClass	str	No	Explanation: Storage classes Value range: See Table 3. Default value: None

**Table 3** StorageClass
Parameter	Type	Description
STANDARD	Standard storage class	Explanation: Features low access latency and high throughput and is used for storing massive, frequently accessed (multiple times a month) or small objects (< 1 MB) requiring quick response.
WARM	Infrequent Access storage class	Explanation: Used for storing data that is semi-frequently accessed (fewer than 12 times a year) but is instantly available when needed.
COLD	Archive storage class	Explanation: Used for storing rarely accessed (once a year) data.

Responses

**Table 4** List of returned results
Type	Description
GetResult	Explanation: SDK common results

**Table 5** GetResult
Parameter	Type	Description
status	int	Explanation: HTTP status code Value range: A status code is a group of digits ranging from 2xx (indicating successes) to 4xx or 5xx (indicating errors). It indicates the status of a response. For more information, see Status Code. Default value: None
reason	str	Explanation: Reason description. Default value: None
errorCode	str	Explanation: Error code returned by the OBS server. If the value of status is less than 300, this parameter is left blank. Default value: None
errorMessage	str	Explanation: Error message returned by the OBS server. If the value of status is less than 300, this parameter is left blank. Default value: None
requestId	str	Explanation: Request ID returned by the OBS server Default value: None
indicator	str	Explanation: Error indicator returned by the OBS server. Default value: None
hostId	str	Explanation: Requested server ID. If the value of status is less than 300, this parameter is left blank. Default value: None
resource	str	Explanation: Error source (a bucket or an object). If the value of status is less than 300, this parameter is left blank. Default value: None
header	list	Explanation: Response header list, composed of tuples. Each tuple consists of two elements, respectively corresponding to the key and value of a response header. Default value: None
body	object	Explanation: Result content returned after the operation is successful. If the value of status is larger than 300, this parameter value is null. The value varies with the API being called. For details, see Bucket-Related APIs (SDK for Python) and Object-Related APIs (SDK for Python). Default value: None

Code Examples

This example configures the object metadata.

    
     
       
       
         from obs import SetObjectMetadataHeader
from obs import ObsClient
import os
import traceback

# Obtain an AK and SK pair using environment variables or import the AK and SK pair in other ways. Using hard coding may result in leakage.
# Obtain an AK and SK pair on the management console. For details, see https://support.huaweicloud.com/intl/en-us/usermanual-ca/ca_01_0003.html.
ak = os.getenv("AccessKeyID")
sk = os.getenv("SecretAccessKey")
# (Optional) If you use a temporary AK and SK pair and a security token to access OBS, obtain them from environment variables.
security_token = os.getenv("SecurityToken")
# Set server to the endpoint corresponding to the bucket. Here uses CN-Hong Kong as an example. Replace it with the one in use.
server = "https://obs.ap-southeast-1.myhuaweicloud.com"

# Create an obsClient instance.
# If you use a temporary AK and SK pair and a security token to access OBS, you must specify security_token when creating an instance.
obsClient = ObsClient(access_key_id=ak, secret_access_key=sk, server=server)
try:
    # Specify custom metadata.
    metadata = {'property1': 'property-value1', 'property2': 'property-value2'}
    # Specify the additional headers of the request for configuring object metadata.
    headers = SetObjectMetadataHeader()
    # (Optional) Specify the MIME type of the object.
    headers.contentType = "Your Content-Type"
    bucketName = "examplebucket"
    objectKey = "objectname"
    # Configure metadata for the object.
    resp = obsClient.setObjectMetadata(bucketName, objectKey, metadata, headers)

    # If status code 2xx is returned, the API is called successfully. Otherwise, the API call fails.
    if resp.status < 300:
        print('Set Object Metadata Succeeded')
        print('requestId:', resp.requestId)
    else:
        print('Set Object Metadata Failed')
        print('requestId:', resp.requestId)
        print('errorCode:', resp.errorCode)
        print('errorMessage:', resp.errorMessage)
except:
    print('Set Object Metadata Failed')
    print(traceback.format_exc())

        

      

    
   