Object Storage Service:Manage object metadata (Python SDK V1)

Objects stored in Object Storage Service (OSS) consist of keys, data, and object metadata. Object metadata describes object attributes. Object metadata includes standard HTTP headers and user metadata. You can create custom HTTP request policies such as object cache policies and forced object download policies by configuring standard HTTP headers. You can also configure user metadata for an object to identify the purposes or attributes of the object.

Usage notes

• In this topic, the public endpoint of the China (Hangzhou) region is used. If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use an internal endpoint. For more information about OSS regions and endpoints, see Regions and endpoints.

• In this topic, an OSSClient instance is created by using an OSS endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization.

• To configure object metadata, you must have the oss:PutObject permission. To query object metadata, you must have the oss:GetObject permission. For more information, see Attach a custom policy to a RAM user.

Set HTTP headers

The following code shows how to set HTTP headers for the exampleobject.txt object in the exampledir folder of the examplebucket bucket.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Get access credentials from environment variables. Before you run this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Set the region ID that corresponds to the endpoint. Example: cn-hangzhou. This parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set the full path of the object. Example: exampledir/exampleobject.txt. The full path cannot contain the bucket name.
object_name = 'exampledir/exampleobject.txt'
# Set the string to upload.
content = '{"age": 1}'
# Set the HTTP headers. For example, set the Content-Type header to 'application/json; charset=utf-8'.
bucket.put_object(object_name, content, headers={'Content-Type': 'application/json; charset=utf-8'})

Set custom metadata

You can set custom metadata for an object to describe the object.

The following code shows how to set custom metadata for the exampleobject.txt object in the exampledir folder of the examplebucket bucket.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Get access credentials from environment variables. Before you run this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Set the region ID that corresponds to the endpoint. Example: cn-hangzhou. This parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set the full path of the object. Example: exampledir/exampleobject.txt. The full path cannot contain the bucket name.
object_name = 'exampledir/exampleobject.txt'
# Set the string to upload.
content = 'a novel'

# Set the custom metadata. Custom metadata must be prefixed with x-oss-meta-. For example, set the custom metadata name to x-oss-meta-author and the value to 'O. Henry'.
bucket.put_object(object_name, content, headers={'x-oss-meta-author': 'O. Henry', 'Content-Type': 'application/json; charset=utf-8'})

Modify object metadata

The following code shows how to modify the metadata of the exampleobject.txt object in the exampledir folder of the examplebucket bucket.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Get access credentials from environment variables. Before you run this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Set the region ID that corresponds to the endpoint. Example: cn-hangzhou. This parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set the full path of the object. Example: exampledir/exampleobject.txt. The full path cannot contain the bucket name.
object_name = 'exampledir/exampleobject.txt'
# Modify the object metadata.
bucket.update_object_meta(object_name, {'x-oss-meta-author': 'O. Henry'})
# Each call to bucket.update_object_meta clears the existing user-defined metadata and writes the new metadata.
bucket.update_object_meta(object_name, {'Content-Type': 'text/plain'})

Get object metadata

You can use methods provided by the SDK to retrieve object metadata.

The following code shows how to retrieve the metadata of the exampleobject.txt object in the exampledir folder of the examplebucket bucket.

# -*- coding: utf-8 -*-
import oss2
from oss2.credentials import EnvironmentVariableCredentialsProvider

# Get access credentials from environment variables. Before you run this code, make sure the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are set.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Set endpoint to the endpoint of the region where the bucket is located. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"

# Set the region ID that corresponds to the endpoint. Example: cn-hangzhou. This parameter is required for V4 signatures.
region = "cn-hangzhou"

# Set yourBucketName to the name of the bucket.
bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

# Set the full path of the object. Example: exampledir/exampleobject.txt. The full path cannot contain the bucket name.
object_name = 'exampledir/exampleobject.txt'

# Get partial object metadata using the get_object_meta method.
simplifiedmeta = bucket.get_object_meta(object_name)
# Print the partial object metadata.
print("Last-Modified: " + simplifiedmeta.headers['Last-Modified'])  # Get the last modified time of the object.
print("Content-Length: " + simplifiedmeta.headers['Content-Length'])  # Get the size of the object.
print("ETag: " + simplifiedmeta.headers['ETag'])  # Get the ETag of the object.
# After you enable access tracking, you can get object metadata that includes the last access time (x-oss-last-access-time). Only Python SDK 2.16.1 and later supports getting x-oss-last-access-time.
# print(simplifiedmeta.headers['x-oss-last-access-time'])

# Get all object metadata using the head_object method.
objectmeta = bucket.head_object(object_name)
# This example shows how to print partial object metadata. Add code to print other metadata as needed.
# Print the partial object metadata.
print("Content-Type: " + objectmeta.headers['Content-Type'])  # Get the Multipurpose Internet Mail Extensions (MIME) type of the object.
print("Content-MD5: " + objectmeta.headers['Content-MD5'])  # Get the MD5 checksum of the object.
print("x-oss-storage-class: " + objectmeta.headers['x-oss-storage-class'])  # Get the storage class of the object.
print("x-oss-hash-crc64ecma: " + objectmeta.headers['x-oss-hash-crc64ecma'])  # Get the CRC-64-ECMA checksum of the object.


# Print all header fields.
# To print all header fields, uncomment the following code.
# print("\nAll headers:")
# for key, value in objectmeta.headers.items():
#     print(f"{key}: {value}")

References

• For more information about object metadata, see Manage object metadata.

• For more information about the API operation used to set object metadata during a simple upload, see PutObject.

• For more information about the API operations used to retrieve object metadata, see GetObjectMeta and HeadObject.