本文介紹如何從Go SDK V1版本遷移到Go SDK V2 版本。
最低Go版本
請注意，V2版本要求Go版本最低為1.18。
導入路徑
V2版本使用新的代碼倉庫，同時也對代碼結構進行了調整，按照功能模塊組織，以下是這些模塊路徑和說明：
模塊路徑 | 說明 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss | SDK核心，基礎接口和高級接口實現 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials | 訪問憑證相關 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/retry | 重試相關 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/signer | 簽名相關 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/transport | HTTP客戶端相關 |
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto | 客戶端加密相關 |
V1版示例
import (
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)V2版示例
import (
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
// 根據需要，導入 retry，transport 或者 signer
//"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/xxxx"
)配置加載
V2版本簡化了配置設置方式，全部遷移到config下，并提供了以With為前綴的輔助函數，方便以編程方式覆蓋缺省配置。
V2版本默認使用V4簽名，所以必須配置區域（Region）。
V2版本支持從區域（Region）信息構造訪問域名（Endpoint），當訪問的是公有云時，可以不設置Endpoint。
V1版示例
import (
"github.com/aliyun/aliyun-oss-go-sdk/oss"
)
...
// 環境變量中獲取訪問憑證
provider, err := oss.NewEnvironmentVariableCredentialsProvider()
// 設置HTTP連接超時時間為20秒，HTTP讀取或寫入超時時間為60秒。
time := oss.Timeout(20,60)
// 不校驗SSL證書校驗
verifySsl := oss.InsecureSkipVerify(true)
// 設置日志
logLevel := oss.SetLogLevel(oss.LogInfo)
// Endpoint
endpoint := "oss-cn-hangzhou.aliyuncs.com"
client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), time, verifySsl, logLevel)V2版示例
import (
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
)
...
// 環境變量中獲取訪問憑證
provider := credentials.NewEnvironmentVariableCredentialsProvider()
cfg := oss.LoadDefaultConfig().
WithCredentialsProvider(provider).
// 設置HTTP連接超時時間為20秒
WithConnectTimeout(20 * time.Second).
// HTTP讀取或寫入超時時間為60秒
ReadWriteTimeout(60 * time.Second).
// 不校驗SSL證書校驗
WithInsecureSkipVerify(true).
// 設置日志
WithLogLevel(oss.LogInfo).
// 設置區域
WithRegion("cn-hangzhou")
client := oss.NewClient(cfg)創建Client
V2版本把Client的創建函數從New修改為NewClient，同時創建函數不再支持傳入Endpoint以及access key id和access key secret參數。
V1版示例
client, err := oss.New(endpoint, "ak", "sk")V2版示例
client := oss.NewClient(cfg)調用API操作
基礎API接口都合并為單一操作方法'<OperationName>'，操作的請求參數為'<OperationName>Request'，操作的返回值為'<OperationName>Result'。這些操作方法都遷移到Client下，同時需要設置context.Context。如下格式：
func (c *Client) <OperationName>(ctx context.Context, request *<OperationName>Request, optFns ...func(*Options)) (*<OperationName>Result，, error) 關于API接口的詳細使用說明，請參考基礎接口。
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")))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")),
})預簽名
V2版本把預簽名接口名字從SignURL修改為Presign，同時把接口遷移到Client下。接口形式如下：
func (c *Client) Presign(ctx context.Context, request any, optFns ...func(*PresignOptions)) (*PresignResult, error)對于request參數，其類型與API接口中的'<OperationName>Request'一致。
對于返回結果，除了返回預簽名URL外，還返回HTTP方法，過期時間和被簽名的請求頭，如下：
type PresignResult struct {
Method string
URL string
Expiration time.Time
SignedHeaders map[string]string
}關于預簽名的詳細使用說明，請參考預簽名接口。
以生成下載對象的預簽名URL為例，如何從V1遷移到V2。
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)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)
}斷點續傳接口
V2版本使用傳輸管理器'Uploader'，'Downloader' 和'Copier'分別管理對象的上傳，下載和拷貝。 同時移除了原有的斷點續傳接口Bucket.UploadFile，Bucket.DownloadFile和Bucket.CopyFile。
接口對比如下：
使用場景 | v2 | v1 |
上傳文件 | Uploader.UploadFile | Bucket.UploadFile |
上傳流（io.Reader） | Uploader.UploadFrom | 不支持 |
下載到文件 | Downloader.DownloadFile | Bucket.DownloadFile |
拷貝對象 | Copier.Copy | Bucket.CopyFile |
默認參數的變化：
場景 | v2 | v1 |
上傳-分片默認值 | 6 MiB | 通過參數設置 |
上傳-并發默認值 | 3 | 1 |
上傳-閾值 | 分片大小 | 無 |
上傳-記錄checkpoint | 支持 | 支持 |
下載-分片默認值 | 6 MiB | 通過參數設置 |
下載-并發默認值 | 3 | 1 |
下載-閾值 | 分片大小 | 無 |
下載-記錄checkpoint | 支持 | 支持 |
拷貝-分片默認值 | 64 MiB | Bucket.UploadFile |
拷貝-并發默認值 | 3 | 1 |
拷貝-閾值 | 200 MiB | 無 |
拷貝-記錄checkpoint | 不支持 | 支持 |
閾值（上傳/下載拷貝）表示對象/文件大小大于該值時，使用分片方式（上傳/下載/拷貝）。
關于傳輸管理器的詳細使用說明，請參考傳輸管理器。
客戶端加密
V2版本使用EncryptionClient來提供客戶端加密功能，同時也對API 接口做了精簡，采用了和Client一樣的接口命名規則和調用方式。另外，該版本僅保留基于RSA自主管理的主密鑰的參考實現。
對于KMS的實現，可以參考sample/crypto/kms.go。
關于客戶端加密的詳細使用說明，請參考客戶端加密。
下面以使用主密鑰RSA上傳對象為例，展示如何從 V1 遷移到 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")),
})重試
V2版本默認開啟對HTTP請求的重試行為。從V1版本遷移到V2時，您需要移除原有的重試代碼，避免放大重試次數。