SDK 中心 Java

二、依赖环境

1. JDK 7 版本及以上。

2. 从腾讯云控制台开通相应产品。

三、获取安装

使用 SDK 需要 API 密钥，可前往腾讯云控制台 – 访问密钥页面申请，API 密钥包括 SecretID 和 SecretKey，密钥须严格保管，避免泄露。

四、通过 Maven 安装（推荐）

从 3.1.500 版本开始，本项目使用 KonaJDK 编译发布。

通过 Maven 获取安装是使用 JAVA SDK 的推荐方法，Maven 是 JAVA 的依赖管理工具，支持你项目所需的依赖项，并将其安装到项目中。

关于 Maven 详细可参考 Maven 页面，并下载对应系统 Maven 安装包进行安装。

五、安装指定产品 SDK（推荐）

例如，安装指定产品包：

<dependency> <groupId>com.tencentcloudapi</groupId> <artifactId>tencentcloud-sdk-java-指定产品包名</artifactId> <!– 如 CVM 产品包：tencentcloud-sdk-java-cvm –> <!– 请到 maven 页面查询 sdk 的所有版本，例如 cvm 的产品包链接为 https://central.sonatype.com/artifact/com.tencentcloudapi/tencentcloud-sdk-java-cvm/versions –> <version>3.1.1000</version></dependency>

具体产品的包名缩写请参考 products.md 中的包名字段。

六、安装全产品 SDK

<dependency> <groupId>com.tencentcloudapi</groupId> <artifactId>tencentcloud-sdk-java</artifactId> <!– go to https://central.sonatype.com/artifact/com.tencentcloudapi/tencentcloud-sdk-java/versions and get the latest version. –> <!– 请到 https://central.sonatype.com/artifact/com.tencentcloudapi/tencentcloud-sdk-java/versions 查询所有版本，最新版本如下 –> <version>3.1.1000</version></dependency>

全产品 SDK 包含了所有云产品的调用代码，体积偏大，对体积敏感的场景，推荐安装指定产品 SDK。

七、注意事项

·安装全产品 SDK 和安装指定产品的 SDK 两种方式只能选择其中一种。

·如果同时安装多个产品的包，建议多个产品的包和 common 包保持在同一个版本。

·项目中添加 Maven 依赖项，只需在 Maven pom.xml 添加以下依赖项即可。注意这里的版本号只是举例，你可以在 Maven 仓库上找到最新的版本（最新版本是 3.1.1000）。请知悉，SDK 是先确认 mvn deploy 发布成功后再更新 GitHub tag，但是 Maven 页面索引更新有延迟，导致新发布的版本暂时（约1-2小时）在 Maven 页面搜索不到，实际不影响使用最新版本，你可以正常执行 mvn compile 等指令。

·maven 仓库中显示的 4.0.11 是废弃版本，我们已经联系 maven 删除 jar 包，但 maven 索引无法清除，请勿使用。

·无法使用源的用户可以使用镜像源加速下载，编辑 maven 的 settings.xml 配置文件，在 mirrors 段落增加镜像配置：

<mirror> <id>tencent</id> <name>tencent maven mirror</name> <url>https://mirrors.tencent.com/nexus/repository/maven-public/</url> <mirrorOf>*</mirrorOf> </mirror>

八、通过源码包安装

1. 前往 CNB、Github 仓库或者 Gitee 仓库下载源码压缩包。

2. 将源码包解压到你项目合适的位置。

3. 将 vendor 目录下的 jar 包放在 Java 可以找到的路径中。

4. 引用方法可参考以下示例。

九、示例

以查询实例接口 DescribeInstances 为例：

十、简化版

import com.tencentcloudapi.common.Credential;import com.tencentcloudapi.common.exception.TencentCloudSDKException;import com.tencentcloudapi.cvm.v20170312.CvmClient;import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesRequest;import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesResponse;public class DescribeInstances { public static void main(String[] args) { try { // 为了保护密钥安全，建议将密钥设置在环境变量中或者配置文件中，请参考这篇凭证管理章节。 // 硬编码密钥到代码中有可能随代码泄露而暴露，有安全隐患，并不推荐。 // Credential cred = new Credential("SecretId", "SecretKey"); Credential cred = new Credential(System.getenv("TENCENTCLOUD_SECRET_ID"), System.getenv("TENCENTCLOUD_SECRET_KEY")); CvmClient client = new CvmClient(cred, "ap-shanghai"); DescribeInstancesRequest req = new DescribeInstancesRequest(); DescribeInstancesResponse resp = client.DescribeInstances(req); System.out.println(DescribeInstancesResponse.toJsonString(resp)); } catch (TencentCloudSDKException e) { System.out.println(e.toString()); } }}

十一、详细版

import com.tencentcloudapi.common.Credential;import com.tencentcloudapi.common.exception.TencentCloudSDKException;// 导入对应产品模块的clientimport com.tencentcloudapi.cvm.v20170312.CvmClient;// 导入要请求接口对应的request response类import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesRequest;import com.tencentcloudapi.cvm.v20170312.models.DescribeInstancesResponse;import com.tencentcloudapi.cvm.v20170312.models.Filter;//导入可选配置类import com.tencentcloudapi.common.profile.ClientProfile;import com.tencentcloudapi.common.profile.HttpProfile;import com.tencentcloudapi.common.profile.Language;public class DescribeInstances { public static void main(String[] args) { try { // 实例化一个认证对象，入参需要传入腾讯云账户 SecretId，SecretKey。 // 为了保护密钥安全，建议将密钥设置在环境变量中或者配置文件中，请参考这篇凭证管理章节。 // 硬编码密钥到代码中有可能随代码泄露而暴露，有安全隐患，并不推荐。 // Credential cred = new Credential("SecretId", "SecretKey"); Credential cred = new Credential(System.getenv("TENCENTCLOUD_SECRET_ID"), System.getenv("TENCENTCLOUD_SECRET_KEY")); // 实例化一个http选项，可选的，没有特殊需求可以跳过 HttpProfile httpProfile = new HttpProfile(); // 从3.0.96版本开始, 单独设置 HTTP 代理 // httpProfile.setProxyHost("真实代理ip"); // httpProfile.setProxyPort(真实代理端口); httpProfile.setReqMethod("GET"); // get请求(默认为post请求) httpProfile.setConnTimeout(30); // 请求连接超时时间，单位为秒(默认60秒) httpProfile.setWriteTimeout(30); // 设置写入超时时间，单位为秒(默认0秒) httpProfile.setReadTimeout(30); // 设置读取超时时间，单位为秒(默认0秒) httpProfile.setEndpoint("cvm.ap-shanghai.tencentcloudapi.com"); // 指定接入地域域名(默认就近接入) // 实例化一个client选项，可选的，没有特殊需求可以跳过 ClientProfile clientProfile = new ClientProfile(); clientProfile.setSignMethod("HmacSHA256"); // 指定签名算法(默认为HmacSHA256) // 自3.1.80版本开始，SDK 支持打印日志。 clientProfile.setHttpProfile(httpProfile); clientProfile.setDebug(true); // 从3.1.16版本开始，支持设置公共参数 Language, 默认不传，选择(ZH_CN or EN_US) clientProfile.setLanguage(Language.EN_US); // 实例化要请求产品(以cvm为例)的client对象,clientProfile是可选的 CvmClient client = new CvmClient(cred, "ap-shanghai", clientProfile); // 实例化一个cvm实例信息查询请求对象,每个接口都会对应一个request对象。 DescribeInstancesRequest req = new DescribeInstancesRequest(); // 填充请求参数,这里request对象的成员变量即对应接口的入参 // 你可以通过页面接口文档或跳转到request对象的定义处查看请求参数的定义 Filter respFilter = new Filter(); // 创建Filter对象, 以zone的维度来查询cvm实例 respFilter.setName("zone"); respFilter.setValues(new String[] { "ap-shanghai-1", "ap-shanghai-2" }); req.setFilters(new Filter[] { respFilter }); // Filters 是成员为Filter对象的列表 // 通过client对象调用DescribeInstances方法发起请求。注意请求方法名与请求对象是对应的 // 返回的resp是一个DescribeInstancesResponse类的实例，与请求对象对应 DescribeInstancesResponse resp = client.DescribeInstances(req); // 输出json格式的字符串回包 System.out.println(DescribeInstancesResponse.toJsonString(resp)); // 也可以取出单个值。 // 你可以通过页面接口文档或跳转到response对象的定义处查看返回字段的定义 System.out.println(resp.getTotalCount()); } catch (TencentCloudSDKException e) { System.out.println(e.toString()); } }}

十二、详细版示例代码分步骤介绍

1. 导入待调用的类：

2. 实例化一个认证对象 cred，入参需要传入腾讯云账户密钥 secretId 和 secretKey，你可以前往 API 密钥管理页面获取密钥。

注意：此处还需注意密钥对的保密。

// 为了保护密钥安全，建议将密钥设置在环境变量中或者配置文件中，请参考这篇凭证管理章节。// 硬编码密钥到代码中有可能随代码泄露而暴露，有安全隐患，并不推荐。Credential cred = new Credential(System.getenv("TENCENTCLOUD_SECRET_ID"), System.getenv("TENCENTCLOUD_SECRET_KEY"));

3. 实例化一个 http 选项，若没有特殊需求可参照简化版示例代码跳过设置。若有需求可以参照下方示例代码设置 http 选项中的参数。

HttpProfile httpProfile = new HttpProfile();// 从3.1.16版本开始, 单独设置 HTTP 代理// httpProfile.setProxyHost("真实代理ip");// httpProfile.setProxyPort(真实代理端口);// get请求(默认为post请求)httpProfile.setReqMethod("GET"); // get请求(默认为post请求)httpProfile.setProtocol("https://"); // 合法值：https:// 或者 http:// ，公有云只能使用 https。httpProfile.setConnTimeout(30); // 请求连接超时时间，单位为秒(默认60秒)httpProfile.setWriteTimeout(30); // 设置写入超时时间，单位为秒(默认0秒)httpProfile.setReadTimeout(30); // 设置读取超时时间，单位为秒(默认0秒)httpProfile.setEndpoint("cvm.ap-shanghai.tencentcloudapi.com"); // 指定接入地域域名(默认就近接入)

4. 实例化一个 client 选项，若没有特殊需求可参照简化版示例代码跳过设置。若有需求可以参照下方示例代码设置 client 选项中的参数。

ClientProfile clientProfile = new ClientProfile();clientProfile.setSignMethod("HmacSHA256"); // 指定签名算法(默认为HmacSHA256)// 自3.1.80版本开始，SDK 支持打印日志。clientProfile.setHttpProfile(httpProfile);clientProfile.setDebug(true);// 从3.1.16版本开始，支持设置公共参数 Language, 默认不传，选择(ZH_CN or EN_US)clientProfile.setLanguage(Language.EN_US);

5. 实例化要请求产品的 client 对象，示例代码以 CVM 产品为例，实例化 CvmClient 对象。

CvmClient client = new CvmClient(cred, "ap-shanghai", clientProfile);

6. 实例化一个 CVM 实例信息查询请求对象 req，每个接口都会对应一个 request 对象，若有需要可以参照页面文档设置对象中的参数。

DescribeInstancesRequest req = new DescribeInstancesRequest();// 填充请求参数,这里request对象的成员变量即对应接口的入参// 你可以通过页面接口文档或跳转到request对象的定义处查看请求参数的定义Filter respFilter = new Filter(); // 创建Filter对象, 以zone的维度来查询cvm实例respFilter.setName("zone");respFilter.setValues(new String[] { "ap-shanghai-1", "ap-shanghai-2" });req.setFilters(new Filter[] { respFilter }); // Filters 是成员为Filter对象的列表

7. 通过 client 对象调用你想调用的接口，返回对应的 Response 类的实例。

// 通过client对象调用DescribeInstances方法发起请求。注意请求方法名与请求对象是对应的// 返回的resp是一个DescribeInstancesResponse类的实例，与请求对象对应DescribeInstancesResponse resp = client.DescribeInstances(req);

8. 可以打印输出返回的数据值。

// 输出json格式的字符串回包System.out.println(DescribeInstancesResponse.toJsonString(resp));// 也可以取出单个值。// 你可以通过页面接口文档或跳转到response对象的定义处查看返回字段的定义System.out.println(resp.getTotalCount());}

9. 使用 catch 处理报错，错误码详细内容请参考页面产品文档对应的错误码章节。

catch (TencentCloudSDKException e) { System.out.println(e.toString());}

十三、更多示例

你可以在 GitHub 中 examples 目录下找到更多详细的示例。

十五、代理

从 3.0.96 版本开始，可以单独设置 HTTP 代理：

HttpProfile httpProfile = new HttpProfile();httpProfile.setProxyHost("代理ip或者域名");httpProfile.setProxyPort(代理端口);httpProfile.setProxyUsername("代理用户名");httpProfile.setProxyPassword("代理密码");

十六、语言

从 3.1.16 版本开始，我们添加了对公共参数 Language 的支持，以满足部分产品国际化的需求。和以前一样，Language 默认不传，行为由各产品接口自行决定。通常情况下，接口的默认语言是中文，但也有一些接口的默认语言是英文。目前可选值为中文或者英文，如果你需要设置 Language 参数，可使用以下方法：

import com.tencentcloudapi.common.profile.ClientProfile;import com.tencentcloudapi.common.profile.Language;… ClientProfile clientProfile = new ClientProfile(); clientProfile.setLanguage(Language.ZH_CN);

十七、支持 http

SDK 支持 HTTP 协议和 HTTPS 协议，通过设置 HttpProfile 的 setProtocol() 方法可以实现协议间的切换：

HttpProfile httpProfile = new HttpProfile();httpProfile.setProtocol("http://"); //http协议httpProfile.setProtocol("https://"); //https协议

十八、支持打印日志

自 3.1.80 版本开始，SDK 支持打印日志。你可以通过以下步骤来设置：

首先，在创建 CLientProfile 对象时，设置 debug 模式为真，这将打印 SDK 异常信息和流量信息。

ClientProfile clientProfile = new ClientProfile();clientProfile.setDebug(true);

腾讯云 Java SDK 使用 commons.logging 类进行打印日志，示例如下：

九月 10, 2020 5:14:30 下午 com.tencentcloudapi.cvm.v20170312.CvmClient info信息: send request, request url: https://cvm.ap-shanghai.tencentcloudapi.com/?Nonce=367595572&Action=DescribeInstances&Filters.0.Values.1=ap-shanghai-2&Version=2017-03-12&Filters.0.Values.0=ap-shanghai-1&SecretId=************************************&Filters.0.Name=zone&RequestClient=SDK_JAVA_3.1.129&Region=ap-shanghai&SignatureMethod=HmacSHA256&Timestamp=1599729270&Signature=DcGRPdquMZZRPj1NFXP5bsOGnRlaT2KXy7aegNhZa00%3D. request headers information: 九月 10, 2020 5:14:32 下午 com.tencentcloudapi.cvm.v20170312.CvmClient info信息: recieve response, response url: https://cvm.ap-shanghai.tencentcloudapi.com/?Nonce=367595572&Action=DescribeInstances&Filters.0.Values.1=ap-shanghai-2&Version=2017-03-12&Filters.0.Values.0=ap-shanghai-1&SecretId=************************************&Filters.0.Name=zone&RequestClient=SDK_JAVA_3.1.129&Region=ap-shanghai&SignatureMethod=HmacSHA256&Timestamp=1599729270&Signature=DcGRPdquMZZRPj1NFXP5bsOGnRlaT2KXy7aegNhZa00%3D, response headers: Server: nginx;Date: Thu, 10 Sep 2020 09:14:32 GMT;Content-Type: application/json;Content-Length: 103;Connection: keep-alive;OkHttp-Selected-Protocol: http/1.1;OkHttp-Sent-Millis: 1599729271230;OkHttp-Received-Millis: 1599729272020;,response body information: com.squareup.okhttp.internal.http.RealResponseBody@8646db9

你可以根据自己的需要配置日志打印类，例如 log4j。配置方法如下：

·配置 pom 文件，设置 log4j 版本。

·设置环境变量为 log4j，并创建 log 类。

System.setProperty("org.apache.commons.logging.Log", "org.apache.commons.logging.impl.Log4JLogger");Log logger = LogFactory.getLog("TestLog");logger.info("hello world");

十九、地域容灾

从 3.1.779 版本开始，腾讯云的 Java SDK 支持地域容灾功能。当满足以下条件时，SDK 会自动将你的请求设置为备选地域：

1. 失败次数 ≥ 5次

2. 失败率 ≥ 75%

你可以通过以下设置来配置相关功能：

// 设置备用请求地址，不需要指定服务，SDK 会自动在头部加上服务名(如cvm)// 例如，设置为 ap-guangzhou.tencentcloudapi.com，则最终的请求为 cvm.ap-guangzhou.tencentcloudapi.comclientProfile.setBackupEndpoint("ap-guangzhou.tencentcloudapi.com");// 自定义断路器条件CircuitBreaker.Setting setting = new CircuitBreaker.Setting();setting.maxFailNum = 6;setting.maxFailPercentage = 0.8f;CircuitBreaker rb = new CircuitBreaker(setting);client.setRegionBreaker(rb);

请注意，此功能仅支持单个客户端的同步请求。

20、Common Client

从3.1.303版本开始，腾讯云 Java SDK 支持使用泛用性的 API 调用方式 (Common Client) 进行请求。你只需要安装 Common 包，即可向任何产品发起调用。

注意：你必须明确了解你调用的接口所需的参数，否则可能会导致调用失败。

目前仅支持使用 POST 方式，且签名方法必须使用签名方法 v3。详细使用请参见示例使用 Common Client 进行调用。

21、支持重试请求

从 3.1.310 版本开始，腾讯云 Java SDK 支持重试请求。你可以为每个请求设置重试次数，如果接口请求未成功，SDK 会进行重试，直到请求成功或达到设置的重试次数。待设置的重试次数最大为10，最小为0，每次重试失败需要睡眠1秒钟。详细使用请参见示例使用 retry 进行重试请求。

22、凭证管理

腾讯云 Java SDK 目前支持以下几种方式进行凭证管理：

1. 环境变量

默认读取环境变量 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 获取 secretId 和 secretKey。相关代码如下：

Credential cred = new EnvironmentVariableCredentialsProvider().getCredentials();

2. 配置文件

配置文件路径要求为：

·Windows： c:\\Users\\NAME\\.tencentcloud\\credentials

·Linux： ~/.tencentcloud/credentials 或 /etc/tencentcloud/credentials

配置文件格式如下：

[default]secret_id = xxxxxsecret_key = xxxxx

23、自定义 SSLSocketFactory 和 X509TrustManager

ClientProfile cpf = new ClientProfile();cpf.getHttpProfile().setSslSocketFactory(new MySSLSocketFactoryImpl());cpf.getHttpProfile().setX509TrustManager(new MyX509TrustManagerImpl());

24、跳过证书校验

ClientProfile cpf = new ClientProfile();// 创建一个信任所有证书的 TrustManagerTrustManager[] trustAllCerts = new TrustManager[] { new X509TrustManager() { @Override public void checkClientTrusted(X509Certificate[] chain, String authType) throws CertificateException { } @Override public void checkServerTrusted(X509Certificate[] chain, String authType) throws CertificateException { } @Override public X509Certificate[] getAcceptedIssuers() { return new X509Certificate[0]; } }};SSLContext sslContext = SSLContext.getInstance("TLS");sslContext.init(null, trustAllCerts, new java.security.SecureRandom());SSLSocketFactory sslSocketFactory = sslContext.getSocketFactory();httpProfile.setSslSocketFactory(sslSocketFactory);httpProfile.setX509TrustManager((X509TrustManager) trustAllCerts[0]);httpProfile.setHostnameVerifier(new HostnameVerifier() { @Override //创建一个不进行主机名验证的 HostnameVerifier public boolean verify(String hostname, SSLSession session) { return true; }});

26、DescribeInstancesRequest 示例

ClientProfile cpf = new ClientProfile();// 自定义 Header 需要使用 v3 签名方式cpf.setSignMethod(ClientProfile.SIGN_TC3_256);DescribeInstancesRequest request = new DescribeInstancesRequest();Map<String, String> header = new HashMap<String, String>();header.put("X-TC-TraceId","ffe0c072-8a5d-4e17-8887-a8a60252abca");request.SetHeader(header);

27、CommonClientRequest 示例

ClientProfile cpf = new ClientProfile();// 自定义 Header 需要使用 v3 签名方式cpf.setSignMethod(ClientProfile.SIGN_TC3_256);CommonClientRequest request = new CommonClientRequest();Map<String, String> header = new HashMap<String, String>();header.put("X-TC-TraceId","ffe0c072-8a5d-4e17-8887-a8a60252abca");request.SetHeader(header);

29、版本升级

注意：从 3.0.x 版本升级到 3.1.x 版本有兼容性问题，对于 Integer 字段的使用修改为了 Long 类型，需要重新编译项目。

30、证书问题

证书问题通常是客户端环境配置错误导致的。SDK 没有对证书进行操作，依赖的是 Java 运行环境本身的处理。出现证书问题后，你可以使用-Djavax.net.debug=ssl开启详细日志辅助判断。

有用户报告使用 IBM JDK 1.8出现证书报错：javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure，使用 Oracle JDK 后问题消失。

31、kotlin 问题

部分用户可能使用时遇到报错：java.lang.NoSuchMethodError: kotlin.collections.ArraysKt.copyInto。这是因为 kotlin 运行环境版本较低所导致的，你可以尝试升级 kotlin 版本来解决此问题。

32、java.lang.NoSuchMethodError: xxx.setSkipSign 问题

部分用户可能使用时遇到报错：java.lang.NoSuchMethodError: xxx.setSkipSign。这是因为 tencentcloud-sdk-java-common 包和其他产品（如tencentcloud-sdk-java-cvm）的版本不一致导致的。

该问题可能是 pom 中指定的 common 包版本有误，也可能是因为引用了其他第三方 sdk 而间接引用了不匹配的common 版本导致的。

解决方式是在 pom.xml 中显式指定相同版本的 common 包版本。

<dependency> <groupId>com.tencentcloudapi</groupId> <artifactId>tencentcloud-sdk-java-common</artifactId> <version>3.1.1000</version></dependency>