Upgrade OSS SDK for Go from V1 to V2 | Migration Guide - Object Storage Service: Central de Documentação do Alibaba Cloud

Versão mínima do Go

A V2 exige o Go 1.18 ou posterior.

Caminhos de importação

A V2 utiliza um novo repositório (alibabacloud-oss-go-sdk-v2) com código organizado por módulo funcional.

Caminho do módulo	Descrição
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss	Módulo principal para operações de API básicas e avançadas.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials	Credenciais de acesso.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/retry	Políticas de nova tentativa.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/signer	Assinaturas.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/transport	Clientes HTTP.
github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/crypto	Criptografia no lado do cliente.

Exemplo do OSS SDK for Go V1

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

Exemplo do OSS SDK for Go V2

import (
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss"
  "github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/credentials"
  // Import retry, transport, or signer based on your business requirements.
  //"github.com/aliyun/alibabacloud-oss-go-sdk-v2/oss/xxxx"
)

Configuração

A V2 consolida as configurações em config e fornece funções auxiliares com prefixo With para substituições.
A V2 usa assinaturas V4 por padrão; portanto, especifique a região.
A V2 deriva o endpoint da região. Para acesso à nuvem pública, não é necessário definir um endpoint explicitamente.

Exemplo do OSS SDK for Go V1

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

// Obtain access credentials from environment variables.
provider, err := oss.NewEnvironmentVariableCredentialsProvider()

// Set the timeout period of an HTTP connection to 20 and the read or write timeout period of an HTTP connection to 60. Unit: seconds. 
time := oss.Timeout(20,60)

// Do not verify SSL certificates.
verifySsl := oss.InsecureSkipVerify(true)

// Specify logs.
logLevel := oss.SetLogLevel(oss.LogInfo)

// Endpoint
endpoint := "oss-cn-hangzhou.aliyuncs.com"

client, err := oss.New(endpoint, "", "", oss.SetCredentialsProvider(&provider), time, verifySsl, logLevel)

Exemplo do OSS SDK for Go V2

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

...

// Obtain access credentials from environment variables.
provider := credentials.NewEnvironmentVariableCredentialsProvider()

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(provider).
  // Set the timeout period of an HTTP connection to 20. Unit: seconds.
  WithConnectTimeout(20 * time.Second).
  // Set the read or write timeout period of an HTTP connection to 60. Unit: seconds.
  ReadWriteTimeout(60 * time.Second).
  // Do not verify SSL certificates.
  WithInsecureSkipVerify(true).
  // Specify logs.
  WithLogLevel(oss.LogInfo).
  // Specify the region.
  WithRegion("cn-hangzhou")

client := oss.NewClient(cfg)

Crie um cliente

A V2 substitui New por NewClient. Este método não aceita mais endpoint, AK ou SK como parâmetros diretos.

Exemplo do OSS SDK for Go V1

client, err := oss.New(endpoint, "ak", "sk")

Exemplo do OSS SDK for Go V2

client := oss.NewClient(cfg)

Operações de API

A V2 unifica cada API em um único método do Client chamado <OperationName>. Os tipos de solicitação e resposta são <OperationName>Request e <OperationName>Result, respectivamente. Cada chamada requer um context.Context. Sintaxe:

func (c *Client) <OperationName>(ctx context.Context, request *<OperationName>Request, optFns ...func(*Options)) (*<OperationName>Result,, error)

Operações básicas de API.

Exemplo do OSS SDK for Go V1

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

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

err = bucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

Exemplo do OSS SDK for Go V2

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

...

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.PutObject(context.TODO(), &oss.PutObjectRequest{
  Bucket: oss.Ptr("examplebucket"),
  Key:    oss.Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

URLs pré-assinadas

A V2 renomeia o método de pré-assinatura de SignURL para Presign e o move para o Client. Sintaxe:

func (c *Client) Presign(ctx context.Context, request any, optFns ...func(*PresignOptions)) (*PresignResult, error)

O tipo do parâmetro request corresponde a '<OperationName>Request' da API correspondente.

A resposta inclui a URL pré-assinada, o método HTTP, o tempo de expiração e os cabeçalhos assinados. Exemplo:

type PresignResult struct {
  Method        string
  URL           string
  Expiration    time.Time
  SignedHeaders map[string]string
}

URL pré-assinada.

Os exemplos a seguir geram uma URL pré-assinada de download nas versões V1 e V2:

Exemplo do OSS SDK for Go V1

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

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

bucket, err := client.Bucket("examplebucket")

signedURL, err := bucket.SignURL("exampleobject.txt", oss.HTTPGet, 60)

fmt.Printf("Sign Url:%s\n", signedURL)

Exemplo do OSS SDK for Go V2

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

...

cfg := oss.LoadDefaultConfig().
	WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
	WithRegion("your region")

client := oss.NewClient(cfg)

result, err := client.Presign(
	context.TODO(),
	&oss.GetObjectRequest{
		Bucket: oss.Ptr("examplebucket"),
		Key:    oss.Ptr("exampleobject.txt"),
	},
	oss.PresignExpires(60*time.Second),
)

fmt.Printf("Sign Method:%v\n", result.Method)
fmt.Printf("Sign Url:%v\n", result.URL)
fmt.Printf("Sign Expiration:%v\n", result.Expiration)
for k, v := range result.SignedHeaders {
	fmt.Printf("SignedHeader %v:%v\n", k, v)
}

Transferências retomáveis

A V2 substitui os métodos retomáveis da V1 (Bucket.UploadFile, Bucket.DownloadFile, Bucket.CopyFile) por gerenciadores de transferência: Uploader, Downloader e Copier.

A tabela a seguir mapeia os métodos da V1 para seus equivalentes na V2.

Cenário	v2	v1
Carregar um objeto	Uploader.UploadFile	Bucket.UploadFile
Carregar um fluxo (io.Reader)	Uploader.UploadFrom	Não suportado
Baixe um objeto para um computador local	Downloader.DownloadFile	Bucket.DownloadFile
Copiar um objeto	Copier.Copy	Bucket.CopyFile

Alterações nos valores padrão

Cenário	v2	v1
Tamanho da parte de carregamento do objeto	6 MiB	Configure o tamanho da parte especificando parâmetros
Valor padrão de simultaneidade para carregamento de objeto	3	1
Limiar de tamanho para carregamento de objeto	Tamanho da parte	Nenhum
Registro do progresso de carregamento no arquivo de ponto de verificação	Suportado	Suportado
Tamanho da parte de download do objeto	6 MiB	Configure o tamanho da parte especificando parâmetros
Valor padrão de simultaneidade para download de objeto	3	1
Limiar de tamanho para download de objeto	Tamanho da parte	Nenhum
Registro do progresso de download no arquivo de ponto de verificação	Suportado	Suportado
Tamanho da parte de cópia de objeto	64 MiB	Bucket.UploadFile
Valor padrão de simultaneidade para cópia de objeto	3	1
Limiar de tamanho para cópia de objeto	200 MiB	Nenhum
Registro do progresso de cópia no arquivo de ponto de verificação	Não suportado	Suportado

Nota

Quando um objeto excede o limiar de tamanho, a V2 utiliza automaticamente carregamento, download ou cópia multipart.

Gerenciadores de transferência.

Criptografia no lado do cliente

A V2 introduz o EncryptionClient para criptografia no lado do cliente. Ele segue as mesmas convenções de nomenclatura e padrões de chamada do Client. A V2 fornece exemplos apenas para CMKs autogerenciadas baseadas em RSA.

Um exemplo baseado em KMS está disponível em sample/crypto/kms.go.

Criptografia no lado do cliente.

Os exemplos a seguir carregam um objeto com criptografia CMK baseada em RSA nas versões V1 e V2:

V1

import "github.com/aliyun/aliyun-oss-go-sdk/oss"
import "github.com/aliyun/aliyun-oss-go-sdk/oss/crypto"

...

provider, err := oss.NewEnvironmentVariableCredentialsProvider()

client, err := oss.New("yourEndpoint", "", "", oss.SetCredentialsProvider(&provider))  

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

masterRsaCipher, err := osscrypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")

contentProvider := osscrypto.CreateAesCtrCipher(masterRsaCipher)

cryptoBucket, err := osscrypto.GetCryptoBucket(client, "examplebucket", contentProvider)

err = cryptoBucket.PutObject("exampleobject.txt", bytes.NewReader([]byte("example data")))

V2

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

cfg := oss.LoadDefaultConfig().
  WithCredentialsProvider(credentials.NewEnvironmentVariableCredentialsProvider()).
  WithRegion("your region")

client := oss.NewClient(cfg)

materialDesc := make(map[string]string)
materialDesc["desc"] = "your master encrypt key material describe information"

mc, err := crypto.CreateMasterRsa(materialDesc, "yourRsaPublicKey", "yourRsaPrivateKey")
eclient, err := NewEncryptionClient(client, mc)

result, err := eclient.PutObject(context.TODO(), &PutObjectRequest{
  Bucket: Ptr("examplebucket"),
  Key:    Ptr("exampleobject.txt"),
  Body:   bytes.NewReader([]byte("example data")),
})

Configure políticas de nova tentativa

A V2 repete solicitações HTTP por padrão. Remova qualquer lógica personalizada de nova tentativa do código V1 para evitar repetições excessivas.

Referência

Guia do Desenvolvedor.