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](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/manager#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 : + `PartSize`— Spécifie la taille de la mémoire tampon, en octets, de chaque partie à télécharger. La taille minimale par pièce est de 5 MiB. + `Concurrency`— Spécifie le nombre de pièces à télécharger en parallèle. + `LeavePartsOnError`— Indique s'il faut laisser les parties chargées avec succès dans Amazon S3. 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` de`5`. 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\$1 5). `Concurrency` **Avertissement** Votre application est censée limiter les appels simultanés afin d'`Upload`éviter l'épuisement des ressources de l'application. 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](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/manager#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.ReaderAt`interface `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'*`PartSize`*environ\$1 *`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. `Uploader`calcule 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'`AbortMultipartUpload`opé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 le`UploadID`. ``` 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], " ") } 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](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/manager#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. GetObject](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#Client.GetObject)opé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'`WriterAt`interface 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 : + `PartSize`— Spécifie la taille de la mémoire tampon, en octets, de chaque partie à télécharger. La taille minimale par pièce est de 5 Mo. + `Concurrency`— Spécifie le nombre de pièces à télécharger en parallèle. 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` de`5`. 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\$1 5). `Concurrency` **Avertissement** Votre application est censée limiter les appels simultanés afin d'`Download`éviter l'épuisement des ressources de l'application. Pour plus d'informations sur les autres options de configuration `Downloader` et sur ses autres options de configuration, consultez [Manager.Downloader](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/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 [GetBucketRegion](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/manager#GetBucketRegion)est une fonction utilitaire permettant de déterminer l'emplacement AWS régional d'un compartiment Amazon S3. `GetBucketRegion`prend 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'`GetBucketRegion`est pas en mesure de déterminer l'emplacement d'un bucket, la fonction renvoie un type [BucketNotFound](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/feature/s3/manager#BucketNotFound)d'erreur, comme indiqué dans l'exemple. ## Entrée de streaming invisible Pour les opérations d'API telles que `PutObject` et`UploadPart`, le client Amazon S3 s'attend à ce que la valeur du paramètre `Body` d'entrée implémente l'interface [io.Seeker](https://pkg.go.dev/io#Seeker) par défaut. L'`io.Seeker`interface 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](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html). 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'[Intergiciel](middleware.md)aide d'options fonctionnelles. L'APIOptionsassistant [With](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#WithAPIOptions) 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](https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html), ajoutez v4. SwapComputePayloadSHA256ForUnsignedPayloadMiddleware](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/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, )) ``` **Avertissement** Amazon S3 exige que la longueur du contenu soit fournie pour tous les objets chargés dans un compartiment. Comme le paramètre `Body` d'entrée n'`io.Seeker`implémente pas l'interface, le client ne pourra pas calculer le `ContentLength` paramètre de la demande. Le paramètre doit être fourni par l'application. La demande échouera si le `ContentLength` paramètre n'est pas fourni. Utilisez le SDK [Gestionnaire de téléchargement Amazon S3](#s3-upload-manager) pour les téléchargements qui ne sont pas consultables et dont la durée n'est pas connue.