Tous les produits
Search

Ce produit

    Object Storage Service:Migrer OSS SDK for Go de V1 vers V2

    Centre de documentation

    Object Storage Service:Migrer OSS SDK for Go de V1 vers V2

    Dernière mise à jour :Aug 19, 2026

    Cette rubrique présente les principales modifications entre OSS SDK for Go V1 et V2, notamment les chemins d'importation, la configuration, les opérations API, les URL présignées, les transferts avec reprise et le chiffrement.

    Version minimale de Go

    V2 nécessite Go 1.18 ou une version ultérieure.

    Chemins d'importation

    V2 utilise un nouveau dépôt (alibabacloud-oss-go-sdk-v2) dont le code est organisé par module fonctionnel.

    Chemin du module

    Description

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

    Module principal pour les opérations API de base et avancées.

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

    Identifiants d'accès.

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

    Politiques de nouvelle tentative.

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

    Signatures.

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

    Clients HTTP.

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

    Chiffrement côté client.

    Exemple avec OSS SDK for Go V1

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

    Exemple avec 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"
)

    Configuration

    1. V2 regroupe les paramètres dans config et fournit des fonctions d'aide préfixées par With pour les remplacements.

    2. V2 utilise les signatures V4 par défaut ; vous devez donc spécifier la région.

    3. V2 déduit l'endpoint à partir de la région. Pour un accès au cloud public, aucun endpoint explicite n'est nécessaire.

    Exemple avec 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)

    Exemple avec 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)

    Créer un client

    V2 remplace New par NewClient, qui n'accepte plus l'endpoint, l'AK ou le SK en tant que paramètres directs.

    Exemple avec OSS SDK for Go V1

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

    Exemple avec OSS SDK for Go V2

    client := oss.NewClient(cfg)

    Opérations API

    V2 unifie chaque API en une seule méthode Client nommée <OperationName>, avec un type de requête <OperationName>Request et un type de réponse <OperationName>Result. Chaque appel nécessite un context.Context. Syntaxe :

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

    Opérations API de base.

    Exemple avec 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")))

    Exemple avec 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")),
})

    URL présignées

    V2 renomme la méthode de présignature de SignURL en Presign et la déplace vers Client. Syntaxe :

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

    Le type de paramètre request correspond à '<OperationName>Request' de l'API correspondante.

    La réponse inclut l'URL présignée, la méthode HTTP, l'heure d'expiration et les en-têtes signés. Exemple :

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

    URL présignée.

    Les exemples suivants génèrent une URL de téléchargement présignée dans V1 et V2 :

    Exemple avec 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)

    Exemple avec 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)
}

    Transferts avec reprise

    V2 remplace les méthodes de reprise V1 (Bucket.UploadFile, Bucket.DownloadFile, Bucket.CopyFile) par des gestionnaires de transfert : Uploader, Downloader et Copier.

    Le tableau suivant établit la correspondance entre les méthodes V1 et leurs équivalents V2.

    Scénario

    v2

    v1

    Téléverser un objet

    Uploader.UploadFile

    Bucket.UploadFile

    Téléverser un flux (io.Reader)

    Uploader.UploadFrom

    Non pris en charge

    Télécharger un objet sur un ordinateur local

    Downloader.DownloadFile

    Bucket.DownloadFile

    Copier un objet

    Copier.Copy

    Bucket.CopyFile

    Modifications des valeurs par défaut

    Scénario

    v2

    v1

    Taille de partie pour le téléversement d'objet

    6 MiB

    Configurer la taille de partie en spécifiant des paramètres

    Valeur par défaut de concurrence pour le téléversement d'objet

    3

    1

    Seuil de taille pour le téléversement d'objet

    La taille de la partie

    Aucun

    Enregistrer la progression du téléversement dans le fichier de point de contrôle

    Pris en charge

    Pris en charge

    Taille de partie pour le téléchargement d'objet

    6 MiB

    Configurer la taille de partie en spécifiant des paramètres

    Valeur par défaut de concurrence pour le téléchargement d'objet

    3

    1

    Seuil de taille pour le téléchargement d'objet

    La taille de la partie

    Aucun

    Enregistrer la progression du téléchargement dans le fichier de point de contrôle

    Pris en charge

    Pris en charge

    Taille de partie pour la copie d'objet

    64 MiB

    Bucket.UploadFile

    Valeur par défaut de concurrence pour la copie d'objet

    3

    1

    Seuil de taille pour la copie d'objet

    200 MiB

    Aucun

    Enregistrer la progression de la copie dans le fichier de point de contrôle

    Non pris en charge

    Pris en charge
    Remarque

    Lorsqu'un objet dépasse le seuil de taille, V2 utilise automatiquement le téléversement multipartie, le téléchargement ou la copie.

    Gestionnaires de transfert.

    Chiffrement côté client

    V2 introduit EncryptionClient pour le chiffrement côté client, en suivant les mêmes conventions de nommage et modèles d'appel que Client. V2 fournit des exemples uniquement pour les CMK gérés par l'utilisateur basés sur RSA.

    Un exemple basé sur KMS est disponible à l'adresse sample/crypto/kms.go.

    Chiffrement côté client.

    Les exemples suivants téléversent un objet avec un chiffrement CMK basé sur RSA dans V1 et 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")),
})

    Configurer les politiques de nouvelle tentative

    V2 réessaie les requêtes HTTP par défaut. Supprimez toute logique de nouvelle tentative personnalisée de votre code V1 pour éviter des tentatives excessives.

    Référence

    Guide du développeur.