OSS Go SDK V2 - 对象存储 OSS

Github | OSS Go SDK V2开发者指南｜OSS SDK for Go API

快速接入

接入OSS Go SDK V2的流程如下：

环境准备

要求 Go 1.18 及以上版本。

可以通过 go -version 命令查看 Go 版本。如果当前环境没有 Go 或版本低于 Go 1.18，请安装Golang。

安装SDK

创建项目目录并初始化Go模块。

mkdir oss-go-example && cd oss-go-example && go mod init oss-go-example

执行以下命令获取远程代码包。请根据需求选择合适的OSS Go SDK V2版本，推荐使用最新的版本，确保本文中的代码示例可以正常运行。
```
go get github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss
```

使用以下代码引入OSS Go SDK V2包。

import "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"

配置访问凭证

使用 RAM 用户的 AccessKey 配置访问凭证。

在 RAM 控制台，创建使用永久 AccessKey 访问的 RAM 用户，保存 AccessKey，然后为该用户授予 AliyunOSSFullAccess 权限。

使用 RAM 用户 AccessKey 配置环境变量。

Linux

在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

执行以下命令使变更生效。
```
source ~/.bashrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

macOS

在终端中执行以下命令，查看默认Shell类型。

echo $SHELL

根据默认Shell类型进行操作。

Zsh

执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

执行以下命令使变更生效。
```
source ~/.zshrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Bash

执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

执行以下命令使变更生效。
```
source ~/.bash_profile
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

在CMD中运行以下命令。

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

运行以下命令，检查环境变量是否生效。
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

在PowerShell中运行以下命令。

[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

运行以下命令，检查环境变量是否生效。

[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

初始化客户端

使用地域和访问域名初始化 OSSClient，并运行测试代码。

package main

import (
	"context"
	"log"
	"strings"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

/*
Go SDK V2 客户端初始化配置说明：

1. 签名版本：Go SDK V2 默认使用 V4 签名，提供更高的安全性
2. Region配置：初始化 Client 时，您需要指定阿里云通用 Region ID 作为发起请求地域的标识
   本示例代码使用华东1（杭州）Region ID：cn-hangzhou
   如需查询其它 Region ID 请参见：OSS地域和访问域名
3. Endpoint配置：
   - 可以通过 Endpoint 参数，自定义服务请求的访问域名
   - 当不指定时，SDK 默认根据 Region 信息，构造公网访问域名
   - 例如当 Region 为 'cn-hangzhou' 时，构造出来的访问域名为：'https://oss-cn-hangzhou.aliyuncs.com'
4. 协议配置：
   - SDK 构造访问域名时默认采用 HTTPS 协议
   - 如需采用 HTTP 协议，请在指定域名时指定为 HTTP，例如：'http://oss-cn-hangzhou.aliyuncs.com'
*/

func main() {
	// 方式一：只填写Region（推荐）
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou") // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou，SDK会根据Region自动构造HTTPS访问域名

	// 方式二：同时填写Region和Endpoint
	// cfg := oss.LoadDefaultConfig().
	//     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	//     WithRegion("cn-hangzhou").                                // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	//     WithEndpoint("https://oss-cn-hangzhou.aliyuncs.com")     // 填写Bucket所在地域对应的公网Endpoint。以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou.aliyuncs.com'

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	// 定义要上传的字符串内容
	body := strings.NewReader("hi oss")

	// 创建上传对象的请求
	request := &oss.PutObjectRequest{
		Bucket: oss.Ptr("Your Bucket Name"),      // 存储空间名称
		Key:    oss.Ptr("Your Object Key"),       // 对象名称
		Body:   body,                             // 要上传的字符串内容
	}

	// 发送上传对象的请求
	result, err := client.PutObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put object %v", err)
	}

	// 打印上传对象的结果
	log.Printf("Status: %#v\n", result.Status)
	log.Printf("RequestId: %#v\n", result.ResultCommon.Headers.Get("X-Oss-Request-Id"))
	log.Printf("ETag: %#v\n", *result.ETag)
}

运行后将会输出上传文件成功的结果：

Status: "200 OK"
RequestId: "68746C5FE001B434303B90B6"
ETag: "B22E0DC370A7F7067FACF5F75D7FA385"

客户端配置

客户端支持哪些配置？

Region	（必选）请求发送的区域, 必选	WithRegion("cn-hangzhou")
CredentialsProvider	（必选）设置访问凭证	WithCredentialsProvider(provider)
Endpoint	访问域名	WithEndpoint("oss-cn-hanghzou.aliyuncs.com")
HttpClient	HTTP客户端	WithHttpClient(customClient)
RetryMaxAttempts	HTTP请求时的最大尝试次数, 默认值为 3	WithRetryMaxAttempts(5)
Retryer	HTTP请求时的重试实现	WithRetryer(customRetryer)
ConnectTimeout	建立连接的超时时间, 默认值为 5 秒	WithConnectTimeout(10 * time.Second)
ReadWriteTimeout	应用读写数据的超时时间, 默认值为 10 秒	WithReadWriteTimeout(30 * time.Second)
InsecureSkipVerify	是否跳过SSL证书校验，默认检查SSL证书	WithInsecureSkipVerify(true)
EnabledRedirect	是否开启HTTP重定向, 默认不开启	WithEnabledRedirect(true)
ProxyHost	设置代理服务器	WithProxyHost("http://user:passswd@proxy.example-***.com")
ProxyFromEnvironment	通过环境变量设置代理服务器	WithProxyFromEnvironment(true)
UploadBandwidthlimit	整体的上传带宽限制，单位为 KiB/s	WithUploadBandwidthlimit(10*1024)
DownloadBandwidthlimit	整体的下载带宽限制，单位为 KiB/s	WithDownloadBandwidthlimit(10*1024)
SignatureVersion	签名版本，默认值为v4	WithSignatureVersion(oss.SignatureVersionV1)
LogLevel	设置日志级别	WithLogLevel(oss.LogInfo)
LogPrinter	设置日志打印接口	WithLogPrinter(customPrinter)
DisableSSL	不使用https请求，默认使用https	WithDisableSSL(true)
UsePathStyle	使用路径请求风格，即二级域名请求风格，默认为bucket托管域名	WithUsePathStyle(true)
UseCName	是否使用自定义域名访问，默认不使用	WithUseCName(true)
UseDualStackEndpoint	是否使用双栈域名访问，默认不使用	WithUseDualStackEndpoint(true)
UseAccelerateEndpoint	是否使用传输加速域名访问，默认不使用	WithUseAccelerateEndpoint(true)
UseInternalEndpoint	是否使用内网域名访问，默认不使用	WithUseInternalEndpoint(true)
DisableUploadCRC64Check	上传时关闭CRC64校验，默认开启CRC64校验	WithDisableUploadCRC64Check(true)
DisableDownloadCRC64Check	下载时关闭CRC64校验，默认开启CRC64校验	WithDisableDownloadCRC64Check(true)
AdditionalHeaders	指定额外的签名请求头，V4签名下有效	WithAdditionalHeaders([]string{"content-length"})
UserAgent	指定额外的User-Agent信息	WithUserAgent("user identifier")

使用自定义域名

使用OSS默认域名访问时，可能会出现文件禁止访问、文件无法预览等问题；通过绑定自定义域名至Bucket默认域名，不仅支持浏览器直接预览文件，还可结合CDN加速分发。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 请填写您的自定义域名，例如https://www.example-***.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://www.example-***.com").
		WithUseCName(true) // 请注意，设置true开启CNAME选项，否则无法使用自定义域名

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

超时控制

package main

import (
	"time"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").             // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
		WithConnectTimeout(10 * time.Second).  // 设置连接超时时间，默认值为5秒
		WithReadWriteTimeout(30 * time.Second) // 设置读写超时时间，默认值为10秒

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

最大错误重试次数

请求异常时，OSSClient 默认重试 3 次。

高并发或网络不稳定时，使用 WithRetryMaxAttempts 增加重试次数。这能提升请求成功率。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou"). // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
		WithRetryMaxAttempts(5)    // 设置最大重试次数，默认值为3

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

HTTP/HTTPS 协议

使用 WithDisableSSL(true) 设置不使用HTTPS协议。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou"). // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
		WithDisableSSL(true)       // 设置不使用HTTPS协议。默认使用HTTPS

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	// 使用client执行后续操作...
}

代理服务器

企业安全策略通常限制直接访问公网。使用 WithProxyHost 配置代理服务器访问 OSS。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").                                 // 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
		WithUserAgent("aliyun-sdk-go").                            // 设置用户代理，指HTTP的User-Agent头
		WithProxyHost("http://user:passswd@proxy.example-***.com") // 设置代理服务器IP，如"http://user:passswd@proxy.example-***.com"）

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

使用内网域名

当您的应用部署在阿里云的ECS实例上，并且需要频繁访问同地域的OSS资源时，使用内网域名可以降低流量成本并提高访问速度。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() 
	// 方式一：填写Region并设置WithUseInternalEndpoint为true
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseInternalEndpoint(true)

	// 方式二：直接填写Region和Endpoint
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 填写Bucket所在地域对应的内网Endpoint，以华东1（杭州）为例，Endpoint填写为'https://oss-cn-hangzhou-internal.aliyuncs.com'。如需指定为http协议，请在指定域名时填写为'http://oss-cn-hangzhou-internal.aliyuncs.com'
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-cn-hangzhou-internal.aliyuncs.com")

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	// 使用client执行后续操作...

}

使用传输加速域名

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 方式一：填写Region并设置WithUseAccelerateEndpoint为true
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseAccelerateEndpoint(true)

	// 方式二：直接填写Region和Endpoint
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 填写Bucket所在地域对应的传输加速Endpoint，以华东1（杭州）为例，Endpoint填写为'https://oss-accelerate.aliyuncs.com'。如需指定为http协议，请在指定域名时填写为'http://oss-accelerate.aliyuncs.com'
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-accelerate.aliyuncs.com").

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

使用专有域

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 请填写您的专有域，例如：https://service.corp.example.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://service.corp.example.com")

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

使用金融云域名

以下是使用金融云域名配置OSSClient的示例代码。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 填写Region和Endpoint
        // 填写Bucket所在地域。以华东1 金融云为例，Region填写为cn-hangzhou-finance
	// 填写Bucket所在地域对应的内网Endpoint。以华东1 金融云为例，Endpoint填写为'https://oss-cn-hzjbp-a-internal.aliyuncs.com',
        // 如需指定为http协议，请在指定域名时填写为'http://oss-cn-hzjbp-a-internal.aliyuncs.com'
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou-finance").
		WithEndpoint("https://oss-cn-hzjbp-a-internal.aliyuncs.com")

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

使用政务云域名

以下是使用政务云域名配置OSSClient的示例代码。

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 填写Region和Endpoint
        // 填写Bucket所在地域。以华北2 阿里政务云1为例，Region填写为cn-north-2-gov-1
	// 填写Bucket所在地域对应的内网Endpoint。以华北2 阿里政务云1为例，Endpoint填写为'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
        // 如需指定为http协议，请在指定域名时填写为'http://oss-cn-north-2-gov-1-internal.aliyuncs.com'
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-north-2-gov-1").
		WithEndpoint("https://oss-cn-north-2-gov-1-internal.aliyuncs.com")

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

访问云盒Bucket

package main

import (
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 方式一：自动检测云盒ID
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 填写Endpoint为云盒bucket的数据域名，例如：http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// 设置WithEnableAutoDetectCloudBoxId为true，自动检测云盒ID
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
		WithEnableAutoDetectCloudBoxId(true)

	// 方式二：手动设置云盒ID
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	// 填写Endpoint为云盒bucket的数据域名，例如：http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// 手动填写云盒ID，例如：cb-xxxxxx
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
	// 	WithCloudBoxId("cb-xxxxxx")

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client执行后续操作...
}

自定义HTTPClient

当常用配置参数无法满足场景需求时，使用WithHTTPClient替换默认的HTTP客户端。

package main

import (
	"crypto/tls"
	"net/http"
	"time"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/transport"
)

func main() {
	// 常用超时或其它设置
	transConfig := transport.Config{
		// 连接超时, 默认值 5秒
		ConnectTimeout: oss.Ptr(10 * time.Second),
		// 应用读写数据的超时时间, 默认值 10秒
		ReadWriteTimeout: oss.Ptr(20 * time.Second),
		// 连接空闲超时时间, 默认值 50 秒
		IdleConnectionTimeout: oss.Ptr(40 * time.Second),
		// 网络连接的保持期限, 默认值 30 秒
		KeepAliveTimeout: oss.Ptr(40 * time.Second),
		// 是否打开启HTTP重定向，默认不启用
		EnabledRedirect: oss.Ptr(true),
	}

	// http.Transport 设置
	var transports []func(*http.Transport)
	// 最大连接数，默认值 100
	transports = append(transports, transport.MaxConnections(200))
	// 如果请求有“Expect: 100-Continue”标头，则此设置表示完全写入请求标头后等待服务器第一个响应标头的最长时间，默认 1秒
	transports = append(transports, transport.ExpectContinueTimeout(2*time.Second))
	// TLS的最低版本，默认值 TLS 1.2
	transports = append(transports, transport.TLSMinVersion(tls.VersionTLS13))
	// 是否跳过证书检查，默认不跳过
	transports = append(transports, transport.InsecureSkipVerify(true))
	// 更多Transport参数设置，请参考 https://pkg.go.dev/net/http#Transport
	// 创建自定义HTTP Client
	customClient := transport.NewHttpClient(&transConfig, transports...)

	cfg := oss.LoadDefaultConfig().
		WithHttpClient(customClient).
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	// 使用client进行后续操作...
}

访问凭证配置

OSS 提供多种凭证初始化方式。请根据您的认证和授权需求选择合适的初始化方式。

如何选择访问凭证？

凭证提供者初始化方式	适用场景	是否需要提供前置的AK或STS Token	底层实现基于的凭证	凭证有效期	凭证轮转或刷新方式
使用RAM用户的AK	部署运行在安全、稳定且不易受外部攻击的环境的应用程序，无需频繁轮转凭证就可以长期访问云服务	是	AK	长期	手动轮转
使用STS临时访问凭证	部署运行在不可信的环境的应用程序，希望能控制访问的有效期、权限	是	STS Token	临时	手动刷新
使用RAMRoleARN	需要授权访问云服务，例如跨阿里云账号访问云服务的应用程序	是	STS Token	临时	自动刷新
使用ECSRAMRole	部署运行在阿里云的ECS实例、ECI实例、容器服务Kubernetes版的Worker节点中的应用程序	否	STS Token	临时	自动刷新
使用OIDCRoleARN	部署运行在阿里云的容器服务Kubernetes版的Worker节点中的不可信应用程序	否	STS Token	临时	自动刷新
自定义凭证提供者	如果以上凭证配置方式都不满足要求时，您可以自定义获取凭证的方式	自定义	自定义	自定义	自定义
使用默认凭据链	当您初始化凭据客户端，且不传入任何参数时，将会尝试按照默认凭据链顺序查找相关凭据信息	自定义	自定义	自定义	自定义

使用RAM用户的AK

如果您的应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问您的OSS，且不能频繁轮转凭证时，您可以使用阿里云主账号或RAM用户的AK（Access Key ID、Access Key Secret）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个AK，存在安全性风险和维护复杂度增加的风险。

警告

阿里云账号拥有资源的全部权限，AK一旦泄露，会给系统带来巨大风险，不建议使用。推荐使用最小化授权的RAM用户的AK。
如需创建RAM用户的AK，请直接访问创建AccessKey。RAM用户的Access Key ID、Access Key Secret信息仅在创建时显示，请及时保存，如若遗忘请考虑创建新的AK进行轮换。

环境变量

使用RAM用户AccessKey配置环境变量。

Linux

在命令行界面执行以下命令来将环境变量设置追加到~/.bashrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

执行以下命令使变更生效。
```
source ~/.bashrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

macOS

在终端中执行以下命令，查看默认Shell类型。

echo $SHELL

根据默认Shell类型进行操作。

Zsh

执行以下命令来将环境变量设置追加到 ~/.zshrc 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

执行以下命令使变更生效。
```
source ~/.zshrc
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Bash

执行以下命令来将环境变量设置追加到 ~/.bash_profile 文件中。

echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

执行以下命令使变更生效。
```
source ~/.bash_profile
```

执行以下命令检查环境变量是否生效。

echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

Windows

CMD

在CMD中运行以下命令。

setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

运行以下命令，检查环境变量是否生效。
```
echo %OSS_ACCESS_KEY_ID%
echo %OSS_ACCESS_KEY_SECRET%
```

PowerShell

在PowerShell中运行以下命令。

[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

运行以下命令，检查环境变量是否生效。

[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
[Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

参考上述方式修改系统环境变量后，请重启或刷新您的编译运行环境，包括IDE、命令行界面、其他桌面应用程序及后台服务，以确保最新的系统环境变量成功加载。

使用环境变量来传递凭证信息。

package main

import (
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET
	provider := credentials.NewEnvironmentVariableCredentialsProvider()

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

静态凭证

以下示例代码展示了如何对访问凭据直接进行硬编码，显式设置要使用的访问密钥。

警告

请勿将访问凭据嵌入到生产环境的应用程序中，此方法仅用于测试目的。

package main

import (
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 填写RAM用户的Access Key ID和Access Key Secret
	accessKeyID := "yourAccessKeyID"
	accessKeySecret := "yourAccessKeySecret"

	// 使用NewStaticCredentialsProvider方法直接设置AK和SK
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret)

	// 加载默认配置并设置凭证提供者和区域
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

使用STS临时访问凭证

如果您的应用程序需要临时访问OSS，您可以使用通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token）初始化凭证提供者。需要注意的是，该方式需要您手动维护一个STS Token，存在安全性风险和维护复杂度增加的风险。此外，如果您需要多次临时访问OSS，您需要手动刷新STS Token。

重要

如果您希望通过OpenAPI的方式简单快速获取到STS临时访问凭证，请参见AssumeRole - 获取扮演角色的临时身份凭证。
如果您希望通过SDK的方式获取STS临时访问凭证，请参见使用STS临时访问凭证访问OSS。
请注意，STS Token在生成的时候需要指定过期时间，过期后自动失效不能再使用。
如果您希望获取关于STS服务的接入点列表，请参见服务接入点。

环境变量

使用临时身份凭证设置环境变量。
Mac OS X/Linux/Unix
警告
请注意，此处使用的是通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token），而非RAM用户的Access Key和Access Key Secret。
请注意区分STS服务获取的Access Key ID以STS开头，例如“STS.****************”。
```
export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
```
Windows
警告
请注意，此处使用的是通过STS服务获取的临时身份凭证（Access Key ID、Access Key Secret和Security Token），而非RAM用户的AK（Access Key ID、Access Key Secret）。
请注意区分STS服务获取的Access Key ID以STS开头，例如“STS.****************”。
```
set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>
```

通过环境变量来传递凭证信息。

package main

import (
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET，OSS_SESSION_TOKEN
	provider := credentials.NewEnvironmentVariableCredentialsProvider()

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

静态凭证

您可以在应用程序中对凭据直接进行硬编码，显式设置要使用的临时访问密钥。

警告

请勿将访问凭据嵌入到生产环境的应用程序中，此方法仅用于测试目的。

package main

import (
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 请设置为您通过STS服务获取的临时身份凭证Access Key ID、Access Key Secret和Security Token，而非RAM用户的身份凭证信息
        // 请注意区分STS服务获取的Access Key ID是以STS开头，如下所示
	accessKeyID := "STS.****************"
	accessKeySecret := "yourAccessKeySecret"
	// 填写获取的STS安全令牌（SecurityToken）
	stsToken := "yourSecurityToken"

	// 使用NewStaticCredentialsProvider方法直接设置AK、SK和STS Token
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret, stsToken)

	// 加载默认配置并设置凭证提供者和区域
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

使用RAMRoleARN

如果您的应用程序需要授权访问OSS，例如跨阿里云账号访问OSS，您可以使用RAMRoleARN初始化凭证提供者。该方式底层实现是STS Token。通过指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具会前往STS服务获取STS Token，并在会话到期前调用AssumeRole接口申请新的STS Token。此外，您还可以通过为policy赋值来限制RAM角色到一个更小的权限集合。

重要

阿里云账号拥有资源的全部权限，AK一旦泄露，会给系统带来巨大风险，不建议使用。推荐使用最小化授权的RAM用户的AK。
如需创建RAM用户的AK，请直接访问创建AccessKey。RAM用户的Access Key ID、Access Key Secret信息仅在创建时显示，请及时保存，如若遗忘请考虑创建新的AK进行轮换。
如需获取RAMRoleARN，请直接访问CreateRole - 创建角色。

添加credentials依赖。

go get github.com/aliyun/credentials-go/credentials

配置访问凭证。

package main

import (
	"context"
	"log"
	"os"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	openapicred "github.com/aliyun/credentials-go/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	config := new(openapicred.Config).
		// 填写Credential类型，固定值为ram_role_arn
		SetType("ram_role_arn").
		// 从环境变量中获取RAM用户的访问密钥（AccessKeyId和AccessKeySecret）
		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
		// 以下操作默认直接填入参数数值，您也可以通过添加环境变量，并使用os.Getenv("<变量名称>")的方式来set对应参数
		// 从环境变量中获取RAM角色的ARN信息，即需要扮演的角色ID，格式为acs:ram::$accountID:role/$roleName
		SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // RoleArn默认环境变量规范名称ALIBABA_CLOUD_ROLE_ARN
		// 自定义角色会话名称，用于区分不同的令牌
		SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // RoleSessionName默认环境变量规范名称ALIBABA_CLOUD_ROLE_SESSION_NAME
		//（可选）限制STS Token权限
		SetPolicy("Policy").
		//（可选）限制STS Token的有效时间
		SetRoleSessionExpiration(3600)

	arnCredential, gerr := openapicred.NewCredential(config)
	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
		if gerr != nil {
			return credentials.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return credentials.Credentials{}, err
		}
		return credentials.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

使用ECSRAMRole

如果您的应用程序运行在ECS实例、ECI实例、容器服务Kubernetes版的Worker节点中，建议您使用ECSRAMRole初始化凭证提供者。该方式底层实现是STS Token。ECSRAMRole允许您将一个角色关联到ECS实例、ECI实例或容器服务 Kubernetes 版的Worker节点，实现在实例内部自动刷新STS Token。该方式无需您提供一个AK或STS Token，消除了手动维护AK或STS Token的风险。如何获取ECSRAMRole，请参见CreateRole - 创建角色。

添加credentials依赖。

go get github.com/aliyun/credentials-go/credentials

配置访问凭证。

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	openapicred "github.com/aliyun/credentials-go/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	config := new(openapicred.Config).
		// 指定Credential类型，固定值为ecs_ram_role
		SetType("ecs_ram_role").
		// （可选项）指定角色名称。如果不指定，OSS会自动获取角色。强烈建议指定角色名称，以降低请求次数
		SetRoleName("RoleName")

	arnCredential, gerr := openapicred.NewCredential(config)
	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
		if gerr != nil {
			return credentials.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return credentials.Credentials{}, err
		}
		return credentials.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

使用OIDCRoleARN

在容器服务Kubernetes版中设置了Worker节点RAM角色后，对应节点内的Pod中的应用也就可以像ECS上部署的应用一样，通过元数据服务（Meta Data Server）获取关联角色的STS Token。但如果容器集群上部署的是不可信的应用（比如部署您的客户提交的应用，代码也没有对您开放），您可能并不希望它们能通过元数据服务获取Worker节点关联实例RAM角色的STS Token。为了避免影响云上资源的安全，同时又能让这些不可信的应用安全地获取所需的STS Token，实现应用级别的权限最小化，您可以使用RRSA（RAM Roles for Service Account）功能。该方式底层实现是STS Token。阿里云容器集群会为不同的应用Pod创建和挂载相应的服务账户OIDC Token文件，并将相关配置信息注入到环境变量中，Credentials工具通过获取环境变量的配置信息，调用STS服务的AssumeRoleWithOIDC接口换取绑定角色的STS Token。该方式无需您提供一个AK或STS Token，消除了手动维护AK或STS Token的风险。详情请参见通过RRSA配置ServiceAccount的RAM权限实现Pod权限隔离。

添加credentials依赖。

go get github.com/aliyun/credentials-go/credentials

配置访问凭证。

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	openapicred "github.com/aliyun/credentials-go/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	config := new(openapicred.Config).
		// 指定Credential类型，固定值为oidc_role_arn
		SetType("oidc_role_arn").
		// 指定 OIDC 提供者的 ARN（Amazon Resource Name），格式为 acs:ram::account-id:oidc-provider/provider-name
		SetOIDCProviderArn("OIDCProviderArn").
		// 指定 OIDC 令牌的文件路径，用于存储 OIDC 令牌
		SetOIDCTokenFilePath("OIDCTokenFilePath").
		// 自定义角色会话名称，用于区分不同的令牌
		SetRoleSessionName("RoleSessionName"). // RoleSessionName默认环境变量规范名称ALIBABA_CLOUD_ROLE_SESSION_NAME
		// （可选）指定访问角色时要使用的策略
		SetPolicy("Policy").
		// 填写角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::113511544585****:oidc-provider/TestOidcProvider
		SetRoleArn("RoleArn").
		// 设置会话有效期
		SetSessionExpiration(3600)

	arnCredential, gerr := openapicred.NewCredential(config)
	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
		if gerr != nil {
			return credentials.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return credentials.Credentials{}, err
		}
		return credentials.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

自定义凭证提供者

当以上凭证配置方式不满足要求时，您可以自定义获取凭证的方式。SDK 支持多种实现方式。

通过credentials.CredentialsProviderFunc接口

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 创建自定义凭证提供者
	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
		// 返回长期凭证
		return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
		// 返回临时凭证
		//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
	})

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

实现credentials.CredentialsProvider接口

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

type CustomerCredentialsProvider struct {
	// TODO
}

func NewCustomerCredentialsProvider() CustomerCredentialsProvider {
	return CustomerCredentialsProvider{}
}

func (s CustomerCredentialsProvider) GetCredentials(_ context.Context) (credentials.Credentials, error) {
	// 返回长期凭证
	return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
	// 返回临时凭证
	//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
}

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"

	// 创建自定义凭证提供者
	provider := NewCustomerCredentialsProvider()

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

使用默认凭据链

当您在初始化凭据客户端不传入任何参数时，Credentials会使用默认凭据链方式初始化客户端。默认凭据的读取逻辑请参见默认凭据链。

package main

import (
	"context"
	"log"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	osscred "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
	"github.com/aliyun/credentials-go/credentials"
)

func main() {
	// 请根据实际要求设置region，以实例华东1（杭州）为例，regionID为cn-hangzhou
	region := "cn-hangzhou"
	// 传nil，则会走默认凭证链模式，会自动获取凭证
	arnCredential, gerr := credentials.NewCredential(nil)
	provider := osscred.CredentialsProviderFunc(func(ctx context.Context) (osscred.Credentials, error) {
		if gerr != nil {
			return osscred.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return osscred.Credentials{}, err
		}

		return osscred.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// 加载默认配置并设置凭证提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 创建ossClient
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

错误排查

使用Go SDK V2访问OSS出现错误时，OSS会返回HTTP Code、Message、RequestId、EC错误码等信息，其中EC码对应一个具体的错误原因，可以使用EC码自助进行错误排查。

例如，当您使用以下代码下载一个并不存在的文件时。

package main

import (
	"context"
	"flag"
	"io"
	"log"
	"os"

	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)

// 定义全局变量
var (
	region     string // 存储区域
	bucketName string // 存储空间名称
	objectName string // 对象名称
)

// init函数用于初始化命令行参数
func init() {
	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
	flag.StringVar(&objectName, "object", "", "The name of the object.")
}

func main() {
	// 解析命令行参数
	flag.Parse()

	// 检查bucket名称是否为空
	if len(bucketName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, bucket name required")
	}

	// 检查region是否为空
	if len(region) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, region required")
	}

	// 检查object名称是否为空
	if len(objectName) == 0 {
		flag.PrintDefaults()
		log.Fatalf("invalid parameters, object name required")
	}

	// 定义输出文件路径
	outputFile := "downloaded.txt" // 替换为你希望保存的文件路径

	// 加载默认配置并设置凭证提供者和区域
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion(region)

	// 创建OSS客户端
	client := oss.NewClient(cfg)

	// 创建获取对象的请求
	request := &oss.GetObjectRequest{
		Bucket: oss.Ptr(bucketName), // 存储空间名称
		Key:    oss.Ptr(objectName), // 对象名称
	}

	// 执行获取对象的操作并处理结果
	result, err := client.GetObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to get object %v", err)
	}
	defer result.Body.Close() // 确保在函数结束时关闭响应体

	// 一次性读取整个文件内容
	data, err := io.ReadAll(result.Body)
	if err != nil {
		log.Fatalf("failed to read object %v", err)
	}

	// 将内容写入到文件
	err = os.WriteFile(outputFile, data, 0644)
	if err != nil {
		log.Fatalf("failed to write to output file %v", err)
	}

	log.Printf("file downloaded successfully to %s", outputFile)
}

返回示例如下，返回结果中包含'EC': '0026-00000001'，作为该错误原因的唯一标识。
通过以上错误请求示例返回的EC错误码查找问题原因及对应解决方法的操作步骤如下。
1. 打开OpenAPI问题自助诊断平台。
2. 在搜索框中，输入EC错误码，例如0026-00000001。
3. 在搜索结果中查找问题原因及对应解决方案。

示例代码

OSS Go SDK V2提供丰富的示例代码供参考或直接使用。

示例内容	GitHub示例文件
创建存储空间	put_bucket.go
列举存储空间	list_buckets.go
判断存储空间是否存在	is_bucket_exist.go
获取存储空间的地域	get_bucket_location.go
获取存储空间的信息	get_bucket_info.go
获取存储空间的存储容量	get_bucket_stat.go
资源组	put_bucket_resource_group.go get_bucket_resource_group.go
删除存储空间	delete_bucket.go
存储空间标签	put_bucket_tags.go get_bucket_tags.go
请求者付费模式	put_bucket_request_payment.go get_bucket_request_payment.go
简单上传（Go SDK V2）	put_object.go
追加上传	append_file.go append_object.go
分片上传	initiate_multipart_upload.go upload_part.go complete_multipart_upload.go
表单上传	post_object.go
使用预签名URL上传	presign.go
文件上传管理器	-
简单下载	get_object.go get_object_to_file.go
类文件只读	open_file.go
使用预签名URL下载	presign.go
文件下载管理器	-
拷贝对象	copy_object.go
分片拷贝	upload_part_copy.go
文件拷贝管理器	-
判断文件是否存在	is_object_exist.go
列举文件	list_objects_v2.go
删除文件	delete_object.go delete_mutiple_objects.go
查询文件	select_object.go
解冻文件	restore_object.go
管理文件元数据	head_object.go get_object_meta.go
转换文件存储类型	copy_object.go
重命名文件	copy_object.go
管理软链接	put_symlink.go get_symlink.go
设置对象标签获取对象标签删除对象标签	put_object_tagging.go get_object_tagging.go delete_object_tagging.go
管理存储空间读写权限	put_bucket_acl.go get_bucket_acl.go
管理文件访问权限	put_object_acl.go get_object_acl.go
Bucket Policy	put_bucket_policy.go get_bucket_policy.go delete_bucket_policy.go
管理版本控制	put_bucket_versioning.go get_bucket_versioning.go
防盗链	put_bucket_referer.go get_bucket_referer.go
跨域资源共享	put_bucket_cors.go get_bucket_cors.go
合规保留策略	initiate_bucket_worm.go abort_bucket_worm.go complete_bucket_worm.go extent_bucket_worm.go get_bucket_worm.go
服务端加密	put_bucket_encryption.go get_bucket_encryption.go delete_bucket_encryption.go
客户端加密	encryption_client.go
数据复制	put_bucket_replication.go
访问跟踪	put_bucket_access_monitor.go
生命周期管理	put_bucket_lifecycle.go get_bucket_lifecycle.go
存储空间清单	put_bucket_inventory.go get_bucket_inventory.go
静态网站托管（镜像回源）	put_bucket_website.go
日志转存	put_bucket_logging.go get_bucket_logging.go
归档直读	put_bucket_archive_direct_read.go get_bucket_archive_direct_read.go
标量检索向量检索	open_meta_query.go do_meta_query.go get_meta_query_status.go close_meta_query.go
绑定自定义域名	create_cname_token.go put_cname.go get_cname_token.go list_cname.go delete_cname.go
传输加速	put_bucket_transfer_acceleration.go get_bucket_transfer_acceleration.go
同步处理	process_object.go
异步处理	async_process_object.go
OSS全局阻止公共访问	put_public_access_block.go
Bucket级别阻止公共访问	put_bucket_public_access_block.go
接入点级别阻止公共访问	put_access_point_public_access_block.go
资源池QoS管理	-

快速接入

环境准备

安装SDK

配置访问凭证

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

初始化客户端

客户端配置

使用自定义域名

超时控制

最大错误重试次数

HTTP/HTTPS 协议

代理服务器

使用内网域名

使用传输加速域名

使用专有域

使用金融云域名

使用政务云域名

访问云盒Bucket

自定义HTTPClient

访问凭证配置

使用RAM用户的AK

环境变量

Linux

macOS

Zsh

Bash

Windows

CMD

PowerShell

静态凭证

使用STS临时访问凭证

环境变量

Mac OS X/Linux/Unix

Windows

静态凭证

使用RAMRoleARN

使用ECSRAMRole

使用OIDCRoleARN

自定义凭证提供者

使用默认凭据链

错误排查

示例代码