Aliyun Python SDK Core V3

2.13.33 · active · verified Thu Apr 16

The `aliyun-python-sdk-core-v3` library provides the foundational components for interacting with Alibaba Cloud services using Python. It includes core functionalities like client initialization (`AcsClient`), request signing, and common request structures, upon which service-specific SDKs are built. The current version is 2.13.33, with releases occurring irregularly but consistently to support new features and fixes across Alibaba Cloud's ecosystem.

Common errors

```
No module named 'aliyunsdkcore'
```
cause The Python interpreter cannot find the `aliyunsdkcore` module. This usually happens if the `aliyun-python-sdk-core-v3` package was not installed or an incorrect import path was used.

fix Ensure the package is correctly installed: `pip install aliyun-python-sdk-core-v3`. Verify your import statements are `from aliyunsdkcore.client import AcsClient` etc.
```
Server Exception: Code: InvalidAccessKeyId.NotFound
```
cause The `AccessKeyId` provided to the `AcsClient` is either incorrect, expired, or does not exist in your Alibaba Cloud account.

fix Double-check your `ALIYUN_AK_ID` environment variable or the hardcoded `access_key_id` value against your Alibaba Cloud RAM console. Generate a new AccessKey if necessary.
```
Server Exception: Code: SignatureDoesNotMatch
```
cause The `AccessKeySecret` provided does not match the `AccessKeyId`, leading to a failed signature verification.

fix Verify your `ALIYUN_AK_SECRET` environment variable or the hardcoded `access_key_secret` value. Pay close attention to typos, leading/trailing spaces, and ensure it matches the correct `AccessKeyId`.
```
Server Exception: Code: UnsupportedRegion
```
cause The specified `region_id` (e.g., 'cn-hangzhou') does not support the specific Alibaba Cloud service or API action you are attempting to call.

fix Consult the official Alibaba Cloud documentation for the specific service (e.g., ECS, OSS) to find the list of supported regions for the API you are using, and update your `ALIYUN_REGION` or client initialization accordingly.

Warnings

gotcha The import path `aliyunsdkcore` does not directly reflect the PyPI package name `aliyun-python-sdk-core-v3`. This is a common source of `ModuleNotFoundError`.
Fix: Always use `from aliyunsdkcore.client import AcsClient` and `from aliyunsdkcore.request import CommonRequest`.
gotcha For robust error handling, always prefer `client.do_action_with_exception(request)` over the older `client.do_action(request)`. The latter can silently fail or return incomplete responses without raising an exception.
Fix: Update your API calls to use `do_action_with_exception` and wrap them in a try-except block to handle potential `ClientException` or `ServerException`.
gotcha Authentication failures are common due to incorrect `AccessKeyId`, `AccessKeySecret`, or an unsupported `region_id`. Errors like `InvalidAccessKeyId.NotFound` or `SignatureDoesNotMatch` indicate credential issues.
Fix: Ensure your `ALIYUN_AK_ID`, `ALIYUN_AK_SECRET`, and `ALIYUN_REGION` environment variables are correctly set and correspond to active, valid credentials and a region that supports the requested service.

Install

pip install aliyun-python-sdk-core-v3 Install latest version

Imports

AcsClient
wrong:
```
from aliyun_python_sdk_core_v3.client import AcsClient
```
correct:
```
from aliyunsdkcore.client import AcsClient
```
The actual import path is 'aliyunsdkcore', not directly reflecting the PyPI package name 'aliyun-python-sdk-core-v3'.
CommonRequest
wrong:
```
from aliyun_python_sdk_core_v3.request import CommonRequest
```
correct:
```
from aliyunsdkcore.request import CommonRequest
```
The actual import path is 'aliyunsdkcore', not directly reflecting the PyPI package name 'aliyun-python-sdk-core-v3'.

Quickstart

This quickstart demonstrates how to initialize the `AcsClient` with credentials and make a generic `CommonRequest` to an Alibaba Cloud service (e.g., listing ECS regions). It emphasizes using environment variables for sensitive data.

import os
from aliyunsdkcore.client import AcsClient
from aliyunsdkcore.request import CommonRequest

# Get credentials from environment variables or provide them directly
access_key_id = os.environ.get('ALIYUN_AK_ID', 'YOUR_ACCESS_KEY_ID')
access_key_secret = os.environ.get('ALIYUN_AK_SECRET', 'YOUR_ACCESS_KEY_SECRET')
region_id = os.environ.get('ALIYUN_REGION', 'cn-hangzhou')

# Initialize the AcsClient
client = AcsClient(access_key_id, access_key_secret, region_id)

# Create a CommonRequest for a service (e.g., ECS - DescribeRegions)
request = CommonRequest()
request.set_domain('ecs.aliyuncs.com') # Example: ECS service domain
request.set_version('2014-05-26')      # Example: API version
request.set_action_name('DescribeRegions') # Example: API action
request.set_method('POST')             # Example: HTTP method

# Send the request and print the response
try:
    response = client.do_action_with_exception(request)
    print(f"API Response: {response.decode('utf-8')}")
except Exception as e:
    print(f"An error occurred: {e}")

view raw JSON →