Tous les produits
Search
Centre de documentation

Object Storage Service:Téléchargement fractionné (Go SDK V1)

Dernière mise à jour :Sep 25, 2026

Object Storage Service (OSS) propose une fonctionnalité de téléchargement fractionné pour les objets volumineux. Ce processus consiste à diviser un objet volumineux en parties plus petites, à les télécharger indépendamment, puis à appeler l'API CompleteMultipartUpload pour assembler les parties en un seul objet. Cette approche permet la reprise des téléchargements interrompus.

Notes

  • Cette rubrique utilise le point de terminaison public de la région Chine (Hangzhou). Si vous souhaitez accéder à OSS depuis d'autres services Alibaba Cloud situés dans la même région, utilisez un point de terminaison interne. Pour plus d'informations sur les régions et les points de terminaison OSS, consultez Régions et points de terminaison.

  • Dans cette rubrique, les identifiants d'accès sont récupérés à partir des variables d'environnement. Pour savoir comment configurer les identifiants d'accès, consultez Configurer les identifiants d'accès.

  • Cette rubrique explique comment créer une instance OSSClient avec un point de terminaison OSS. Pour d'autres configurations, telles que l'utilisation d'un nom de domaine personnalisé ou l'authentification via des identifiants du Security Token Service (STS), consultez Configurer un client (Go SDK V1).

  • Le téléchargement fractionné utilise les méthodes InitiateMultipartUpload, UploadPart et CompleteMultipartUpload. Vous devez disposer de l'autorisation oss:PutObject. Accorder des politiques d'accès personnalisées à un utilisateur RAM.

  • L'exemple de code présenté dans cette rubrique nécessite Go SDK V2.2.5 ou une version ultérieure.

Procédure de téléchargement fractionné

Le téléchargement fractionné s'effectue en trois étapes :

  1. Initialisez le téléchargement fractionné.

    Appelez la méthode Bucket.InitiateMultipartUpload. OSS renvoie un ID de téléchargement unique au niveau mondial.

  2. Téléchargez les parties.

    Appelez la méthode Bucket.UploadPart pour télécharger les données de chaque partie.

    Remarque
    • Pour un même ID de téléchargement, le numéro de partie identifie la position relative d'une partie au sein de l'objet. Si vous téléchargez de nouvelles données avec le même numéro de partie, les données existantes de cette partie dans OSS sont écrasées.

    • OSS renvoie le hachage MD5 des données de la partie reçues dans l'en-tête ETag.

    • OSS calcule le hachage MD5 des données téléchargées et le compare au hachage MD5 calculé par le SDK. Si les deux hachages MD5 ne correspondent pas, le code d'erreur InvalidDigest est renvoyé.

  3. Finalisez le téléchargement fractionné.

    Une fois toutes les parties téléchargées, appelez la méthode Bucket.CompleteMultipartUpload pour assembler toutes les parties en un objet complet.

Exemple de code

Utilisez le code suivant pour effectuer un téléchargement fractionné complet.

package main

import (
	"fmt"
	"log"
	"os"

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

func main() {
	// Obtain access credentials from environment variables. Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured.
	provider, err := oss.NewEnvironmentVariableCredentialsProvider()
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	// Create an OSSClient instance.
	// Set yourEndpoint to the endpoint of the bucket. For example, for a bucket 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 where the bucket is located. For example, for a bucket 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 {
		log.Fatalf("Error: %v", err)
	}

	// Set the bucket name.
	bucketName := "examplebucket"
	// Set the full path of the object. The full path cannot contain the bucket name.
	objectName := "exampleobject.txt"
	// Set the full path of the local file. If you do not specify a local path, the file is uploaded from the local path that corresponds to the project of the sample program.
	localFilename := "/localpath/exampleobject.txt"

	bucket, err := client.Bucket(bucketName)
	if err != nil {
		log.Fatalf("Error: %v", err)
	}

	// Set the part size in bytes. In this example, the part size is set to 5 MB.
	partSize := int64(5 * 1024 * 1024)

	// Call the multipart upload function.
	if err := uploadMultipart(bucket, objectName, localFilename, partSize); err != nil {
		log.Fatalf("Failed to upload multipart: %v", err)
	}

}

// Multipart upload function.
func uploadMultipart(bucket *oss.Bucket, objectName, localFilename string, partSize int64) error {
	// Split the local file into parts.
	chunks, err := oss.SplitFileByPartSize(localFilename, partSize)
	if err != nil {
		return fmt.Errorf("failed to split file into chunks: %w", err)
	}

	// Open the local file.
	file, err := os.Open(localFilename)
	if err != nil {
		return fmt.Errorf("failed to open file: %w", err)
	}
	defer file.Close()

	// Step 1: Initialize a multipart upload event.
	imur, err := bucket.InitiateMultipartUpload(objectName)
	if err != nil {
		return fmt.Errorf("failed to initiate multipart upload: %w", err)
	}

	// Step 2: Upload parts.
	var parts []oss.UploadPart
	for _, chunk := range chunks {
		part, err := bucket.UploadPart(imur, file, chunk.Size, chunk.Number)
		if err != nil {
			// If a part fails to be uploaded, try to abort the multipart upload task.
			if abortErr := bucket.AbortMultipartUpload(imur); abortErr != nil {
				log.Printf("Failed to abort multipart upload: %v", abortErr)
			}
			return fmt.Errorf("failed to upload part: %w", err)
		}
		parts = append(parts, part)
	}

	// Set the access control list (ACL) of the object to private. By default, the ACL of the object is inherited from the bucket.
	objectAcl := oss.ObjectACL(oss.ACLPrivate)

	// Step 3: Complete the multipart upload.
	_, err = bucket.CompleteMultipartUpload(imur, parts, objectAcl)
	if err != nil {
		// If the upload fails to be completed, try to abort the upload.
		if abortErr := bucket.AbortMultipartUpload(imur); abortErr != nil {
			log.Printf("Failed to abort multipart upload: %v", abortErr)
		}
		return fmt.Errorf("failed to complete multipart upload: %w", err)
	}

	log.Printf("Multipart upload completed successfully.")
	return nil
}

FAQ

Comment annuler un événement de téléchargement fractionné ?

Utilisez la méthode Bucket.AbortMultipartUpload pour annuler un événement de téléchargement fractionné dans les scénarios suivants.

  1. Erreur de fichier :

    • Si vous découvrez qu'un fichier est corrompu ou contient du code malveillant pendant le téléchargement, annulez l'opération pour prévenir les menaces potentielles.

  2. Réseau instable :

    • Si la connexion réseau est instable ou interrompue, des parties peuvent être perdues ou corrompues pendant le téléchargement. Annulez l'opération et redémarrez-la pour garantir l'intégrité et la cohérence des données.

  3. Limites des ressources :

    • Si votre espace de stockage est limité et que le fichier à télécharger est trop volumineux, annulez le téléchargement pour libérer des ressources de stockage. Cela vous permet d'allouer les ressources à des tâches plus prioritaires.

  4. Opération accidentelle :

    • Si vous lancez par erreur une tâche de téléchargement inutile ou si vous téléchargez une version incorrecte d'un fichier, annulez l'événement de téléchargement.

...
if err = bucket.AbortMultipartUpload(imur); err != nil {
log.Fatalf("failed to abort multipart upload: %w", err)
}

log.Printf("Multipart upload aborted successfully.")

Comment répertorier les parties téléchargées ?

Utilisez la méthode Bucket.ListUploadedParts pour répertorier les parties qui ont été téléchargées avec succès pour un événement de téléchargement fractionné spécifique dans les scénarios suivants.

Surveiller la progression du téléchargement :

  1. Téléchargements de fichiers volumineux :

    • Lorsque vous téléchargez un fichier volumineux, répertoriez les parties téléchargées pour vous assurer que l'opération se déroule comme prévu et identifier rapidement tout problème.

  2. Reprise des téléchargements :

    • Si le réseau est instable ou si le téléchargement est interrompu, consultez les parties téléchargées pour décider s'il convient de retélécharger les parties restantes. Cela facilite la reprise du téléchargement.

  3. Dépannage :

    • Si une erreur survient pendant le téléchargement, vérifiez les parties téléchargées pour localiser rapidement la source du problème. Par exemple, si une partie spécifique échoue, traitez le problème en conséquence.

  4. Gestion des ressources :

    • Dans les scénarios où vous devez contrôler strictement l'utilisation des ressources, surveillez la progression du téléchargement pour mieux gérer l'espace de stockage et la bande passante. Cela garantit une utilisation efficace des ressources.

...	
if lsRes, err := bucket.ListUploadedParts(imur); err != nil {
log.Fatalf("Failed to list uploaded parts: %v", err)
}

for _, upload := range lsRes.UploadedParts {
log.Printf("List PartNumber: %d, ETag: %s, LastModified: %v\n", upload.PartNumber, upload.ETag, upload.LastModified)
}

Répertorier les événements de téléchargement fractionné

Utilisez la méthode Bucket.ListMultipartUploads pour répertorier tous les événements de téléchargement fractionné en cours dans un compartiment dans les scénarios suivants.

Scénarios de surveillance :

  1. Gestion des téléchargements de fichiers par lots :

    • Lorsque vous devez télécharger de nombreux fichiers, utilisez la méthode ListMultipartUploads pour surveiller toutes les activités de téléchargement fractionné en temps réel. Cela garantit que tous les fichiers sont correctement téléchargés par parties.

  2. Détection et récupération des pannes :

    • Si des problèmes réseau ou d'autres pannes surviennent pendant le téléchargement, certaines parties peuvent échouer. En surveillant les événements de téléchargement fractionné en cours, détectez rapidement ces problèmes et prenez les mesures nécessaires pour reprendre les téléchargements.

  3. Optimisation et gestion des ressources :

    • Lors de téléchargements de fichiers à grande échelle, la surveillance des événements de téléchargement fractionné en cours peut aider à optimiser l'allocation des ressources. Par exemple, ajustez l'utilisation de la bande passante ou optimisez la politique de téléchargement en fonction de la progression.

  4. Migration de données :

    • Lorsque vous effectuez un projet de migration de données à grande échelle, surveillez tous les événements de téléchargement fractionné en cours pour assurer le bon déroulement de la tâche de migration. Cela vous permet de détecter et de résoudre rapidement tout problème potentiel.

Paramètres

Paramètre

Description

Delimiter

Caractère utilisé pour regrouper les noms d'objets. Tous les noms d'objets contenant le préfixe spécifié et apparaissant avant la première occurrence du caractère délimiteur sont regroupés en un seul élément.

MaxUploads

Nombre maximal d'événements de téléchargement fractionné à renvoyer. La valeur par défaut et la valeur maximale sont toutes deux de 1000.

KeyMarker

Événements de téléchargement fractionné dont les noms d'objets sont supérieurs, selon l'ordre lexicographique, à la valeur du paramètre KeyMarker. Vous pouvez utiliser ce paramètre conjointement avec le paramètre UploadIDMarker pour spécifier la position de départ des résultats à renvoyer.

Prefix

Préfixe que les noms d'objets renvoyés doivent contenir. Notez que si vous utilisez le paramètre Prefix dans une requête, les noms d'objets renvoyés contiennent toujours le préfixe.

UploadIDMarker

Position de départ des résultats à renvoyer. Ce paramètre est utilisé conjointement avec le paramètre KeyMarker.

  • Si le paramètre KeyMarker n'est pas défini, OSS ignore ce paramètre.

  • Si le paramètre KeyMarker est défini, les résultats de la requête incluent les éléments suivants :

    • Événements de téléchargement fractionné dont les noms d'objets sont supérieurs, selon l'ordre lexicographique, à la valeur du paramètre KeyMarker.

    • Événements de téléchargement fractionné dont les noms d'objets sont identiques à la valeur du paramètre KeyMarker, mais dont les ID de téléchargement sont supérieurs à la valeur du paramètre UploadIDMarker.

  • Utilisez les paramètres par défaut.

    ...
    lsRes, err := bucket.ListMultipartUploads(oss.KeyMarker(keyMarker), oss.UploadIDMarker(uploadIdMarker))
    if err != nil {
    log.Fatalf("failed to list multipart uploads: %w", err)
    }
    
    for _, upload := range lsRes.Uploads {
    log.Printf("Upload: %s, UploadID: %s\n", upload.Key, upload.UploadID)
    }
  • Spécifiez le préfixe comme file.

    ...
    lsRes, err := bucket.ListMultipartUploads(oss.Prefix('file'))
    if err != nil {
    log.Fatalf("failed to list multipart uploads with prefix: %w", err)
    }
    
    log.Printf("Uploads:", lsRes.Uploads)
  • Spécifiez un maximum de 100 résultats à renvoyer.

    ...
    lsRes, err := bucket.ListMultipartUploads(oss.MaxUploads(100))
    if err != nil {
    log.Fatalf("failed to list multipart uploads with limit: %w", err)
    }
    
    log.Printf("Uploads:", lsRes.Uploads)
  • Spécifiez le préfixe comme file et un maximum de 100 résultats à renvoyer.

    ...
    lsRes, err := bucket.ListMultipartUploads(oss.Prefix("file"), oss.MaxUploads(100))
    if err != nil {
    log.Fatalf("failed to list multipart uploads with prefix and limit: %w", err)
    }
    
    log.Printf("Uploads:", lsRes.Uploads)

Références

  • Pour l'exemple de code complet relatif au téléchargement fractionné, consultez Exemple GitHub.

  • Un téléchargement fractionné complet implique trois opérations API. Pour plus d'informations sur ces opérations, consultez les rubriques suivantes :

    • Pour plus d'informations sur l'opération API utilisée pour initialiser un événement de téléchargement fractionné, consultez InitiateMultipartUpload.

    • Pour plus d'informations sur l'opération API utilisée pour télécharger une partie, consultez UploadPart.

    • Pour plus d'informations sur l'opération API utilisée pour finaliser un téléchargement fractionné, consultez CompleteMultipartUpload.

  • Pour plus d'informations sur l'opération API utilisée pour annuler un événement de téléchargement fractionné, consultez AbortMultipartUpload.

  • Pour plus d'informations sur l'opération API utilisée pour répertorier les parties téléchargées, consultez ListUploadedParts.

  • Pour plus d'informations sur l'opération API utilisée pour répertorier tous les événements de téléchargement fractionné en cours (événements initiés mais non encore finalisés ou annulés), consultez ListMultipartUploads.