本文以調用查詢一台或多台ECS執行個體的詳細資料(DescribeInstances)介面為例,為您介紹Java V2.0 SDK的安裝和使用。
前提條件
由於阿里雲帳號(主帳號)擁有資源的所有許可權,其AccessKey一旦泄露風險巨大,所以建議您使用滿足最小化許可權需求的RAM使用者的AccessKey。具體操作方式請參見建立AccessKey。
給RAM使用者授予操作Elastic Compute Service相關資源的許可權。本文提供的範例程式碼為查詢樣本,所以選擇AliyunECSReadonlyAccess系統權限原則,您在使用的時候可以根據業務需求進行自訂授權。
使用自訂權限原則。
關於如何建立自訂權限原則,請參見建立自訂權限原則和授權資訊。
Elastic Compute Service依據最佳實務提供了一些自訂權限原則樣本,您可以參考這些樣本以快速建立符合自身業務需求的自訂權限原則,具體詳情請參見Elastic Compute Service自訂權限原則參考。
使用系統權限原則。
Elastic Compute Service支援的所有系統權限原則及其對應的許可權描述,請參見Elastic Compute Service系統權限原則參考。
在環境變數中配置AccessKey,具體操作步驟請參見在Linux、macOS和Windows系統配置環境變數。
安裝SDK
Java SDK支援多種安裝方式,本樣本以Apache Maven安裝方式為例,更多安裝方式擷取方式,請參見SDK中心。
開啟Maven專案的pom.xml檔案,在<dependencies>
節點中加入依賴配置,並重新整理Maven配置。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>ecs20140526</artifactId>
<version>5.3.0</version>
</dependency>
使用SDK
1. 初始化用戶端
阿里雲SDK支援多種訪問憑據用於初始化用戶端,例如AccessKey和STS Token等,更多方式請參見管理訪問憑據。本樣本以通過AccessKey初始化用戶端為例。
import com.aliyun.ecs20140526.Client;
import com.aliyun.teaopenapi.models.Config;
public class Sample {
private static Client createClient() throws Exception {
Config config = new Config()
// 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
// 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
// Endpoint 請參考 https://api.aliyun.com/product/Ecs
.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
return new Client(config);
}
}
2. 構建介面的請求對象
在構建請求對象之前,請查看該介面的API文檔擷取參數資訊。
請求對象命名規則:{API名稱}Request,例如DescribeInstances該介面的請求對象為DescribeInstancesRequest。
// 構造請求對象
DescribeInstancesRequest request = new DescribeInstancesRequest().setRegionId("cn-hangzhou");
3. 發起調用
通過用戶端調用OpenAPI時,支援設定運行時參數,例如逾時配置、代理配置等,更多資訊請查看進階配置。
介面返回對象命名規則:{API名稱}Response,例如DescribeInstances該介面的返回對象為DescribeInstancesResponse。
// 設定運行時參數
RuntimeOptions runtime = new RuntimeOptions();
// 調用 DescribeInstances 介面
DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
System.out.println(response.body.toMap());
4. 異常處理
Java SDK將異常進行了細緻的分類,主要劃分為TeaUnretryableException和TeaException。
TeaUnretryableException:主要是因為網路問題造成,一般是網路問題達到最大重試次數後拋出。
TeaException:主要以業務報錯為主的異常。
建議採取合理的措施來處理異常,比如合理地傳播異常、記錄日誌、嘗試恢複等,以確保系統的健壯性和穩定性。
5. 完整樣本
import com.aliyun.ecs20140526.Client;
import com.aliyun.ecs20140526.models.DescribeInstancesRequest;
import com.aliyun.ecs20140526.models.DescribeInstancesResponse;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.aliyun.teaopenapi.models.Config;
import com.aliyun.teautil.models.RuntimeOptions;
public class Sample {
private static Client createClient() throws Exception {
Config config = new Config()
// 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_ID。
.setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
// 必填,請確保代碼運行環境設定了環境變數 ALIBABA_CLOUD_ACCESS_KEY_SECRET。
.setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"))
// Endpoint 請參考 https://api.aliyun.com/product/Ecs
.setEndpoint("ecs.cn-hangzhou.aliyuncs.com");
return new Client(config);
}
public static void main(String[] args) {
try {
Client client = Sample.createClient();
// 構造請求對象
DescribeInstancesRequest request = new DescribeInstancesRequest()
.setRegionId("cn-hangzhou");
// 設定運行時參數
RuntimeOptions runtime = new RuntimeOptions();
// 調用 DescribeInstances 介面
DescribeInstancesResponse response = client.describeInstancesWithOptions(request, runtime);
System.out.println(response.body.toMap());
} catch (TeaUnretryableException ue) {
// 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
ue.printStackTrace();
// 列印錯誤資訊
System.out.println(ue.getMessage());
// 列印請求記錄,查詢錯誤發生時的請求資訊
System.out.println(ue.getLastRequest());
} catch (TeaException e) {
// 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
e.printStackTrace();
// 列印錯誤碼
System.out.println(e.getCode());
// 列印錯誤資訊,錯誤資訊中包含 RequestId
System.out.println(e.getMessage());
// 列印服務端返回的具體錯誤內容
System.out.println(e.getData());
} catch (Exception e) {
// 此處僅做列印展示,請謹慎對待異常處理,在工程專案中切勿直接忽略異常。
e.printStackTrace();
}
}
}
情境化樣本
更多內容
除了使用上述調用方式外,您還可以使用泛化調用方式調用ECS的OpenAPI,詳細介紹請參見泛化調用。
若您當前使用的是V1.0 SDK,並希望進一步瞭解V1.0 SDK的相關內容,請參見V1.0 Java SDK。