AI 助理
备案控制台
官方文档
有奖调研
输入文档关键字查找
首页 对象存储 开发参考 SDK参考 Go 2.0手册 高级配置 配置客户端

Go配置客户端

更新时间：
产品详情
我的收藏
重要

本文中含有需要您注意的重要提示信息，忽略该信息可能对您的业务造成影响，请务必仔细阅读。

使用Go SDK V2发起OSS请求时，您需要初始化一个OSS Client实例，并根据需要修改默认配置项。

注意事项

  • 初始化OSS Client前，您需要配置访问凭证，本文以从环境变量读取访问凭证为例，更多配置示例请参见配置访问凭证。

  • 关于OSS支持的Region与Endpoint的对应关系，请参见OSS地域和访问域名。

前置条件

重要

在配置客户端前，您需要先使用RAM用户AccessKey完成配置环境变量。

  1. 创建有OSS管理权限的RAM用户AccessKey。

    使用ROS脚本快速创建有OSS管理权限的RAM用户AccessKey

    在资源编排ROS控制台的创建资源栈页面的安全确认下，勾选确认，然后单击创建。

    1.png

    创建完成后，在输出中，复制创建的AccessKey。

    image

  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

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

        source ~/.bashrc

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

        echo $OSS_ACCESS_KEY_ID
echo $OSS_ACCESS_KEY_SECRET

    macOS

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

      echo $SHELL

      1. 根据默认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"

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

        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)

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

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

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

默认配置示例

重要

  • Go SDK V2默认使用V4签名，在初始化Client时，您需要指定阿里云通用Region ID作为发起请求地域的标识，本示例代码使用华东1（杭州）Region ID：cn-hangzhou。如需查询其它Region ID请参见OSS地域和访问域名。

  • Go SDK V2可以通过Endpoint参数，自定义服务请求的访问域名。当不指定时，SDK默认根据Region信息，构造公网访问域名。例如当Region为'cn-hangzhou'时，构造出来的访问域名为'https://oss-cn-hangzhou.aliyuncs.com'。

  • Go SDK V2构造访问域名时默认采用https协议，如需采用http协议，请在指定域名时指定为http，例如'http://oss-cn-hangzhou.aliyuncs.com'。

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即可
	// 填写Bucket所在地域，以华东1（杭州）为例，Region填写为cn-hangzhou
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

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

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

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

常见场景配置示例

内网域名配置示例

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

以下是使用OSS内网域名配置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并设置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执行后续操作...

}

自定义域名配置示例

当您有多个不同的OSS Bucket用于不同的目的时，可以通过为每个Bucket设置不同的子域名来更好地管理和组织资源。

以下是使用自定义域名配置OSSClient的示例代码。

警告

您需要先将自定义域名绑定至Bucket默认域名，否则将引发报错！关于绑定自定义域名的详细操作，请参见绑定自定义域名至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() {
	// 填写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执行后续操作...

}

传输加速域名配置示例

以下是使用传输加速域名配置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并设置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执行后续操作...

}

专有域配置示例

以下是使用专有域配置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() {
	// 填写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配置示例

以下是设置OSSClient以访问云盒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执行后续操作...

}

连接超时配置示例

以下代码用于设置OSSClient的连接超时时间。

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执行后续操作...
}

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进行后续操作...

}

配置参数汇总

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同地域的其他阿里云产品访问OSS，如何提升传输速度？

当您的使用场景对上传速度有要求时，建议您通过与OSS同地域的其他阿里云产品（如ECS服务器）访问OSS，并且请改成使用内网 Endpoint进行访问，请参见 ECS实例通过OSS内网地址访问OSS资源。

如何查看RAM用户的AK信息？

  1. 如需查看RAM用户的AK，请直接登录RAM控制台选择具体用户查看AK信息。

  2. RAM用户的AccessKey Secret仅在创建时显示，之后无法查看，若已经遗忘了的话无法找回。您可以直接访问RAM控制台选择具体用户，并创建新的AccessKey进行轮换。具体操作请参见创建AccessKey。

如果遇到报错问题该如何查询具体的错误类型？

关于错误类型的查询，OSS文档提供了EC错误码供您参阅，例如关于认证方面的常见报错问题，可参见02-AUTH。

相关文档

关于配置客户端的更多信息，请参见开发者指南。

上一篇：配置访问凭证下一篇：查询Endpoint信息