PythonSDK，泛化调用_阿里云SDK(Alibaba Cloud SDK)-阿里云帮助中心

阿里云V1.0 SDK支持一种通用的方式调用OpenAPI，此方式被称为泛化调用。本文将为您详细介绍如何使用泛化调用访问OpenAPI。

特点

轻量级：仅需安装aliyun-python-sdk-core即可调用所有OpenAPI，无需依赖各产品的独立SDK。
快速迭代兼容性：当云产品尚未提供相应的SDK，或当新API发布但SDK未能及时更新时，可以使用泛化调用。这样，无需等待SDK的更新，即可及时调用最新发布的API接口。

使用说明

在使用泛化调用之前，必须手动获取并配置OpenAPI的版本号、请求路径、参数类型等元数据信息。可以通过查看OpenAPI元数据来获取有关OpenAPI的API风格、请求参数、资源路径等相关信息。

安装核心SDK

在Terminal中执行以下命令安装核心SDK。

pip install aliyun-python-sdk-core

调用OpenAPI

初始化请求客户端

通过在aliyunsdkcore包中创建client模块以初始化请求客户端，并通过该Client发起OpenAPI调用。此处仅列举使用AccessKey（简称：AK）初始化客户端的方式，更多初始化方式请参见管理访问凭据。

说明

为了避免凭据泄露，常见的方案是将其写入到环境变量中，具体操作请参见在Linux、macOS和Windows系统配置环境变量。

import os
from aliyunsdkcore.client import AcsClient

# 使用 AccessKey 直接初始化。os.environ表示从环境变量中获取访问密钥
client = AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], 'cn-hangzhou')

配置OpenAPI信息及请求参数

通过aliyunsdkcore包中的request模块来配置OpenAPI所需的基本信息及请求参数。

说明

request的核心作用是通过标准化的请求配置流程，将原始API元数据（如版本号、路径、参数类型）和请求参数转化为有效的HTTP请求，最终返回原始响应数据。参数传递方式根据API风格和接口设计选择。

from aliyunsdkcore.request import CommonRequest
import urllib.parse
import json

# 创建CommonRequest对象并配置OpenAPI基本信息和请求参数。
request = CommonRequest()

# 1.配置OpenAPI基本信息
request.set_domain('ecs.aliyuncs.com')  # API服务地址
request.set_version('2014-05-26')  # API版本号
# request 参数中包含action_name参数的是RPC风格，而包含uri_pattern参数的是ROA风格。
# 若传入错误的标识，可能会导致调用到其他API或收到ApiNotFound的错误信息。
request.set_action_name('DescribeRegions')  # API名称，当调用RPC风格API时，必须配置set_action_name()指定接口名称
# request.set_uri_pattern()  # API资源路径，当调用ROA风格API时，必须配置set_uri_pattern()指定完整资源路径。
request.set_method('POST')  # API请求方式
request.set_protocol_type('https')  # 请求协议：HTTPS或HTTP，建议使用HTTPS。

# 2.配置请求参数
# 方式1：使用add_query_param()添加query参数。
request.add_query_param('InstanceChargeType', 'PrePaid')

# 方式2：使用add_body_params()设置formData类型参数。
# request.add_body_params('InstanceChargeType', 'PrePaid')
# request.add_header('Content-Type', 'application/x-www-form-urlencoded')

# 方式3：使用set_content()设置byte类型参数。
# body = {
#     'InstanceChargeType': 'PrePaid'
# }
# bytes_body = json.dumps(body).encode('utf-8')
# request.set_content(bytes_body)

# 方式4：使用set_content()设置Json类型参数。
# 注意：此方式仅适用于明确支持JSON请求体的接口，可能存在接口不支持使用JSON的方式传参，否则参数可能被忽略或报错，请先查阅API文档确认
# request.add_body_params('InstanceChargeType', 'PrePaid')
# request.add_header('Content-Type', 'application/json')

发起请求

通过client调用do_action_with_exception发起请求。

# 发起请求
response = client.do_action_with_exception(request)
# 返回值是 bytes 类型，包含RequestId以及OpenAPI的返回参数
print(f"response：\n{response}")  
# 解析响应内容（JSON 格式）
response_json = json.loads(response.decode('utf-8'))  # 转换为 Python 字典
print("RequestId：", response_json["RequestId"])  # 请求ID

代码示例

示例：调用RPC风格的API

以调用ECS的DescribeRegions接口为例，展示如何使用泛化调用方式。

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

class Sample:

    @staticmethod
    def main():
       # 使用 AccessKey 直接初始化。os.environ表示从环境变量中获取访问密钥
       client = AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], 'cn-hangzhou')  
       # 创建请求对象
       request = CommonRequest()
       request.set_domain('ecs.aliyuncs.com')  # API服务地址
       request.set_version('2014-05-26')  # API版本号
       request.set_action_name('DescribeRegions')  # API名称，当调用RPC风格API时，必须配置set_action_name()指定接口名称
       request.set_method('POST')  # API请求方式
       request.add_query_param('InstanceChargeType', 'PrePaid')  # 配置请求参数 
       # 发起请求并处理响应
       response = client.do_action_with_exception(request)
       print(response)

if __name__ == '__main__':
    Sample.main()

示例：调用RESTful（ROA）风格的API

以调用容器服务查询集群列表信息DescribeClustersV1接口为例，展示如何使用泛化调用。

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

class Sample:

    @staticmethod
    def main():
        # 使用 AccessKey 直接初始化。os.environ表示从环境变量中获取访问密钥
        client = AcsClient(os.environ['ALIBABA_CLOUD_ACCESS_KEY_ID'], os.environ['ALIBABA_CLOUD_ACCESS_KEY_SECRET'], 'cn-hangzhou')
        # 创建请求对象
        request = CommonRequest()
        request.set_domain('cs.aliyuncs.com')  # API服务地址
        request.set_version('2015-12-15')  # API版本号
        request.set_uri_pattern(f'/api/v1/clusters')  # API资源路径，当调用ROA风格API时，必须配置set_uri_pattern()指定完整资源路径。从OpenAPI元数据中data.path获取资源路径。
        request.set_method('GET')  # API请求方法
        request.add_query_param('name', 'cluster-demo')  # 配置请求参数
        # 发起请求并处理响应
        response = client.do_action_with_exception(request)        
        print(response)

if __name__ == '__main__':  
    Sample.main()