初始化客户端（Go SDK）--对象存储-火山引擎

文档中心

对象存储

初始化客户端（Go SDK）

本文介绍初始化客户端的示例代码及常见配置场景。

前提条件

配置长期访问凭证

初始化 SDK 前，您需要先配置长期访问凭证。本章节介绍不同操作系统下配置长期访问凭证的操作步骤。

macOS

Linux

Windows

打开终端并执行以下命令打开文件。

nano ~/.bash_profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source ~/.bash_profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

打开终端并执行以下命令打开文件。

sudo vim /etc/profile

在文件末尾添加 AKSK 信息。

export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****

保存文件并退出。
执行以下命令生效配置信息。

source /etc/profile

执行以下命令验证配置信息。

echo $TOS_ACCESS_KEY
echo $TOS_SECRET_KEY

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

打开命令行工具，执行以下命令，添加 AKSK 信息。

set TOS_ACCESS_KEY=AKTPYmI1Z****
set TOS_SECRET_KEY=T1dJM01UU****

执行以下命令生效配置信息。

setx TOS_ACCESS_KEY "%TOS_ACCESS_KEY%"
setx TOS_SECRET_KEY "%TOS_SECRET_KEY%"

重启命令行工具，然后执行以下命令验证配置信息。

echo %TOS_ACCESS_KEY%
echo %TOS_SECRET_KEY%

如果配置成功，则返回如下示例：

AKTPYmI1Z****
T1dJM01UU****

创建 TosClient

初始化 TOSClient 实例之后，可以向 TOS 服务发送 HTTP/HTTPS 请求。
TOSClient 提供了一系列接口用来与 TOS 服务进行交互，以管理存储桶和对象等 TOS 服务上的资源。初始化 TOSClient 时，需要带上 AccessKey、SecretKey、Endpoint 和 Region。

说明

Endpoint 为 TOS 对外服务的访问域名。TOS 支持的 Endpoint 信息，请参见访问域名 Endpoint。
AKSK 信息可从环境变量获取，配置方式，请参见配置访问凭证。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      // endpoint 若没有指定 HTTP 协议（HTTP/HTTPS），默认使用 HTTPS
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }
   // 使用结束后，关闭 client
   client.Close()
}

通过 Option 设置 Client 可选参数
在 Client 初始化时，可以通过调用返回为 ClientOption 的函数设置 Client 可选参数满足业务场景的需求。
以下示例通过 WithConnectionTimeout 和 WithSocketTimeout ，设置建立连接超时时间和读写超时时间。

package main

import (
   "fmt"
   "os"
   "time"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      // endpoint 若没有指定 HTTP 协议（HTTP/HTTPS），默认使用 HTTPS
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 可以通过 tos.WithXXX 的方式添加可选参数
   // 示例中通过 WithConnectionTimeout 设置建立连接超时时间
   // 通过 WithSocketTimeout 设置一次读写连接超时时间
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithConnectionTimeout(10*time.Second), tos.WithSocketTimeout(30*time.Second, 30*time.Second))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }

   // 使用结束后，关闭 client
   client.Close()
}

常见配置场景

配置 STS

如果您不希望透露长期使用的密钥信息，您可以通过 STS 服务创建一个临时访问凭证，使用户能在凭证有效期内访问 TOS 资源，过期即失效，有效保证您的资源安全。

说明

您可以通过 STS 服务的 AssumeRole 接口获取临时访问凭证，临时访问凭证中包含安全密钥（AccessKeyId、SecretAccessKey）和安全令牌（SessionToken），后续您可以使用该信息访问 TOS 服务。关于搭建 STS 服务的基本操作，请参见使用 STS 临时 AK/SK+Token 访问火山引擎 TOS。

在获取到 STS Token 后，您可以通过以下示例代码初始化 TOS SDK。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = "*** Provide your access key ***"
      sk       = "*** Provide your secret key ***"
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
      stsToken = "*** Provide your sts token ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 初始化 Client 时使用 STS Token 
   credential.WithSecurityToken(stsToken)
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }
   client.Close()
}

配置超时机制

在 SDK 中可以通过可选参数调整超时时间，可以通过下列参数对超时进行配置：

WithConnectionTimeout
通过 WithConnectionTimeout 可以设置连接超时，表示在建立连接阶段最长等待时间，SDK 默认超时时间为 10s。
WithSocketTimeout
通过 WithSocketTimeout 可以设置读写网络流的超时，表示一次 Read/Write 最长等待时间，SDK 默认超时时间为 30s。

SDK 中 ConnectionTimeout 默认配置为 10s， SocketTimeout 中 Read/Write 默认时间为 30s。

package main

import (
   "fmt"
   "os"
   "time"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      // endpoint 若没有指定 HTTP 协议（HTTP/HTTPS），默认使用 HTTPS
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 通过 WithConnectionTimeout，设置建立连接超时时间
   // 通过 WithSocketTimeout，设置一次读写连接超时时间
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithConnectionTimeout(10*time.Second), tos.WithSocketTimeout(30*time.Second, 30*time.Second))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }

   // 使用结束后，关闭 client
   client.Close()
}

配置重试策略

在 TOS SDK 通过初始化参数 WithMaxRetryCount 配置请求失败后的重试次数，以解决网络抖动等问题造成的请求失败，降低再遭遇偶限错误的概率。由于部分场景重试仍然会失败，甚至造成不可预期的结果。重试只在请求超时、服务端返回 5XX 错误或 429 错误时可实现幂等语义的场景下进行重试，TOS SDK 的重试策略如下：

所有的 GET/HEAD 类型的 HTTP 接口，例如 GetObjectV2、HeadObject。
部分 PUT/DELETE 类型的 HTTP 接口，例如 PutObjectACL、DeleteObjectV2。
PutObjectV2/UploadPartV2 接口在请求体（Content 字段）可以进行 Reset 的情况下可作为幂等语义。

TOS 重试时会以 100ms 为基础进行指数退避直到到达最大重试次数，例如，最大重试次数是 3 次时，重试间隔分别为 100ms、200ms 及 400ms。
SDK 默认实现中重试次数为 0 次，表示不会进行重试。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 可以通过 tos.WithRetry 的方式添加重试次数
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithMaxRetryCount(3))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }

   // 使用结束后，关闭 client
   client.Close()
}

配置数据校验

TOS SDK 在上传/下载对象时默认开启 CRC 数据校验，确保数据传输过程中的完整性。

警告

强烈建议您不要关闭 CRC 数据校验功能。若关闭此功能，TOS 不保障上传和下载过程中数据完整性。

您可以使用以下代码，开启 CRC 数据校验。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 可以通过 tos.WithEnableCRC 开启 CRC 校验，SDK 默认实现是 True
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithEnableCRC(true))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }
   // 使用结束后，关闭 client
   client.Close()
}

配置 DNS 缓存

在公网环境中，有可能出现域名解析较为耗时或出现一段时间内无法解析的情况，TOS SDK通过设置 WithDNSCacheTime，提供域名缓存的有效期，默认值为 0 ，代表关闭域名缓存特性。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 可以通过 tos.WithDNSCacheTime 开启 DNS 缓存时间
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithDNSCacheTime(60))
   if err != nil {
      fmt.Println("Error:", err)
      panic(err)
   }
   // 使用结束后，关闭 client
   client.Close()
}

配置代理服务器

TOS Go SDK 支持设置 HTTP 协议代理服务，通过 NewProxy 新建 HTTP 代理，如果是需要账号密码的方式，可以通过 Proxy 的 WithAuth 的方式进行设置账户和密码，获取到 Proxy 后可以通过 WithProxy 设置。

说明

目前只支持 HTTP 协议代理。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func checkErr(err error) {
   if err != nil {
      if serverErr, ok := err.(*tos.TosServerError); ok {
         fmt.Println("Error:", serverErr.Error())
         fmt.Println("Request ID:", serverErr.RequestID)
         fmt.Println("Response Status Code:", serverErr.StatusCode)
         fmt.Println("Response Header:", serverErr.Header)
         fmt.Println("Response Err Code:", serverErr.Code)
         fmt.Println("Response Err Msg:", serverErr.Message)
      } else if clientErr, ok := err.(*tos.TosClientError); ok {
         fmt.Println("Error:", clientErr.Error())
         fmt.Println("Client Cause Err:", clientErr.Cause.Error())
      } else {
         fmt.Println("Error:", err)
      }
      panic(err)
   }
}

func main() {
   var (
      ak        = os.Getenv("TOS_ACCESS_KEY")
      sk        = os.Getenv("TOS_SECRET_KEY")
      endpoint  = "*** Provide your endpoint ***"
      region    = "*** Provide your region ***"
      proxyHost = "*** Provide your proxy host ***"
      proxyPort = 8080 /* Provide your proxy port */
   )
   proxy, err := tos.NewProxy(proxyHost, proxyPort)
   checkErr(err)
   credential := tos.NewStaticCredentials(ak, sk)
   // 可以通过 tos.WithProxy 的方式添加请求代理
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), tos.WithProxy(proxy))
   checkErr(err)
   // 使用结束后，关闭 client
   client.Close()
}

配置连接池

TOS Go SDK 支持连接池配置，您可以在初始化 TosClient 时，添加可选参数配置连接池大小。连接池配置的参数说明如下。

参数	说明	默认值
MaxIdleConns	设置空闲连接池大小。	1024
MaxIdleConnsPerHost	设置单个 Host 在空闲连接池的缓存数量。	1024
MaxConnsPerHost	设置单个 Host 最多可用连接数量。	1024

在 SDK 中，可以通过 WithMaxConnections 设置连接池参数。

package main

import (
   "fmt"
   "os"

   "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
   var (
      ak       = os.Getenv("TOS_ACCESS_KEY")
      sk       = os.Getenv("TOS_SECRET_KEY")
      endpoint = "*** Provide your endpoint ***"
      region   = "*** Provide your region ***"
   )
   credential := tos.NewStaticCredentials(ak, sk)
   // 设置连接池参数
   op := tos.WithMaxConnections(1024)
   client, err := tos.NewClientV2(endpoint, tos.WithCredentials(credential), tos.WithRegion(region), op)
   if err != nil {
      fmt.Println("Error:", err)
      os.Exit(-1)
   }
   // 使用结束后，关闭 client
   client.Close()
}

说明

WithMaxConnections 会默认将三个参数设置为相同参数，如需单独配置，您可以通过 Transport 设置。

设置自定义域名

TOS Go SDK 支持设置自定义域名，您可以在初始化 TosClient 时，传入自定义域名作为 Host。指定自定义域名后，使用 SDK 接口中无需传入 Bucket 。

说明

使用自定义域名前需要在服务端配置自定义域名，详情请参见设置自定义域名。

在 SDK 中，可以通过 WithCustomDomain 标识当前域名为自定义域名。

package main

import (
    "fmt"
    "os"

    "github.com/volcengine/ve-tos-golang-sdk/v2/tos"
)

func main() {
    var (
       ak           = os.Getenv("TOS_ACCESS_KEY")
       sk           = os.Getenv("TOS_SECRET_KEY")
       customDomain = "*** Provide your custom domain ***"
       region       = "*** Provide your region ***"
    )
    credential := tos.NewStaticCredentials(ak, sk)
    // 标识当前域名为自定义域名
    // 使用自定义域名前，需要在 TOS 上完成配置
    // 详情：https://www.volcengine.com/docs/6349/128983
    op := tos.WithCustomDomain(true)
    client, err := tos.NewClientV2(customDomain, tos.WithCredentials(credential), tos.WithRegion(region), op)
    if err != nil {
       fmt.Println("Error:", err)
       os.Exit(-1)
    }
    // 使用结束后，关闭 client
    client.Close()
}

初始化参数列表

初始化TosClient支持参数如下。

参数	参数类型	是否必选	示例值	说明
AccessKeyID	string	必选	AKTPYmI1ZGQwMDA0NjlhNGFkMzhjNzM0N2Q0OTQ3ZTV****	Access Key ID，即密钥 ID。
AccessKeySecret	string	必选	T1dJM01UUXpOak0wTVdWak5EUmtOR0poWldJNU1HWmxaV1V5TkdReVl6****	SecretAccess Key，即私有访问密钥。
Endpoint	string	必选	tos-cn-beijing.volces.com	访问域名。
Region	string	必选	cn-beijing	TOS 服务端所在地域。
SecurityToken	string	可选	STSeyJBY2NvdW50SWQiOjIxMDAwMDUyMjQsIklkZW50aXR5VHlwZSI6NCwiSWRlbnRpdHlJZCI6MTE3MjI5NiwiQ2hhbm5lbCI6IlVzZXIiLCJBY2Nlc3NLZXlJZCI6IkFLVFBZbUkxWkdRd01EQTBOamxoTkdGa016aGpOek0wTjJRME9UUTNaVFZqTXpFIiwiU2l************	临时访问凭证中的安全令牌。
EnableVerifySSL	bool	可选	True	配置是否开启 SSL 证书校验，默认值为 False。
Transport	struct	可选	参考 DefaultTransportConfig 的配置	设置自定义 Transport，默认值详见 tos.DefaultTransportConfig()。
AutoRecognizeContentType	bool	可选	True	自动识别 MIME 类型，默认开启。
SocketTimeout	time.Duration	可选	30*time.Second	Socket 读写超时时间，默认值为 30s。
ConnectionTimeout	time.Duration	可选	10*time.Second	设置建立连接超时时间，默认值为 10s。
MaxConnections	int	可选	1024	设置最大连接数量，默认值为 1024。
IdleConnTimeout	time.Duration	可选	60*time.Second	设置最大连接空闲时间，若超过该时间，连接将被关闭。SDK 默认值为 60s。
Logger	struct	可选	logrus.New()	设置自定义 Logger，默认不打印日志。
MaxRetryCount	int	可选	5	设置最大重试次数，默认值为 0 次。
EnableCRC	bool	可选	True	设置开启 CRC 校验，默认值为 True。
DNSCacheTime	int	可选	30	设置域名缓存时间，时间单位为分钟。默认值为 0min，不开启域名缓存。
Proxy	struct	可选		设置 HTTP 正向代理。默认值为空，不使用连接代理。
IsCustomDomain	bool	可选	False	是否将桶名拼接到 Endpoint 前，通过虚拟主机域名的方式访问 TOS，取值说明如下： `true`：不拼接。 `false`：拼接。默认值为 false。说明通过自定义域名访问 TOS 时，需要设置 `isCustomDomain` 为 `true`。

最近更新时间：2025.05.30 15:02:12

这个页面对您有帮助吗？

有用

无用

对象存储

前提条件 #

配置长期访问凭证 #

创建 TosClient #

常见配置场景 #

配置 STS #

配置超时机制 #

配置重试策略 #

配置数据校验 #

配置 DNS 缓存 #

配置代理服务器 #

配置连接池 #

设置自定义域名 #

初始化参数列表 #

前提条件

配置长期访问凭证

创建 TosClient

常见配置场景

配置 STS

配置超时机制

配置重试策略

配置数据校验

配置 DNS 缓存

配置代理服务器

配置连接池

设置自定义域名

初始化参数列表