Alibaba Cloud OSS SDK V2 for Python

Warnings

• breaking The `alibabacloud-oss-v2` SDK is a complete rewrite and is not compatible with the previous `aliyun-oss-python-sdk` (or `oss2`) SDK. Migrating from V1 to V2 will require significant code changes.
  Fix: Rewrite V1 code using the new V2 API patterns, import paths (e.g., `alibabacloud_oss_v2` instead of `oss2`), and client initialization methods.
• breaking In version 1.1.3, the type of `MetaQuery.media_types` was changed to `MetaQueryMediaTypes`. This is a type-hinting or strict-typing breaking change if you were directly using this attribute.
  Fix: Update your code to use the new `MetaQueryMediaTypes` type for the `MetaQuery.media_types` attribute.
• gotcha Starting March 20, 2025, new OSS users in Chinese mainland regions must use a custom domain name (CNAME) for data API operations, as default public endpoints are restricted. You must bind a valid SSL Certificate to your custom domain if accessing via HTTPS.
  Fix: For new deployments in affected regions, configure a custom domain (CNAME) and ensure an SSL certificate is bound for HTTPS access. Update your endpoint configuration to use the custom domain.
• gotcha Avoid hardcoding Alibaba Cloud credentials directly in your code. It's a security best practice to use environment variables or Alibaba Cloud RAM roles for authentication.
  Fix: Set `ALIBABA_CLOUD_ACCESS_KEY_ID` and `ALIBABA_CLOUD_ACCESS_KEY_SECRET` as environment variables. The SDK's `EnvironmentVariableCredentialsProvider` will automatically pick these up. For production, consider using RAM roles.
• gotcha For uploading large files (typically >100MB to 5GB, depending on best practices), it's highly recommended to use multipart upload for better reliability and performance.
  Fix: Utilize the SDK's multipart upload functionality for larger objects. The SDK supports `put_object_with_stream_and_auto_compress_and_hash` or the `Copier` for managing multipart uploads.

Install

• pip install alibabacloud-oss-v2 Install with pip

Imports

• Client

  from alibabacloud_oss_v2 import client as oss_client
  from alibabacloud_oss_v2 import models as oss_models
  from alibabacloud_oss_v2 import config as oss_config
  from alibabacloud_oss_v2.credentials import EnvironmentVariableCredentialsProvider

  The `oss2` package refers to the previous major version (V1) of the Alibaba Cloud OSS SDK. `alibabacloud-oss-v2` is the current, incompatible V2.

Quickstart

This quickstart demonstrates how to initialize the OSS V2 client using environment variables for credentials and then list all accessible OSS buckets. Ensure you set `ALIBABA_CLOUD_ACCESS_KEY_ID`, `ALIBABA_CLOUD_ACCESS_KEY_SECRET`, and `ALIBABA_CLOUD_REGION_ID` environment variables for authentication.

import os
from alibabacloud_oss_v2 import client as oss_client
from alibabacloud_oss_v2 import models as oss_models
from alibabacloud_oss_v2 import config as oss_config
from alibabacloud_oss_v2.credentials import EnvironmentVariableCredentialsProvider

# Set environment variables for authentication (replace with your actual region and credentials)
# os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'] = 'your_access_key_id'
# os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'] = 'your_access_key_secret'
# os.environ['ALIBABA_CLOUD_REGION_ID'] = 'cn-hangzhou'

region = os.environ.get('ALIBABA_CLOUD_REGION_ID', 'cn-hangzhou')

try:
    # Loading credentials from environment variables
    credentials_provider = EnvironmentVariableCredentialsProvider()

    # Using the SDK's default configuration
    cfg = oss_config.load_default()
    cfg.credentials_provider = credentials_provider
    cfg.region = region

    client = oss_client.Client(cfg)

    # Create a Paginator for the ListBuckets operation
    paginator = client.list_buckets_paginator()

    print(f"Listing buckets in region: {region}")
    # Iterate through the bucket pages
    found_buckets = False
    for page in paginator.iter_page(oss_models.ListBucketsRequest()):
        for bucket_info in page.buckets:
            print(f'Bucket: {bucket_info.name}, Location: {bucket_info.location}, Creation Date: {bucket_info.creation_date}')
            found_buckets = True
    if not found_buckets:
        print("No buckets found or access denied.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure ALIBABA_CLOUD_ACCESS_KEY_ID and ALIBABA_CLOUD_ACCESS_KEY_SECRET environment variables are set.")