文档

Go初始化

更新时间:

Client是OSS的Go客户端,用于管理存储空间和文件等OSS资源。使用Go SDK发起OSS请求时,您需要初始化一个Client实例,并根据需要修改默认配置项。

前提条件

初始化OSS SDK前,您需要配置访问凭证。详情请参见配置访问凭证

新建Client

V4签名(推荐)

推荐使用更安全的V4签名算法。使用V4签名初始化时,除指定Endpoint以外,您还需要指定阿里云通用Region ID作为发起请求地域的标识,示例值为cn-hangzhou。同时声明oss.AuthV4。OSS Go SDK 3.0.2及以上版本支持V4签名。

以使用OSS域名初始化时使用V4签名为例,其他通过自定义域名等初始化的场景可参考以下示例执行相应修改。

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
)
func main(){
    // 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }    

    // 创建OSSClient实例。
    // yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
    // yourRegion填写Endpoint对应的Region信息,例如cn-hangzhou。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region("yourRegion"))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    fmt.Printf("client:%#v\n", client)
}

V1签名(不推荐)

重要

阿里云对象存储OSS自2024年12月1日起不再对新用户(即新UID )开放使用V1签名,并将于2025年06月01日起停止更新与维护且不再对新增Bucket开放使用V1签名。请尽快切换到V4签名,避免影响服务。更多信息,请参见公告说明

使用OSS域名新建Client

以下代码用于使用OSS域名初始化。关于不同地域的OSS域名,请参见访问域名和数据中心

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
)
func main(){
    // 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }    

    // 创建OSSClient实例。
    // yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    fmt.Printf("client:%#v\n", client)
}

使用自定义域名新建Client

以下代码用于使用自定义域名新建Client。关于使用自定义域名访问OSS的更多信息,请参见绑定自定义域名至Bucket默认域名

重要

使用自定义域名时无法使用ossClient.listBuckets方法。

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
)
func main(){
    // 从环境变量中获取访问凭证。运行本代码示例之前,请先配置环境变量。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }    

    // yourEndpoint填写Bucket对应的自定义域名。
    // oss.UseCname(true)用于开启CNAME。CNAME用于将自定义域名绑定至存储空间。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider),oss.UseCname(true))
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    fmt.Printf("client:%#v\n", client)
}

配置Client

您可以通过Client配置代理、连接超时、最大连接数等参数。

参数

描述

方法

MaxIdleConns

最大闲置连接数。默认值为100。

oss.MaxConns

MaxIdleConnsPerHost

每个主机的最大闲置连接数。默认值为100。

oss.MaxConns

MaxConnsPerHost

每个主机的最大连接数。默认为空。

oss.MaxConns

ConnectTimeout

HTTP超时时间,单位为秒。默认值为10秒,0表示不超时。

oss.Timeout

ReadWriteTimeout

HTTP读取或写入超时时间,单位为秒。默认值为20秒,0表示不超时。

oss.Timeout

IsCname

是否支持将自定义域名作为Endpoint,默认不支持。

oss.UseCname

UserAgent

设置HTTP的User-Agent头,默认值为aliyun-sdk-go。

oss.UserAgent

ProxyHost

是否开启代理服务器主机地址和端口。取值如下:

  • true:开启代理服务器主机地址和端口。

  • false(默认值):关闭代理服务器主机地址和端口。

oss.AuthProxy

ProxyUser

代理服务器验证的用户名。

oss.AuthProxy

ProxyPassword

代理服务器验证的密码。

oss.AuthProxy

RedirectEnabled

设置是否开启HTTP重定向。取值如下:

  • true(默认值):开启HTTP重定向。

  • false:关闭HTTP重定向。

oss.RedirectEnabled

InsecureSkipVerify

设置是否开启SSL证书校验。取值如下:

  • true(默认值):开启SSL证书校验。

  • false:关闭SSL证书校验。

oss.InsecureSkipVerify

IsEnableCRC

是否开启CRC数据校验。取值如下:

  • true(默认值):开启CRC数据校验。

  • false:关闭CRC数据校验。

    重要

    强烈建议不要关闭CRC数据校验功能。如果您关闭此功能,则阿里云不保证上传、下载过程数据的完整性。

oss.EnableCRC

LogLevel

设置日志模式。取值如下:

  • oss.LogOff

  • oss.Debug

  • oss.Error

  • oss.Warn

  • oss.Info

oss.SetLogLevel

配置示例如下:

package main

import (
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
)

func main() {  
   // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }
    // 设置连接数为10,每个主机的最大闲置连接数为20,每个主机的最大连接数为20。
    conn := oss.MaxConns(10,20,20)
    // 设置HTTP连接超时时间为20秒,HTTP读取或写入超时时间为60秒。
    time := oss.Timeout(20,60)
    // 设置是否支持将自定义域名作为Endpoint,默认不支持。
    cname := oss.UseCname(true)
    // 设置HTTP的User-Agent头,默认为aliyun-sdk-go。
    userAgent := oss.UserAgent("aliyun-sdk-go")
    // 设置是否开启HTTP重定向,默认开启。
    redirect := oss.RedirectEnabled(true)
    // 设置是否开启SSL证书校验,默认关闭。
    verifySsl := oss.InsecureSkipVerify(false)
    // 设置代理服务器地址和端口。
    //proxy := oss.Proxy("yourProxyHost")
    // 设置代理服务器的主机地址和端口,代理服务器验证的用户名和密码。
    authProxy := oss.AuthProxy("yourProxyHost","yourProxyUserName","yourProxyPassword")
    // 开启CRC加密。
    crc := oss.EnableCRC(true)
    // 设置日志模式。
    logLevel := oss.SetLogLevel(oss.LogOff)  
   
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider),conn,time,cname,userAgent,authProxy,verifySsl,redirect,crc,logLevel)
    if err != nil {
        fmt.Println("Error:", err)
        os.Exit(-1)
    }

    fmt.Printf("%#v\n", client)


}            

设置请求上下文

您可以通过请求上下文控制和管理请求的生命周期,以及传递请求相关的上下文信息。

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

package main

import (
    "context"
    "fmt"
    "github.com/aliyun/aliyun-oss-go-sdk/oss"
    "os"
    "time"
)

func main() {
    // 从环境变量中获取访问凭证。运行本代码示例之前,请确保已设置环境变量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
    provider, err := oss.NewEnvironmentVariableCredentialsProvider()
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // 创建OSSClient实例。
    // yourEndpoint填写Bucket对应的Endpoint,以华东1(杭州)为例,填写为https://oss-cn-hangzhou.aliyuncs.com。其它Region请按实际情况填写。
    // 阿里云账号AccessKey拥有所有API的访问权限,风险很高。强烈建议您创建并使用RAM用户进行API访问或日常运维,请登录RAM控制台创建RAM用户。
    client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }
    // 填写存储空间名称,例如examplebucket。
    bucketName := "examplebucket"

    bucket, err := client.Bucket(bucketName)
    if err != nil {
    fmt.Println("Error:", err)
    os.Exit(-1)
    }

    // 设置请求上下文。
    ctx := context.Background()
    // 指定请求上下文过期时间。
    ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
    defer cancel()
    // 将本地文件上传至OSS。
    err = bucket.PutObjectFromFile("yourObjectName", "yourLocalFile", oss.WithContext(ctx))
    if err != nil {
    select {
    case <-ctx.Done():
    fmt.Println("Request cancelled or timed out")
    default:
    fmt.Println("Upload fail, Error:", err)
    }
    os.Exit(-1)
    }
    fmt.Println("Upload Success!")
}

后续步骤

初始化Go SDK后,您可以使用Client发起请求。详情请参见快速入门