Object Storage Service：OSS Go SDK V2

快速接入

接入OSS Go SDK V2的流程如下：

環境準備

要求 Go 1.18 及以上版本。

可以通過 go -version 命令查看 Go 版本。如果當前環境沒有 Go 或版本低於 Go 1.18，請安裝Golang。

安裝SDK

• 建立專案目錄並初始化Go模組。

  mkdir oss-go-example && cd oss-go-example && go mod init oss-go-example

• 執行以下命令擷取遠程程式碼封裝。請根據需求選擇合適的OSS Go SDK V2版本，推薦使用最新的版本，確保本文中的程式碼範例可以正常運行。

  go get github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss

• 使用以下代碼引入OSS Go SDK V2包。

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

初始化用戶端

使用地區和訪問網域名稱初始化 OSSClient，並運行測試代碼。

package main

import (
	"context"
	"log"
	"strings"

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

/*
Go SDK V2 用戶端初始化配置說明：

1. 簽名版本：Go SDK V2 預設使用 V4 簽名，提供更高的安全性
2. Region配置：初始化 Client 時，您需要指定阿里雲通用 Region ID 作為發起請求地區的標識
   本範例程式碼使用華東1（杭州）Region ID：cn-hangzhou
   如需查詢其它 Region ID 請參見：OSS地區和訪問網域名稱
3. Endpoint配置：
   - 可以通過 Endpoint 參數，自訂服務要求的訪問網域名稱
   - 當不指定時，SDK 預設根據 Region 資訊，構造公網訪問網域名稱
   - 例如當 Region 為 'cn-hangzhou' 時，構造出來的訪問網域名稱為：'https://oss-cn-hangzhou.aliyuncs.com'
4. 協議配置：
   - SDK 構造訪問網域名稱時預設採用 HTTPS 協議
   - 如需採用 HTTP 協議，請在指定網域名稱時指定為 HTTP，例如：'http://oss-cn-hangzhou.aliyuncs.com'
*/

func main() {
	// 方式一：只填寫Region（推薦）
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou") // 填寫Bucket所在地區，以華東1（杭州）為例，Region填寫為cn-hangzhou，SDK會根據Region自動構造HTTPS訪問網域名稱

	// 方式二：同時填寫Region和Endpoint
	// cfg := oss.LoadDefaultConfig().
	//     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	//     WithRegion("cn-hangzhou").                                // 填寫Bucket所在地區，以華東1（杭州）為例，Region填寫為cn-hangzhou
	//     WithEndpoint("https://oss-cn-hangzhou.aliyuncs.com")     // 填寫Bucket所在地區對應的公網Endpoint。以華東1（杭州）為例，Endpoint填寫為'https://oss-cn-hangzhou.aliyuncs.com'

	// 建立OSS用戶端
	client := oss.NewClient(cfg)

	// 定義要上傳的字串內容
	body := strings.NewReader("hi oss")

	// 建立上傳對象的請求
	request := &oss.PutObjectRequest{
		Bucket: oss.Ptr("Your Bucket Name"),      // 儲存空間名稱
		Key:    oss.Ptr("Your Object Key"),       // 對象名稱
		Body:   body,                             // 要上傳的字串內容
	}

	// 發送上傳對象的請求
	result, err := client.PutObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put object %v", err)
	}

	// 列印上傳對象的結果
	log.Printf("Status: %#v\n", result.Status)
	log.Printf("RequestId: %#v\n", result.ResultCommon.Headers.Get("X-Oss-Request-Id"))
	log.Printf("ETag: %#v\n", *result.ETag)
}

運行後將會輸出上傳檔案成功的結果：

Status: "200 OK"
RequestId: "68746C5FE001B434303B90B6"
ETag: "B22E0DC370A7F7067FACF5F75D7FA385"

用戶端配置

使用自訂網域名

使用OSS預設網域名稱訪問時，可能會出現檔案禁止訪問、檔案無法預覽等問題；通過綁定自訂網域名至Bucket預設網域名稱，不僅支援瀏覽器直接預覽檔案，還可結合CDN加速分發。

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執行後續操作...
}

逾時控制

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執行後續操作...
}

最大錯誤重試次數

請求異常時，OSSClient 預設重試 3 次。

高並發或網路不穩定時，使用 WithRetryMaxAttempts 增加重試次數。這能提升請求成功率。

package main

import (
	"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
		WithRetryMaxAttempts(5)    // 設定最大重試次數，預設值為3

	// 建立OSS用戶端
	client := oss.NewClient(cfg)
	// 使用client執行後續操作...
}

HTTP/HTTPS 協議

使用 WithDisableSSL(true) 設定不使用HTTPS協議。

package main

import (
	"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
		WithDisableSSL(true)       // 設定不使用HTTPS協議。預設使用HTTPS

	// 建立OSS用戶端
	client := oss.NewClient(cfg)

	// 使用client執行後續操作...
}

Proxy 伺服器

企業安全性原則通常限制直接存取公網。使用 WithProxyHost 配置Proxy 伺服器訪問 OSS。

package main

import (
	"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
		WithUserAgent("aliyun-sdk-go").                            // 設定使用者代理程式，指HTTP的User-Agent頭
		WithProxyHost("http://user:passswd@proxy.example-***.com") // 設定Proxy 伺服器IP，如"http://user:passswd@proxy.example-***.com"）

	// 建立OSS用戶端
	client := oss.NewClient(cfg)
	// 使用client執行後續操作...
}

使用內網網域名稱

當您的應用部署在阿里雲的ECS執行個體上，並且需要頻繁訪問同地區的OSS資源時，使用內網網域名稱可以降低流量成本並提高訪問速度。

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執行後續操作...

}

使用傳輸加速網域名稱

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執行後續操作...
}

使用專有域

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

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執行後續操作...
}

自訂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進行後續操作...
}

訪問憑證配置

OSS 提供多種憑證初始化方式。請根據您的認證和授權需求選擇合適的初始化方式。

使用RAM使用者的AK

如果您的應用程式部署運行在安全、穩定且不易受外部攻擊的環境中，需要長期訪問您的OSS，且不能頻繁輪轉憑證時，您可以使用阿里雲主帳號或RAM使用者的AK（Access Key ID、Access Key Secret）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個AK，存在安全性風險和維護複雜度增加的風險。

package main

import (
	"log"

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

func main() {
	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
	region := "cn-hangzhou"

	// 填寫RAM使用者的Access Key ID和Access Key Secret
	accessKeyID := "yourAccessKeyID"
	accessKeySecret := "yourAccessKeySecret"

	// 使用NewStaticCredentialsProvider方法直接設定AK和SK
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret)

	// 載入預設配置並設定憑證提供者和地區
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 建立OSS用戶端
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

使用STS臨時訪問憑證

如果您的應用程式需要臨時訪問OSS，您可以使用通過STS服務擷取的臨時身份憑證（Access Key ID、Access Key Secret和Security Token）初始化憑證提供者。需要注意的是，該方式需要您手動維護一個STS Token，存在安全性風險和維護複雜度增加的風險。此外，如果您需要多次臨時訪問OSS，您需要手動重新整理STS Token。

package main

import (
	"log"

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

func main() {
	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
	region := "cn-hangzhou"

	// 請設定為您通過STS服務擷取的臨時身份憑證Access Key ID、Access Key Secret和Security Token，而非RAM使用者的身份憑證資訊
        // 請注意區分STS服務擷取的Access Key ID是以STS開頭，如下所示
	accessKeyID := "STS.****************"
	accessKeySecret := "yourAccessKeySecret"
	// 填寫擷取的STS安全性權杖（SecurityToken）
	stsToken := "yourSecurityToken"

	// 使用NewStaticCredentialsProvider方法直接設定AK、SK和STS Token
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret, stsToken)

	// 載入預設配置並設定憑證提供者和地區
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 建立OSS用戶端
	client := oss.NewClient(cfg)

	log.Printf("ossclient: %v", client)
}

使用RAMRoleARN

如果您的應用程式需要授權訪問OSS，例如跨阿里雲帳號訪問OSS，您可以使用RAMRoleARN初始化憑證提供者。該方式底層實現是STS Token。通過指定RAM角色的ARN（Alibabacloud Resource Name），Credentials工具會前往STS服務擷取STS Token，並在會話到期前調用AssumeRole介面申請新的STS Token。此外，您還可以通過為policy賦值來限制RAM角色到一個更小的許可權集合。

1. 添加credentials依賴。

   go get github.com/aliyun/credentials-go/credentials

2. 配置訪問憑證。

   package main
   
   import (
   	"context"
   	"log"
   	"os"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 填寫Credential類型，固定值為ram_role_arn
   		SetType("ram_role_arn").
   		// 從環境變數中擷取RAM使用者的存取金鑰（AccessKeyId和AccessKeySecret）
   		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
   		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
   		// 以下操作預設直接填入參數數值，您也可以通過添加環境變數，並使用os.Getenv("<變數名稱>")的方式來set對應參數
   		// 從環境變數中擷取RAM角色的ARN資訊，即需要扮演的角色ID，格式為acs:ram::$accountID:role/$roleName
   		SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // RoleArn預設環境變數正式名稱ALIBABA_CLOUD_ROLE_ARN
   		// 自訂角色會話名稱，用於區分不同的令牌
   		SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // RoleSessionName預設環境變數正式名稱ALIBABA_CLOUD_ROLE_SESSION_NAME
   		//（可選）限制STS Token許可權
   		SetPolicy("Policy").
   		//（可選）限制STS Token的有效時間
   		SetRoleSessionExpiration(3600)
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// 載入預設配置並設定憑證提供者和region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// 建立OSS用戶端
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

使用ECSRAMRole

如果您的應用程式運行在ECS執行個體、ECI執行個體、Container ServiceKubernetes版的Worker節點中，建議您使用ECSRAMRole初始化憑證提供者。該方式底層實現是STS Token。ECSRAMRole允許您將一個角色關聯到ECS執行個體、ECI執行個體或Container Service Kubernetes 版的Worker節點，實現在執行個體內部自動重新整理STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。如何擷取ECSRAMRole，請參見CreateRole - 建立角色。

1. 添加credentials依賴。

   go get github.com/aliyun/credentials-go/credentials

2. 配置訪問憑證。

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 指定Credential類型，固定值為ecs_ram_role
   		SetType("ecs_ram_role").
   		// （可選項）指定角色名稱。如果不指定，OSS會自動擷取角色。強烈建議指定角色名稱，以降低請求次數
   		SetRoleName("RoleName")
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// 載入預設配置並設定憑證提供者和region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// 建立OSS用戶端
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

使用OIDCRoleARN

在Container ServiceKubernetes版中設定了Worker節點RAM角色後，對應節點內的Pod中的應用也就可以像ECS上部署的應用一樣，通過中繼資料服務（Meta Data Server）擷取關聯角色的STS Token。但如果容器叢集上部署的是不可信的應用（比如部署您的客戶提交的應用，代碼也沒有對您開放），您可能並不希望它們能通過中繼資料服務擷取Worker節點關聯執行個體RAM角色的STS Token。為了避免影響雲上資源的安全，同時又能讓這些不可信的應用安全地擷取所需的STS Token，實現應用層級的許可權最小化，您可以使用RRSA（RAM Roles for Service Account）功能。該方式底層實現是STS Token。阿里雲容器叢集會為不同的應用Pod建立和掛載相應的服務賬戶OIDC Token檔案，並將相關配置資訊注入到環境變數中，Credentials工具通過擷取環境變數的配置資訊，調用STS服務的AssumeRoleWithOIDC介面換取綁定角色的STS Token。該方式無需您提供一個AK或STS Token，消除了手動維護AK或STS Token的風險。詳情請參見通過RRSA配置ServiceAccount的RAM許可權實現Pod許可權隔離。

1. 添加credentials依賴。

   go get github.com/aliyun/credentials-go/credentials

2. 配置訪問憑證。

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   	openapicred "github.com/aliyun/credentials-go/credentials"
   )
   
   func main() {
   	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// 指定Credential類型，固定值為oidc_role_arn
   		SetType("oidc_role_arn").
   		// 指定 OIDC 提供者的 ARN（Amazon Resource Name），格式為 acs:ram::account-id:oidc-provider/provider-name
   		SetOIDCProviderArn("OIDCProviderArn").
   		// 指定 OIDC 令牌的檔案路徑，用於儲存 OIDC 令牌
   		SetOIDCTokenFilePath("OIDCTokenFilePath").
   		// 自訂角色會話名稱，用於區分不同的令牌
   		SetRoleSessionName("RoleSessionName"). // RoleSessionName預設環境變數正式名稱ALIBABA_CLOUD_ROLE_SESSION_NAME
   		// （可選）指定訪問角色時要使用的策略
   		SetPolicy("Policy").
   		// 填寫角色的ARN資訊，即需要扮演的角色ID。格式為acs:ram::113511544585****:oidc-provider/TestOidcProvider
   		SetRoleArn("RoleArn").
   		// 設定會話有效期間
   		SetSessionExpiration(3600)
   
   	arnCredential, gerr := openapicred.NewCredential(config)
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		if gerr != nil {
   			return credentials.Credentials{}, gerr
   		}
   		cred, err := arnCredential.GetCredential()
   		if err != nil {
   			return credentials.Credentials{}, err
   		}
   		return credentials.Credentials{
   			AccessKeyID:     *cred.AccessKeyId,
   			AccessKeySecret: *cred.AccessKeySecret,
   			SecurityToken:   *cred.SecurityToken,
   		}, nil
   	})
   
   	// 載入預設配置並設定憑證提供者和region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// 建立OSS用戶端
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

自訂憑證提供者

當以上憑證配置方式不滿足要求時，您可以自訂擷取憑證的方式。SDK 支援多種實現方式。

1. 通過credentials.CredentialsProviderFunc介面

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   )
   
   func main() {
   	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
   	region := "cn-hangzhou"
   
   	// 建立自訂憑證提供者
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		// 返回長期憑證
   		return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   		// 返回臨時憑證
   		//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   	})
   
   	// 載入預設配置並設定憑證提供者和region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// 建立OSS用戶端
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

2. 實現credentials.CredentialsProvider介面

   package main
   
   import (
   	"context"
   	"log"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   )
   
   type CustomerCredentialsProvider struct {
   	// TODO
   }
   
   func NewCustomerCredentialsProvider() CustomerCredentialsProvider {
   	return CustomerCredentialsProvider{}
   }
   
   func (s CustomerCredentialsProvider) GetCredentials(_ context.Context) (credentials.Credentials, error) {
   	// 返回長期憑證
   	return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   	// 返回臨時憑證
   	//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   }
   
   func main() {
   	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
   	region := "cn-hangzhou"
   
   	// 建立自訂憑證提供者
   	provider := NewCustomerCredentialsProvider()
   
   	// 載入預設配置並設定憑證提供者和region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// 建立OSS用戶端
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

使用預設憑據鏈

當您在初始化憑據用戶端不傳入任何參數時，Credentials會使用預設憑據鏈方式初始化用戶端。預設憑據的讀取邏輯請參見預設憑據鏈。

package main

import (
	"context"
	"log"

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

func main() {
	// 請根據實際要求設定region，以執行個體華東1（杭州）為例，regionID為cn-hangzhou
	region := "cn-hangzhou"
	// 傳nil，則會走預設憑證鏈模式，會自動擷取憑證
	arnCredential, gerr := credentials.NewCredential(nil)
	provider := osscred.CredentialsProviderFunc(func(ctx context.Context) (osscred.Credentials, error) {
		if gerr != nil {
			return osscred.Credentials{}, gerr
		}
		cred, err := arnCredential.GetCredential()
		if err != nil {
			return osscred.Credentials{}, err
		}

		return osscred.Credentials{
			AccessKeyID:     *cred.AccessKeyId,
			AccessKeySecret: *cred.AccessKeySecret,
			SecurityToken:   *cred.SecurityToken,
		}, nil
	})

	// 載入預設配置並設定憑證提供者和region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// 建立ossClient
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

錯誤排查

使用Go SDK V2訪問OSS出現錯誤時，OSS會返回HTTP Code、Message、RequestId、EC錯誤碼等資訊，其中EC碼對應一個具體的錯誤原因，可以使用EC碼自助進行錯誤排查。

範例程式碼

OSS Go SDK V2提供豐富的範例程式碼供參考或直接使用。