全部產品
Search

搜尋本產品

    Cloud Control API：Java整合SDK

    文件中心

    Cloud Control API：Java整合SDK

    更新時間：Feb 06, 2026

    雲控制API Java SDK 是一套專為 Java 開發人員設計的工具包，雲端式控制API（CloudControl API）構建。通過該 SDK，開發人員可以輕鬆調用標準化介面，高效管理阿里雲資源的全生命週期（建立、查詢、更新、刪除）。無論是多產品整合、快速適配新特性，還是處理非同步任務，SDK 都能顯著降低開發複雜度，讓開發人員專註於商務邏輯，無需關心底層介面差異。本文將詳細介紹 SDK 的整合與使用方法。

    前提條件

    • 調用雲控制API通常需要設定存取金鑰（AccessKey）。由於阿里雲帳號（主帳號）具有資源的所有許可權，一旦發生泄露將面臨重大風險。建議您使用RAM使用者，並為該RAM使用者建立AccessKey，具體操作方式，請參見建立RAM使用者和建立AccessKey。

    • 調用雲控制API通常需要設定訪問憑據，常見憑據類型為AccessKey（簡稱：AK）為防止憑據泄露，常用的方案是將其儲存到環境變數中。

      說明

      本文以設定環境變數ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET為例：

      設定訪問憑據到系統內容

      Linux和macOS系統配置方法

      通過export命令配置環境變數

      重要

      使用export命令配置的臨時環境變數僅當前會話有效，當會話退出之後所設定的環境變數將會丟失。若需長期保留環境變數，可將export命令配置到對應作業系統的啟動設定檔中。

      • 配置AccessKey ID並按斷行符號。

        # 將<ACCESS_KEY_ID>替換為您自己的AccessKey ID。
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

      • 配置AccessKey Secret並斷行符號。

        # 將<ACCESS_KEY_SECRET>替換為您自己的AccessKey Secret。
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

      • 驗證是否配置成功。

        執行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令，如果返回正確的AccessKey ID，則說明配置成功。

      Windows系統配置方法

      通過圖形化使用者介面GUI

      • 操作步驟

        以下為Windows 10中通過圖形化使用者介面設定環境變數的步驟。

        在案頭按右鍵此電腦，選擇屬性>進階系統設定>環境變數>系統變數/使用者變數>建立，完成以下配置：

        變數

        樣本值

        AccessKey ID

        • 變數名：ALIBABA_CLOUD_ACCESS_KEY_ID

        • 變數值：LTAI****************

        AccessKey Secret

        • 變數名：ALIBABA_CLOUD_ACCESS_KEY_SECRET

        • 變數值：yourAccessKeySecret

      • 測試設定是否成功

        單擊開始（或快速鍵：Win+R）> 運行（輸入 cmd）> 確定（或按 Enter 鍵），開啟命令提示字元，執行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正確的AccessKey，則說明配置成功。

      通過命令列提示符CMD

      • 操作步驟

        以管理員身份開啟命令提示字元，並使用以下命令在系統中新增環境變數。

        setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M

        其中/M表示系統級環境變數，設定使用者級環境變數時可以不攜帶該參數。

      • 測試設定是否成功

        單擊開始（或快速鍵：Win+R）> 運行（輸入 cmd）> 確定（或按 Enter 鍵），開啟命令提示字元，執行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正確的AccessKey，則說明配置成功。

      通過Windows PowerShell

      在PowerShell中，設定新的環境變數（對所有新會話都有效）：

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)

      為所有使用者佈建環境變數（需要管理員權限）：

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)

      設定臨時的環境變數（僅當前會話有效）： 

      $env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"

      在PowerShell中，執行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正確的AccessKey，則說明配置成功。

    • 在調用雲控制API之前，請首先為RAM使用者授予相應資源的操作許可權。有關具體操作方式請參見管理RAM使用者的許可權。

    • 在實際使用過程中，若要實現許可權的精細化管理，您可以建立自訂權限原則。具體操作請參見建立自訂權限原則。

      說明

      本文樣本將以列舉Virtual Private Cloud資源為例進行說明：

      • 快速授權：授予AliyunCloudControlAPIFullAccess許可權，具備管理雲控制API所有許可權。

      • 精細化授權：若您希望實現許可權的精細化管理，則只需建立針對列舉VPC資源的自訂權限原則：

        列舉Virtual Private Cloud資源自訂權限原則

        {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudcontrol:List*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "vpc:DescribeVpcs",
      "Resource": "*"
    }
  ]
}

    環境要求

    JDK版本 >= 1.8。

    引入 SDK

    1. 登入SDK Center，選擇雲控制API產品，例如您將要調用資源列舉的API。

    2. 在安裝頁面，所有語言選擇Java。然後在快速入門頁簽中，您可以擷取雲控制API的 SDK 安裝方式。image

      <dependency>
  <groupId>com.aliyun</groupId>
  <artifactId>cloudcontrol20220830</artifactId>
  <version>1.1.1</version>
</dependency>

    編寫調用代碼

    本文展示了如何調用 GetResources介面，以發起列舉Virtual Private Cloud 資源的請求。

    初始化請求用戶端

    在 SDK 中，所有的雲控制API均通過 SDK 提供的請求用戶端（Client）發起調用。訪問雲控制API門戶，在服務地區中根據所屬地區正確填寫服務接入地址（Endpoint）。關於服務地址更多資訊，請參見支援的地區。本樣本以使用AK進行初始化為例，更多初始化方式請參見Java SDK 管理訪問憑據。

    //      初始化用戶端
com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//      System.getenv()表示從環境變數擷取AccessKey
    .setAccessKeyId(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"))
    .setAccessKeySecret(System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
//      服務地址    
config.endpoint = "cloudcontrol.aliyuncs.com";
com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);

//        使用預設憑據鏈初始化用戶端
//        com.aliyun.credentials.Client credentialClient = new com.aliyun.credentials.Client();
//        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
//                .setCredential(credentialClient);
//        config.endpoint = "cloudcontrol.aliyuncs.com";
//        com.aliyun.cloudcontrol20220830.Client client = new com.aliyun.cloudcontrol20220830.Client(config);
    說明

    • getenv()函數的功能是讀取環境變數。當您在機器上設定環境變數名稱為ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET時，getenv將能夠擷取其對應的值。

    • 當您在初始化憑據用戶端不傳入任何參數時，Credentials工具會使用預設憑據鏈方式初始化用戶端。預設憑據的讀取邏輯請參見預設憑據鏈。

    定義請求路徑

    // 請求路徑
String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";
    說明

    請求路徑格式為： /api/v1/providers/{provider}/products/{product}/resources/{resourceTypeCode}。

    • 請求路徑中的變數說明如下：

      欄位

      說明

      樣本值

      {provider}

      雲廠商名稱。目前僅支援 Aliyun。

      Aliyun

      {product}

      產品 Code。通過調用列舉產品介面擷取。

      VPC

      {resourceTypeCode}

      資源 Code。通過調用列舉產品介面擷取。

      VPC

    • 資源是否存在父資源，可以通過 resourceType 的格式進行判斷：

      resourceType 格式

      說明

      樣本值

      ****

      不包含 /，表示該資源沒有父資源。

      VPC

      ****/****

      包含/，說明該資源存在父資源。例如產品KVStore for Redis，擁有資源Redis執行個體（DBInstance）和資料庫帳號（DBInstance/Account），其中資料庫帳號的resourceType為”DBInstance/Account“，說明資料庫帳號存在父資源，父資源的resourceType為DBInstance，即Redis執行個體。

      DBInstance/Account

      具體說明，請參見父資源與子資源。

    建立請求對象

    建立請求對象時，使用的函數名稱為<介面名稱>Request。通過 request 類的屬性設定必要的資訊，即 API 中必須要提供的資訊。

    // 過濾條件（可選）
// java.util.Map < String, Object > filter = TeaConverter.buildMap(
//    new TeaPair("IsDefault", true), // 是否是預設VPC
//    new TeaPair("ResourceGroupId", "<YOUR_RESOURCEGROUPID>"), // 資源群組ID
//    new TeaPair("DhcpOptionsSetId", "<YOUR_DHCPOPTIONSSETID>"), // DHCP選項集的ID
//    new TeaPair("VpcId", "<YOUR_VPCID>"), // VPC的ID
//    new TeaPair("VpcName", "<YOUR_VPCNAME>") // VPC的名稱
// );
// 建立請求對象
com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
    .setRegionId("cn-hangzhou") // 地區ID
//    .setFilter(filter) // 查詢過濾條件
//    .setNextToken("") // 標記當前開始讀取的位置
    .setMaxResults(2); // 分頁查詢時每頁行數

    發起請求

    通過請求用戶端調用OpenAPI時，使用的函數名稱為<介面名稱>WithOptions，其中<介面名稱>為OpenAPI名稱的首字母小寫格式。該函數包含四個參數：請求路徑、請求對象、要求標頭參數和運行時參數。請求對象為上一步建立的請求對象；運行時參數用於配置請求的行為，例如逾時設定、代理配置等。

    // 運行時參數
com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
//        // 忽略對 SSL 憑證的驗證
//        runtime.ignoreSSL = true;
//        // 代理配置
//        runtime.httpProxy = "http://127.0.0.1:9898";
//        runtime.httpsProxy = "http://user:password@127.0.0.1:8989";
//        runtime.noProxy = "127.0.0.1,localhost";
//        // 連線逾時
//        runtime.connectTimeout = 5000;
//        // 讀逾時
//        runtime.readTimeout = 10000;
//        // 開啟自動重試機制
//        runtime.autoretry = true;
//        // 設定自動重試次數
//        runtime.maxAttempts = 3;
// headers 參數，可自訂要求標頭，覆蓋預設值或添加額外的資訊。
java.util.Map < String, String > headers = new java.util.HashMap<>();
//        headers.put("x-acs-action", "GetResources"); // 設定介面名稱
// 發起請求
GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);

    異常處理

    Java V2.0 SDK將異常進行了細緻的分類，主要劃分為TeaUnretryableException和TeaException。

    • TeaUnretryableException：主要是因為網路問題造成，一般是網路問題達到最大重試次數後拋出。

    • TeaException：主要以業務報錯為主的異常。

    重要

    建議採取合理的措施來處理異常，例如有效地傳播異常資訊、記錄日誌、實施恢複嘗試等，以確保系統的健壯性和穩定性。

    完整範例程式碼

    package com.aliyun.sample;

import com.aliyun.cloudcontrol20220830.models.*;
import com.aliyun.tea.TeaException;
import com.aliyun.tea.TeaUnretryableException;
import com.google.gson.Gson;
public class Sample {


    public static com.aliyun.cloudcontrol20220830.Client createClient() throws Exception {
        // 使用預設憑據鏈初始化用戶端，此方式為更安全的無AK方式
        com.aliyun.credentials.Client credential = new com.aliyun.credentials.Client();
        com.aliyun.teaopenapi.models.Config config = new com.aliyun.teaopenapi.models.Config()
            .setCredential(credential);
        config.endpoint = "cloudcontrol.aliyuncs.com";
        return new com.aliyun.cloudcontrol20220830.Client(config);
    }

    public static void main(String[] args_) throws Exception {

        com.aliyun.cloudcontrol20220830.Client client = Sample.createClient();
        // 請求路徑
        String requestPath = "/api/v1/providers/Aliyun/products/VPC/resources/VPC";
        // 請求對象
        com.aliyun.cloudcontrol20220830.models.GetResourcesRequest getResourcesRequest = new com.aliyun.cloudcontrol20220830.models.GetResourcesRequest()
            .setRegionId("cn-hangzhou");
        // 運行時參數    
        com.aliyun.teautil.models.RuntimeOptions runtime = new com.aliyun.teautil.models.RuntimeOptions();
        // 自訂要求標頭參數
        java.util.Map < String, String > headers = new java.util.HashMap < > ();
        try {
            // 發起請求
            GetResourcesResponse getResourcesResponse = client.getResourcesWithOptions(requestPath, getResourcesRequest, headers, runtime);
            // 結果列印
            System.out.println(new Gson().toJson(getResourcesResponse.getBody()));
            // 擷取 requestId
            System.out.println(getResourcesResponse.body.requestId);
        } catch (TeaException error) {
            // 錯誤 message
            System.out.println(error.getMessage());
            // 診斷地址
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        } catch (TeaUnretryableException ue) {
            ue.printStackTrace();
            // 列印錯誤資訊
            System.out.println(ue.getMessage());
            // 列印請求記錄，查詢錯誤發生時的請求資訊
            System.out.println(ue.getLastRequest());
        } catch (Exception _error) {
            TeaException error = new TeaException(_error.getMessage(), _error);
            // 錯誤 message
            System.out.println(error.getMessage());
            // 診斷地址
            System.out.println(error.getData().get("Recommend"));
            com.aliyun.teautil.Common.assertAsString(error.message);
        }
    }
}

    常見問題

    • 調用OpenAPI時報錯，提示“You are not authorized to perform this operation”。

      問題原因：您所使用的AccessKey對應的RAM使用者沒有許可權調用該API。

      解決方案：請為該RAM使用者授予相應OpenAPI許可權。關於如何為RAM使用者進行授權，請參見管理RAM使用者的許可權。

      例如，當您在調用GetResources 時提示“You are not authorized to perform this operation”，您可以建立如下所示的自訂權限原則，並為該RAM使用者授予相應的許可權。

      {
  "Version": "1",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": "cloudcontrol:List*",
      "Resource": "*"
    },
    {
      "Effect": "Allow",
      "Action": "vpc:DescribeVpcs",
      "Resource": "*"
    }
  ]
}

    • 調用OpenAPI時報錯，提示“Cannot invoke "com.aliyun.credentials.Client.getCredential()" because "this._credential" is null”。

      問題原因：沒有將AccessKey正確設定環境變數。

      解決方案：

      設定訪問憑據到系統內容

      Linux和macOS系統配置方法

      通過export命令配置環境變數

      重要

      使用export命令配置的臨時環境變數僅當前會話有效，當會話退出之後所設定的環境變數將會丟失。若需長期保留環境變數，可將export命令配置到對應作業系統的啟動設定檔中。

      • 配置AccessKey ID並按斷行符號。

        # 將<ACCESS_KEY_ID>替換為您自己的AccessKey ID。
export ALIBABA_CLOUD_ACCESS_KEY_ID=yourAccessKeyID

      • 配置AccessKey Secret並斷行符號。

        # 將<ACCESS_KEY_SECRET>替換為您自己的AccessKey Secret。
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=yourAccessKeySecret

      • 驗證是否配置成功。

        執行echo $ALIBABA_CLOUD_ACCESS_KEY_ID命令，如果返回正確的AccessKey ID，則說明配置成功。

      Windows系統配置方法

      通過圖形化使用者介面GUI

      • 操作步驟

        以下為Windows 10中通過圖形化使用者介面設定環境變數的步驟。

        在案頭按右鍵此電腦，選擇屬性>進階系統設定>環境變數>系統變數/使用者變數>建立，完成以下配置：

        變數

        樣本值

        AccessKey ID

        • 變數名：ALIBABA_CLOUD_ACCESS_KEY_ID

        • 變數值：LTAI****************

        AccessKey Secret

        • 變數名：ALIBABA_CLOUD_ACCESS_KEY_SECRET

        • 變數值：yourAccessKeySecret

      • 測試設定是否成功

        單擊開始（或快速鍵：Win+R）> 運行（輸入 cmd）> 確定（或按 Enter 鍵），開啟命令提示字元，執行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正確的AccessKey，則說明配置成功。

      通過命令列提示符CMD

      • 操作步驟

        以管理員身份開啟命令提示字元，並使用以下命令在系統中新增環境變數。

        setx ALIBABA_CLOUD_ACCESS_KEY_ID yourAccessKeyID /M
setx ALIBABA_CLOUD_ACCESS_KEY_SECRET yourAccessKeySecret /M

        其中/M表示系統級環境變數，設定使用者級環境變數時可以不攜帶該參數。

      • 測試設定是否成功

        單擊開始（或快速鍵：Win+R）> 運行（輸入 cmd）> 確定（或按 Enter 鍵），開啟命令提示字元，執行echo %ALIBABA_CLOUD_ACCESS_KEY_ID%、echo %ALIBABA_CLOUD_ACCESS_KEY_SECRET%命令。若返回正確的AccessKey，則說明配置成功。

      通過Windows PowerShell

      在PowerShell中，設定新的環境變數（對所有新會話都有效）：

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::User)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::User)

      為所有使用者佈建環境變數（需要管理員權限）：

      [System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_ID', 'yourAccessKeyID', [System.EnvironmentVariableTarget]::Machine)
[System.Environment]::SetEnvironmentVariable('ALIBABA_CLOUD_ACCESS_KEY_SECRET', 'yourAccessKeySecret', [System.EnvironmentVariableTarget]::Machine)

      設定臨時的環境變數（僅當前會話有效）： 

      $env:ALIBABA_CLOUD_ACCESS_KEY_ID = "yourAccessKeyID"
$env:ALIBABA_CLOUD_ACCESS_KEY_SECRET = "yourAccessKeySecret"

      在PowerShell中，執行Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_ID、Get-ChildItem env:ALIBABA_CLOUD_ACCESS_KEY_SECRET命令。若返回正確的AccessKey，則說明配置成功。