阿里云SDK for Java
本文以Java語言為例,為您介紹如何使用阿里云SDK。
背景信息
前提條件
如果SDK的認證方式是AccessKey,請確保已創(chuàng)建AccessKey。具體操作,請參見創(chuàng)建AccessKey。
如果SDK的認證方式是RAM角色,請確保已創(chuàng)建RAM角色。具體操作,請參見授予實例RAM角色。
步驟一:添加SDK依賴
在項目中添加Maven依賴,從Maven倉庫中自動下載Java安裝包。
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-core</artifactId>
<version>4.5.2</version>
</dependency>
<dependency>
<groupId>com.aliyun</groupId>
<artifactId>aliyun-java-sdk-kms</artifactId>
<version>2.16.0</version>
</dependency>
建議您安裝最新版本的SDK。關(guān)于版本的更多信息,請參見阿里云SDK概覽。
步驟二:初始化Client
使用阿里云SDK發(fā)起KMS API請求,您需要初始化一個Client。本文介紹使用AccessKey認證和使用RAM角色認證,阿里云SDK還提供了其他認證方式。更多信息,請參見Credentials 設(shè)置。
請根據(jù)KMS所屬地域正確填寫服務(wù)接入地址(又稱“訪問端點”或“Endpoint”),關(guān)于服務(wù)接入地址的更多信息,請參見支持的地域。
使用AccessKey認證
阿里云賬號AccessKey擁有所有OpenAPI的訪問權(quán)限,建議您使用RAM用戶進行API訪問或日常運維。強烈建議不要把AccessKey ID和AccessKey Secret保存到工程代碼里,否則可能導(dǎo)致AccessKey泄露,威脅您賬號下所有資源的安全。
本示例以將AccessKey配置在環(huán)境變量ALIBABA_CLOUD_ACCESS_KEY_ID和ALIBABA_CLOUD_ACCESS_KEY_SECRET的方式來實現(xiàn)身份驗證為例。
更多認證信息配置方式,請參見Credentials 設(shè)置。
不同操作系統(tǒng)的環(huán)境變量配置方法不同,具體操作,請參見在Linux、macOS和Windows系統(tǒng)配置環(huán)境變量。
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.profile.*;
import com.aliyuncs.http.*;
/**
* 創(chuàng)建KmsClient,使用自定義Endpoint、AK認證。
*/
public static DefaultAcsClient initClientByAK(String regionId, String endpoint) {
//指定KMS的Endpoint
DefaultProfile.addEndpoint(regionId, "kms", endpoint);
IClientProfile profile = DefaultProfile.getProfile(regionId, System.getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"), System.getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"));
HttpClientConfig clientConfig = HttpClientConfig.getDefault();
profile.setHttpClientConfig(clientConfig);
DefaultAcsClient kmsClient = new DefaultAcsClient(profile);
return kmsClient;
}
使用RAM角色認證
以ECS實例通過RAM角色訪問KMS為例,介紹如何初始化Client。
import com.aliyuncs.DefaultAcsClient;
import com.aliyuncs.profile.*;
import com.aliyuncs.auth.AlibabaCloudCredentialsProvider;
import com.aliyuncs.auth.InstanceProfileCredentialsProvider;
/**
* 創(chuàng)建KmsClient,使用自定義Endpoint、RAMRole認證。
*/
public static DefaultAcsClient initClientByRamRole(String regionId, String ramRoleName, String endpoint) {
//添加自定義Endpoint。
DefaultProfile.addEndpoint(regionId, "kms", endpoint);
DefaultProfile profile = DefaultProfile.getProfile(regionId);
//設(shè)置ECS實例RAM角色的憑證Provider。
AlibabaCloudCredentialsProvider provider = new InstanceProfileCredentialsProvider(ramRoleName);
DefaultAcsClient client = new DefaultAcsClient(profile, provider);
return client;
}
步驟三:使用已初始化的Client調(diào)用KMS API
初始化Client后,您可以通過Client調(diào)用KMS API。本文介紹如下幾個使用場景和代碼示例。
調(diào)用CreateKey創(chuàng)建密鑰
示例代碼以在KMS實例中創(chuàng)建密鑰規(guī)格為RSA_2048、密鑰用途為SIGN/VERIFY的密鑰為例。
import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.exceptions.ServerException; import com.aliyuncs.kms.model.v20160120.CreateKeyRequest; import com.aliyuncs.kms.model.v20160120.CreateKeyResponse; /** * @param kmsClient 阿里云SDK客戶端 * @param kmsInstanceId KMS實例Id * @return * @throws ClientException */ public static void createKeySample(DefaultAcsClient kmsClient, String kmsInstanceId) { final CreateKeyRequest request = new CreateKeyRequest(); // 在KMS軟件密鑰管理實例或硬件密鑰管理實例中創(chuàng)建密鑰時,請務(wù)必正確設(shè)置參數(shù)DKMSInstanceId,其他創(chuàng)建密鑰的場景無需填寫該參數(shù)。 // 設(shè)置KMS實例Id request.setDKMSInstanceId(kmsInstanceId); // 密鑰規(guī)格 request.setKeySpec("RSA_2048"); // 密鑰用途 request.setKeyUsage("SIGN/VERIFY"); final CreateKeyResponse response; try { response = kmsClient.getAcsResponse(request); System.out.println("KeyId:" + response.getKeyMetadata().getKeyId()); } catch (ServerException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getErrCode()); // 打印 RequestId System.out.println(e.getRequestId()); // 打印錯誤信息 System.out.println(e.getErrMsg()); } catch (ClientException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getMessage()); } }
調(diào)用ListKeys列舉密鑰
示例代碼以列舉密鑰狀態(tài)(KeyState)為啟用(Enabled)、密鑰規(guī)格(KeySpec)為RSA_2048的密鑰為例,同時設(shè)置了每頁返回值的個數(shù)(PageSize)為100。
import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.exceptions.ServerException; import com.aliyuncs.kms.model.v20160120.ListKeysRequest; import com.aliyuncs.kms.model.v20160120.ListKeysResponse; public static void listKeysSample(DefaultAcsClient kmsClient) { final ListKeysRequest request = new ListKeysRequest(); request.setPageNumber(1); request.setPageSize(100); String filters = "[{\"Key\":\"KeyState\", \"Values\":[\"Enabled\"]},{\"Key\":\"KeySpec\", \"Values\":[\"RSA_2048\"]}]"; request.setFilters(filters); try{ final ListKeysResponse listKeysResponse = kmsClient.getAcsResponse(request); System.out.println("TotalCount:" + listKeysResponse.getTotalCount()); } catch (ServerException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getErrCode()); // 打印 RequestId System.out.println(e.getRequestId()); // 打印錯誤信息 System.out.println(e.getErrMsg()); } catch (ClientException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getMessage()); } }
調(diào)用CreateSecret創(chuàng)建憑據(jù)
示例代碼以在KMS實例中創(chuàng)建一個通用憑據(jù),并將憑據(jù)值版本設(shè)置為V1為例。
import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.exceptions.ServerException; import com.aliyuncs.kms.model.v20160120.CreateSecretRequest; import com.aliyuncs.kms.model.v20160120.CreateSecretResponse; public static void createSecretSample(DefaultAcsClient kmsClient) { final CreateSecretRequest request = new CreateSecretRequest(); // 設(shè)置 KMS實例Id(DKMSInstanceId),即指定將憑據(jù)創(chuàng)建于哪個KMS實例。 request.setDKMSInstanceId("<KMS Instance Id>"); //用于加密憑據(jù)值的密鑰的標識符(EncryptionKeyId),該密鑰必須為對稱密鑰且和憑據(jù)屬于同一個KMS實例。 request.setEncryptionKeyId("<KeyId>"); // 憑據(jù)名稱(SecretName) request.setSecretName("Your-secret-name"); // 憑據(jù)類型(SecretType)。可選參數(shù)值詳見 CreateSecret 接口 API 文檔。 request.setSecretType("Generic"); // 對憑據(jù)的描述(Description) request.setDescription("<Description of the secret>"); // 憑據(jù)值版本(VersionId) request.setVersionId("V1"); // 憑據(jù)值(SecretData) request.setSecretData("<Your Secret Data>"); try{ final CreateSecretResponse createSecretResponse = kmsClient.getAcsResponse(request); System.out.println("Arn:" + createSecretResponse.getArn()); } catch (ServerException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getErrCode()); // 打印 RequestId System.out.println(e.getRequestId()); // 打印錯誤信息 System.out.println(e.getErrMsg()); } catch (ClientException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getMessage()); } }
調(diào)用GetSecretValue獲取憑據(jù)值
請求的AcceptFormat默認使用JSON格式,如果您的憑據(jù)值內(nèi)容(SecretData)中包含特殊字符
<>&
,請將AcceptFormat設(shè)置為XML,以避免特殊字符被轉(zhuǎn)義。示例代碼以AcceptFormat設(shè)置為XML為例。import com.aliyuncs.DefaultAcsClient; import com.aliyuncs.exceptions.ClientException; import com.aliyuncs.exceptions.ServerException; import com.aliyuncs.http.FormatType; import com.aliyuncs.kms.model.v20160120.GetSecretValueRequest; import com.aliyuncs.kms.model.v20160120.GetSecretValueResponse; public static void getSecretValueSample(DefaultAcsClient kmsClient) { GetSecretValueRequest request = new GetSecretValueRequest(); // 設(shè)置AcceptFormat為XML request.setAcceptFormat(FormatType.XML); request.setSecretName("Your-secret-name"); try { final GetSecretValueResponse getSecretValueResponse = kmsClient.getAcsResponse(request); // 獲取憑據(jù)值(SecretData) getSecretValueResponse.getSecretData(); } catch (ServerException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getErrCode()); // 打印 RequestId System.out.println(e.getRequestId()); // 打印錯誤信息 System.out.println(e.getErrMsg()); } catch (ClientException e) { // 打印整體的錯誤輸出 e.printStackTrace(); // 打印錯誤碼 System.out.println(e.getMessage()); } }