Object Storage Service:OSS SDK for Go 2.0

Quick integration

Below is the process of integrating OSS SDK for Go 2.0:

Environment preparation

Go 1.18 or later is required.

You can use the go -version command to check the Go version. If your environment does not have Go installed or the version is lower than Go 1.18, please install Golang.

Install OSS SDK for Go

• Create a project directory and initialize the Go module.

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

• Run the following command to obtain the OSS SDK for Go package. We recommend using the latest version to ensure that the code example below run properly.

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

• Run the following code to import the OSS SDK for Go 2.0 package.

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

Initialize client

Use regions and endpoints to initialize the OSSClient and run the test code.

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 client initialization configuration description:

1. Signature version: Go SDK V2 uses V4 signature by default, providing higher security
2. Region configuration: When initializing the Client, you need to specify the Alibaba Cloud general Region ID as the identifier of the region from which the request is initiated
   This example code uses China (Hangzhou) Region ID: cn-hangzhou
   To query other Region IDs, see: OSS regions and endpoints
3. Endpoint configuration:
   - You can customize the service request access domain name through the Endpoint parameter
   - When not specified, the SDK constructs a public network access domain name based on the Region information
   - For example, when Region is 'cn-hangzhou', the constructed access domain name is: 'https://oss-cn-hangzhou.aliyuncs.com'
4. Protocol configuration:
   - The SDK uses HTTPS protocol by default when constructing access domain names
   - To use HTTP protocol, please specify HTTP when specifying the domain name, for example: 'http://oss-cn-hangzhou.aliyuncs.com'
*/

func main() {
	// Method 1: Only specify Region (recommended)
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou") // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou. The SDK will automatically construct an HTTPS access domain name based on the region

	// Method 2: Specify both Region and Endpoint
	// cfg := oss.LoadDefaultConfig().
	//     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	//     WithRegion("cn-hangzhou").                                // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	//     WithEndpoint("https://oss-cn-hangzhou.aliyuncs.com")     // Specify the public endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the endpoint to 'https://oss-cn-hangzhou.aliyuncs.com'

	// Create an OSSClient instance
	client := oss.NewClient(cfg)

	// Specify the string that you want to upload
	body := strings.NewReader("hi oss")

	// Create a request to upload an object
	request := &oss.PutObjectRequest{
		Bucket: oss.Ptr("Your Bucket Name"),      // The name of the bucket
		Key:    oss.Ptr("Your Object Key"),       // The name of the object
		Body:   body,                             // The string content to upload
	}

	// Execute the request to upload the object
	result, err := client.PutObject(context.TODO(), request)
	if err != nil {
		log.Fatalf("failed to put object %v", err)
	}

	// Display the result of the object upload operation
	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)
}

After running, it will output the successful result of the file upload:

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

Client configuration

Use custom domain names

When accessing with the default OSS domain name, issues such as file access prohibition or file preview failure may occur. By binding a custom domain name to the default bucket domain name, you can not only directly preview files in browsers but also combine with CDN for accelerated distribution.

package main

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

func main() {
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Specify a custom domain name. Example: https://www.example-***.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://www.example-***.com").
		WithUseCName(true) // To enable CNAME, set this parameter to true. Otherwise, you cannot use a custom domain name

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Timeout control

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").             // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
		WithConnectTimeout(10 * time.Second).  // Specify the connection timeout period. Default value: 5 seconds
		WithReadWriteTimeout(30 * time.Second) // Specify the read/write timeout period. Default value: 10 seconds

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Maximum error retry attempts

By default, the OSSClient retries 3 times when a request exception occurs.

In high concurrency or unstable network scenarios, use WithRetryMaxAttempts to increase the number of retries. This can improve the request success rate.

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"). // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
		WithRetryMaxAttempts(5)    // Set the maximum number of retries. Default value: 3

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

HTTP/HTTPS protocol

Use WithDisableSSL(true) to disable the HTTPS protocol.

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"). // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
		WithDisableSSL(true)       // Set not to use HTTPS protocol. HTTPS is used by default

	// Create an OSSClient instance
	client := oss.NewClient(cfg)

	// Use the client to perform subsequent operations...
}

Proxy server

Enterprise security policies often restrict direct access to the public network. Use WithProxyHost to configure a proxy server to access 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").                                 // Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
		WithUserAgent("aliyun-sdk-go").                            // Set the user agent, which specifies the HTTP User-Agent header
		WithProxyHost("http://user:passswd@proxy.example-***.com") // Set the proxy server IP, such as "http://user:passswd@proxy.example-***.com"

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Use internal endpoints

If your applications are deployed on an ECS instance and you need to frequently access OSS data in a bucket in the same region as the ECS instance, use an internal endpoint to significantly reduce network latency and bandwidth costs.

package main

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

func main() 
	// Method 1: Specify the region and set WithUseInternalEndpoint to true
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseInternalEndpoint(true)

	// Method 2: Directly specify Region and Endpoint
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Specify the internal endpoint of the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the endpoint to 'https://oss-cn-hangzhou-internal.aliyuncs.com'. To use the HTTP protocol, set the endpoint to 'http://oss-cn-hangzhou-internal.aliyuncs.com'
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-cn-hangzhou-internal.aliyuncs.com")

	// Create an OSSClient instance
	client := oss.NewClient(cfg)

	// Use the client to perform subsequent operations...

}

Use accelerated endpoints

package main

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

func main() {
	// Method 1: Specify the region and set WithUseAccelerateEndpoint to true
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithUseAccelerateEndpoint(true)

	// Method 2: Directly specify Region and Endpoint
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Specify the acceleration endpoint of the region in which the bucket is located. For example, if the bucket is located in the China (Hangzhou) region, set the endpoint to https://oss-accelerate.aliyuncs.com. To use the HTTP protocol, set the endpoint to http://oss-accelerate.aliyuncs.com
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("cn-hangzhou").
	// 	WithEndpoint("https://oss-accelerate.aliyuncs.com").

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Use private domains

package main

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

func main() {
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Specify the private domain. Example: https://service.corp.example.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou").
		WithEndpoint("https://service.corp.example.com")

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Use Gov Cloud endpoints

The following is an example of configuring the OSSClient with Alibaba Gov Cloud endpoints.

package main

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

func main() {
	// Specify Region and Endpoint
        // Specify the region in which the bucket is located. For example, if the bucket is located in the China North 2 Ali Gov 1 region, set the region to cn-north-2-gov-1
	// Specify the internal endpoint of the region in which the bucket is located. For example, if the bucket is located in the China North 2 Ali Gov 1 region, set the endpoint to 'https://oss-cn-north-2-gov-1-internal.aliyuncs.com',
        // To use the HTTP protocol, set the endpoint to '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")

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Access CloudBox buckets

package main

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

func main() {
	// Method 1: Automatically detect CloudBox ID
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Set the Endpoint to the data domain name of the CloudBox bucket, for example: http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// Set WithEnableAutoDetectCloudBoxId to true to automatically detect the CloudBox ID
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
		WithEnableAutoDetectCloudBoxId(true)

	// Method 2: Manually set CloudBox ID
	// Specify the region in which the bucket is located. For example, if your bucket is located in the China (Hangzhou) region, set the region to cn-hangzhou
	// Set the Endpoint to the data domain name of the CloudBox bucket, for example: http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com
	// Manually fill in the CloudBox ID, for example: cb-xxxxxx
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithEndpoint("http://cb-xxxxxx.cn-hangzhou.oss-cloudbox.aliyuncs.com").
	// 	WithCloudBoxId("cb-xxxxxx")

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client to perform subsequent operations...
}

Custom HTTPClient

When common configuration parameters cannot meet your scenario requirements, use WithHTTPClient to replace the default HTTP client.

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() {
	// Specify common timeout period or other parameters
	transConfig := transport.Config{
		// Specify the timeout period for a connection. Default value: 5. Unit: seconds
		ConnectTimeout: oss.Ptr(10 * time.Second),
		// Specify the timeout period for the application to read and write data. Default value: 10. Unit: seconds
		ReadWriteTimeout: oss.Ptr(20 * time.Second),
		// Specify the timeout period for an idle connection. Default value: 50. Unit: seconds
		IdleConnectionTimeout: oss.Ptr(40 * time.Second),
		// Specify the retention period of a network connection. Default value: 30. Unit: seconds
		KeepAliveTimeout: oss.Ptr(40 * time.Second),
		// Specify whether to enable HTTP redirection. By default, HTTP redirection is disabled
		EnabledRedirect: oss.Ptr(true),
	}

	// http.Transport settings
	var transports []func(*http.Transport)
	// Specify the maximum number of connections. Default value: 100
	transports = append(transports, transport.MaxConnections(200))
	// If a request contains the Expect: 100-Continue header, it indicates the maximum period of time to wait for the first response header returned from the server after request headers are completely written. Default value: 1. Unit: seconds
	transports = append(transports, transport.ExpectContinueTimeout(2*time.Second))
	// Specify the earliest version of Transport Layer Security (TLS). Default value: TLS 1.2
	transports = append(transports, transport.TLSMinVersion(tls.VersionTLS13))
	// Specify whether to skip the SSL certificate verification. By default, the SSL certificate is verified
	transports = append(transports, transport.InsecureSkipVerify(true))
	// For more Transport parameter settings, see https://pkg.go.dev/net/http#Transport
	// Create a custom HTTP Client
	customClient := transport.NewHttpClient(&transConfig, transports...)

	cfg := oss.LoadDefaultConfig().
		WithHttpClient(customClient).
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("cn-hangzhou")

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	// Use the client for subsequent operations...
}

Access credential configurations

OSS provides multiple credential initialization methods. Choose the appropriate initialization method based on your authentication and authorization requirements.

Use RAM user's AK

If your application is deployed in a secure and stable environment that is not vulnerable to external attacks and requires long-term access to OSS, you can use an AccessKey pair of your Alibaba Cloud account or a RAM user to initialize a credential provider. The AccessKey pair consists of an AccessKey ID and an AccessKey secret. Note that this method requires you to manually maintain an AccessKey pair, which poses security risks and increases maintenance complexity.

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() {
	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
	region := "cn-hangzhou"

	// Specify the AccessKey ID and AccessKey secret of the RAM user
	accessKeyID := "yourAccessKeyID"
	accessKeySecret := "yourAccessKeySecret"

	// Use the NewStaticCredentialsProvider method to directly set the AccessKey ID and AccessKey secret
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret)

	// Load the default configurations and specify the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// Create an OSSClient instance
	client := oss.NewClient(cfg)

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

Use STS temporary access credentials

If your application needs to access OSS temporarily, you can use temporary access credentials, which consist of an AccessKey pair and a security token, obtained from Security Token Service (STS). Note that this method requires you to manually maintain a security token, which poses security risks and increases maintenance complexity. If you want to prolong access after the existing STS token expires, you need to manually refresh the 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() {
	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
	region := "cn-hangzhou"

	// Specify the AccessKey ID, AccessKey secret, and STS token that are provided by STS, rather than the AccessKey ID and AccessKey secret of the RAM user
        // The AccessKey ID provided by STS starts with STS
	accessKeyID := "STS.****************"
	accessKeySecret := "yourAccessKeySecret"
	// Specify the STS token (SecurityToken)
	stsToken := "yourSecurityToken"

	// Use the NewStaticCredentialsProvider method to directly set the AccessKey ID, AccessKey secret, and STS token
	provider := credentials.NewStaticCredentialsProvider(accessKeyID, accessKeySecret, stsToken)

	// Load the default configurations and specify the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// Create an OSSClient instance
	client := oss.NewClient(cfg)

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

Use RAMRoleARN

To authorize your application to access OSS, for example, when your application requires access to OSS resources of another Alibaba Cloud account, you can use RAMRoleARN to initialize a credential provider. The underlying logic of this method is to use an STS token to configure access credentials. The Credentials tool obtains an STS token based on the RAM role identified by the ARN of the RAM role and refreshes the STS token by calling the AssumeRole operation before the session expires. Additionally, you can limit the RAM role to a smaller set of permissions by assigning a value to policy.

1. Add the credentials dependency.

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

2. Configure access credentials.

   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() {
   	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// Set the credential type to ram_role_arn
   		SetType("ram_role_arn").
   		// Obtain the AccessKey ID and AccessKey secret of the RAM user from the environment variables
   		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
   		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
   		// By default, the values of the parameters are directly entered for the following operations. You can also add environment variables and use os.Getenv("<variable name>") to specify the corresponding parameters
   		// Obtain the ARN of the RAM role from environment variables. The ARN is the ID of the role to be assumed, in the format of acs:ram::$accountID:role/$roleName
   		SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // By default, the canonical name of the RoleArn environment variable is ALIBABA_CLOUD_ROLE_ARN
   		// Specify a custom session name for the role to distinguish different tokens
   		SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // By default, the canonical name of the RoleSessionName environment variable is ALIBABA_CLOUD_ROLE_SESSION_NAME
   		// Optional. Specify the permissions of the security token
   		SetPolicy("Policy").
   		// Optional. Specify the validity period of the security 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
   	})
   
   	// Load the default configurations and specify the credential provider and region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// Create an OSSClient instance
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

Use ECSRAMRole

If your application runs on an ECS instance, an ECI instance, or a Container Service for Kubernetes worker node, we recommend that you use ECSRAMRole to initialize the credential provider. The underlying logic of this method is to use an STS token. ECSRAMRole lets you associate a role with an ECS instance, an ECI instance, or a Container Service for Kubernetes worker node to automatically refresh the STS token within the instance. This method does not require you to provide an AccessKey pair or an STS token, which eliminates the risks associated with manually managing these credentials. For more information about how to obtain an ECSRAMRole, see CreateRole - Create a role.

1. Add the credentials dependency.

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

2. Configure access credentials.

   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() {
   	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// Set the credential type to ecs_ram_role
   		SetType("ecs_ram_role").
   		// Optional. Specify the role name. If you do not specify the role name, OSS automatically obtains a role name. We recommend that you specify a role name to reduce the number of requests
   		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
   	})
   
   	// Load the default configurations and specify the credential provider and region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// Create an OSSClient instance
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

Use OIDCRoleARN

After you attach a RAM role to a worker node in Container Service for Kubernetes (ACK), applications within pods on that node can obtain the Security Token Service (STS) token for the attached role from the metadata service, similar to applications that are deployed on ECS instances. However, if untrusted applications are deployed on the container cluster, such as applications that are submitted by your customers and whose code is not available to you, you may not want the applications to obtain the STS token of the RAM role that is attached to the worker node from the metadata service. To ensure the security of your cloud resources, allow these untrusted applications to securely obtain the required STS tokens, and implement the principle of least privilege at the application level, you can use the RAM Roles for Service Account (RRSA) feature. The underlying logic of this method is to use an STS token. ACK creates and mounts corresponding service account OpenID Connect (OIDC) token files for different application pods, and injects relevant configuration information into environment variables. The Credentials tool obtains the configuration information from the environment variables and calls the AssumeRoleWithOIDC operation of STS to obtain the STS token for the attached role. This method does not require you to provide an AccessKey (AK) pair or an STS token, which eliminates the risks that are associated with manually maintaining AK pairs or STS tokens. For more information, see Use RRSA to configure RAM permissions for a ServiceAccount to isolate pod permissions.

1. Add the credentials dependency.

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

2. Configure access credentials.

   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() {
   	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
   	region := "cn-hangzhou"
   
   	config := new(openapicred.Config).
   		// Set the credential type to oidc_role_arn
   		SetType("oidc_role_arn").
   		// Specify the ARN of the OIDC IdP. The ARN is in the acs:ram::account-id:oidc-provider/provider-name format
   		SetOIDCProviderArn("OIDCProviderArn").
   		// Specify the path of the file in which the OIDC token is stored
   		SetOIDCTokenFilePath("OIDCTokenFilePath").
   		// Specify a custom session name for the role to distinguish different tokens
   		SetRoleSessionName("RoleSessionName"). // By default, the canonical name of the RoleSessionName environment variable is ALIBABA_CLOUD_ROLE_SESSION_NAME
   		// Optional. Specify the policy of the RAM role
   		SetPolicy("Policy").
   		// Specify the ARN of the RAM role, which is the ID of the role to be assumed. Format: acs:ram::113511544585****:oidc-provider/TestOidcProvider
   		SetRoleArn("RoleArn").
   		// Specify the validity period of the session
   		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
   	})
   
   	// Load the default configurations and specify the credential provider and region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// Create an OSSClient instance
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

Custom credential provider

If the preceding credential configuration methods do not meet your business requirements, you can specify the method that you want to use to obtain access credentials. The following methods are supported:

1. Use the credentials.CredentialsProviderFunc method

   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() {
   	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
   	region := "cn-hangzhou"
   
   	// Create a credential provider
   	provider := credentials.CredentialsProviderFunc(func(ctx context.Context) (credentials.Credentials, error) {
   		// Return long-term credentials
   		return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   		// Return temporary credentials
   		//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   	})
   
   	// Load the default configurations and specify the credential provider and region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// Create an OSSClient instance
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

2. Implement the credentials.CredentialsProvider interface

   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 long-term credentials
   	return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret"}, nil
   	// Return temporary credentials
   	//return credentials.Credentials{AccessKeyID: "id", AccessKeySecret: "secret",    SecurityToken: "token"}, nil
   }
   
   func main() {
   	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
   	region := "cn-hangzhou"
   
   	// Create a credential provider
   	provider := NewCustomerCredentialsProvider()
   
   	// Load the default configurations and specify the credential provider and region
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(provider).
   		WithRegion(region)
   
   	// Create an OSSClient instance
   	client := oss.NewClient(cfg)
   	log.Printf("ossclient: %v", client)
   }
   

Use default credential provider chain

If you initialize a Credentials client without specifying an initialization method, the Credentials tool uses the default credential provider chain. For more information about the logic of the default credential provider chain, see Default credential chain.

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() {
	// Specify the ID of the region in which the bucket is located as needed. For example, if the bucket is located in the China (Hangzhou) region, set the region ID to cn-hangzhou
	region := "cn-hangzhou"
	// If you set the parameter to nil, the default credential provider chain is used and the credentials are automatically obtained
	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
	})

	// Load the default configurations and specify the credential provider and region
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

	// Create an OSSClient instance
	client := oss.NewClient(cfg)
	log.Printf("ossclient: %v", client)
}

Troubleshooting

When an error occurs while you use the Go SDK V2 to access OSS, OSS returns the HTTP status code, error message, request ID, and error code (EC). The EC corresponds to a specific error cause, which you can use to troubleshoot the error.

Sample code

OSS Go SDK V2 provides a variety of sample code for reference or direct use.