{"id":7918,"library":"alibabacloud-gateway-oss","title":"Alibaba Cloud OSS Gateway Client","description":"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.","status":"active","version":"0.0.24","language":"en","source_language":"en","source_url":"https://github.com/aliyun/alibabacloud-gateway/tree/master/alibabacloud-gateway-oss","tags":["alibaba cloud","oss","object storage","gateway","sdk"],"install":[{"cmd":"pip install alibabacloud-gateway-oss","lang":"bash","label":"Install with pip"}],"dependencies":[],"imports":[{"note":"Standard import for the generated client.","symbol":"Client","correct":"from alibabacloud_gateway_oss.client import Client"},{"note":"Imports data models and request/response structures.","symbol":"models","correct":"from alibabacloud_gateway_oss import models"},{"note":"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.","wrong":"import oss2","symbol":"OSS Client"}],"quickstart":{"code":"import os\nfrom alibabacloud_gateway_oss.client import Client\nfrom alibabacloud_gateway_oss import models\nfrom alibabacloud_tea_openapi.models import Config\n\n# Configure credentials and endpoint from environment variables\naccess_key_id = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_ID', 'your_access_key_id')\naccess_key_secret = os.environ.get('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'your_access_key_secret')\nendpoint = os.environ.get('ALIBABA_CLOUD_OSS_ENDPOINT', 'oss-cn-hangzhou.aliyuncs.com') # e.g., 'oss-cn-hangzhou.aliyuncs.com'\n\n# Basic client configuration\nconfig = Config(\n    access_key_id=access_key_id,\n    access_key_secret=access_key_secret,\n    endpoint=endpoint\n)\n\n# You can also set a security token for STS credentials\nsecurity_token = os.environ.get('ALIBABA_CLOUD_SECURITY_TOKEN')\nif security_token:\n    config.security_token = security_token\n\nclient = Client(config)\n\nprint(\"Alibaba Cloud OSS Gateway Client initialized.\")\nprint(f\"Endpoint: {client._endpoint}\")\n\n# Note: This is a low-level gateway client. Specific API operations\n# are accessed via methods on the 'client' object, often requiring\n# request and response models from 'alibabacloud_gateway_oss.models'.\n# For common OSS operations like listing buckets, uploading/downloading objects,\n# consider using the higher-level 'alibabacloud-oss-v2' (oss2) SDK.\n\n# Example of a placeholder request (replace with actual API call if applicable)\n# try:\n#     # This is a hypothetical example as specific API methods are not readily documented for this gateway client.\n#     # You would consult the Alibaba Cloud OSS API documentation for specific request/response types.\n#     list_buckets_request = models.ListBucketsRequest(\n#         prefix='my-prefix'\n#     )\n#     response = client.list_buckets(list_buckets_request)\n#     print(f\"List Buckets Response: {response.body}\")\n# except Exception as e:\n#     print(f\"Error performing operation: {e}\")","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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.","severity":"breaking","affected_versions":"All versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"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`.","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`).","error":"ModuleNotFoundError: No module named 'oss2'"},{"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.","cause":"The provided AccessKey ID is incorrect, disabled, or has leading/trailing spaces.","error":"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"},{"fix":"Grant the `AliyunSTSAssumeRoleAccess` system authorization permission to the RAM user, or ensure the specified role trusts the requesting Alibaba Cloud account ID.","cause":"The RAM user or role used for authentication lacks the necessary `sts:AssumeRole` permission to perform the requested operation.","error":"SDKError: NoPermission ErrorMessage: No permission perform sts:AssumeRole on this Role."}]}