Java-SDK 中心-腾讯云

简介
欢迎使用腾讯云开发者工具套件（SDK）3.0，SDK 3.0是云 API 3.0 平台的配套工具。
为方便 JAVA 开发者调试和接入腾讯云产品 API，本文向您介绍适用于 Java 的腾讯云开发工具包，提供了简单示例来帮助您快速获取腾讯云 Java SDK 并开始调用。
依赖环境
1. JDK 7 版本及以上。
2. 从 腾讯云控制台 开通相应产品。
3. 获取 SecretID、SecretKey 以及调用地址（endpoint）。云 API 密钥 SecretId 和 SecretKey 请前往 API 密钥管理 获取。endpoint 一般形式为 *.tencentcloudapi.com，例如云服务器 CVM 的调用地址为 cvm.tencentcloudapi.com，详情请参见各产品的说明文档。
获取安装
在安装 Java SDK 之前，请先获取安全凭证。在首次使用云 API 之前，您需要在腾讯云控制台上申请安全凭证。安全凭证包括 SecretID 和 SecretKey。SecretID 用于标识 API 调用者的身份，SecretKey 用于加密签名字符串和服务器端验证签名字符串。请严格保管 SecretKey，避免泄露。
通过 Maven 安装（推荐）
从 3.1.500 版本开始，本项目使用 KonaJDK 编译发布。
通过 Maven 获取安装是使用 JAVA SDK 的推荐方法，Maven 是 JAVA 的依赖管理工具，支持您项目所需的依赖项，并将其安装到项目中。您可以参考 Maven 官网获取更详细的信息。以下是使用 Maven 安装的步骤：
1. 请访问 Maven 官网 ，下载对应系统 Maven 安装包进行安装。
2. 为您的项目添加 Maven 依赖项，只需在 Maven pom.xml 文件中添加以下依赖项。
注意：
这里的版本号只是举例，您可以在 Maven 仓库 中找到最新的版本（最新版本是3.1.708）。请知悉，SDK 是先确认 mvn deploy 发布成功后再更新 GitHub tag，但是 Maven 官网索引更新有延迟，导致新发布的版本暂时（约1-2小时）在 Maven 官网搜索不到，实际不影响使用最新版本，您可以正常执行 mvn compile 等指令。
Maven 仓库中显示的4.0.11是废弃版本，我们已经联系 Maven 官方删除该版本的 jar 包，但 Maven 索引无法清除，请勿使用。
引用方法可参考以下示例：
<dependency>
 <groupId>com.tencentcloudapi</groupId>
 <artifactId>tencentcloud-sdk-java</artifactId>
 <!-- go to https://search.maven.org/search?q=tencentcloud-sdk-java and get the latest version. -->
 <!-- 请到https://search.maven.org/search?q=tencentcloud-sdk-java查询所有版本，最新版本如下 -->
 <version>3.1.830</version>
</dependency>
3. 使用上述引用方式会将腾讯云所有产品的 SDK 下载到本地。如果您只需要特定产品的 SDK，可以将 artifactId 替换为 tencentcloud-sdk-java-cvm/cbs/vpc 等。代码中的使用方式和整体 SDK 相同，可参考示例。您也可以在 Maven 仓库 中查询最新版本，可节省存储空间。
4. 中国大陆地区的用户可以使用镜像源加速下载，编辑 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. 前往 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;
// 导入对应产品模块的client
import 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. 导入待调用的类：
import com.tencentcloudapi.common.Credential;
import com.tencentcloudapi.common.exception.TencentCloudSDKException;
// 导入对应产品模块的client
import 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;
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=AKIDziAMHwiVO0LPCizu61e1iCQP7YiaOX7Q&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=AKIDziAMHwiVO0LPCizu61e1iCQP7YiaOX7Q&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 版本。
    <dependency>
      <groupId>log4j</groupId>
      <artifactId>log4j</artifactId>
      <version>1.2.17</version>
    </dependency>
设置环境变量为 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.com
clientProfile.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);
请注意，此功能仅支持单个客户端的同步请求。
Common Client
从3.1.303版本开始，腾讯云 Java SDK 支持使用泛用性的 API 调用方式 (Common Client) 进行请求。您只需要安装  Common 包，即可向任何产品发起调用。
注意：
您必须明确了解您调用的接口所需的参数，否则可能会导致调用失败。
目前仅支持使用 POST 方式，且签名方法必须使用签名方法 v3。详细使用请参见示例 使用 Common Client 进行调用。
支持重试请求
从3.1.310版本开始，腾讯云 Java SDK 支持重试请求。您可以为每个请求设置重试次数，如果接口请求未成功，SDK 会进行重试，直到请求成功或达到设置的重试次数。待设置的重试次数最大为10，最小为0，每次重试失败需要睡眠1秒钟。详细使用请参见示例 使用 retry 进行重试请求。
凭证管理
腾讯云 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 = xxxxx
secret_key = xxxxx
相关代码如下：
Credential cred = new ProfileCredentialsProvider().getCredentials();
3. 角色扮演
有关角色扮演的相关概念请参见 腾讯云角色概述。如果使用此种方式，您需要在腾讯云访问管理控制台上创建一个角色，具体创建过程请参见 腾讯云角色创建。
在您拥有角色后，可以通过持久密钥和 roleArn 获取临时凭证，SDK 会自动刷新临时凭证，相关代码如下：
Credential cred = new STSCredential("secretId", "secretKey", "roleArn", "roleSessionName");
4. 实例角色
有关实例角色的相关概念请参见 腾讯云实例角色。
在您为实例绑定角色后，您可以在实例中访问相关元数据接口获取临时凭证，SDK 会自动刷新临时凭证。相关代码如下：
Credential cred = new CvmRoleCredential();
5. TKE OIDC 凭证
有关 TKE OIDC 凭证的相关示例请参见 Pod 使用 CAM 对数据库身份验证。
OIDCRoleArnProvider provider = new OIDCRoleArnProvider();
Credential credential = provider.getCredentials();
6. 凭证提供链
腾讯云 Java SDK 提供了凭证提供链，它会按照环境变量 > 配置文件 > 实例角色 > TKE OIDC 凭证的顺序尝试获取凭证，并返回第一个获取到的凭证。相关代码如下：
Credential cred = new DefaultCredentialsProvider().getCredentials();
凭证管理详细使用请参见 使用凭证提供链。
自定义 SSLSocketFactory 和 X509TrustManager
ClientProfile cpf = new ClientProfile();
cpf.getHttpProfile().setSslSocketFactory(new MySSLSocketFactoryImpl());
cpf.getHttpProfile().setX509TrustManager(new MyX509TrustManagerImpl());
其他问题
版本升级
注意：
从 3.0.x 版本升级到 3.1.x 版本有兼容性问题，对于 Integer 字段的使用修改为了 Long 类型，需要重新编译项目。
证书问题
证书问题通常是客户端环境配置错误导致的。SDK 没有对证书进行操作，依赖的是 Java 运行环境本身的处理。出现证书问题后，您可以使用-Djavax.net.debug=ssl开启详细日志辅助判断。
有用户报告使用 IBM JDK 1.8出现证书报错：javax.net.ssl.SSLHandshakeException: Received fatal alert: handshake_failure，使用 Oracle JDK 后问题消失。
kotlin 问题
部分用户可能使用时遇到报错：java.lang.NoSuchMethodError: kotlin.collections.ArraysKt.copyInto。这是因为 kotlin 运行环境版本较低所导致的，您可以尝试升级 kotlin 版本来解决此问题。
SDK 简介

PHP

Python

Java

Go

.NET

Node.js

C++

Ruby

联系我们

Java

本页目录：

简介

依赖环境

获取安装

通过 Maven 安装（推荐）

通过源码包安装

示例

简化版

详细版

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

更多示例

相关配置

代理

语言

支持 http

支持打印日志

地域容灾

Common Client

支持重试请求

凭证管理

自定义 SSLSocketFactory 和 X509TrustManager

其他问题

版本升级

证书问题

kotlin 问题
