如何初始化Go SDK - Object Storage Service

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

前提條件

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

建立Client

V4簽名（推薦）

推薦使用更安全的V4簽名演算法。使用V4簽名初始化時，除指定Endpoint以外，您還需要指定阿里雲通用Region ID作為發起請求地區的標識，樣本值為cn-hangzhou。同時聲明oss.AuthV4。OSS Go SDK 3.0.2及以上版本支援V4簽名。

以使用OSS網域名稱初始化時使用V4簽名為例，其他通過自訂網域名等初始化的情境可參考以下樣本執行相應修改。

package main

import (
	"log"

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

// handleError 用於處理不可恢複的錯誤，並記錄錯誤資訊後終止程式。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用於設定並建立OSS用戶端執行個體。
// 參數：
//
//	endpoint - Bucket對應的Endpoint。
//	region - Endpoint對應的Region資訊。
//
// 返回建立的OSS用戶端執行個體。
func setupClient(endpoint, region string) (*oss.Client, error) {
	// 從環境變數中擷取訪問憑證。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 建立OSSClient執行個體，並使用V4簽名。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.AuthVersion(oss.AuthV4), oss.Region(region))
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	endpoint := "yourEndpoint"

	// yourRegion填寫Endpoint對應的Region資訊，例如cn-hangzhou。
	region := "yourRegion"

	// 檢查環境變數是否已經設定。
	if endpoint == "" || region == "" {
		log.Fatal("Please set yourEndpoint and yourRegion.")
	}

	// 設定並建立OSS用戶端執行個體。
	client, err := setupClient(endpoint, region)
	if err != nil {
		handleError(err)
	}

	// 輸出用戶端資訊。
	log.Printf("Client: %#v\n", client)
}

V1簽名（不推薦）

重要

阿里雲Object Storage Service自2024年12月1日起不再對新使用者（即新UID ）開放使用V1簽名，並將於2025年06月01日起停止更新與維護且不再對新增Bucket開放使用V1簽名。請儘快切換到V4簽名，避免影響服務。更多資訊，請參見公告說明。

使用OSS網域名稱建立Client

以下代碼用於使用OSS網域名稱初始化。關於不同地區的OSS網域名稱，請參見OSS地區和訪問網域名稱。

package main

import (
	"log"

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

// handleError 用於處理不可恢複的錯誤，並記錄錯誤資訊後終止程式。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用於設定並建立OSS用戶端執行個體。
// 參數：
//
//	endpoint - Bucket對應的Endpoint。
//
// 返回建立的OSS用戶端執行個體。
func setupClient(endpoint string) (*oss.Client, error) {
	// 從環境變數中擷取訪問憑證。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 建立OSSClient執行個體。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// 設定簽名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New(endpoint, "", "", clientOptions...)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	endpoint := "yourEndpoint"

	// 檢查環境變數是否已經設定。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 設定並建立OSS用戶端執行個體。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 輸出用戶端資訊。
	log.Printf("Client: %#v\n", client)
}

使用自訂網域名建立Client

以下代碼用於使用自訂網域名建立Client。關於使用自訂網域名訪問OSS的更多資訊，請參見綁定自訂網域名至Bucket預設網域名稱。

重要

使用自訂網域名時無法使用ossClient.listBuckets方法。

package main

import (
	"log"

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

// handleError 用於處理不可恢複的錯誤，並記錄錯誤資訊後終止程式。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用於設定並建立OSS用戶端執行個體，支援CNAME。
// 參數：
//
//	endpoint - 自訂網域名，即綁定到儲存空間的自訂網域名。
//
// 返回建立的OSS用戶端執行個體。
func setupClient(endpoint string) (*oss.Client, error) {
	// 從環境變數中擷取訪問憑證。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 建立OSSClient執行個體，並啟用CNAME支援。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	clientOptions = append(clientOptions, oss.UseCname(true))
	// 設定簽名版本
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New(endpoint, "", "", clientOptions...)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填寫Bucket對應的自訂網域名。
	// 樣本：填寫為 "custom-domain-for-your-bucket.com"。
	endpoint := "yourEndpoint"

	// 檢查環境變數是否已經設定。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 設定並建立OSS用戶端執行個體，支援CNAME。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 輸出用戶端資訊。
	log.Printf("Client: %#v\n", client)
}

配置Client

您可以通過Client配置代理、連線逾時、最大串連數等參數。

參數	描述	方法
MaxIdleConns	最大閑置串連數。預設值為100。	oss.MaxConns
MaxIdleConnsPerHost	每個主機的最大閑置串連數。預設值為100。	oss.MaxConns
MaxConnsPerHost	每個主機的最大串連數。預設為空白。	oss.MaxConns
ConnectTimeout	HTTP逾時時間，單位為秒。預設值為10秒，0表示不逾時。	oss.Timeout
ReadWriteTimeout	HTTP讀取或寫入逾時時間，單位為秒。預設值為20秒，0表示不逾時。	oss.Timeout
IsCname	是否支援將自訂網域名作為Endpoint，預設不支援。	oss.UseCname
UserAgent	設定HTTP的User-Agent頭，預設值為aliyun-sdk-go。	oss.UserAgent
ProxyHost	是否開啟Proxy 伺服器主機地址和連接埠。取值如下： true：開啟Proxy 伺服器主機地址和連接埠。 false（預設值）：關閉Proxy 伺服器主機地址和連接埠。	oss.AuthProxy
ProxyUser	Proxy 伺服器驗證的使用者名稱。	oss.AuthProxy
ProxyPassword	Proxy 伺服器驗證的密碼。	oss.AuthProxy
RedirectEnabled	設定是否開啟HTTP重新導向。取值如下： true（預設值）：開啟HTTP重新導向。 false：關閉HTTP重新導向。	oss.RedirectEnabled
InsecureSkipVerify	設定是否開啟SSL認證校正。取值如下： true（預設值）：忽略SSL認證校正。 false：開啟SSL認證校正。	oss.InsecureSkipVerify
IsEnableCRC	是否開啟CRC資料校正。取值如下： true（預設值）：開啟CRC資料校正。 false：關閉CRC資料校正。重要強烈建議不要關閉CRC資料校正功能。如果您關閉此功能，則阿里雲不保證上傳、下載過程資料的完整性。	oss.EnableCRC
LogLevel	設定記錄模式。取值如下： oss.LogOff oss.Debug oss.Error oss.Warn oss.Info	oss.SetLogLevel

配置樣本如下：

package main

import (
	"log"

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

// handleError 用於處理不可恢複的錯誤，並記錄錯誤資訊後終止程式。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// setupClient 用於設定並建立OSS用戶端執行個體。
// 參數：
//
//	endpoint - Bucket對應的Endpoint。
//
// 返回建立的OSS用戶端執行個體。
func setupClient(endpoint string) (*oss.Client, error) {
	// 從環境變數中擷取訪問憑證。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return nil, err
	}

	// 設定串連數為10，每個主機的最大閑置串連數為20，每個主機的最大串連數為20。
	conn := oss.MaxConns(10, 20, 20)

	// 設定HTTP連線逾時時間為20秒，HTTP讀取或寫入逾時時間為60秒。
	time := oss.Timeout(20, 60)

	// 設定是否支援將自訂網域名作為Endpoint，預設不支援。
	cname := oss.UseCname(true)

	// 設定HTTP的User-Agent頭，預設為aliyun-sdk-go。
	userAgent := oss.UserAgent("aliyun-sdk-go")

	// 設定是否開啟HTTP重新導向，預設開啟。
	redirect := oss.RedirectEnabled(true)

	// 設定是否開啟SSL認證校正，預設忽略。
	verifySsl := oss.InsecureSkipVerify(false)

	// 設定Proxy 伺服器地址和連接埠。
	// proxy := oss.Proxy("yourProxyHost")

	// 設定Proxy 伺服器的主機地址和連接埠，Proxy 伺服器驗證的使用者名稱和密碼。
	authProxy := oss.AuthProxy("yourProxyHost", "yourProxyUserName", "yourProxyPassword")

	// 開啟CRC加密。
	crc := oss.EnableCRC(true)

	// 設定記錄模式。
	logLevel := oss.SetLogLevel(oss.LogOff)

	// 建立OSSClient執行個體。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4),
		conn, time, cname, userAgent, authProxy, verifySsl, redirect, crc, logLevel)
	if err != nil {
		return nil, err
	}

	return client, nil
}

func main() {
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	endpoint := "yourEndpoint"

	// 檢查環境變數是否已經設定。
	if endpoint == "" {
		log.Fatal("Please set yourEndpoint.")
	}

	// 設定並建立OSS用戶端執行個體。
	client, err := setupClient(endpoint)
	if err != nil {
		handleError(err)
	}

	// 輸出用戶端資訊。
	log.Printf("Client: %#v\n", client)
}

佈建要求上下文

您可以通過請求上下文控制和管理請求的生命週期，以及傳遞請求相關的上下文資訊。

以下代碼用於佈建要求上下文。僅OSS Go SDK 2.2.9及以上版本支援佈建要求上下文。

package main

import (
	"context"
	"fmt"
	"log"
	"time"

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

// handleError 用於處理不可恢複的錯誤，並記錄錯誤資訊後終止程式。
func handleError(err error) {
	log.Fatalf("Error: %v", err)
}

// uploadFile 用於將本地檔案上傳到OSS儲存桶。
// 參數：
//
//	bucketName - 儲存空間名稱。
//	objectName - Object完整路徑，完整路徑中不包含Bucket名稱。
//	localFileName - 本地檔案的完整路徑。
//	endpoint - Bucket對應的Endpoint。
//
// 如果成功，記錄成功日誌；否則，返回錯誤。
func uploadFile(bucketName, objectName, localFileName, endpoint string) error {
	// 從環境變數中擷取訪問憑證。
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		return err
	}

	// 建立OSSClient執行個體。
	// yourRegion填寫Bucket所在地區，以華東1（杭州）為例，填寫為cn-hangzhou。其它Region請按實際情況填寫。
	client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), oss.Region("yourRegion"), oss.AuthVersion(oss.AuthV4))
	if err != nil {
		return err
	}

	// 擷取儲存空間。
	bucket, err := client.Bucket(bucketName)
	if err != nil {
		return err
	}

	// 佈建要求上下文。
	ctx := context.Background()

	// 指定請求上下文到期時間。
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	// 將本地檔案上傳至OSS。
	err = bucket.PutObjectFromFile(objectName, localFileName, oss.WithContext(ctx))
	if err != nil {
		select {
		case <-ctx.Done():
			return fmt.Errorf("Request cancelled or timed out")
		default:
			return err
		}
	}

	// 檔案上傳成功後，記錄日誌。
	log.Printf("File uploaded successfully: %s/%s", bucketName, objectName)
	return nil
}

func main() {
	// yourEndpoint填寫Bucket對應的Endpoint，以華東1（杭州）為例，填寫為https://oss-cn-hangzhou.aliyuncs.com。其它Region請按實際情況填寫。
	endpoint := "yourEndpoint"

	// 填寫儲存空間名稱，例如examplebucket。
	bucketName := "examplebucket"

	// yourObjectName填寫Object完整路徑，完整路徑中不包含Bucket名稱。
	objectName := "yourObjectName"

	// yourLocalFile填寫本地檔案的完整路徑。
	localFileName := "yourLocalFile"

	// 檢查環境變數是否已經設定。
	if endpoint == "" || bucketName == "" || objectName == "" || localFileName == "" {
		log.Fatal("Please set yourEndpoint, bucketName, objectName, and localFileName.")
	}

	// 嘗試上傳檔案，如果失敗則處理錯誤。
	if err := uploadFile(bucketName, objectName, localFileName, endpoint); err != nil {
		handleError(err)
	}

	// 輸出上傳成功的訊息。
	log.Println("Upload Success!")
}