You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /
  • 对象存储

初始化客户端（Go SDK）

最近更新时间：2024.02.04 18:30:55

首次发布时间：2021.12.31 17:38:36

我的收藏

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

前提条件

配置长期访问凭证

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

  1. 打开终端并执行以下命令打开文件。
nano ~/.bash_profile
  1. 在文件末尾添加 AKSK 信息。
export TOS_ACCESS_KEY=AKTPYmI1Z****
export TOS_SECRET_KEY=T1dJM01UU****
  1. 保存文件并退出。
  2. 执行以下命令生效配置信息。
source ~/.bash_profile
  1. 执行以下命令验证配置信息。
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

是否为自定义域名。