Object Storage Service:OSS Go SDK V2

Configurar credenciais de acesso

Use o AccessKey de um usuário RAM para configurar as credenciais de acesso.

1. No console do RAM, crie um usuário RAM com Access By Using Permanent AccessKey, salve o par de AccessKey e conceda a permissão AliyunOSSFullAccess.

2. Use o AccessKey do usuário RAM para configurar as variáveis de ambiente.

   Linux

   1. Anexe as variáveis de ambiente ao arquivo ~/.bashrc.

      echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bashrc
      echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bashrc

      1. Aplique as alterações.

         source ~/.bashrc

      2. Verifique se as variáveis de ambiente foram definidas.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Verifique seu shell padrão.

      echo $SHELL

      1. Configure as variáveis de ambiente conforme o seu shell.

         Zsh

         1. Anexe as variáveis de ambiente ao arquivo ~/.zshrc.

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.zshrc
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.zshrc

         2. Aplique as alterações.

            source ~/.zshrc

         3. Verifique se as variáveis de ambiente foram definidas.

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

         Bash

         1. Anexe as variáveis de ambiente ao arquivo ~/.bash_profile.

            echo "export OSS_ACCESS_KEY_ID='YOUR_ACCESS_KEY_ID'" >> ~/.bash_profile
            echo "export OSS_ACCESS_KEY_SECRET='YOUR_ACCESS_KEY_SECRET'" >> ~/.bash_profile

         2. Aplique as alterações.

            source ~/.bash_profile

         3. Verifique se as variáveis de ambiente foram definidas.

            echo $OSS_ACCESS_KEY_ID
            echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Execute os comandos a seguir no CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

      1. Verifique se as variáveis de ambiente foram definidas.

         echo %OSS_ACCESS_KEY_ID%
         echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Execute os comandos a seguir no PowerShell.

      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_ID", "YOUR_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
      [Environment]::SetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", "YOUR_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

      1. Verifique se as variáveis de ambiente foram definidas.

         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_ID", [EnvironmentVariableTarget]::User)
         [Environment]::GetEnvironmentVariable("OSS_ACCESS_KEY_SECRET", [EnvironmentVariableTarget]::User)

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:

1. Signature version: Go SDK V2 uses v4 signatures by default to provide enhanced security.
2. Region configuration: You must specify an Alibaba Cloud region ID to identify the request region.
3. Endpoint configuration:
   - You can use the endpoint parameter to specify a custom domain name for service requests.
   - If this parameter is not specified, the SDK automatically constructs a public endpoint based on the region information.
4. Protocol configuration:
   - The SDK uses the HTTPS protocol by default to construct endpoints.
   - To use HTTP, you must specify an endpoint that starts with http://.
*/

func main() {
	// Method 1: Specify only the region (recommended).
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>") // Specify the region where the bucket is located.

	// Method 2: Specify both the region and the endpoint.
	// cfg := oss.LoadDefaultConfig().
	//     WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	//     WithRegion("<region-id>").                                // Specify the region where the bucket is located.
	//     WithEndpoint("<endpoint>")     // Specify the public endpoint of the region where the bucket is located.

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

	// Create the upload body.
	body := strings.NewReader("hi oss")

	// Create a request to upload the 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.
	}

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

	// Print the result of the 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)
}

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

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 where the bucket is located.
	// Specify your custom domain name, for example, https://www.example-***.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>").
		WithEndpoint("https://www.example-***.com").
		WithUseCName(true) // Set this parameter to true to use a custom domain name via CNAME.

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

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("<region-id>").             // The region where your bucket is located.
		WithConnectTimeout(10 * time.Second).  // Connection timeout. Defaults to 5s.
		WithReadWriteTimeout(30 * time.Second) // Read/write timeout. Defaults to 10s.

	// Create the OSS client.
	client := oss.NewClient(cfg)
	// Use the client to perform further operations...
}

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("<region-id>"). // Specifies the bucket's region.
		WithRetryMaxAttempts(5)    // Sets the maximum number of retry attempts. The default is 3.

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

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("<region-id>"). // Specify the region where the bucket is located.
		WithDisableSSL(true)       // Disable the HTTPS protocol, which is enabled by default.

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

	// Use the client for subsequent operations...
}

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("<region-id>").                                 // Specify the region where the bucket is located.
		WithUserAgent("aliyun-sdk-go").                            // Set the user agent for the HTTP User-Agent header.
		WithProxyHost("http://user:passswd@proxy.example-***.com") // Set the proxy server, e.g., "http://user:passswd@proxy.example-***.com".

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

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 where the bucket is located.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>").
		WithUseInternalEndpoint(true)

	// Method 2: Directly specify the region and endpoint.
	// Specify the internal endpoint corresponding to the bucket's region.
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("<region-id>").
	// 	WithEndpoint("<endpoint>")

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

	// Use this client for further operations.

}

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.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>").
		WithUseAccelerateEndpoint(true)

	// Method 2: Directly specify the region and endpoint.
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithRegion("<region-id>").
	// 	WithEndpoint("https://oss-accelerate.aliyuncs.com").

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

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 that contains the bucket.
	// Specify your private domain. Example: https://service.corp.example.com
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithRegion("<region-id>").
		WithEndpoint("https://service.corp.example.com")

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

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 where the bucket is located and its corresponding internal endpoint.
	// For example, for the China North 2 Ali Gov 1 region, set Region to "cn-north-2-gov-1" and Endpoint to "https://oss-cn-north-2-gov-1-internal.aliyuncs.com".
	// To use the HTTP protocol, use the HTTP endpoint: "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 OSS client.
	client := oss.NewClient(cfg)
	// Use the client to perform further operations...
}

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 the CloudBox ID.
	// Specify the region where the bucket is located.
	// Set the endpoint to the data domain name of the CloudBox bucket. Example: http://cb-xxxxxx.<region-id>.oss-cloudbox.aliyuncs.com
	// Set WithEnableAutoDetectCloudBoxId to true to automatically detect the CloudBox ID.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
		WithEndpoint("http://cb-xxxxxx.<region-id>.oss-cloudbox.aliyuncs.com").
		WithEnableAutoDetectCloudBoxId(true)

	// Method 2: Manually set the CloudBox ID.
	// Specify the region where the bucket is located.
	// Set the endpoint to the data domain name of the CloudBox bucket. Example: http://cb-xxxxxx.<region-id>.oss-cloudbox.aliyuncs.com
	// Specify the CloudBox ID manually. Example: cb-xxxxxx
	// cfg := oss.LoadDefaultConfig().
	// 	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	// 	WithEndpoint("http://cb-xxxxxx.<region-id>.oss-cloudbox.aliyuncs.com").
	// 	WithCloudBoxId("cb-xxxxxx")

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

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() {
	// Common timeout or other settings.
	transConfig := transport.Config{
		// The connection timeout. Default: 5 seconds.
		ConnectTimeout: oss.Ptr(10 * time.Second),
		// The timeout for reading data from and writing data to a connection. Default: 10 seconds.
		ReadWriteTimeout: oss.Ptr(20 * time.Second),
		// The idle connection timeout. Default: 50 seconds.
		IdleConnectionTimeout: oss.Ptr(40 * time.Second),
		// The keep-alive timeout for a network connection. Default: 30 seconds.
		KeepAliveTimeout: oss.Ptr(40 * time.Second),
		// Enables HTTP redirection. Disabled by default.
		EnabledRedirect: oss.Ptr(true),
	}

	// http.Transport settings.
	var transports []func(*http.Transport)
	// The maximum number of connections. Default: 100.
	transports = append(transports, transport.MaxConnections(200))
	// The maximum time to wait for a server's first response header after the request headers are written if the request has an 'Expect: 100-Continue' header. Default: 1 second.
	transports = append(transports, transport.ExpectContinueTimeout(2*time.Second))
	// The minimum TLS version. Default: TLS 1.2.
	transports = append(transports, transport.TLSMinVersion(tls.VersionTLS13))
	// Skips certificate verification. The default is false (certificates are verified).
	transports = append(transports, transport.InsecureSkipVerify(true))
	// For more transport parameters, 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("<region-id>")

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

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() {
	// Set the region based on your requirements.
	region := "<region-id>"
	// Passing nil uses the default credential provider chain to find credentials.
	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 configuration and set the credential provider and region.
	cfg := oss.LoadDefaultConfig().
		WithCredentialsProvider(provider).
		WithRegion(region)

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

1. Por exemplo, ao usar o código abaixo para baixar um objeto inexistente:

   package main
   
   import (
   	"context"
   	"flag"
   	"io"
   	"log"
   	"os"
   
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
   	"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
   )
   
   // Define global variables.
   var (
   	region     string // The region where the bucket is located.
   	bucketName string // The name of the bucket.
   	objectName string // The name of the object.
   )
   
   // The init function initializes command-line parameters.
   func init() {
   	flag.StringVar(&region, "region", "", "The region in which the bucket is located.")
   	flag.StringVar(&bucketName, "bucket", "", "The name of the bucket.")
   	flag.StringVar(&objectName, "object", "", "The name of the object.")
   }
   
   func main() {
   	// Parse command-line parameters.
   	flag.Parse()
   
   	// Check if the bucket name is empty.
   	if len(bucketName) == 0 {
   		flag.PrintDefaults()
   		log.Fatalf("invalid parameters, bucket name required")
   	}
   
   	// Check if the region is empty.
   	if len(region) == 0 {
   		flag.PrintDefaults()
   		log.Fatalf("invalid parameters, region required")
   	}
   
   	// Check if the object name is empty.
   	if len(objectName) == 0 {
   		flag.PrintDefaults()
   		log.Fatalf("invalid parameters, object name required")
   	}
   
   	// Define the output file path.
   	outputFile := "downloaded.txt" // Replace this with the desired file path.
   
   	// Load the default configuration and set the credential provider and region.
   	cfg := oss.LoadDefaultConfig().
   		WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
   		WithRegion(region)
   
   	// Create an OSS client.
   	client := oss.NewClient(cfg)
   
   	// Create a request to get the object.
   	request := &oss.GetObjectRequest{
   		Bucket: oss.Ptr(bucketName), // The name of the bucket.
   		Key:    oss.Ptr(objectName), // The name of the object.
   	}
   
   	// Get the object and process the result.
   	result, err := client.GetObject(context.TODO(), request)
   	if err != nil {
   		log.Fatalf("failed to get object %v", err)
   	}
   	defer result.Body.Close() // Ensure the response body is closed when the function finishes.
   
   	// Read the entire object content at once.
   	data, err := io.ReadAll(result.Body)
   	if err != nil {
   		log.Fatalf("failed to read object %v", err)
   	}
   
   	// Write the content to the file.
   	err = os.WriteFile(outputFile, data, 0644)
   	if err != nil {
   		log.Fatalf("failed to write to output file %v", err)
   	}
   
   	log.Printf("file downloaded successfully to %s", outputFile)
   }
   

2. A seguir, um exemplo de mensagem de erro retornada. Ela inclui o código de erro EC 'EC': '0026-00000001', que identifica exclusivamente a causa do erro.

   2025/03/07 15:13:46 failed to get object operation error GetObject: Error returned by Service.
   Http Status Code: 404.
   Error Code: NoSuchKey.
   Request Id: 67CA9CAADC44E03938AD91F0.
   Message: The specified key does not exist..
   EC: 0026-00000001.
   Timestamp: 2025-03-07 07:13:46 +0000 UTC.
   Request Endpoint: GET https://xxx.oss-cn-hangzhou.aliyuncs.com/asdgkhfk.

3. Para solucionar o erro usando o código de erro EC do exemplo, siga estas etapas:

   1. Abra a Plataforma de Autodiagnóstico OpenAPI.

   2. Na caixa de pesquisa, insira o código de erro EC, como 0026-00000001. Em seguida, cole a mensagem de erro que contém o ID da solicitação na caixa de texto e clique em Diagnose.

   3. O diagnóstico mostra a causa do erro e a solução. Para o código de erro EC 0026-00000001: o objeto alvo não existe. As possíveis causas incluem falha no upload, exclusão por regra de ciclo de vida, exclusão por outro usuário ou sincronização de replicação entre regiões. Verifique o objeto com HeadObject, confira as versões com ListObjectVersions e revise as convenções de nomenclatura, regras de ciclo de vida, permissões e regras de replicação. Erros relacionados: NoSuchKey e NoSuchVersion.