tencentcloud-sdk-go

> 编程语言

开源

Tencent 云 API 3.0 Golang 版 SDK

743 stars0 点赞0 次浏览

访问官网 GitHub

工具介绍

Tencent 云 API 3.0 Golang 版 SDK

Tencent Cloud SDK for Go

简介

欢迎使用腾讯云开发者工具套件（SDK），此 SDK 是云 API 3.0 平台的配套开发工具。

获取安装

依赖环境

Go 1.9 版本及以上（如使用 go mod 需要 Go 1.14）。
部分产品需要在腾讯云控制台开通后，才能正常调用此产品的接口。
在腾讯云控制台访问管理页面获取密钥 SecretID 和 SecretKey，请务必妥善保管，或者使用更安全的临时安全凭证。

通过go get安装（推荐）

推荐使用腾讯云镜像加速下载：

Linux 或 MacOS:

bash

export GOPROXY=https://mirrors.tencent.com/go/

Windows:

cmd

set GOPROXY=https://mirrors.tencent.com/go/

按需安装（推荐）

注意：此安装方式仅支持使用 Go Modules 模式进行依赖管理，即环境变量 GO111MODULE=auto或者GO111MODULE=on, 并且在您的项目中执行了 go mod init xxx.

安装指定产品 SDK（推荐）

v1.0.170后可以按照产品下载，您只需下载基础包和对应的产品包(如cvm)即可，不需要下载全部的产品，从而加快您构建镜像或者编译的速度：

安装公共基础包：

bash

go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/common

安装对应的产品包(如cvm):

bash

go get -v -u github.com/tencentcloud/tencentcloud-sdk-go/tencentcloud/cvm

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

注意事项

如果同时安装多个产品的包，建议多个产品的包和 common 包保持在同一个版本。
为了支持 go mod，SDK 版本号从 v3.x 降到了 v1.x。并于2021.05.10移除了所有v3.0.*和3.0.*的tag，如需追溯以前的tag，请参考项目根目录下的 commit2tag 文件。

通过源码安装

前往代码托管地址 CNB、Github 或者 Gitee 下载最新代码，解压后安装到 $GOPATH/src/github.com/tencentcloud 目录下。

快速开始

每个接口都有一个对应的 Request 结构和一个 Response 结构。例如云服务器的查询实例列表接口 DescribeInstances 有对应的请求结构体 DescribeInstancesRequest 和返回结构体 DescribeInstancesResponse 。

下面以云服务器查询实例列表接口为例，介绍 SDK 的基础用法。

简化版

…

详细版

出于演示的目的，有一些非必要的代码，例如对默认配置的修改，以尽量展示 SDK 的功能。在实际编写代码使用 SDK 的时候，建议尽量使用默认配置，酌情修改。

…

更多示例参见 examples 目录。对于复杂接口的 Request 初始化例子，可以参考例一。对于使用json字符串初始化 Request 的例子，可以参考例二。

请求方式

SDK默认使用POST方法。如果您一定要使用GET方法，可以在这里设置。GET方法无法处理一些较大的请求。

cpf.HttpProfile.ReqMethod = "POST"

超时时间

SDK有默认的超时时间，如非必要请不要修改默认设置。如有需要请在代码中查阅以获取最新的默认值。单位：秒

cpf.HttpProfile.ReqTimeout = 30

指定域名

SDK会自动指定域名。通常是不需要特地指定域名的，但是如果您访问的是金融区的服务，则必须手动指定域名，例如云服务器的上海金融区域名： cvm.ap-shanghai-fsi.tencentcloudapi.com

cpf.HttpProfile.Endpoint = "cvm.tencentcloudapi.com"

签名方式

SDK默认用 TC3-HMAC-SHA256 进行签名，它更安全但是会轻微降低性能。

cpf.SignMethod = "HmacSHA1"

DEBUG模式

DEBUG模式会打印更详细的日志，当您需要进行详细的排查错误时可以开启。
默认为 false

cpf.Debug = true

禁用长连接(Keep-alive)

SDK 的每一个 client 默认使用长连接模式，即请求的头部 Connection 字段的值为 keep-alive.

如果您需要使用短连接，可以按照以下方式进行设置：

...
    client, _ := cvm.NewClient(credential, regions.Guangzhou, cpf)
    tp := &http.Transport{
        DisableKeepAlives: true,
    }
    client.WithHttpTransport(tp)
...

则此 client 发出的每个请求头部的 Connection 字段的值为 close

地域容灾

从 v1.0.227开始，腾讯云 GO SDK 支持地域容灾功能：

当请求满足以下条件时：

失败次数 >= 5 次
失败率 >= 75%

SDK 会自动将您请求的地域设置为备选地域。

代理

如果是有代理的环境下，需要设置系统环境变量 https_proxy ，否则可能无法正常调用，抛出连接超时的异常。或者自定义 Transport 指定代理，通过 client.WithHttpTransport 覆盖默认配置。

开启 DNS 缓存

当前 GO SDK 总是会去请求 DNS 服务器，而没有使用到 nscd 的缓存，可以通过导出环境变量GODEBUG=netdns=cgo，或者go build编译时指定参数-tags 'netcgo'控制读取 nscd 缓存。

忽略服务器证书校验

虽然使用 SDK 调用公有云服务时，必须校验服务器证书，以识破他人伪装的服务器，确保请求的安全。但是某些极端情况下，例如测试时，您可能会需要忽略自签名的服务器证书。以下是其中一种可能的方法：

import "crypto/tls"
...
    client, _ := cvm.NewClient(credential, regions.Guangzhou, cpf)
    tr := &http.Transport{
        TLSClientConfig: &tls.Config{InsecureSkipVerify: true},
    }
    client.WithHttpTransport(tr)
...

再次强调，除非您知道自己在做什么，并明白由此带来的风险，否则不要尝试关闭服务器证书校验。

功能介绍

凭证管理

从版本 v1.0.217 开始，腾讯云 GO SDK 支持以下几种方式进行凭证管理：

环境变量

默认读取环境变量 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY 获取 secretId 和 secretKey. 相关代码如下：
go
```
provider := common.DefaultEnvProvider()
credential, err := provider.GetCredential()
```
配置文件

配置文件路径为：
1. 环境变量 TENCENTCLOUD_CREDENTIALS_FILE 所指定的路径
2. Linux or MacOS: ~/.tencentcloud/credentials
3. Windows: c:\Users\NAME\.tencentcloud\credentials
配置文件格式如下：
ini
```
[default]
secret_id = xxxxx
secret_key = xxxxx
```
相关代码如下：
go
```
provider := common.DefaultProfileProvider()
credential, err := provider.GetCredential()
```
角色扮演

有关角色扮演的相关概念请参阅：腾讯云角色概述

要使用此种方式，您必须在腾讯云访问管理控制台上创建了一个角色，具体创建过程请参阅：腾讯云角色创建

在您拥有角色后，可以通过如下方式获取凭证：
go
```
provider := common.DefaultRoleArnProvider(secretId, secretKey, roleArn)
credential, err := provider.GetCredential()
```
实例角色

有关实例角色的相关概念请参阅：腾讯云实例角色

在您为实例绑定角色后，您可以在实例中访问相关元数据接口获取临时凭证。相关代码如下：
go
```
provider := common.DefaultCvmRoleProvider()
credential, err := provider.GetCredential()
```
TKE OIDC凭证

有关 TKE OIDC 凭证的相关示例请参阅：Pod 使用 CAM 对数据库身份验证

示例代码请参考 examples/ssm/v20190923/get_secret_value.go
go
```
provider, err := common.DefaultTkeOIDCRoleArnProvider()
credential, err := provider.GetCredential()
```
凭证提供链

腾讯云 GO SDK 提供了凭证提供链，它会默认以 环境变量->配置文件->实例角色 的顺序尝试获取凭证，并返回第一个获取到的凭证。相关代码如下：
go
```
provider := common.DefaultProviderChain()
credential, err := provider.GetCredential()
```
您也可以自定义自己的凭证提供链，从而改变其调用顺序：
go
```
provider1 := common.DefaultCvmRoleProvider()
provider2 := common.DefaultEnvProvider()
customProviderChain := []common.Provider{provider1, provider2}
provider := common.NewProviderChain(customProviderChain)
credential, err := provider.GetCredential()
```
更详细的使用方式请参考示例：使用ProviderChain

错误处理

从 v1.0.181 开始，腾讯云 GO SDK 会将各个产品的返回的错误码定义为常量，您可以直接调用处理，无需手动定义。如果您使用 IDE (如 Goland )进行开发，可以使用他们的代码提示功能直接选择。例如：

...//Your other go code

// Handling errors
response, err := client.DescribeInstances(request)
if terr, ok := err.(*errors.TencentCloudSDKError); ok {
    code := terr.GetCode()
    if code == cvm.FAILEDOPERATION_ILLEGALTAGKEY{
        fmt.Printf("Handling error: FailedOperation.IllegalTagKey,%s", err)
    }else if code == cvm.UNAUTHORIZEDOPERATION{
        fmt.Printf("Handling error: UnauthorizedOperation,%s", err)
    }else{
        fmt.Printf("An API error has returned: %s", err)
    }
    return
}
...

同时，各个接口函数的注释部分也列出了此接口可能会返回的错误码，方便您进行处理：

…

Common Client

从 v1.0.189开始，腾讯云 GO SDK 支持使用 泛用型的API调用方式(Common Client) 进行请求。您只需安装 common 包, 即可向任何产品发起调用。

注意，您必须明确知道您调用接口的参数内容，否则会调用失败。

目前仅支持使用 POST 方式发送请求，且签名方法必须使用签名方法 v3。

详细使用请参阅示例：使用 Common Client 进行调用

自定义 Header

RunInstancesRequest示例

    request := cvm.NewRunInstancesRequest()
	request.SetHeader(map[string]string{
        "X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca",
    })

CommonRequest示例

    request := tchttp.NewCommonRequest("cvm", "2017-03-12", "DescribeZones")
    request.SetHeader(map[string]string{
        "X-TC-TraceId": "ffe0c072-8a5d-4e17-8887-a8a60252abca",
    })

http 代理

DescribeInstances示例

    // with authentication
    clientProfile.HttpProfile.Proxy = "http://username:[email protected]:1080"
    // without authentication
    clientProfile.HttpProfile.Proxy = "http://127.0.0.1:1080"

请求重试

网络错误重试

当发生临时网络错误或超时时，SDK可以被配置为自动重试。默认不开启。通过 ClientProfile 配置重试次数和重试间隔时间。

通过反射检查 Request 结构体是否存在 ClientToken 字段，存在该字段则认为是幂等请求。幂等请求才会在网络错误时自动重试，非幂等请求会抛出异常，防止请求多次重放造成结果不一致。

…

更多用法参考测试文件

限频重试

当发生API限频时，SDK可以被配置为自动重试。默认不开启。通过 ClientProfile 配置重试次数和重试间隔时间。

…

幂等标识符

当网络超时重试或限频重试开启时，会自动向请求中注入 ClientToken 参数（如果请求存在ClientToken字段且为空）。当用户手动指定 ClientToken 时，会跳过注入流程。

注入的 ClientToken 在 100000/s 并发量以下提供全局唯一性。

空数组和omitempty

在 v1.0.738 以及之前的版本, SDK使用omitempty标签来序列化请求, 这会导致 nil 数组和长度为0的空数组都无法被序列化。这在您希望发送一个空数组的时候会造成不便, 在之前您需要使用 CommonClient 来解决这个问题。

在 >= v1.0.739 的版本, SDK使用omitnil标签来序列化请求, 此时nil数组会被忽略掉, 但是空数组可以被正常发送。

在 >= v1.0.885 版本中我们对这一特性增加了开关, 当你不希望发送一个空数组时, 可以通过 json.OmitBehaviour = json.OmitEmpty 来关闭该特性, 参考示例

EOF 报错

若您遇到错误 Code=ClientError.NetworkError, Message=Fail to get response because Post "https://xxx.tencentcloudapi.com/": EOF, 可能与长连接有关。SDK 默认使用 HTTP POST 且开启了长连接，服务器对长连接启用了空闲超时等相关设置, 满足条件服务器会主动在当前请求完成后关闭连接。但有可能服务器 TCP FIN 包尚未到达客户端, 客户端仍尝试在已被关闭的连接上发送请求，此时将导致服务器返回 TCP RST 包。通常客户端自动重试请求即可解决，但 Golang net/http 库认为 POST 请求非幂等不会重试，从而导致该错误。解决办法有如下几种：

如果请求包都很小，不需要通过 POST 发送大请求包，可以将 SDK 默认 HTTP 方法改为 GET ；
启用 ClientProfile.UnsafeRetryOnConnectionFailure, 在连接关闭时自动重试，请确保请求具备幂等性（如只读接口），避免因重试导致非预期的行为；

如果要修改 SDK 的 HTTP 客户端相关参数，例如空闲 HTTP 长连接的 keep-alive 时间，可以参考示例

支持产品列表

参见产品列表文档

Issues· 0 开放

查看全部 Issues 在 GitHub 打开

暂无开放 Issues，或尚未同步最近议题。

> 标签

暂无评论，来聊聊你的看法吧

> 工具信息

发布日期2026年8月1日

最后更新2026年9月17日

分类编程语言

定价开源

> 相关工具

TypeScript

JavaScript 的超集，为前端与全栈提供静态类型

Python

通用编程语言，广泛用于 Web、数据与 AI

Google 推出的简洁高效系统语言

tencentcloud-sdk-go

工具介绍

目录

简介

获取安装

依赖环境

通过go get安装（推荐）

按需安装（推荐）

安装指定产品 SDK（推荐）

注意事项

通过源码安装

快速开始

简化版

详细版

相关配置

请求方式

超时时间

指定域名

签名方式

DEBUG模式

禁用长连接(Keep-alive)

地域容灾

代理

开启 DNS 缓存

忽略服务器证书校验

功能介绍

凭证管理

错误处理

Common Client

自定义 Header

http 代理

请求重试

网络错误重试

限频重试

幂等标识符

空数组和omitempty

EOF 报错

支持产品列表

Issues· 0 开放

> 标签

> 讨论区

> 工具信息

> 相关工具