全部產品
Search

搜尋本產品

    Object Storage Service：Go SDK V1到V2遷移指南

    文件中心

    Object Storage Service：Go SDK V1到V2遷移指南

    更新時間：Mar 18, 2025

    本文介紹如何從Go SDK V1版本遷移到Go SDK V2 版本。

    最低Go版本

    請注意，V2版本要求Go版本最低為1.18。

    匯入路徑

    V2版本使用新的代碼倉庫(alibabacloud-oss-go-sdk-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"
)

    配置載入

    1. V2版本簡化了配置設定方式，全部遷移到config下，並提供了以With為首碼的輔助函數，方便以編程方式覆蓋預設配置。

    2. V2版本預設使用V4簽名，所以必須配置地區（Region）。

    3. 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時，您需要移除原有的重試代碼，避免放大重試次數。

    相關文檔

    關於Go SDK V1遷移到V2的更多內容，請參見遷移指南。