泛化調用

阿里雲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

以調用Container Service查詢叢集列表資訊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()

特點