JavaSDK使用CommonRequest進行調用 - Alibaba Cloud SDK

阿里雲V1.0 SDK支援一種通用的方式調用OpenAPI，此方式被稱為泛化調用。本文將為您詳細介紹如何使用泛化調用訪問OpenAPI。

特點

輕量級：僅需安裝aliyun-java-sdk-core即可調用所有OpenAPI，無需依賴各產品的獨立SDK。
快速迭代相容性：當雲產品尚未提供相應的SDK，或當新API發布但SDK未能及時更新時，可以使用泛化調用。這樣，無需等待SDK的更新，即可及時調用最新發行的API介面。

使用說明

在使用泛化調用之前，必須手動擷取並配置OpenAPI的版本號碼、請求路徑、參數類型等中繼資料資訊。可以通過查看OpenAPI中繼資料來擷取有關OpenAPI的API風格、請求參數、資源路徑等相關資訊。

安裝核心SDK

在pom.xml中添加以下依賴安裝核心SDK。

<dependency>
     <groupId>com.aliyun</groupId>
     <artifactId>aliyun-java-sdk-core</artifactId>
     // 可選擇版本
     <version>[(4.0.0,5.0.0)]</version>
</dependency>

調用OpenAPI

初始化請求用戶端

通過在com.aliyuncs包中建立client對象以初始化請求用戶端，並通過該Client發起OpenAPI調用。此處僅列舉使用AccessKey（簡稱：AK）初始化用戶端的方式，更多初始化方式請參見管理訪問憑據。

說明

為了避免憑據泄露，常見的方案是將其寫入到環境變數中，具體操作請參見在Linux、macOS和Windows系統配置環境變數。

 import com.aliyuncs.DefaultAcsClient;
 import com.aliyuncs.profile.DefaultProfile;
 
        // 1.建立DefaultAcsClient執行個體並初始化
        DefaultProfile profile = DefaultProfile.getProfile(
                // 您的地區ID
                "cn-hangzhou",
                // System.getenv表示從環境變數擷取RAM帳號的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // System.getenv表示從環境變數擷取RAM帳號的AccessKey SECRET
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        // Client HTTPS配置（可選）
        HttpClientConfig clientConfig = HttpClientConfig.getDefault();
//        // 設定不校正服務端認證
//        clientConfig.setIgnoreSSLCerts(true);
//        // 每個Host的最大串連數
//        clientConfig.setMaxRequestsPerHost(6);
//        // 連線逾時時間
//        clientConfig.setConnectionTimeoutMillis(30000L);
//        // 讀取逾時時間
//        clientConfig.setReadTimeoutMillis(30000L);
//        // 寫入逾時時間
//        clientConfig.setWriteTimeoutMillis(60000L);
//        // 設定HTTP代理
//        clientConfig.setHttpProxy("http://127.0.0.1:9898");
//        // 設定HTTPS代理
//        clientConfig.setHttpsProxy("http://user:password@127.0.0.1:8989");
//        // 設定忽略Proxy 位址列表
//        clientConfig.setNoProxy("127.0.0.1,localhost");

        profile.setHttpClientConfig(clientConfig);
        IAcsClient client = new DefaultAcsClient(profile);

配置OpenAPI基本資料及請求參數

通過CommonRequest來配置OpenAPI所需的公用請求參數及介面請求參數。關於更多公用請求參數的介紹及使用請參見進階配置。

說明

CommonRequest的核心作用在於通過標準化的請求配置流程，將原始API中繼資料（例如版本號碼、路徑及參數類型）和請求參數轉化為有效HTTP請求，最終返回原始響應資料。參數傳遞方式的選擇依據API風格和介面設計。

介面請求參數說明

請求參數應該如何傳參需要查看介面對應的OpenAPI中繼資料，例如DescribeInstanceStatus的請求參數RegionId在中繼資料中資訊為{"name":"RegionId","in":"query",...}}，其中"in":"query"表示RegionId通過putQueryParameter傳遞。

描述	傳參方式
請求參數顯示`"in":"query"`時。	putQueryParameter(String key,String value) 說明如果請求參數的類型是集合，那麼參數應該按照putQueryParameter("key.1","value1"); putQueryParameter("key.2","value2");...格式傳參。
請求參數顯示`"in":"body"`或`"in": "formData"`時。	putBodyParameter(String key,String value) 說明如果請求參數的類型不是String類型，需要將參數值轉為JSON字串賦值給變數value。例如：request.putBodyParameter("key",new Gson().toJson(value));
上傳檔案時。	setHttpContent(byte[] content,String charset,FormatType formatType) 說明其中參數formatType固定為FormatType.RAW。

        // 2.建立API請求並配置OpenAPI參數
        // 此樣本以 RPC 風格 DescribeInstanceStatus（擷取ECS執行個體狀態資訊）介面為例
        CommonRequest request = new CommonRequest();
        // 2.1 設定公用請求參數
        request.setSysMethod(com.aliyuncs.http.MethodType.POST);
        request.setSysDomain("ecs-cn-hangzhou.aliyuncs.com");// API的網域名稱
        request.setSysVersion("2014-05-26");// API版本號碼
        request.setSysAction("DescribeInstanceStatus"); // API名稱，當調用RPC風格API時，必須配置SysAction()指定介面名稱
        request.setSysConnectTimeout(30000); // 逾時時間
        request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS); //請求協議：HTTPS或HTTP，建議使用HTTPS。
//        request.setSysUriPattern("/"); // API資源路徑，ROA介面必傳。RPC介面禁止設定該參數。
        
        // 2.2 配置介面請求參數
        // 情境一：Query參數通過putQueryParameter(string key,string value)設定
        request.putQueryParameter("RegionId", "cn-hangzhou");
        List<String> instanceIds = List.of(
                "i-bp1axhql4dqXXXXXXXX",
                "i-bp124uve8zqXXXXXXXX"
        );
        for(int i = 0; i < instanceIds.size(); ++i) {
            request.putQueryParameter("InstanceId." + (i + 1), (String)instanceIds.get(i));
        }
        request.putQueryParameter("PageNumber", "1");
        request.putQueryParameter("PageSize", "30");

        // 情境二：body參數通過putBodyParameter(string key,string value)設定
        // request.putBodyParameter("key1", "value1");
        // request.putBodyParameter("key2", "value2");
        // request.putBodyParameter("key3", "value3");

        // 情境三：檔案上傳setHttpContent(byte[] content,String charset,FormatType formatType)，其中formatType參數值固定為FormatType.RAW。
        // byte[] bodyImg = Files.readAllBytes(Paths.get("<FILE_PATH>")); // <FILE_PATH>需替換為實際檔案路徑
        // request.setHttpContent(bodyImg, "UTF-8", FormatType.RAW);

發起請求

通過client調用getCommonResponse發起請求。

// 發起請求
CommonResponse response = client.getCommonResponse(request);
// 傳回值response.getData()是JSON類型資料，包含RequestId以及OpenAPI的返回參數
System.out.println(response.getData());

程式碼範例

樣本：調用RPC風格的API

以調用ECS的DescribeInstanceStatus介面為例，展示如何使用CommonRequest調用方式。

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.http.FormatType;
import com.aliyuncs.profile.DefaultProfile;
import com.google.gson.GsonBuilder;

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.nio.charset.StandardCharsets;

public class Sample {
    public static void main(String[] args) throws ClientException, UnsupportedEncodingException {
        // 建立DefaultAcsClient執行個體並初始化
        DefaultProfile profile = DefaultProfile.getProfile(
                // 您的地區ID
                "cn-hangzhou",
                // 從環境變數擷取RAM帳號的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM帳號的AccessKey SECRET
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        
        // 建立API請求並設定參數
        CommonRequest request = new CommonRequest();
        request.setSysMethod(com.aliyuncs.http.MethodType.POST); // 請求方式
        request.setSysDomain("ecs-cn-hangzhou.aliyuncs.com"); // API的網域名稱
        request.setSysVersion("2014-05-26"); // API版本號碼
        request.setSysAction("DescribeInstanceStatus"); // API名稱，當調用RPC風格API時，必須配置SysAction()指定介面名稱
         request.setSysProtocol(com.aliyuncs.http.ProtocolType.HTTPS); //請求協議：HTTPS或HTTP，建議使用HTTPS。
        request.putQueryParameter("RegionId", "cn-hangzhou");
        List<String> instanceIds = List.of(
                "i-bp1axhql4dqXXXXXXXX",
                "i-bp124uve8zqXXXXXXXX"
        );
        for(int i = 0; i < instanceIds.size(); ++i) {
            request.putQueryParameter("InstanceId." + (i + 1), (String)instanceIds.get(i));
        }
        request.putQueryParameter("PageNumber", "1");
        request.putQueryParameter("PageSize", "30");
        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (ClientException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
}

樣本：調用RESTful（ROA）風格的API

以調用Container Service查詢叢集列表資訊DescribeClustersV1介面為例，展示如何使用CommonRequest調用。

import com.aliyuncs.CommonRequest;
import com.aliyuncs.CommonResponse;
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.IAcsClient;
import com.aliyuncs.exceptions.ClientException;
import com.aliyuncs.exceptions.ServerException;
import com.aliyuncs.profile.DefaultProfile;
public class Sample {
    public static void main(String[] args) {
        // 建立DefaultAcsClient執行個體並初始化
        DefaultProfile profile = DefaultProfile.getProfile(
                // 您的地區ID
                "cn-hangzhou",
                // 從環境變數擷取RAM帳號的AccessKey ID
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
                // 從環境變數擷取RAM帳號的AccessKey SECRET
                System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
        IAcsClient client = new DefaultAcsClient(profile);
        // 建立API請求並設定參數
        CommonRequest request = new CommonRequest();
        request.setSysDomain("cs.aliyuncs.com");// 網域名稱
        request.setSysVersion("2015-12-15");// API版本
        request.setSysUriPattern("/clusters"); // API資源路徑，當調用ROA風格API時，必須配置UriPattern()指定完整資源路徑。從OpenAPI中繼資料中data.path擷取資源路徑。
        request.setSysMethod(MethodType.GET);// 請求方式
        try {
            CommonResponse response = client.getCommonResponse(request);
            System.out.println(response.getData());
        } catch (ServerException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (ClientException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }
}

常見問題

報錯提示“The input parameter "AccessKeyId" that is mandatory for processing this request is not supplied. ”。
問題原因：AK未正確配置。
解決方案：
1. 執行以下命令，檢查您的環境變數中是否配置有ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET：
  Linux/macOS
```
echo $ALIBABA_CLOUD_ACCESS_KEY_ID
echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
```
  Windows
```
echo %ALIBABA_CLOUD_ACCESS_KEY_ID%
echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%
```
  若返回正確的AccessKey，則說明配置成功。如果返回為空白或錯誤，請嘗試重新設定，具體操作請參見在Linux、macOS和Windows系統配置環境變數。
2. 檢查代碼中AK相關內容是否存在錯誤。
  常見錯誤樣本：
```
accessKeyId = System.getenv("yourAccessKeyID"),
accessKeySecret = System.getenv("yourAccessKeySecret")
```
  說明
  此錯誤樣本將System.getenv()的入參視為需要填入的AK，然而實際上該函數的功能是讀取環境變數。當您在機器上設定環境變數名稱為ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET時，System.getenv將能夠擷取其對應的值。
  正確樣本
```
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")
System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
```
報錯提示“com.aliyuncs.exceptions.ClientException: MissingParameter : The input parameter "Timestamp" that is mandatory for processing this request is not supplied.”
問題原因：RPC介面公用請求參數設定了SysUriPattern參數。
解決方案：在公用請求參數中去掉SysUriPattern參數。

特點