对象存储 OSS：OSS Go SDK V1

准备环境

请参考Golang安装下载和安装Go编译运行环境。推荐使用Go 1.13及以上版本。

• Go 1.13及以上版本默认启用模块模式管理包依赖关系，无需手动设置GOPATH。

• Go 1.12及以下版本需要设置GOPATH系统变量，并将其指向代码目录。

执行go version命令可查看Go版本。

安装SDK

根据开发环境选择合适的安装方式。建议使用最新版本的SDK，确保代码示例正常运行。

require (
    github.com/aliyun/aliyun-oss-go-sdk v3.0.2+incompatible
)

go get github.com/aliyun/aliyun-oss-go-sdk/oss

配置访问凭证

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

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

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

   Linux

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

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

   2. 执行以下命令使变更生效。

      source ~/.bashrc

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

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

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

      echo $SHELL

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

      Zsh

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

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

      2. 执行以下命令使变更生效。

         source ~/.zshrc

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

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. 执行以下命令，将环境变量设置追加到 ~/.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

      2. 执行以下命令使变更生效。

         source ~/.bash_profile

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

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. 在CMD中运行以下命令。

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

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

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. 在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)

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

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

初始化客户端

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

package main

// OSS Go SDK V1初始化客户端示例

import (
	"fmt"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {

	// 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// 创建OSS客户端实例
	client, _ := oss.New(
		"<endpoint>",
		"",
		"",
		oss.SetCredentialsProvider(&provider),
		oss.AuthVersion(oss.AuthV4),
		oss.Region("<region-id>"),
	)

	// 列举所有Bucket
	buckets, err := client.ListBuckets()
	if err != nil {
		fmt.Printf("列举Bucket失败: %v\n", err)
		return
	}

	// 输出Bucket列表信息
	fmt.Printf("共找到 %d 个Bucket:\n", len(buckets.Buckets))

	for _, bucket := range buckets.Buckets {
		fmt.Printf("%s\n", bucket.Name)
	}
}

使用内网域名

初始化OSS客户端时，将Endpoint指定为内网访问域名即可实现内网访问。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

// 创建OSS客户端实例
client, _ := oss.New(
	"<endpoint>",
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("<region-id>"),
)

使用自定义域名

将Endpoint指定为自定义域名，并在初始化客户端时通过oss.UseCname(true)参数启用CNAME选项，即可实现自定义域名访问。

使用自定义域名前，需确保已将自定义域名绑定到Bucket。具体操作参见通过自定义域名访问OSS。

运行示例代码前，请将代码中的 <region-id>占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

// 设置是否支持将自定义域名作为Endpoint，默认不支持。
cname := oss.UseCname(true)

// 创建OSS客户端实例
client, _ := oss.New(
	"http://example.com", // 自定义域名
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("<region-id>"),
	cname,
)

超时控制

初始化OSS客户端时，使用oss.Timeout参数设置HTTP连接超时时间和HTTP读取或写入超时时间，单位为秒。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

// 设置HTTP连接超时时间为20秒，HTTP读取或写入超时时间为60秒
time := oss.Timeout(20, 60)

// 创建OSS客户端实例
client, _ := oss.New(
	"<endpoint>",
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("<region-id>"),
	time,
)

设置连接池大小

初始化OSS客户端时，通过oss.MaxConns参数调整连接池大小。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

// 设置最大闲置连接数MaxIdleConns为10，默认值为100
// 设置每个主机的最大闲置连接数MaxIdleConnsPerHost为20，默认值为100
// 设置每个主机的最大连接数MaxConnsPerHost为50，默认值为空
conn := oss.MaxConns(10, 20, 50)

// 创建OSS客户端实例
client, _ := oss.New(
	"<endpoint>",
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("<region-id>"),
	conn,
)

关闭CRC数据校验

可通过oss.EnableCRC(false)参数关闭CRC数据校验功能。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

// 关闭CRC数据校验
crc := oss.EnableCRC(false)

// 创建OSS客户端实例
client, _ := oss.New(
	"<endpoint>",
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("<region-id>"),
	crc,
)

签名版本

以下示例代码采用V1签名初始化客户端。V4签名客户端初始化示例代码参见初始化客户端。

运行示例代码前，请将代码中的 endpoint占位符替换为实际的地域和Endpoint，如 oss-ap-southeast-1.aliyuncs.com。

package main

// OSS Go SDK V1签名版本初始化客户端示例

import (
	"fmt"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {

	// 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// 创建OSS客户端实例
	client, _ := oss.New(
		"<endpoint>",
		"",
		"",
		oss.SetCredentialsProvider(&provider),
	)

	// 列举所有Bucket
	buckets, err := client.ListBuckets()
	if err != nil {
		fmt.Printf("列举Bucket失败: %v\n", err)
		return
	}

	// 输出Bucket列表信息
	fmt.Printf("共找到 %d 个Bucket:\n", len(buckets.Buckets))

	for _, bucket := range buckets.Buckets {
		fmt.Printf("%s\n", bucket.Name)
	}
}

设置请求上下文

通过请求上下文控制和管理请求的生命周期。

仅OSS Go SDK 2.2.9及以上版本支持设置请求上下文。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

package main

// OSS Go SDK V1设置请求上下文示例

import (
	"context"
	"fmt"
	"time"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

func main() {

	// 从环境变量中加载访问凭证（需要设置OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET）
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// 创建OSS客户端实例
	client, _ := oss.New(
		"<endpoint>",
		"",
		"",
		oss.SetCredentialsProvider(&provider),
		oss.AuthVersion(oss.AuthV4),
		oss.Region("<region-id>"),
	)

	// 获取Bucket对象
	bucket, _ := client.Bucket("example-bucket-hz")

	// 配置文件信息
	key := "oss-browser2-mac-arm64-2.1.0.dmg"       // OSS中的文件路径
	file_path := "oss-browser2-mac-arm64-2.1.0.dmg" // 本地保存路径

	// 设置请求上下文
	ctx := context.Background()

	// 指定请求上下文过期时间为5秒
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	// 将OSS中的文件下载到本地指定路径，并设置请求上下文
	err := bucket.GetObjectToFile(key, file_path, oss.WithContext(ctx))
	if err != nil {
		select {
		case <-ctx.Done():
			fmt.Printf("请求取消或超时: %v\n", err)
		default:
			fmt.Printf("下载失败: %v\n", err)
		}
		return
	}

	fmt.Printf("文件下载完成: %s -> %s\n", key, file_path)
}

使用RAM用户的AK

适用于应用程序部署运行在安全、稳定且不易受外部攻击的环境中，需要长期访问OSS且无法频繁轮转凭证的场景。通过阿里云主账号或RAM用户的AK（Access Key ID、Access Key Secret）初始化凭证提供者。该方式需要手动维护AK，存在安全性风险和维护复杂度增加的风险。

使用STS临时访问凭证

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

1. 使用临时身份凭证设置环境变量。

   Mac OS/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>

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

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   )
   
   func main() {
   	// 从环境变量中获取访问凭证。运行本代码示例之前，请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET，OSS_SESSION_TOKEN。
   	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	// 创建OSSClient实例。
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

使用RAMRoleARN

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

1. 添加credentials依赖。

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

2. 配置AK和RAMRoleARN作为访问凭证。

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type defaultCredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild *defaultCredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewRamRoleArnCredentialsProvider(credential credentials.Credential) defaultCredentialsProvider {
   	return defaultCredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.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("").
   		// （可选）限制STS Token的有效时间。
   		SetRoleSessionExpiration(3600)
   
   	arnCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   
   	provider := NewRamRoleArnCredentialsProvider(arnCredential)
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   
   	fmt.Printf("client:%#v\n", client)
   }

使用ECSRAMRole

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

1. 添加credentials依赖。

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

2. 配置ECSRAMRole作为访问凭证。

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewEcsCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// 指定Credential类型，固定值为ecs_ram_role。
   		SetType("ecs_ram_role").
   		// （可选项）指定角色名称。如果不指定，OSS会自动获取角色。强烈建议指定角色名称，以降低请求次数。
   		SetRoleName("RoleName")
   
   	ecsCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewEcsCredentialsProvider(ecsCredential)
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", 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权限隔离。

1. 添加credentials依赖。

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

2. 配置OIDC的RAM角色作为访问凭证。

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewOIDCRoleARNCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// 指定 OIDC 令牌的文件路径，用于存储 OIDC 令牌。
   		SetOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
   		// 以下操作默认直接填入参数数值，您也可以通过添加环境变量，并使用os.Getenv("<变量名称>")的方式来set对应参数
   		// 指定Credential类型，固定值为oidc_role_arn。
   		SetType("oidc_role_arn").
   		// 指定 OIDC 提供者的 ARN（Amazon Resource Name），格式为 acs:ram::account-id:oidc-provider/provider-name。
   		SetOIDCProviderArn("acs:ram::113511544585****:oidc-provider/TestOidcProvider"). // OIDCProviderArn默认环境变量规范名称ALIBABA_CLOUD_OIDC_PROVIDER_ARN
   		// 自定义角色会话名称，用于区分不同的令牌。
   		SetRoleSessionName("role_session_name"). // RoleSessionName默认环境变量规范名称ALIBABA_CLOUD_ROLE_SESSION_NAME
   		// 填写角色的ARN信息，即需要扮演的角色ID。格式为acs:ram::113511544585****:oidc-provider/TestOidcProvider
   		SetRoleArn("acs:ram::113511544585****:role/testoidc"). // RoleArn默认环境变量规范名称ALIBABA_CLOUD_ROLE_ARN
   		// （可选）指定访问角色时要使用的策略。
   		SetPolicy("").
   		SetSessionExpiration(3600)
   	oidcCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewOIDCRoleARNCredentialsProvider(oidcCredential)
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

使用函数计算上下文中的Credentials

适用于应用程序的函数部署运行在函数计算中的场景。可以使用函数计算上下文中的Credentials初始化凭证提供者，底层实现基于STS Token。函数计算根据函数配置的角色，通过扮演服务角色获取一个STS Token，然后通过上下文中的参数Credentials将STS Token传递给应用程序。该STS Token的有效期为36小时，且不支持修改。函数的最大执行时间为24小时，因此，执行函数过程中，STS Token不会过期，无需考虑刷新问题。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。如何授予函数计算访问OSS的权限，请参见使用函数角色授予函数计算访问其他云服务的权限。

1. 添加函数计算上下文依赖。

   go get github.com/aliyun/fc-runtime-go-sdk/fc
   go get github.com/aliyun/fc-runtime-go-sdk/fccontext

2. 使用函数计算上下文中的Credentials初始化凭证提供者。

   package main
   
   import (
   	"context"
   	"fmt"
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/fc-runtime-go-sdk/fc"
   	"github.com/aliyun/fc-runtime-go-sdk/fccontext"
   )
   
   type GetObjectContext struct {
   	OutputRoute string `json:"outputRoute"`
   	OutputToken string `json:"outputToken"`
   	InputOssUrl string `json:"inputOssUrl"`
   }
   
   type StructEvent struct {
   	GetObjectContext GetObjectContext `json:"getObjectContext"`
   }
   
   func HandleRequest(ctx context.Context, event StructEvent) error {
   	endpoint := event.GetObjectContext.OutputRoute
   	fctx, _ := fccontext.FromContext(ctx)
   	client, err := oss.New(endpoint, fctx.Credentials.AccessKeyId, fctx.Credentials.AccessKeySecret, oss.SecurityToken(fctx.Credentials.SecurityToken))
   	if err != nil {
   		return fmt.Errorf("client new error: %v", err)
   	}
   	fmt.Printf("client:%#v\n", client)
   	return nil
   }
   
   func main() {
   	fc.Start(HandleRequest)
   }

使用CredentialsURI

适用于应用程序需要通过外部系统获取阿里云凭证，从而实现灵活的凭证管理和无密钥访问的场景。可以使用CredentialsURI初始化凭证提供者，底层实现基于STS Token。Credentials工具通过提供的URI获取STS Token，完成凭证客户端初始化。该方式无需提供AK或STS Token，消除了手动维护AK或STS Token的风险。

1. 为了使Credentials工具正确解析和使用STS Token，URI必须遵循以下响应协议：

   • 响应状态码：200

   • 响应体结构：

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. 添加credentials依赖。

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

3. 配置CredentialsURI作为访问凭证。

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewCredentialsUriCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// 指定Credential类型，固定值为credentials_uri。
   		SetType("credentials_uri").
   		// 指定 url 地址；您也可以通过设置环境变量，并使用"os.Getenv("<变量名称>")的方式进行参数传递。
   		// URLCredential默认环境变量规范名称ALIBABA_CLOUD_CREDENTIALS_URI
   		SetURLCredential("http://127.0.0.1")
   	uriCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewCredentialsUriCredentialsProvider(uriCredential)
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

使用自动轮转的AK

适用于应用程序需要长期访问OSS，但部署运行的环境面临AK泄露风险，需要频繁手动轮转（轮换）AK的场景。可以使用ClientKey初始化凭证提供者，底层实现基于AK。使用ClientKey后，密钥管理服务（KMS）可以对托管的RAM用户AK进行全自动的定期轮转，将静态的RAM用户AK动态化，从而降低AK泄漏的风险。除定期轮转外，KMS还支持立即轮转，在AK泄漏情况下快速更换AK。该方式无需手动维护AK，从而降低安全性风险和维护复杂度。如何获取ClientKey，请参见创建应用接入点。

1. 添加凭据客户端依赖。

   go get -u github.com/aliyun/aliyun-secretsmanager-client-go

2. 创建配置文件secretsmanager.properties。

   # 访问凭据类型
   credentials_type=client_key
   
   # 读取client key的解密密码：支持从环境变量或者文件读取
   client_key_password_from_env_variable=#your client key private key password environment variable name#
   client_key_password_from_file_path=#your client key private key password file path#
   
   # Client Key私钥文件路径
   client_key_private_key_path=#your client key private key file path#
   
   # 关联的KMS服务地域
   cache_client_region_id=[{"regionId":"#regionId#"}]

3. 使用配置文件传递凭证信息。

   运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

   package main
   
   import (
   	"encoding/json"
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/aliyun-secretsmanager-client-go/sdk"
   )
   
   type defaultCredentials struct {
   	config *oss.Config
   }
   
   func (defCre *defaultCredentials) GetAccessKeyID() string {
   	return defCre.config.AccessKeyID
   }
   
   func (defCre *defaultCredentials) GetAccessKeySecret() string {
   	return defCre.config.AccessKeySecret
   }
   
   func (defCre *defaultCredentials) GetSecurityToken() string {
   	return defCre.config.SecurityToken
   }
   
   type defaultCredentialsProvider struct {
   	config *oss.Config
   }
   
   func (defBuild *defaultCredentialsProvider) GetCredentials() oss.Credentials {
   	return &defaultCredentials{config: defBuild.config}
   }
   func NewDefaultCredentialsProvider(accessID, accessKey, token string) (defaultCredentialsProvider, error) {
   	var provider defaultCredentialsProvider
   	if accessID == "" {
   		return provider, fmt.Errorf("access key id is empty!")
   	}
   	if accessKey == "" {
   		return provider, fmt.Errorf("access key secret is empty!")
   	}
   	config := &oss.Config{
   		AccessKeyID:     accessID,
   		AccessKeySecret: accessKey,
   		SecurityToken:   token,
   	}
   	return defaultCredentialsProvider{
   		config,
   	}, nil
   }
   
   func main() {
   	client, err := sdk.NewClient()
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	secretInfo, err := client.GetSecretInfo("#secretName#")
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("SecretValue:%s\n", secretInfo.SecretValue)
   	var m map[string]string
   	err = json.Unmarshal([]byte(secretInfo.SecretValue), &m)
   	if err != nil {
   		fmt.Println("Error decoding JSON:", err)
   		os.Exit(-1)
   	}
   	accessKeyId := m["AccessKeyId"]
   	accessKeySecret := m["AccessKeySecret"]
   	provider, err := NewDefaultCredentialsProvider(accessKeyId, accessKeySecret, "")
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	// yourEndpoint填写Bucket对应的Endpoint
   	// yourRegion填写Bucket所在地域
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("<region-id>"))
   	// 设置签名版本
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	ossClient, err := oss.New("<endpoint>", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", ossClient)
   }

使用自定义访问凭证

当以上凭证配置方式都不满足要求时，可以通过实现Credential Providers接口的方式自定义凭证提供方式。需要注意，如果底层实现基于STS Token，需要提供凭证的更新支持。

运行示例代码前，请将代码中的 <region-id>等占位符替换为实际的地域和Endpoint，如 ap-southeast-1。

package main

import (
	"fmt"
	"os"

	"github.com/aliyun/aliyun-oss-go-sdk/oss"
)

type CustomerCredentialsProvider struct {
	config *oss.Config
}

func NewCustomerCredentialsProvider() CustomerCredentialsProvider {
	return CustomerCredentialsProvider{}
}

func (s CustomerCredentialsProvider) GetCredentials() oss.Credentials {
	// 返回长期凭证
	config := &oss.Config{
		AccessKeyID:     "id",
		AccessKeySecret: "secret",
	}
	return &CustomerCredentialsProvider{
		config,
	}
	// 返回临时凭证
	//config := &oss.Config{
	//    AccessKeyID:     "id",
	//    AccessKeySecret: "secret",
	//    SecurityToken:   "token",
	//}
	//return &CustomerCredentialsProvider{
	//    config,
	//}
}

func (s *CustomerCredentialsProvider) GetAccessKeyID() string {
	return s.config.AccessKeyID
}

func (s *CustomerCredentialsProvider) GetAccessKeySecret() string {
	return s.config.AccessKeySecret
}

func (s *CustomerCredentialsProvider) GetSecurityToken() string {
	return s.config.SecurityToken
}

func main() {
	provider := NewCustomerCredentialsProvider()
	// yourEndpoint填写Bucket对应的Endpoint
	// yourRegion填写Bucket所在地域
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("<region-id>"))
	// 设置签名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("<endpoint>", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Printf("client:%#v\n", client)
}

当使用SDK时遇到报错AccessDenied该如何进行排查？

遇到AccessDenied错误通常是因为缺少相应的访问权限。排查步骤如下：

1. 确认AccessKey ID和AccessKey Secret：确保使用了正确的AccessKey ID和AccessKey Secret。

2. 检查RAM用户权限：确认RAM用户是否拥有Bucket或Object相关操作权限。

3. 检查Bucket Policy：如果错误信息中提到"Access denied by bucket policy"，表明访问被Bucket Policy策略拒绝。

4. 更多错误类型的查询和访问控制方面的常见报错排查方法，请参考异常处理。