Upgrade OSS SDK for Go from V1 to V2 | Migration Guide - Object Storage Service

Minimum Go version

V2 requires Go 1.18 or later.

Import paths

V2 uses a new repository (alibabacloud-oss-go-sdk-v2) with code organized by functional module.

Module path	Description
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss	Core module for basic and advanced API operations.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials	Access credentials.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/retry	Retry policies.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/signer	Signatures.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/transport	HTTP clients.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto	Client-side encryption.

Example of OSS SDK for Go V1

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

Example of OSS SDK for Go V2

import (
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
  // Import retry, transport, or signer based on your business requirements.
  //"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/xxxx"
)

Configuration

V2 consolidates settings into config and provides With-prefixed helper functions for overrides.
V2 uses V4 signatures by default, so you must specify the region.
V2 derives the endpoint from the region. For public cloud access, no explicit endpoint is needed.

Example of OSS SDK for Go V1

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

// Obtain access credentials from environment variables.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()

// Set the timeout period of an HTTP connection to 20 and the read or write timeout period of an HTTP connection to 60. Unit: seconds. 
time := oss.Timeout(20,60)

// Do not verify SSL certificates.
verifySsl := oss.InsecureSkipVerify(true)

// Specify logs.
logLevel := oss.SetLogLevel(oss.LogInfo)

// Endpoint
endpoint := "oss-cn-hangzhou.aliyuncs.com"

client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), time, verifySsl, logLevel)

Example of OSS SDK for Go V2

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

...

// Obtain access credentials from environment variables.
provider := credentials.NewEnvironmentVariableCredentialsProvider()

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(provider).
  // Set the timeout period of an HTTP connection to 20. Unit: seconds.
  WithConnectTimeout(20 * time.Second).
  // Set the read or write timeout period of an HTTP connection to 60. Unit: seconds.
  ReadWriteTimeout(60 * time.Second).
  // Do not verify SSL certificates.
  WithInsecureSkipVerify(true).
  // Specify logs.
  WithLogLevel(oss.LogInfo).
  // Specify the region.
  WithRegion("cn-hangzhou")

client := oss.NewClient(cfg)

Create a client

V2 replaces New with NewClient, which no longer accepts endpoint, AK, or SK as direct parameters.

Example of OSS SDK for Go V1

client, err := oss.New(endpoint, "ak", "sk")

Example of OSS SDK for Go V2

client := oss.NewClient(cfg)

API operations

V2 unifies each API into a single Client method named <OperationName>, with request type <OperationName>Request and response type <OperationName>Result. Each call requires a context.Context. Syntax:

func (c *Client) <OperationName>(ctx context.Context, request *<OperationName>Request, optFns ...func(*Options)) (*<OperationName>Result,, error)

Basic API operations.

Example of OSS SDK for Go V1

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

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

err = bucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

Example of OSS SDK for Go V2

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

...

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket: oss.Ptr("examplebucket"),
  Key:    oss.Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

Presigned URLs

V2 renames the presigning method from SignURL to Presign and moves it to Client. Syntax:

func (c *Client) Presign(ctx context.Context, request any, optFns ...func(*PresignOptions)) (*PresignResult, error)

The request parameter type matches '<OperationName>Request' from the corresponding API.

The response includes the presigned URL, HTTP method, expiration time, and signed headers. Example:

type PresignResult struct {
  Method        string
  URL           string
  Expiration    time.Time
  SignedHeaders map[string]string
}

Presigned URL.

The following examples generate a presigned download URL in V1 and V2:

Example of OSS SDK for Go V1

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

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

signedURL, err := bucket.SignURL("exampleobject.txt", oss.HTTPGet, 60)

fmt.Printf("Sign Url:%s\n", signedURL)

Example of OSS SDK for Go V2

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

...

cfg := oss.LoadDefaultConfig().
	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.Presign(
	context.TODO(),
	&oss.GetObjectRequest{
		Bucket: oss.Ptr("examplebucket"),
		Key:    oss.Ptr("exampleobject.txt"),
	},
	oss.PresignExpires(60*time.Second),
)

fmt.Printf("Sign Method:%v\n", result.Method)
fmt.Printf("Sign Url:%v\n", result.URL)
fmt.Printf("Sign Expiration:%v\n", result.Expiration)
for k, v := range result.SignedHeaders {
	fmt.Printf("SignedHeader %v:%v\n", k, v)
}

Resumable transfers

V2 replaces the V1 resumable methods (Bucket.UploadFile, Bucket.DownloadFile, Bucket.CopyFile) with transfer managers: Uploader, Downloader, and Copier.

The following table maps V1 methods to V2 equivalents.

Scenario	v2	v1
Upload an object	Uploader.UploadFile	Bucket.UploadFile
Upload a stream (io.Reader)	Uploader.UploadFrom	Not supported
Download an object to a local computer	Downloader.DownloadFile	Bucket.DownloadFile
Copy an object	Copier.Copy	Bucket.CopyFile

Changes to default values

Scenario	v2	v1
Object upload-part size	6 MiB	Configure part size by specifying parameters
Object upload-default value for concurrency	3	1
Object upload-size threshold	The size of the part	None
Object upload-record upload progress in the checkpoint file	Supported	Supported
Object download-part size	6 MiB	Configure part size by specifying parameters
Object download-default value for concurrency	3	1
Object download-size threshold	The size of the part	None
Object download-record download progress in the checkpoint file	Supported	Supported
Object copy-part size	64 MiB	Bucket.UploadFile
Object copy-default value for concurrency	3	1
Object copy-size threshold	200 MiB	None
Object copy-record copy progress in the checkpoint file	Not supported	Supported

Note

When an object exceeds the size threshold, V2 automatically uses multipart upload, download, or copy.

Transfer managers.

Client-side encryption

V2 introduces EncryptionClient for client-side encryption, following the same naming conventions and calling patterns as Client. V2 provides examples only for RSA-based, self-managed CMKs.

A KMS-based example is available at sample/crypto/kms.go.

Client-side encryption.

The following examples upload an object with RSA-based CMK encryption in V1 and V2:

V1

import "github.com/aliyun/aliyun-oss-go-sdk/oss"
import "github.com/aliyun/aliyun-oss-go-sdk/oss/crypto"

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

masterRsaCipher, err := osscrypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")

contentProvider := osscrypto.CreateAesCtrCipher(masterRsaCipher)

cryptoBucket, err := osscrypto.GetCryptoBucket(client, "examplebucket", contentProvider)

err = cryptoBucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

V2

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

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

mc, err := crypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")
eclient, err := NewEncryptionClient(client, mc)

result, err := eclient.PutObject(context.TODO(), &PutObjectRequest{
  Bucket: Ptr("examplebucket"),
  Key:    Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

Configure retry policies

V2 retries HTTP requests by default. Remove any custom retry logic from your V1 code to avoid excessive retries.

Reference

Developer Guide.