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

Prerequisites

Before you begin, make sure that you have:

• An OSSClient instance initialized with a valid endpoint. If you want to create an OSSClient instance by using custom domain names or Security Token Service (STS), see Initialization

• The oss:PutObject permission to set or update object metadata

• The oss:GetObject permission to retrieve object metadata

For permission setup, see Attach a custom policy to a RAM user.

Usage notes

• The examples in this topic use the public endpoint for the China (Hangzhou) region (https://oss-cn-hangzhou.aliyuncs.com). If you want to access OSS from other Alibaba Cloud services in the same region as OSS, use the internal endpoint instead. See Regions and endpoints.

• All examples read credentials from environment variables. Set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET before running the code.

Set HTTP headers

Pass HTTP headers to put_object when uploading an object. The following example sets Content-Type for exampledir/exampleobject.txt.

For a full list of supported headers, see RFC 2616.

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

# Load credentials from environment variables.
auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

# Replace with your bucket's endpoint and region.
endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"  # Required for V4 signatures.

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

object_name = "exampledir/exampleobject.txt"
content = '{"age": 1}'

# Set the Content-Type header on upload.
bucket.put_object(object_name, content, headers={"Content-Type": "application/json; charset=utf-8"})

Set user metadata

Pass user metadata as headers in the x-oss-meta-* format when calling put_object. All user metadata keys must be prefixed with x-oss-meta-. The following example sets a custom author attribute on exampledir/exampleobject.txt.

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

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

object_name = "exampledir/exampleobject.txt"
content = "a novel"

# User metadata keys must be prefixed with x-oss-meta-.
bucket.put_object(
    object_name,
    content,
    headers={
        "x-oss-meta-author": "O. Henry",
        "Content-Type": "application/json; charset=utf-8",
    },
)

Update object metadata

Use update_object_meta to modify existing metadata on an object.

The following example updates the metadata of exampledir/exampleobject.txt:

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

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

object_name = "exampledir/exampleobject.txt"

# This call replaces all existing user metadata with the values provided.
bucket.update_object_meta(object_name, {"x-oss-meta-author": "O. Henry"})

# A second call replaces everything set above.
bucket.update_object_meta(object_name, {"Content-Type": "text/plain"})

Get object metadata

OSS provides two methods for retrieving object metadata:

The following example retrieves metadata from exampledir/exampleobject.txt using both methods:

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

auth = oss2.ProviderAuthV4(EnvironmentVariableCredentialsProvider())

endpoint = "https://oss-cn-hangzhou.aliyuncs.com"
region = "cn-hangzhou"

bucket = oss2.Bucket(auth, endpoint, "yourBucketName", region=region)

object_name = "exampledir/exampleobject.txt"

# Retrieve partial metadata (lightweight).
simplified = bucket.get_object_meta(object_name)
print("Last-Modified:", simplified.headers["Last-Modified"])
print("Content-Length:", simplified.headers["Content-Length"])
print("ETag:", simplified.headers["ETag"])

# x-oss-last-access-time is returned only when access tracking is enabled
# and requires Python SDK 2.16.1 or later.
# print("Last-Access-Time:", simplified.headers["x-oss-last-access-time"])

# Retrieve full metadata.
meta = bucket.head_object(object_name)
print("Content-Type:", meta.headers["Content-Type"])        # MIME type
print("Content-MD5:", meta.headers["Content-MD5"])          # MD5 checksum
print("Storage class:", meta.headers["x-oss-storage-class"])
print("CRC-64-ECMA:", meta.headers["x-oss-hash-crc64ecma"])

# To print all headers:
# for key, value in meta.headers.items():
#     print(f"{key}: {value}")

What's next

• Manage object metadata — conceptual overview of object metadata in OSS.

• PutObject — API reference for setting metadata during upload.

• GetObjectMeta — API reference for retrieving partial metadata.

• HeadObject — API reference for retrieving full metadata.