Alibaba Cloud OSS Gateway Client

0.0.24 · active · verified Thu Apr 16

alibabacloud-gateway-oss is a low-level, generated gateway client for Alibaba Cloud Object Storage Service (OSS). While its PyPI summary states "Alibaba Cloud OSS SDK Library for Python," it is *not* the primary, feature-rich SDK for direct OSS interactions. For most use cases involving OSS, the recommended library is `alibabacloud-oss-v2` (or `oss2`). This library, version 0.0.24, provides a basic client for interacting with the OSS API Gateway and is part of a larger `alibabacloud-gateway` monorepo. It has an infrequent release cadence, tied to updates in the underlying API Gateway specification.

Common errors

```
ModuleNotFoundError: No module named 'oss2'
```
cause You installed `alibabacloud-gateway-oss` but your code tries to import `oss2`, which is the module name for the main Alibaba Cloud OSS SDK (`alibabacloud-oss-v2`).

fix If you intend to use the primary OSS SDK, install it with `pip install alibabacloud-oss-v2` and use `import oss2` or `import alibabacloud_oss_v2 as oss`. If you strictly need `alibabacloud-gateway-oss`, adjust your imports to `from alibabacloud_gateway_oss.client import Client`.
```
SDKError: The AccessKey ID is invalid. Make sure that you enter the AccessKey ID correctly and remove leading and trailing spaces from the AccessKey ID. Error code: InvalidAccessKeyId
```
cause The provided AccessKey ID is incorrect, disabled, or has leading/trailing spaces.

fix Double-check your `ALIBABA_CLOUD_ACCESS_KEY_ID` environment variable or the string passed to `Config`. Ensure it is active in the Alibaba Cloud console and has no extraneous characters.
```
SDKError: NoPermission ErrorMessage: No permission perform sts:AssumeRole on this Role.
```
cause The RAM user or role used for authentication lacks the necessary `sts:AssumeRole` permission to perform the requested operation.

fix Grant the `AliyunSTSAssumeRoleAccess` system authorization permission to the RAM user, or ensure the specified role trusts the requesting Alibaba Cloud account ID.

Warnings

gotcha This library (`alibabacloud-gateway-oss`) is a low-level, generated client for the Alibaba Cloud OSS API Gateway. It is *not* the primary, high-level SDK for general Object Storage Service interactions in Python.
Fix: For most direct OSS operations (e.g., listing buckets, uploading/downloading objects), use the `alibabacloud-oss-v2` package (imported as `alibabacloud_oss_v2` or `oss2`). This gateway client is typically used for more specialized or internal API gateway interactions.
breaking Alibaba Cloud has a separate, more commonly used Python SDK for OSS, which is `alibabacloud-oss-v2` (PyPI package `alibabacloud-oss-v2`, imported as `alibabacloud_oss_v2` or `oss2`). The `alibabacloud-gateway-oss` package might have different API signatures and object models, leading to incompatible code if used interchangeably.
Fix: Ensure you install and import the correct SDK for your needs. If you intend to use the feature-rich OSS SDK, install `alibabacloud-oss-v2` (or `oss2`) via `pip install alibabacloud-oss-v2` and adjust your imports accordingly.
gotcha Incorrect endpoint configuration is a leading cause of connection errors. Endpoints are region-specific and must match the region where your OSS bucket is located.
Fix: Always verify the correct OSS endpoint for your region from the Alibaba Cloud console or official documentation (e.g., `oss-cn-hangzhou.aliyuncs.com`). Ensure there are no typos.

Install

pip install alibabacloud-gateway-oss Install with pip

Imports

Client

from alibabacloud_gateway_oss.client import Client

Standard import for the generated client.

models
```
from alibabacloud_gateway_oss import models
```
Imports data models and request/response structures.
OSS Client
wrong:
```
import oss2
```
correct:
This imports the primary OSS SDK (oss2), not the alibabacloud-gateway-oss client. While often the desired library for OSS, it is distinct from this gateway client. The module name for oss2 is `oss2` or `alibabacloud_oss_v2` for the v2 SDK.

Quickstart

Initializes the `alibabacloud-gateway-oss` client using environment variables for authentication and the OSS endpoint. This client provides a low-level interface to the OSS API Gateway. For higher-level, more user-friendly interactions (e.g., direct bucket and object manipulation), the `alibabacloud-oss-v2` (or `oss2`) SDK is generally recommended.

import os
from alibabacloud_gateway_oss.client import Client
from alibabacloud_gateway_oss import models
from alibabacloud_tea_openapi.models import Config

# Configure credentials and endpoint from environment variables
access_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', 'your_access_key_id')
access_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'your_access_key_secret')
endpoint = os.environ.get('ALIBABA_CLOUD_OSS_ENDPOINT', 'oss-cn-hangzhou.aliyuncs.com') # e.g., 'oss-cn-hangzhou.aliyuncs.com'

# Basic client configuration
config = Config(
    access_key_id=access_key_id,
    access_key_secret=access_key_secret,
    endpoint=endpoint
)

# You can also set a security token for STS credentials
security_token = os.environ.get('ALIBABA_CLOUD_SECURITY_TOKEN')
if security_token:
    config.security_token = security_token

client = Client(config)

print("Alibaba Cloud OSS Gateway Client initialized.")
print(f"Endpoint: {client._endpoint}")

# Note: This is a low-level gateway client. Specific API operations
# are accessed via methods on the 'client' object, often requiring
# request and response models from 'alibabacloud_gateway_oss.models'.
# For common OSS operations like listing buckets, uploading/downloading objects,
# consider using the higher-level 'alibabacloud-oss-v2' (oss2) SDK.

# Example of a placeholder request (replace with actual API call if applicable)
# try:
#     # This is a hypothetical example as specific API methods are not readily documented for this gateway client.
#     # You would consult the Alibaba Cloud OSS API documentation for specific request/response types.
#     list_buckets_request = models.ListBucketsRequest(
#         prefix='my-prefix'
#     )
#     response = client.list_buckets(list_buckets_request)
#     print(f"List Buckets Response: {response.body}")
# except Exception as e:
#     print(f"Error performing operation: {e}")

view raw JSON →