Object Storage Service:OSS Go SDK V1

Préparer l'environnement

Téléchargez et installez l'environnement de compilation et d'exécution Go. Pour plus d'informations, consultez Install Go. Utilisez Go 1.13 ou une version ultérieure.

• À partir de Go 1.13, le mode module est activé par défaut pour gérer les dépendances de paquets. Il n'est donc pas nécessaire de définir manuellement GOPATH.

• Pour Go 1.12 et les versions antérieures, définissez la variable d'environnement système GOPATH et faites-la pointer vers votre répertoire de code.

Exécutez la commande go version pour vérifier la version de Go installée.

Installer le SDK

Choisissez une méthode d'installation adaptée à votre environnement de développement. Nous vous recommandons d'utiliser la dernière version du SDK.

require (
    github.com/aliyun/aliyun-oss-go-sdk v3.0.2+incompatible
)

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

Configurer les identifiants d'accès

Configurez les identifiants d'accès à l'aide de la paire AccessKey d'un utilisateur RAM.

1. Dans la console RAM, créez un utilisateur RAM avec une Permanent AccessKey Pair. Enregistrez la paire AccessKey et accordez l'autorisation AliyunOSSFullAccess à cet utilisateur.

2. Utilisez la paire AccessKey de l'utilisateur RAM pour configurer les variables d'environnement.

   Linux

   1. Exécutez les commandes suivantes dans l'interface en ligne de commande pour ajouter les paramètres de variables d'environnement au fichier ~/.bashrc .

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

   2. Exécutez la commande suivante pour appliquer les modifications.

      source ~/.bashrc

   3. Exécutez les commandes suivantes pour vérifier la configuration des variables d'environnement.

      echo $OSS_ACCESS_KEY_ID
      echo $OSS_ACCESS_KEY_SECRET

   macOS

   1. Exécutez la commande suivante dans le terminal pour identifier le shell par défaut.

      echo $SHELL

   2. Effectuez les opérations suivantes selon le type de shell par défaut.

      Zsh

      1. Exécutez les commandes suivantes pour ajouter les paramètres de variables d'environnement au fichier ~/.zshrc.

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

      2. Exécutez la commande suivante pour appliquer les modifications.

         source ~/.zshrc

      3. Exécutez les commandes suivantes pour vérifier la configuration des variables d'environnement.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

      Bash

      1. Exécutez les commandes suivantes pour ajouter les paramètres de variables d'environnement au fichier ~/.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. Exécutez la commande suivante pour appliquer les modifications.

         source ~/.bash_profile

      3. Exécutez les commandes suivantes pour vérifier la configuration des variables d'environnement.

         echo $OSS_ACCESS_KEY_ID
         echo $OSS_ACCESS_KEY_SECRET

   Windows

   CMD

   1. Exécutez les commandes suivantes dans CMD.

      setx OSS_ACCESS_KEY_ID "YOUR_ACCESS_KEY_ID"
      setx OSS_ACCESS_KEY_SECRET "YOUR_ACCESS_KEY_SECRET"

   2. Exécutez les commandes suivantes pour vérifier la configuration des variables d'environnement.

      echo %OSS_ACCESS_KEY_ID%
      echo %OSS_ACCESS_KEY_SECRET%

   PowerShell

   1. Exécutez les commandes suivantes dans 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)

   2. Exécutez les commandes suivantes pour vérifier la configuration des variables d'environnement.

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

Initialiser le client

L'exemple de code suivant initialise un client en utilisant l'endpoint public de la région Chine (Hangzhou) et liste les buckets du compte actuel. Pour obtenir la liste complète des régions et des endpoints, consultez Régions et endpoints.

package main

// Sample code for initializing a client in OSS Go SDK V1

import (
	"fmt"

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

func main() {

	// Load access credentials from environment variables. You must set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// Create an OSS client instance.
	client, _ := oss.New(
		"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
		"",
		"",
		oss.SetCredentialsProvider(&provider),
		oss.AuthVersion(oss.AuthV4),
		oss.Region("cn-hangzhou"),
	)

	// List all buckets.
	buckets, err := client.ListBuckets()
	if err != nil {
		fmt.Printf("Failed to list buckets: %v\n", err)
		return
	}

	// Print the bucket list.
	fmt.Printf("Found %d buckets:\n", len(buckets.Buckets))

	for _, bucket := range buckets.Buckets {
		fmt.Printf("%s\n", bucket.Name)
	}
}

Utiliser un endpoint interne

Pour accéder à OSS via un réseau interne, spécifiez un endpoint interne lors de l'initialisation du client OSS.

// Create an OSS client instance.
client, _ := oss.New(
	"oss-cn-hangzhou-internal.aliyuncs.com", // The internal endpoint of China (Hangzhou) is used as an example.
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("cn-hangzhou"),
)

Utiliser un nom de domaine personnalisé

Pour accéder à OSS à l'aide d'un nom de domaine personnalisé, spécifiez-le comme endpoint et activez l'option CNAME avec oss.UseCname(true) lors de l'initialisation du client.

Avant d'utiliser un nom de domaine personnalisé, assurez-vous d'avoir mappé ce nom de domaine à un bucket. Pour plus d'informations, consultez Accéder à OSS via un nom de domaine personnalisé .

// Specify whether to use a custom domain name as the endpoint. The default value is false.
cname := oss.UseCname(true)

// Create an OSS client instance.
client, _ := oss.New(
	"http://kitkat-cloud.cn", // A custom domain name.
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("cn-hangzhou"),
	cname,
)

Contrôle des délais d'expiration

Utilisez le paramètre oss.Timeout pour définir le délai d'expiration de la connexion HTTP ainsi que le délai d'expiration de lecture/écriture en secondes.

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

// Create an OSS client instance.
client, _ := oss.New(
	"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("cn-hangzhou"),
	time,
)

Définir la taille du pool de connexions

Utilisez le paramètre oss.MaxConns pour ajuster la taille du pool de connexions.

// Set the maximum number of idle connections (MaxIdleConns) to 10. The default value is 100.
// Set the maximum number of idle connections per host (MaxIdleConnsPerHost) to 20. The default value is 100.
// Set the maximum number of connections per host (MaxConnsPerHost) to 50. The default value is empty.
conn := oss.MaxConns(10, 20, 50)

// Create an OSS client instance.
client, _ := oss.New(
	"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("cn-hangzhou"),
	conn,
)

Désactiver la validation des données CRC

Définissez oss.EnableCRC(false) pour désactiver la validation des données CRC.

// Disable CRC data validation.
crc := oss.EnableCRC(false)

// Create an OSS client instance.
client, _ := oss.New(
	"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
	"",
	"",
	oss.SetCredentialsProvider(&provider),
	oss.AuthVersion(oss.AuthV4),
	oss.Region("cn-hangzhou"),
	crc,
)

Version de signature

L'exemple de code suivant initialise un client avec une signature V1. Pour l'initialisation avec une signature V4, consultez Initialiser le client.

package main

// Sample code for initializing a client with a V1 signature in OSS Go SDK V1

import (
	"fmt"

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

func main() {

	// Load access credentials from environment variables. You must set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// Create an OSS client instance.
	client, _ := oss.New(
		"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
		"",
		"",
		oss.SetCredentialsProvider(&provider),
	)

	// List all buckets.
	buckets, err := client.ListBuckets()
	if err != nil {
		fmt.Printf("Failed to list buckets: %v\n", err)
		return
	}

	// Print the bucket list.
	fmt.Printf("Found %d buckets:\n", len(buckets.Buckets))

	for _, bucket := range buckets.Buckets {
		fmt.Printf("%s\n", bucket.Name)
	}
}

Définir le contexte de requête

Utilisez le contexte de requête pour contrôler le cycle de vie des requêtes.

Seul OSS Go SDK 2.2.9 et les versions ultérieures prennent en charge la définition du contexte de requête.

package main

// Sample code for setting the request context in OSS Go SDK V1

import (
	"context"
	"fmt"
	"time"

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

func main() {

	// Load access credentials from environment variables. You must set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// Create an OSS client instance.
	client, _ := oss.New(
		"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
		"",
		"",
		oss.SetCredentialsProvider(&provider),
		oss.AuthVersion(oss.AuthV4),
		oss.Region("cn-hangzhou"),
	)

	// Get the bucket object.
	bucket, _ := client.Bucket("example-bucket-hz")

	// Configure object information.
	key := "oss-browser2-mac-arm64-2.1.0.dmg"       // The path of the object in OSS.
	file_path := "oss-browser2-mac-arm64-2.1.0.dmg" // The local path to save the object.

	// Set the request context.
	ctx := context.Background()

	// Specify that the request context expires in 5 seconds.
	ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
	defer cancel()

	// Download the object from OSS to the specified local path and set the request context.
	err := bucket.GetObjectToFile(key, file_path, oss.WithContext(ctx))
	if err != nil {
		select {
		case <-ctx.Done():
			fmt.Printf("Request canceled or timed out: %v\n", err)
		default:
			fmt.Printf("Download failed: %v\n", err)
		}
		return
	}

	fmt.Printf("Object downloaded: %s -> %s\n", key, file_path)
}

oss: service returned error: StatusCode=404, ErrorCode=NoSuchKey, ErrorMessage="The specified key does not exist.", RequestId=69030EDB2E5F223030953167, Ec=0026-00000001

package main

// Sample code for querying endpoint information in OSS Go SDK V1

import (
	"fmt"

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

func main() {

	fmt.Println("=== Query endpoint information for all supported regions ===\n")

	// Load access credentials from environment variables. You must set OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET.
	provider, _ := oss.NewEnvironmentVariableCredentialsProvider()

	// Create an OSS client instance.
	client, err := oss.New(
		"oss-cn-hangzhou.aliyuncs.com", // The public endpoint of China (Hangzhou) is used as an example.
		"",
		"",
		oss.SetCredentialsProvider(&provider),
		oss.AuthVersion(oss.AuthV4),
		oss.Region("cn-hangzhou"),
	)
	if err != nil {
		fmt.Printf("Failed to create client: %v\n", err)
		return
	}

	// Query endpoint information for all supported regions.
	result, err := client.DescribeRegions()
	if err != nil {
		fmt.Printf("Failed to query endpoint information: %v\n", err)
		return
	}

	// Traverse all region information.
	for _, region := range result.Regions {
		fmt.Printf("Region: %s\n", region.Region)
		fmt.Printf("  Public endpoint (IPv4): %s\n", region.InternetEndpoint)
		fmt.Printf("  Internal endpoint (classic network or VPC): %s\n", region.InternalEndpoint)
		fmt.Printf("  Acceleration endpoint (global upload and download acceleration): %s\n", region.AccelerateEndpoint)
		fmt.Println("--------------------------------------------------------------------------------")
	}

	// Print statistics.
	fmt.Printf("\nFound endpoint information for %d regions\n", len(result.Regions))
}

result, err := client.DescribeRegions(oss.AddParam("regions", "oss-cn-hangzhou"))

Utiliser la paire AccessKey d'un utilisateur RAM

Cette méthode convient aux applications déployées dans un environnement sécurisé qui nécessitent un accès OSS à long terme sans rotation fréquente des identifiants. Initialisez le fournisseur d'identifiants avec la paire AccessKey (AccessKey ID et AccessKey secret) d'un compte Alibaba Cloud ou d'un utilisateur RAM. Cette approche nécessite une maintenance manuelle de la paire AccessKey, ce qui peut introduire des risques de sécurité.

Utiliser des identifiants d'accès temporaires STS

Cette option est destinée aux applications nécessitant un accès temporaire à OSS. Initialisez le fournisseur d'identifiants avec des identifiants temporaires (AccessKey ID, AccessKey secret et Security Token) obtenus via STS. Cette méthode requiert une maintenance manuelle du jeton STS. Pour accéder plusieurs fois à OSS, actualisez manuellement le jeton avant son expiration.

1. Définissez les variables d'environnement à l'aide des identifiants d'identité temporaires.

   Mac OS/Linux/Unix

   Important

   • Utilisez les identifiants d'identité temporaires (AccessKey ID, AccessKey secret et Security Token) obtenus via STS, et non la paire AccessKey (AccessKey ID et AccessKey secret) d'un utilisateur RAM.

   • L'AccessKey ID obtenu via STS commence par « STS. », par exemple « STS. ».

   export OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   export OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   export OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

   Windows

   Important

   • Utilisez les identifiants d'identité temporaires (AccessKey ID, AccessKey secret et Security Token) obtenus via STS, et non la paire AccessKey (AccessKey ID et AccessKey secret) d'un utilisateur RAM.

   • L'AccessKey ID obtenu via STS commence par « STS. », par exemple « STS. ».

   set OSS_ACCESS_KEY_ID=<STS_ACCESS_KEY_ID>
   set OSS_ACCESS_KEY_SECRET=<STS_ACCESS_KEY_SECRET>
   set OSS_SESSION_TOKEN=<STS_SECURITY_TOKEN>

2. Transmettez les informations d'identification via les variables d'environnement.

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   )
   
   func main() {
   	// Obtain access credentials from environment variables. Before you run this sample code, make sure that the OSS_ACCESS_KEY_ID, OSS_ACCESS_KEY_SECRET, and OSS_SESSION_TOKEN environment variables are set.
   	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	// Create an OSSClient instance.
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

Utiliser un ARN de rôle RAM

Recommandé pour les applications nécessitant un accès autorisé à OSS, tel que l'accès inter-comptes. Initialisez le fournisseur d'identifiants en spécifiant l'ARN d'un rôle RAM. L'outil Credentials obtient automatiquement les jetons STS et les actualise avant leur expiration en appelant l'opération AssumeRole. Vous pouvez également attribuer une policy pour restreindre le rôle à un ensemble de permissions plus limité.

1. Ajoutez la dépendance credentials.

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

2. Configurez la paire AccessKey et l'ARN du rôle RAM comme identifiants d'accès.

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type defaultCredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild *defaultCredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewRamRoleArnCredentialsProvider(credential credentials.Credential) defaultCredentialsProvider {
   	return defaultCredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// The credential type. Set the value to ram_role_arn.
   		SetType("ram_role_arn").
   		// The AccessKey ID and AccessKey secret of the RAM user. The values are obtained from environment variables.
   		SetAccessKeyId(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID")).
   		SetAccessKeySecret(os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET")).
   		// The following operations directly use parameter values. You can also add environment variables and use os.Getenv("<variable_name>") to set the corresponding parameters.
   		// The ARN of the RAM role to assume. The value is obtained from an environment variable. Format: acs:ram::$accountID:role/$roleName.
   		SetRoleArn("ALIBABA_CLOUD_ROLE_ARN"). // The standard environment variable name for RoleArn is ALIBABA_CLOUD_ROLE_ARN.
   		// A custom name for the role session to distinguish different tokens.
   		SetRoleSessionName("ALIBABA_CLOUD_ROLE_SESSION_NAME"). // The standard environment variable name for RoleSessionName is ALIBABA_CLOUD_ROLE_SESSION_NAME.
   		// (Optional) Restrict the permissions of the STS token.
   		SetPolicy("").
   		// (Optional) Limit the validity period of the STS token.
   		SetRoleSessionExpiration(3600)
   
   	arnCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   
   	provider := NewRamRoleArnCredentialsProvider(arnCredential)
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   
   	fmt.Printf("client:%#v\n", client)
   }

Utiliser un rôle RAM d'instance ECS

Méthode recommandée pour les applications s'exécutant sur des instances ECS, des instances ECI ou des nœuds worker de Container Service for Kubernetes. Un rôle RAM d'instance ECS associe un rôle à l'instance, permettant l'actualisation automatique du jeton STS sans fournir de paire AccessKey ni de jeton STS. Pour savoir comment obtenir un rôle RAM d'instance ECS, consultez Créer un rôle RAM. Pour savoir comment associer un rôle à une instance ECS, consultez Rôles RAM d'instance.

1. Ajoutez la dépendance credentials.

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

2. Configurez le rôle RAM d'instance ECS comme identifiant d'accès.

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewEcsCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// The credential type. Set the value to ecs_ram_role.
   		SetType("ecs_ram_role").
   		// (Optional) The role name. If you do not specify this parameter, OSS automatically obtains the role. We recommend that you specify the role name to reduce the number of requests.
   		SetRoleName("RoleName")
   
   	ecsCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewEcsCredentialsProvider(ecsCredential)
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   
   }

Utiliser un ARN de rôle OIDC

Pour les applications non approuvées déployées sur des nœuds worker de Container Service for Kubernetes, la fonctionnalité RAM Roles for Service Accounts (RRSA) offre une isolation des identifiants au niveau du pod. Au lieu de partager le rôle RAM d'instance du nœud worker via le service méta global, RRSA monte un fichier de jeton OIDC de compte de service dans chaque pod et injecte la configuration dans les variables d'environnement. L'outil Credentials appelle ensuite l'opération AssumeRoleWithOIDC pour échanger le jeton OIDC contre un jeton STS. Aucune paire AccessKey ni jeton STS n'est requis. Pour plus d'informations, consultez Configurer les permissions RAM pour un ServiceAccount à l'aide de RRSA pour réaliser une isolation des permissions au niveau du pod.

1. Ajoutez la dépendance credentials.

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

2. Configurez le rôle RAM OIDC comme identifiant d'accès.

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewOIDCRoleARNCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// The file path of the OIDC token.
   		SetOIDCTokenFilePath(os.Getenv("ALIBABA_CLOUD_OIDC_TOKEN_FILE")).
   		// The following operations directly use parameter values. You can also add environment variables and use os.Getenv("<variable_name>") to set the corresponding parameters.
   		// The credential type. Set the value to oidc_role_arn.
   		SetType("oidc_role_arn").
   		// The ARN of the OIDC provider. Format: acs:ram::account-id:oidc-provider/provider-name.
   		SetOIDCProviderArn("acs:ram::113511544585****:oidc-provider/TestOidcProvider"). // The standard environment variable name for OIDCProviderArn is ALIBABA_CLOUD_OIDC_PROVIDER_ARN.
   		// A custom name for the role session to distinguish different tokens.
   		SetRoleSessionName("role_session_name"). // The standard environment variable name for RoleSessionName is ALIBABA_CLOUD_ROLE_SESSION_NAME.
   		// The ARN of the role to assume. Format: acs:ram::113511544585****:oidc-provider/TestOidcProvider
   		SetRoleArn("acs:ram::113511544585****:role/testoidc"). // The standard environment variable name for RoleArn is ALIBABA_CLOUD_ROLE_ARN.
   		// (Optional) The policy to use when assuming the role.
   		SetPolicy("").
   		SetSessionExpiration(3600)
   	oidcCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewOIDCRoleARNCredentialsProvider(oidcCredential)
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

Utiliser les identifiants du contexte Function Compute

Convient aux fonctions d'applications déployées dans Function Compute. Function Compute obtient un jeton STS en assumant le rôle de service configuré pour la fonction et le transmet via le paramètre Credentials dans le contexte. Ce jeton STS est valide pendant 36 heures et n'expire pas durant l'exécution de la fonction (maximum 24 heures), aucune actualisation n'est donc nécessaire. Aucune paire AccessKey ni jeton STS n'est requis. Pour savoir comment accorder à Function Compute les permissions d'accès à OSS, consultez Utiliser un rôle de fonction pour accorder à Function Compute les permissions d'accès à d'autres services Alibaba Cloud.

1. Ajoutez les dépendances du contexte Function Compute.

   go get github.com/aliyun/fc-runtime-go-sdk/fc
   go get github.com/aliyun/fc-runtime-go-sdk/fccontext

2. Initialisez le fournisseur d'identifiants en utilisant les identifiants du contexte Function Compute.

   package main
   
   import (
   	"context"
   	"fmt"
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/fc-runtime-go-sdk/fc"
   	"github.com/aliyun/fc-runtime-go-sdk/fccontext"
   )
   
   type GetObjectContext struct {
   	OutputRoute string `json:"outputRoute"`
   	OutputToken string `json:"outputToken"`
   	InputOssUrl string `json:"inputOssUrl"`
   }
   
   type StructEvent struct {
   	GetObjectContext GetObjectContext `json:"getObjectContext"`
   }
   
   func HandleRequest(ctx context.Context, event StructEvent) error {
   	endpoint := event.GetObjectContext.OutputRoute
   	fctx, _ := fccontext.FromContext(ctx)
   	client, err := oss.New(endpoint, fctx.Credentials.AccessKeyId, fctx.Credentials.AccessKeySecret, oss.SecurityToken(fctx.Credentials.SecurityToken))
   	if err != nil {
   		return fmt.Errorf("client new error: %v", err)
   	}
   	fmt.Printf("client:%#v\n", client)
   	return nil
   }
   
   func main() {
   	fc.Start(HandleRequest)
   }

Utiliser un CredentialsURI

Destiné aux applications qui obtiennent leurs identifiants depuis un système externe. L'outil Credentials récupère les jetons STS à partir de l'URI spécifiée et les actualise automatiquement. Aucune paire AccessKey ni jeton STS n'est requis.

1. Pour que l'outil Credentials puisse analyser et utiliser correctement le jeton STS, l'URI doit respecter le protocole de réponse suivant :

   • Code d'état de la réponse : 200

   • Structure du corps de la réponse :

     {
         "Code": "Success",
         "AccessKeySecret": "AccessKeySecret",
         "AccessKeyId": "AccessKeyId",
         "Expiration": "2021-09-26T03:46:38Z",
         "SecurityToken": "SecurityToken"
     }

2. Ajoutez la dépendance credentials.

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

3. Configurez le CredentialsURI comme identifiant d'accès.

   package main
   
   import (
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/credentials-go/credentials"
   )
   
   type Credentials struct {
   	AccessKeyId     string
   	AccessKeySecret string
   	SecurityToken   string
   }
   
   type CredentialsProvider struct {
   	cred credentials.Credential
   }
   
   func (credentials *Credentials) GetAccessKeyID() string {
   	return credentials.AccessKeyId
   }
   
   func (credentials *Credentials) GetAccessKeySecret() string {
   	return credentials.AccessKeySecret
   }
   
   func (credentials *Credentials) GetSecurityToken() string {
   	return credentials.SecurityToken
   }
   
   func (defBuild CredentialsProvider) GetCredentials() oss.Credentials {
   	cred, _ := defBuild.cred.GetCredential()
   	return &Credentials{
   		AccessKeyId:     *cred.AccessKeyId,
   		AccessKeySecret: *cred.AccessKeySecret,
   		SecurityToken:   *cred.SecurityToken,
   	}
   }
   
   func NewCredentialsUriCredentialsProvider(credential credentials.Credential) CredentialsProvider {
   	return CredentialsProvider{
   		cred: credential,
   	}
   }
   
   func main() {
   	config := new(credentials.Config).
   		// The credential type. Set the value to credentials_uri.
   		SetType("credentials_uri").
   		// Specify the URL address. You can also set an environment variable and use os.Getenv("<variable_name>") to pass the parameter.
   		// The standard environment variable name for URLCredential is ALIBABA_CLOUD_CREDENTIALS_URI.
   		SetURLCredential("http://127.0.0.1")
   	uriCredential, err := credentials.NewCredential(config)
   	if err != nil {
   		return
   	}
   	provider := NewCredentialsUriCredentialsProvider(uriCredential)
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", client)
   }

Utiliser une paire AccessKey à rotation automatique

Convient aux applications nécessitant un accès OSS à long terme mais déployées dans des environnements où le risque de fuite de paire AccessKey existe. Initialisez le fournisseur d'identifiants avec une ClientKey. Key Management Service (KMS) fait tourner automatiquement la paire AccessKey de l'utilisateur RAM géré selon un calendrier périodique, transformant ainsi un identifiant statique en identifiant dynamique. KMS prend également en charge la rotation immédiate pour un remplacement rapide en cas de fuite. Pour savoir comment obtenir une ClientKey, consultez Créer un point d'accès d'application.

1. Ajoutez la dépendance du client d'identifiants.

   go get -u github.com/aliyun/aliyun-secretsmanager-client-go

2. Créez un fichier de configuration nommé secretsmanager.properties.

   # Access credential type
   credentials_type=client_key
   
   # The password used to decrypt the client key. The password can be read from an environment variable or a file.
   client_key_password_from_env_variable=#your client key private key password environment variable name#
   client_key_password_from_file_path=#your client key private key password file path#
   
   # The path of the client key's private key file.
   client_key_private_key_path=#your client key private key file path#
   
   # The region of the associated KMS service.
   cache_client_region_id=[{"regionId":"#regionId#"}]

3. Utilisez le fichier de configuration pour transmettre les informations d'identification.

   package main
   
   import (
   	"encoding/json"
   	"fmt"
   	"os"
   
   	"github.com/aliyun/aliyun-oss-go-sdk/oss"
   	"github.com/aliyun/aliyun-secretsmanager-client-go/sdk"
   )
   
   type defaultCredentials struct {
   	config *oss.Config
   }
   
   func (defCre *defaultCredentials) GetAccessKeyID() string {
   	return defCre.config.AccessKeyID
   }
   
   func (defCre *defaultCredentials) GetAccessKeySecret() string {
   	return defCre.config.AccessKeySecret
   }
   
   func (defCre *defaultCredentials) GetSecurityToken() string {
   	return defCre.config.SecurityToken
   }
   
   type defaultCredentialsProvider struct {
   	config *oss.Config
   }
   
   func (defBuild *defaultCredentialsProvider) GetCredentials() oss.Credentials {
   	return &defaultCredentials{config: defBuild.config}
   }
   func NewDefaultCredentialsProvider(accessID, accessKey, token string) (defaultCredentialsProvider, error) {
   	var provider defaultCredentialsProvider
   	if accessID == "" {
   		return provider, fmt.Errorf("access key id is empty!")
   	}
   	if accessKey == "" {
   		return provider, fmt.Errorf("access key secret is empty!")
   	}
   	config := &oss.Config{
   		AccessKeyID:     accessID,
   		AccessKeySecret: accessKey,
   		SecurityToken:   token,
   	}
   	return defaultCredentialsProvider{
   		config,
   	}, nil
   }
   
   func main() {
   	client, err := sdk.NewClient()
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	secretInfo, err := client.GetSecretInfo("#secretName#")
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("SecretValue:%s\n", secretInfo.SecretValue)
   	var m map[string]string
   	err = json.Unmarshal([]byte(secretInfo.SecretValue), &m)
   	if err != nil {
   		fmt.Println("Error decoding JSON:", err)
   		os.Exit(-1)
   	}
   	accessKeyId := m["AccessKeyId"]
   	accessKeySecret := m["AccessKeySecret"]
   	provider, err := NewDefaultCredentialsProvider(accessKeyId, accessKeySecret, "")
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
   	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
   	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
   	clientOptions = append(clientOptions, oss.Region("yourRegion"))
   	// Set the signature version.
   	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
   	ossClient, err := oss.New("yourEndpoint", "", "", clientOptions...)
   	if err != nil {
   		fmt.Println("Error:", err)
   		os.Exit(-1)
   	}
   	fmt.Printf("client:%#v\n", ossClient)
   }

Utiliser des identifiants d'accès personnalisés

Si aucune des méthodes précédentes ne répond à vos besoins, implémentez un fournisseur d'identifiants personnalisé à l'aide de l'interface Credential Providers. Si les identifiants sous-jacents sont basés sur STS, gérez l'actualisation du jeton.

package main

import (
	"fmt"
	"os"

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

type CustomerCredentialsProvider struct {
	config *oss.Config
}

func NewCustomerCredentialsProvider() CustomerCredentialsProvider {
	return CustomerCredentialsProvider{}
}

func (s CustomerCredentialsProvider) GetCredentials() oss.Credentials {
	// Return long-term credentials.
	config := &oss.Config{
		AccessKeyID:     "id",
		AccessKeySecret: "secret",
	}
	return &CustomerCredentialsProvider{
		config,
	}
	// Return temporary credentials.
	//config := &oss.Config{
	//    AccessKeyID:     "id",
	//    AccessKeySecret: "secret",
	//    SecurityToken:   "token",
	//}
	//return &CustomerCredentialsProvider{
	//    config,
	//}
}

func (s *CustomerCredentialsProvider) GetAccessKeyID() string {
	return s.config.AccessKeyID
}

func (s *CustomerCredentialsProvider) GetAccessKeySecret() string {
	return s.config.AccessKeySecret
}

func (s *CustomerCredentialsProvider) GetSecurityToken() string {
	return s.config.SecurityToken
}

func main() {
	provider := NewCustomerCredentialsProvider()
	// Set yourEndpoint to the endpoint of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the endpoint to https://oss-cn-hangzhou.aliyuncs.com. For other regions, set the endpoint as needed.
	// Set yourRegion to the region of the bucket. For example, if the bucket is in the China (Hangzhou) region, set the region to cn-hangzhou. For other regions, set the region as needed.
	clientOptions := []oss.ClientOption{oss.SetCredentialsProvider(&provider)}
	clientOptions = append(clientOptions, oss.Region("yourRegion"))
	// Set the signature version.
	clientOptions = append(clientOptions, oss.AuthVersion(oss.AuthV4))
	client, err := oss.New("yourEndpoint", "", "", clientOptions...)
	if err != nil {
		fmt.Println("Error:", err)
		os.Exit(-1)
	}
	fmt.Printf("client:%#v\n", client)
}

Comment résoudre l'erreur AccessDenied lors de l'utilisation du SDK ?

L'erreur AccessDenied indique généralement des permissions insuffisantes. Suivez ces étapes pour la résoudre :

1. Vérifiez l'AccessKey ID et l'AccessKey secret : assurez-vous d'utiliser les bons identifiants.

2. Contrôlez les permissions de l'utilisateur RAM : confirmez que l'utilisateur RAM dispose des permissions nécessaires pour les opérations sur les buckets ou les objets.

3. Examinez la politique de bucket : si le message d'erreur mentionne « Access denied by bucket policy », cela signifie que l'accès a été refusé par une politique de bucket.

4. Pour plus d'informations sur la façon d'identifier d'autres types d'erreurs et de résoudre les erreurs courantes de contrôle d'accès, consultez Gestion des erreurs.