How to query object metadata by using Python SDK 2.0-Object Storage Service(OSS)-阿里云帮助中心

Retrieve metadata for a specific version of an object in a versioning-enabled bucket using HeadObject or GetObjectMeta.

Prerequisites

Before you begin, ensure that you have:

A versioning-enabled OSS bucket with at least one object
The oss:GetObject permission. For details, see Grant a custom access policy to a RAM user
The version ID of the object you want to inspect

Choose a method

Method	Returns	Use when
`HeadObject`	Full system metadata: content type, ETag, storage class, server-side encryption, CORS headers, and more	You need complete metadata for processing, auditing, or conditional logic
`GetObjectMeta`	Lightweight subset: content length, ETag, last modified time, last access time, version ID, and hash CRC64	You only need to check object size, existence, or modification time

GetObjectMeta sends a lighter-weight request. Use it when you don't need the full metadata set.

Get full metadata with HeadObject

HeadObject returns all system metadata for the specified object version without downloading the object body.

result = client.head_object(oss.HeadObjectRequest(
    bucket="<your-bucket>",
    key="<your-object-key>",
    version_id="<version-id>",
))

The response includes the following fields:

Field	Description
`content_length`	Object size in bytes
`content_type`	MIME type of the object
`etag`	ETag for data integrity verification
`last_modified`	Timestamp of the last modification
`content_md5`	Base64-encoded MD5 digest
`storage_class`	Storage class (Standard, IA, Archive, etc.)
`object_type`	Object type (Normal, Multipart, or Appendable)
`version_id`	Version ID of this object version
`server_side_encryption`	Server-side encryption algorithm, if enabled
`server_side_data_encryption`	Data encryption algorithm used with SSE-KMS, if applicable
`server_side_encryption_key_id`	Key ID used for SSE-KMS encryption, if applicable
`hash_crc64`	CRC-64 checksum for data integrity
`tagging_count`	Number of tags on the object
`expiration`	Lifecycle expiration rule that applies to this object, if any
`restore`	Restore status; only present for Archive-class objects
`next_append_position`	Next write position; only present for Appendable objects
`process_status`	Image processing status
`request_charged`	Indicates requester-pays billing if enabled
`cache_control`	HTTP Cache-Control header value
`content_disposition`	HTTP Content-Disposition header value
`content_encoding`	HTTP Content-Encoding header value
`expires`	HTTP Expires header value
`allow_origin`	CORS allowed origins
`allow_methods`	CORS allowed HTTP methods
`allow_age`	CORS preflight cache duration
`allow_headers`	CORS allowed request headers
`expose_headers`	CORS headers exposed to browsers

Full example

The following script accepts command-line arguments and prints all metadata fields returned by HeadObject.

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="head object sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--version_id', help='The version ID of the object.', required=True)

def main():
    args = parser.parse_args()

    # Load credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.head_object(oss.HeadObjectRequest(
        bucket=args.bucket,
        key=args.key,
        version_id=args.version_id,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content length: {result.content_length},'
          f' content type: {result.content_type},'
          f' etag: {result.etag},'
          f' last modified: {result.last_modified},'
          f' content md5: {result.content_md5},'
          f' cache control: {result.cache_control},'
          f' content disposition: {result.content_disposition},'
          f' content encoding: {result.content_encoding},'
          f' expires: {result.expires},'
          f' hash crc64: {result.hash_crc64},'
          f' storage class: {result.storage_class},'
          f' object type: {result.object_type},'
          f' version id: {result.version_id},'
          f' tagging count: {result.tagging_count},'
          f' server-side encryption: {result.server_side_encryption},'
          f' server-side data encryption: {result.server_side_data_encryption},'
          f' server-side encryption key id: {result.server_side_encryption_key_id},'
          f' next append position: {result.next_append_position},'
          f' expiration: {result.expiration},'
          f' restore: {result.restore},'
          f' process status: {result.process_status},'
          f' request charged: {result.request_charged},'
          f' allow origin: {result.allow_origin},'
          f' allow methods: {result.allow_methods},'
          f' allow age: {result.allow_age},'
          f' allow headers: {result.allow_headers},'
          f' expose headers: {result.expose_headers},'
          )

if __name__ == "__main__":
    main()

Run the script by passing the required arguments:

python head_object.py \
  --region cn-hangzhou \
  --bucket <your-bucket> \
  --key <your-object-key> \
  --version_id <version-id>

The example uses cn-hangzhou as the region and a public endpoint by default. To access OSS from another Alibaba Cloud service in the same region, pass an internal endpoint via --endpoint. For a full list of regions and endpoints, see OSS regions and endpoints.

Get lightweight metadata with GetObjectMeta

GetObjectMeta returns a subset of system metadata without the overhead of a full HeadObject call. It returns only: content length, ETag, last modified time, last access time, version ID, and hash CRC64.

result = client.get_object_meta(oss.GetObjectMetaRequest(
    bucket="<your-bucket>",
    key="<your-object-key>",
    version_id="<version-id>",
))

Full example

import argparse
import alibabacloud_oss_v2 as oss

parser = argparse.ArgumentParser(description="get object meta sample")
parser.add_argument('--region', help='The region in which the bucket is located.', required=True)
parser.add_argument('--bucket', help='The name of the bucket.', required=True)
parser.add_argument('--endpoint', help='The domain names that other services can use to access OSS')
parser.add_argument('--key', help='The name of the object.', required=True)
parser.add_argument('--version_id', help='The version id of the object.', required=True)

def main():
    args = parser.parse_args()

    # Load credentials from environment variables
    credentials_provider = oss.credentials.EnvironmentVariableCredentialsProvider()

    cfg = oss.config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = args.region

    if args.endpoint is not None:
        cfg.endpoint = args.endpoint

    client = oss.Client(cfg)

    result = client.get_object_meta(oss.GetObjectMetaRequest(
        bucket=args.bucket,
        key=args.key,
        version_id=args.version_id,
    ))

    print(f'status code: {result.status_code},'
          f' request id: {result.request_id},'
          f' content length: {result.content_length},'
          f' etag: {result.etag},'
          f' last modified: {result.last_modified},'
          f' last access time: {result.last_access_time},'
          f' version id: {result.version_id},'
          f' hash crc64: {result.hash_crc64},'
          )

if __name__ == "__main__":
    main()

Run the script:

python get_object_meta.py \
  --region cn-hangzhou \
  --bucket <your-bucket> \
  --key <your-object-key> \
  --version_id <version-id>

Obtain object metadata (Python SDK V2)

Prerequisites

Choose a method

Get full metadata with HeadObject

Full example

Get lightweight metadata with GetObjectMeta

Full example

What's next