Go配置用戶端

0.0.201

本文由簡體中文內容自動轉碼而成。阿里雲不保證此自動轉碼的準確性、完整性及時效性。本文内容請以簡體中文版本為準。

OSSClient是OSS的Go用戶端，用於管理儲存空間和檔案等OSS資源。使用Go SDK發起OSS請求時，您需要初始化一個Client執行個體，並根據需要修改預設配置項。

前提條件

初始化OSSClient前，您需要配置訪問憑證。詳情請參見配置訪問憑證。

建立OSSClient

您可以使用以下範例程式碼，通過載入預設配置的方法建立一個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() {
	var (
		// 以華東1（杭州）為例
		region = "cn-hangzhou"

		// 以從環境變數中擷取訪問憑證為例
		provider credentials.CredentialsProvider = credentials.NewEnvironmentVariableCredentialsProvider()
	)

	// 建立OSS用戶端配置
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

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

其中，指定地區region時，您可以指定向何處發送請求，例如cn-hangzhou或cn-shanghai。有關所支援的地區列表，請參閱OSS地區和訪問網域名稱。

因為Go SDK沒有設定預設區域，所以您需要在載入配置時使用config.WithRegion作為參數顯式設定地區。例如：

cfg := oss.LoadDefaultConfig().WithRegion("cn-hangzhou")

重要

Go SDK V2預設使用V4簽名，所以必須指定地區參數。

配置OSSClient

在大多數情況下，使用具有預設值的Client能夠滿足業務需求。您也可以更改Client的預設配置，或自訂HTTP Client，以滿足特定環境下的使用需求。

設定OSSClient常用配置

您可以通過config修改常用的配置，樣本如下：

cfg := oss.LoadDefaultConfig().
  WithConnectTimeout(10 * time.Second).
  UploadBandwidthlimit(10*1024)

常用配置參數匯總

Region	（必選）請求發送的地區, 必選	WithRegion("cn-hangzhou")
CredentialsProvider	（必選）設定訪問憑證	WithCredentialsProvider(provider)
Endpoint	訪問網域名稱	WithEndpoint("oss-cn-hanghzou.aliyuncs.com")
HttpClient	HTTP用戶端	WithHttpClient(customClient)
RetryMaxAttempts	HTTP請求時的最大嘗試次數, 預設值為 3	WithRetryMaxAttempts(5)
Retryer	HTTP請求時的重試實現	WithRetryer(customRetryer)
ConnectTimeout	建立串連的逾時時間, 預設值為 5 秒	WithConnectTimeout(10 * time.Second)
ReadWriteTimeout	應用讀寫資料的逾時時間, 預設值為 10 秒	WithReadWriteTimeout(30 * time.Second)
InsecureSkipVerify	是否跳過SSL認證校正，預設檢查SSL認證	WithInsecureSkipVerify(true)
EnabledRedirect	是否開啟HTTP重新導向, 預設不開啟	WithEnabledRedirect(true)
ProxyHost	設定Proxy 伺服器	WithProxyHost("http://user:passswd@proxy.example-***.com")
ProxyFromEnvironment	通過環境變數設定Proxy 伺服器	WithProxyFromEnvironment(true)
UploadBandwidthlimit	整體的上傳頻寬節流設定，單位為 KiB/s	WithUploadBandwidthlimit(10*1024)
DownloadBandwidthlimit	整體的下載頻寬節流設定，單位為 KiB/s	WithDownloadBandwidthlimit(10*1024)
SignatureVersion	簽名版本，預設值為v4	WithSignatureVersion(oss.SignatureVersionV1)
LogLevel	設定記錄層級	WithLogLevel(oss.LogInfo)
LogPrinter	設定日誌列印介面	WithLogPrinter(customPrinter)
DisableSSL	不使用https請求，預設使用https	WithDisableSSL(true)
UsePathStyle	使用路徑請求風格，即次層網域請求風格，預設為bucket託管網域名稱	WithUsePathStyle(true)
UseCName	是否使用自訂網域名訪問，預設不使用	WithUseCName(true)
UseDualStackEndpoint	是否使用雙棧網域名稱訪問，預設不使用	WithUseDualStackEndpoint(true)
UseAccelerateEndpoint	是否使用傳輸加速網域名稱訪問，預設不使用	WithUseAccelerateEndpoint(true)
UseInternalEndpoint	是否使用內網網域名稱訪問，預設不使用	WithUseInternalEndpoint(true)
DisableUploadCRC64Check	上傳時關閉CRC64校正，預設開啟CRC64校正	WithDisableUploadCRC64Check(true)
DisableDownloadCRC64Check	下載時關閉CRC64校正，預設開啟CRC64校正	WithDisableDownloadCRC64Check(true)
AdditionalHeaders	指定額外的簽章要求頭，V4簽名下有效	WithAdditionalHeaders([]string{"content-length"})
UserAgent	指定額外的User-Agent資訊	WithUserAgent("user identifier")

自訂OSSClient

當常用配置參數無法滿足情境需求時，您可以使用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() {
	var (
		// 以華東1（杭州）為例
		region = "cn-hangzhou"

		// 以從環境變數中擷取訪問憑證為例
		provider credentials.CredentialsProvider = credentials.NewEnvironmentVariableCredentialsProvider()
	)

	// 常用逾時或其它設定
	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(provider).
		WithRegion(region)

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