Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.

Utilitaires Amazon S3

Gestionnaires de transfert Amazon S3

Les gestionnaires de chargement et de téléchargement d'Amazon S3 peuvent diviser des objets volumineux afin qu'ils puissent être transférés en plusieurs parties, en parallèle. Cela permet de reprendre facilement les transferts interrompus.

Gestionnaire de téléchargement Amazon S3

Le gestionnaire de téléchargement Amazon S3 détermine si un fichier peut être divisé en parties plus petites et chargé en parallèle. Vous pouvez personnaliser le nombre de téléchargements parallèles et la taille des parties téléchargées.

L'exemple suivant utilise Amazon S3 Uploader pour charger un fichier. L'utilisation Uploader est similaire à l's3.PutObject()opération.

import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/feature/s3/manager"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Printf("error: %v", err)
    return
}

client := s3.NewFromConfig(cfg)

uploader := manager.NewUploader(client)
result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-object-key"),
    Body:   uploadFile,
})

Options de configuration

Lorsque vous instanciez une Uploader instance à l'aide de NewUploader, vous pouvez spécifier plusieurs options de configuration pour personnaliser le mode de chargement des objets. Les options sont remplacées en fournissant un ou plusieurs arguments à. NewUploader Ces options sont les suivantes :

La Concurrency valeur limite le nombre simultané de téléchargements partiels pouvant avoir lieu pour un Upload appel donné. Il ne s'agit pas d'une limite globale de simultanéité des clients. Modifiez les valeurs de Concurrency configuration PartSize et pour trouver la configuration optimale. Par exemple, les systèmes dotés de connexions à haut débit peuvent envoyer de plus grandes parties et un plus grand nombre de téléchargements en parallèle.

Par exemple, votre application est configurée Uploader avec un paramètre Concurrency de5. Si votre application appelle ensuite Upload depuis deux goroutines différentes, il en résulte des téléchargements partiels 10 simultanés (2 goroutines* 5). Concurrency

Voici un exemple de définition de la taille de pièce par défaut lors de Uploader la création :

uploader := manager.NewUploader(client, func(u *Uploader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

Pour plus d'informations sur Uploader ses configurations, consultez Uploader dans la référence de l' AWS SDK pour Go API.

PutObjectInput Body Field (io. ReadSeeker par rapport à io.Reader)

Le Body champ de la s3.PutObjectInput structure est un io.Reader type. Toutefois, ce champ peut être rempli avec un type satisfaisant à la fois à l'io.ReaderAtinterface io.ReadSeeker et afin d'améliorer l'utilisation des ressources applicatives de l'environnement hôte. L'exemple suivant crée le type ReadSeekerAt qui satisfait les deux interfaces :

type ReadSeekerAt interface {
    io.ReadSeeker
    io.ReaderAt
}

Pour les io.Reader types, les octets du lecteur doivent être mis en mémoire tampon avant que la partie puisse être téléchargée. Lorsque vous augmentez la Concurrency valeur PartSize ou, la mémoire (RAM) requise pour cette opération Uploader augmente de manière significative. La mémoire requise est d'PartSizeenviron* Concurrency. Par exemple, la spécification de 100 Mo pour PartSize et 10 pour Concurrency nécessite au moins 1 Go.

Comme un io.Reader type ne peut pas déterminer sa taille avant de lire ses octets, il Uploader ne peut pas calculer le nombre de parties qui seront téléchargées. Par conséquent, Uploader vous pouvez atteindre la limite de téléchargement Amazon S3 de 10 000 parties pour les fichiers volumineux si vous la définissez PartSize trop faible. Si vous essayez de télécharger plus de 10 000 pièces, le téléchargement s'arrête et renvoie un message d'erreur.

Pour body les valeurs qui implémentent le ReadSeekerAt type, le contenu du corps Uploader n'est pas mis en mémoire tampon avant de l'envoyer à Amazon S3. Uploadercalcule le nombre de pièces attendu avant de télécharger le fichier sur Amazon S3. Si la valeur actuelle de PartSize nécessite plus de 10 000 pièces pour télécharger le fichier, Uploader augmente la valeur de taille des pièces afin de réduire le nombre de pièces nécessaires.

Gestion des échecs de téléchargement

Si un chargement sur Amazon S3 échoue, Uploader utilise par défaut l'AbortMultipartUploadopération Amazon S3 pour supprimer les parties téléchargées. Cette fonctionnalité garantit que les téléchargements échoués ne consomment pas le stockage Amazon S3.

Vous pouvez définir le LeavePartsOnError paramètre sur true afin que les parties téléchargées Uploader ne soient pas supprimées avec succès. Cela est utile pour reprendre des téléchargements partiellement terminés. Pour opérer sur les pièces téléchargées, vous devez obtenir le code UploadID de l'échec du téléchargement. L'exemple suivant montre comment utiliser le type manager.MultiUploadFailure d'interface d'erreur pour obtenir leUploadID.

result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-object-key"),
    Body:   uploadFile,
})
output, err := u.upload(input)
if err != nil {
    var mu manager.MultiUploadFailure
    if errors.As(err, &mu) {
        // Process error and its associated uploadID
        fmt.Println("Error:", mu)
        _ = mu.UploadID() // retrieve the associated UploadID
    } else {
        // Process error generically
        fmt.Println("Error:", err.Error())
    }
    return
}

Remplacer les options de téléchargement par téléchargement

Vous pouvez remplacer les Uploader options lors de l'appel Upload en fournissant un ou plusieurs arguments à la méthode. Ces dérogations sont des modifications sûres pour la simultanéité et n'affectent pas les téléchargements en cours, ni les appels ultérieurs au responsable. Upload Par exemple, pour remplacer la PartSize configuration d'une demande de téléchargement spécifique :

params := &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-key"),
    Body:   myBody,
}
resp, err := uploader.Upload(context.TODO(), params, func(u *manager.Uploader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

Exemples

Charger un dossier sur Amazon S3

L'exemple suivant utilise le path/filepath package pour rassembler de manière récursive une liste de fichiers et les télécharger dans le compartiment Amazon S3 spécifié. Les clés des objets Amazon S3 sont préfixées par le chemin relatif du fichier.

package main

import (
    "context"
    "log"
    "os"
    "path/filepath"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

var (
    localPath string
    bucket    string
    prefix    string
)

func init() {
    if len(os.Args) != 4 {
        log.Fatalln("Usage:", os.Args[0], "<local path> <bucket> <prefix>")
    }
    localPath = os.Args[1]
    bucket = os.Args[2]
    prefix = os.Args[3]
}

func main() {
    walker := make(fileWalk)
    go func() {
        // Gather the files to upload by walking the path recursively 
        if err := filepath.Walk(localPath, walker.Walk); err != nil {
            log.Fatalln("Walk failed:", err)
        }
        close(walker)
    }()

    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        log.Fatalln("error:", err)
    }
    
    // For each file found walking, upload it to Amazon S3
    uploader := manager.NewUploader(s3.NewFromConfig(cfg))
    for path := range walker {
        rel, err := filepath.Rel(localPath, path)
        if err != nil {
            log.Fatalln("Unable to get relative path:", path, err)
        }
        file, err := os.Open(path)
        if err != nil {
            log.Println("Failed opening file", path, err)
            continue
        }
        defer file.Close()
        result, err := uploader.Upload(context.TODO(), &s3.PutObjectInput{
            Bucket: &bucket,
            Key:    aws.String(filepath.Join(prefix, rel)),
            Body:   file,
        })
        if err != nil {
            log.Fatalln("Failed to upload", path, err)
        }
        log.Println("Uploaded", path, result.Location)
    }
}

type fileWalk chan string

func (f fileWalk) Walk(path string, info os.FileInfo, err error) error {
    if err != nil {
        return err
    }
    if !info.IsDir() {
        f <- path
    }
    return nil
}

Gestionnaire de téléchargement

Le gestionnaire Amazon S3 Downloader détermine si un fichier peut être divisé en parties plus petites et téléchargé en parallèle. Vous pouvez personnaliser le nombre de téléchargements parallèles et la taille des parties téléchargées.

Exemple : téléchargement d'un fichier

L'exemple suivant utilise Amazon S3 Downloader pour télécharger un fichier. L'utilisation Downloader est similaire à celle du s3. GetObjectopération.

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/feature/s3/manager"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Println("error:", err)
    return
}

client := s3.NewFromConfig(cfg)

downloader := manager.NewDownloader(client)
numBytes, err := downloader.Download(context.TODO(), downloadFile, &s3.GetObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"), 
    Key:    aws.String("my-key"),
})

Le downloadFile paramètre est un io.WriterAt type. L'WriterAtinterface permet Downloader d'écrire plusieurs parties du fichier en parallèle.

Options de configuration

Lorsque vous instanciez une Downloader instance, vous pouvez spécifier des options de configuration pour personnaliser le mode de téléchargement des objets :

La Concurrency valeur limite le nombre de téléchargements partiels simultanés qui peuvent avoir lieu pour un Download appel donné. Il ne s'agit pas d'une limite globale de simultanéité des clients. Modifiez les valeurs de Concurrency configuration PartSize et pour trouver la configuration optimale. Par exemple, les systèmes dotés de connexions à haut débit peuvent recevoir des pièces plus volumineuses et un plus grand nombre de téléchargements en parallèle.

Par exemple, votre application est configurée Downloader avec un Concurrency de5. Votre application appelle ensuite Download depuis deux goroutines différentes, ce qui se traduira par des téléchargements partiels 10 simultanés (2 goroutines* 5). Concurrency

Pour plus d'informations sur les autres options de configuration Downloader et sur ses autres options de configuration, consultez Manager.Downloader dans la référence de l' AWS SDK pour Go API.

Remplacer les options du téléchargeur par téléchargement

Vous pouvez remplacer les Downloader options lors de l'appel Download en fournissant un ou plusieurs arguments fonctionnels à la méthode. Ces dérogations sont des modifications sûres en matière de simultanéité et n'affectent pas les téléchargements en cours, ni les Download appels ultérieurs au responsable. Par exemple, pour remplacer la PartSize configuration d'une demande de téléchargement spécifique :

params := &s3.GetObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("my-key"),
}
resp, err := downloader.Download(context.TODO(), targetWriter, params, func(u *manager.Downloader) {
    u.PartSize = 10 * 1024 * 1024, // 10 MiB
})

Exemples

Télécharger tous les objets d'un bucket

L'exemple suivant utilise la pagination pour rassembler une liste d'objets à partir d'un compartiment Amazon S3. Il télécharge ensuite chaque objet dans un fichier local.

package main

import (
    "context"
    "fmt"
    "log"
    "os"
    "path/filepath"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/feature/s3/manager"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

var (
    Bucket         = "amzn-s3-demo-bucket" // Download from this bucket
    Prefix         = "logs/"    // Using this key prefix
    LocalDirectory = "s3logs"   // Into this directory
)

func main() {
    cfg, err := config.LoadDefaultConfig(context.TODO())
    if err != nil {
        log.Fatalln("error:", err)
    }

    client := s3.NewFromConfig(cfg)
    manager := manager.NewDownloader(client)

    paginator := s3.NewListObjectsV2Paginator(client, &s3.ListObjectsV2Input{
        Bucket: &Bucket,
        Prefix: &Prefix,
    })

    for paginator.HasMorePages() {
        page, err := paginator.NextPage(context.TODO())
        if err != nil {
            log.Fatalln("error:", err)
        }
        for _, obj := range page.Contents {
            if err := downloadToFile(manager, LocalDirectory, Bucket, aws.ToString(obj.Key)); err != nil {
                log.Fatalln("error:", err)
            }
        }
    }
}

func downloadToFile(downloader *manager.Downloader, targetDirectory, bucket, key string) error {
    // Create the directories in the path
    file := filepath.Join(targetDirectory, key)
    if err := os.MkdirAll(filepath.Dir(file), 0775); err != nil {
        return err
    }

    // Set up the local file
    fd, err := os.Create(file)
    if err != nil {
        return err
    }
    defer fd.Close()

    // Download the file using the AWS SDK for Go
    fmt.Printf("Downloading s3://%s/%s to %s...\n", bucket, key, file)
    _, err = downloader.Download(context.TODO(), fd, &s3.GetObjectInput{Bucket: &bucket, Key: &key})

    return err
}

GetBucketRegion

GetBucketRegionest une fonction utilitaire permettant de déterminer l'emplacement AWS régional d'un compartiment Amazon S3. GetBucketRegionprend un client Amazon S3 et l'utilise pour déterminer l'emplacement du compartiment demandé dans la AWS partition associée à la région configurée du client.

Par exemple, pour trouver la région du compartiment amzn-s3-demo-bucket :

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    log.Println("error:", err)
    return
}

bucket := "amzn-s3-demo-bucket"
region, err := manager.GetBucketRegion(ctx, s3.NewFromConfig(cfg), bucket)
if err != nil {
    var bnf manager.BucketNotFound
    if errors.As(err, &bnf) {
        log.Printf("unable to find bucket %s's Region\n", bucket)
    } else {
        log.Println("error:", err)
    }
    return
}
fmt.Printf("Bucket %s is in %s region\n", bucket, region)

Si elle n'GetBucketRegionest pas en mesure de déterminer l'emplacement d'un bucket, la fonction renvoie un type BucketNotFoundd'erreur, comme indiqué dans l'exemple.

Entrée de streaming invisible

Pour les opérations d'API telles que PutObject etUploadPart, le client Amazon S3 s'attend à ce que la valeur du paramètre Body d'entrée implémente l'interface io.Seeker par défaut. L'io.Seekerinterface est utilisée par le client pour déterminer la longueur de la valeur à télécharger et pour calculer le hachage de la charge utile pour la signature de la demande. Si la valeur du paramètre Body d'entrée n'est pas io.Seeker implémentée, votre application recevra un message d'erreur.

operation error S3: PutObject, failed to compute payload hash: failed to seek
body to start, request stream is not seekable

Vous pouvez modifier ce comportement en modifiant la méthode d'opération à l'Intergicielaide d'options fonctionnelles. L'APIOptionsassistant With renvoie une option fonctionnelle pour zéro ou plusieurs mutateurs intergiciels. Pour désactiver le calcul du hachage de la charge utile par le client et utiliser la signature de demande de charge utile non signée, ajoutez v4. SwapComputePayloadSHA256ForUnsignedPayloadMiddleware.

resp, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
    Bucket: &bucketName,
    Key: &objectName,
    Body: bytes.NewBuffer([]byte(`example object!`)),
    ContentLength: 15, // length of body
}, s3.WithAPIOptions(
    v4.SwapComputePayloadSHA256ForUnsignedPayloadMiddleware,
))