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.
# À l'aide du AWS SDK pour Go
Découvrez les méthodes courantes et recommandées de programmation avec le AWS SDK pour Go dans vos applications.
**Topics**
+ [Création d'un client de service](#constructing-a-service-client)
+ [Opérations du service d'appel](#calling-service-operations)
+ [Utilisation simultanée de clients de service](#concurrently-using-service-clients)
+ [Utilisation des paginateurs d'opérations](#using-operation-paginators)
+ [Utilisation de programmes d'attente](#using-waiters)
+ [Gestion des erreurs dans le SDK](handle-errors.md)
## Création d'un client de service
Les clients de service peuvent être créés à l'aide des `NewFromConfig` fonctions `New` ou des fonctions disponibles dans le package Go du client de service. Chaque fonction renverra un type de `Client` structure contenant les méthodes pour appeler le service. APIs `NewFromConfig`Chacun fournit le `New` même ensemble d'options configurables pour créer un client de service, mais propose des modèles de construction légèrement différents que nous examinerons dans les sections suivantes.
### NewFromConfig
`NewFromConfig`La fonction fournit une interface cohérente pour créer des clients de service à l'aide du fichier [AWS.config.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) Un `aws.Config` peut être chargé à l'aide de la [configuration. LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig). Pour plus d'informations sur la construction d'un`aws.Config`, consultez[Configuration du kit SDK](configure-gosdk.md). L'exemple suivant montre comment créer un client de service Amazon S3 à l'aide de la `NewFromConfig` fonction `aws.Config` et :
```
import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
client := s3.NewFromConfig(cfg)
```
#### Configuration de remplacement
`NewFromConfig`peut prendre un ou plusieurs arguments fonctionnels susceptibles de faire muter la `Options` structure de configuration d'un client. Cela vous permet d'effectuer des dérogations spécifiques, telles que le changement de région ou la modification d'options spécifiques à un service, telles que l'`UseAccelerate`option Amazon S3. Par exemple :
```
import "context"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
client := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.Region = "us-west-2"
o.UseAccelerate = true
})
```
Les remplacements par rapport à la `Options` valeur du client sont déterminés par l'ordre dans lequel les arguments fonctionnels sont donnés. `NewFromConfig`
### New
**Note**
`New`est considérée comme une forme plus avancée de construction client. Nous vous recommandons de l'utiliser `NewFromConfig` pour la construction du client, car cela permet la construction à l'aide de la `aws.Config` structure. Il `Options` n'est donc plus nécessaire de créer une instance de structure pour chaque client de service requis par votre application.
`New`function is a client constructor fournit une interface pour construire des clients en utilisant uniquement la `Options` structure des packages clients pour définir les options de configuration du client. Par exemple, pour créer un client Amazon S3 en utilisant `New` :
```
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
client := s3.New(s3.Options{
Region: "us-west-2",
Credentials: aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, "")),
})
```
#### Configuration de remplacement
`New`peut prendre un ou plusieurs arguments fonctionnels susceptibles de faire muter la `Options` structure de configuration d'un client. Cela vous permet d'effectuer des dérogations spécifiques, telles que le changement de région ou la modification d'options spécifiques à un service, telles que l'`UseAccelerate`option Amazon S3. Par exemple :
```
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
options := s3.Options{
Region: "us-west-2",
Credentials: aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, "")),
}
client := s3.New(options, func(o *s3.Options) {
o.Region = "us-east-1"
o.UseAccelerate = true
})
```
Les remplacements par rapport à la `Options` valeur du client sont déterminés par l'ordre dans lequel les arguments fonctionnels sont donnés. `New`
## Opérations du service d'appel
Une fois que vous avez une instance de client de service, vous pouvez l'utiliser pour appeler les opérations d'un service. Par exemple, pour appeler l'`GetObject`opération Amazon S3 :
```
response, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
Bucket: aws.String("amzn-s3-demo-bucket"),
Key: aws.String("obj-key"),
})
```
Lorsque vous appelez une opération de service, le SDK valide l'entrée de manière synchrone, sérialise la demande, la signe avec vos informations d'identification, l'envoie à AWS, puis désérialise une réponse ou une erreur. Dans la plupart des cas, vous pouvez appeler directement les services de maintenance. Chaque méthode client d'opération de service renverra une structure de réponse d'opération et un type d'interface d'erreur. Vous devez toujours vérifier le `error` type pour déterminer si une erreur s'est produite avant de tenter d'accéder à la structure de réponse de l'opération de service.
### Transmission de paramètres à une opération de service
Chaque méthode d'opération de service utilise une valeur [Context.Context](https://golang.org/pkg/context/#Context) qui peut être utilisée pour définir les délais de demande qui seront respectés par le SDK. De plus, chaque opération de service utilisera une `Input` structure trouvée dans le package Go correspondant au service. Vous transmettez les paramètres d'entrée de l'API à l'aide de la structure d'entrée de l'opération.
Les structures d'entrée des opérations peuvent avoir des paramètres d'entrée tels que les types standard de type numérique Go, booléen, chaîne, carte et liste. Dans le cadre d'opérations d'API plus complexes, un service peut avoir une modélisation plus complexe des paramètres d'entrée. Ces autres types, tels que les structures spécifiques au service et les valeurs d'énumération, se trouvent dans le package `types` Go du service.
En outre, les services peuvent faire la distinction entre la valeur par défaut d'un type Go et le fait que la valeur a été définie ou non par l'utilisateur. Dans ces cas, les paramètres d'entrée peuvent vous obliger à transmettre une référence de pointeur au type en question. Pour les types Go standard tels que les nombres, les booléens et les chaînes, des fonctions `From` pratiques sont `` disponibles dans l'[aws](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws) pour faciliter cette conversion. Par exemple, [AWS.String](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#String) peut être utilisé pour convertir un en un `string` `*string` type pour les paramètres d'entrée qui nécessitent un pointeur vers une chaîne. Inversement, [c'était. ToString](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ToString)peut être utilisé pour transformer un en a `*string` `string` tout en offrant une protection contre le déréférencement d'un pointeur nul. Les `To` fonctions sont utiles lors de la gestion des réponses du service.
Voyons un exemple de la façon dont nous pouvons utiliser un client Amazon S3 pour appeler l'`GetObject`API et construire notre entrée à l'aide du `types` package et des `aws.` assistants.
```
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/service/s3/types"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
panic(err)
}
client := s3.NewFromConfig(cfg)
resp, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
Bucket: aws.String("amzn-s3-demo-bucket"),
Key: aws.String("keyName"),
RequestPayer: types.RequestPayerRequester,
})
```
### Remplacer les options du client pour Operation Call
De la même manière que les options d'opération client peuvent être modifiées lors de la construction d'un client à l'aide d'arguments fonctionnels, les options du client peuvent être modifiées au moment où la méthode d'opération est appelée en fournissant un ou plusieurs arguments fonctionnels à la méthode d'opération de service. Cette action est sûre en matière de simultanéité et n'affectera pas les autres opérations simultanées sur le client.
Par exemple, pour remplacer la région client de « us-west-2 » à « us-east-1 » :
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
if err != nil {
log.Printf("error: %v", err)
return
}
client := s3.NewFromConfig(cfg)
params := &s3.GetObjectInput{
// ...
}
resp, err := client.GetObject(context.TODO(), params, func(o *Options) {
o.Region = "us-east-1"
})
```
### Gestion des réponses aux opérations
Chaque opération de service possède une structure de sortie associée qui contient les membres de réponse aux opérations du service. La structure de sortie suit le modèle `Output` de dénomination suivant. Il se peut qu'aucun membre ne soit défini pour la sortie de certaines opérations. Après avoir appelé une opération de service, le type d'`error`argument de retour doit toujours être vérifié pour déterminer si une erreur s'est produite lors de l'appel de l'opération de service. Les erreurs renvoyées peuvent aller d'erreurs de validation d'entrée côté client à des réponses d'erreur côté service renvoyées au client. La structure de sortie de l'opération ne doit pas être accessible dans le cas où une erreur non nulle est renvoyée par le client.
Par exemple, pour enregistrer une erreur d'opération et revenir prématurément de la fonction appelante :
```
response, err := client.GetObject(context.TODO())
if err != nil {
log.Printf("GetObject error: %v", err)
return
}
```
Pour plus d'informations sur la gestion des erreurs, notamment sur la manière de détecter des types d'erreurs spécifiques, consultez TODO
#### Réponses avec `io.ReadCloser`
Certaines opérations d'API renvoient une structure de réponse contenant un membre de sortie qui est un`io.ReadCloser`. Ce sera le cas pour les opérations d'API qui exposent certains éléments de leur sortie dans le corps de la réponse HTTP elle-même.
Par exemple, l'`GetObject`opération Amazon S3 renvoie une réponse dont le `Body` membre est un `io.ReadCloser` pour accéder à la charge utile de l'objet.
**Avertissement**
Vous DEVEZ TOUJOURS `Close()` n'importe quel membre de `io.ReadCloser` sortie, que vous ayez consommé ou non son contenu. Si vous ne le faites pas, vous risquez de perdre des ressources et de créer des problèmes de lecture des corps de réponse pour les opérations appelées dans le futur.
```
resp, err := s3svc.GetObject(context.TODO(), &s3.GetObjectInput{...})
if err != nil {
// handle error
return
}
// Make sure to always close the response Body when finished
defer resp.Body.Close()
decoder := json.NewDecoder(resp.Body)
if err := decoder.Decode(&myStruct); err != nil {
// handle error
return
}
```
#### Métadonnées de réponse
Toutes les structures de sortie des opérations de service incluent un `ResultMetadata` membre de type [Middleware.Metadata](https://pkg.go.dev/github.com/aws/smithy-go/middleware#Metadata). `middleware.Metadata`est utilisé par le middleware du SDK pour fournir des informations supplémentaires à partir d'une réponse de service qui n'est pas modélisée par le service. Cela inclut des métadonnées telles que`RequestID`. Par exemple, pour récupérer le code `RequestID` associé à une réponse de service afin d'aider le AWS Support à résoudre une demande :
```
import "fmt"
import "log"
import "github.com/aws/aws-sdk-go-v2/aws/middleware"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ..
resp, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
// ...
})
if err != nil {
log.Printf("error: %v", err)
return
}
requestID, ok := middleware.GetRequestIDMetadata(resp.ResultMetadata)
if !ok {
fmt.Println("RequestID not included with request")
}
fmt.Printf("RequestID: %s\n", requestID)
```
## Utilisation simultanée de clients de service
Vous pouvez créer des goroutines qui utilisent simultanément le même client de service pour envoyer plusieurs demandes. Vous pouvez utiliser un service client avec autant de goroutines que vous le souhaitez.
Dans l'exemple suivant, un client de service Amazon S3 est utilisé dans plusieurs goroutines. Cet exemple télécharge simultanément deux objets dans un compartiment Amazon S3.
```
import "context"
import "log"
import "strings"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
client := s3.NewFromConfig(cfg)
type result struct {
Output *s3.PutObjectOutput
Err error
}
results := make(chan result, 2)
var wg sync.WaitGroup
wg.Add(2)
go func() {
defer wg.Done()
output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
Bucket: aws.String("amzn-s3-demo-bucket"),
Key: aws.String("foo"),
Body: strings.NewReader("foo body content"),
})
results <- result{Output: output, Err: err}
}()
go func() {
defer wg.Done()
output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
Bucket: aws.String("amzn-s3-demo-bucket"),
Key: aws.String("bar"),
Body: strings.NewReader("bar body content"),
})
results <- result{Output: output, Err: err}
}()
wg.Wait()
close(results)
for result := range results {
if result.Err != nil {
log.Printf("error: %v", result.Err)
continue
}
fmt.Printf("etag: %v", aws.ToString(result.Output.ETag))
}
```
## Utilisation des paginateurs d'opérations
Généralement, lorsque vous récupérez une liste d'éléments, vous devrez peut-être vérifier la présence d'un jeton ou d'un marqueur dans la structure de sortie pour vérifier si le AWS service a renvoyé tous les résultats de votre demande. Si le jeton ou le marqueur est présent, vous l'utilisez pour demander la page de résultats suivante. Au lieu de gérer ces jetons ou marqueurs, vous pouvez utiliser les types de paginateurs disponibles dans le package de services.
Les assistants Paginator sont disponibles pour les opérations de service prises en charge et se trouvent dans le package Go du client de service. Pour créer un paginateur pour une opération prise en charge, utilisez la `NewPaginator` fonction. Les fonctions de construction du paginateur utilisent le service`Client`, les paramètres `Input` d'entrée de l'opération et un ensemble facultatif d'arguments fonctionnels vous permettant de configurer d'autres paramètres de pagination facultatifs.
Le type de paginateur d'opération renvoyé fournit un moyen pratique d'itérer sur une opération paginée jusqu'à ce que vous ayez atteint la dernière page ou que vous ayez trouvé le ou les éléments recherchés par votre application. Un type de paginateur possède deux méthodes : `HasMorePages` et. `NextPage` `HasMorePages`renvoie une valeur booléenne indiquant `true` si la première page n'a pas été récupérée ou si des pages supplémentaires peuvent être récupérées à l'aide de l'opération. Pour récupérer la première page ou les pages suivantes de l'opération, l'`NextPage`opération doit être appelée. `NextPage`prend `context.Context` et renvoie le résultat de l'opération et toute erreur correspondante. Comme les paramètres de retour de la méthode d'opération client, l'erreur de retour doit toujours être vérifiée avant de tenter d'utiliser la structure de réponse renvoyée. Consultez [Gestion des réponses aux opérations](#handling-operation-responses).
L'exemple suivant utilise le `ListObjectsV2` paginateur pour répertorier jusqu'à trois pages de clés d'objet issues de l'`ListObjectV2`opération. Chaque page comprend jusqu'à 10 clés, définies par l'option de `Limit` pagination.
```
import "context"
import "log"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
client := s3.NewFromConfig(cfg)
params := &s3.ListObjectsV2Input{
Bucket: aws.String("amzn-s3-demo-bucket"),
}
paginator := s3.NewListObjectsV2Paginator(client, params, func(o *s3.ListObjectsV2PaginatorOptions) {
o.Limit = 10
})
pageNum := 0
for paginator.HasMorePages() && pageNum < 3 {
output, err := paginator.NextPage(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
for _, value := range output.Contents {
fmt.Println(*value.Key)
}
pageNum++
}
```
Semblable à la méthode d'opération du client, les options du client telles que la région de requête peuvent être modifiées en fournissant un ou plusieurs arguments fonctionnels à`NextPage`. Pour plus d'informations sur le remplacement des options du client lors de l'appel d'une opération, consultez[Remplacer les options du client pour Operation Call](#overriding-client-options).
## Utilisation de programmes d'attente
Lorsque vous interagissez avec AWS APIs des ressources asynchrones, vous devez souvent attendre qu'une ressource particulière soit disponible pour effectuer d'autres actions sur celle-ci.
Par exemple, l'API Amazon `CreateTable` DynamoDB renvoie immédiatement TableStatus un code CREATING, et vous ne pouvez pas appeler d'opérations de lecture ou d'écriture tant que le statut de la table n'est pas passé à. `ACTIVE`
L'écriture d'une logique permettant de vérifier en permanence l'état de la table peut s'avérer fastidieuse et source d'erreurs. Les serveurs vous aident à vous simplifier la tâche et se APIs chargent simplement de la tâche de sondage à votre place.
Par exemple, vous pouvez utiliser des serveurs pour savoir si une table DynamoDB est créée et prête pour une opération d'écriture.
```
import "context"
import "fmt"
import "log"
import "time"
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/dynamodb"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
client := dynamodb.NewFromConfig(cfg)
// we create a waiter instance by directly passing in a client
// that satisfies the waiters client Interface.
waiter := dynamodb.NewTableExistsWaiter(client)
// params is the input to api operation used by the waiter
params := &dynamodb.DescribeTableInput {
TableName: aws.String("test-table")
}
// maxWaitTime is the maximum wait time, the waiter will wait for
// the resource status.
maxWaitTime := 5 * time.Minutes
// Wait will poll until it gets the resource status, or max wait time
// expires.
err := waiter.Wait(context.TODO(), params, maxWaitTime)
if err != nil {
log.Printf("error: %v", err)
return
}
fmt.Println("Dynamodb table is now ready for write operations")
```
### Modification de la configuration du serveur
Par défaut, le SDK utilise les valeurs de délai minimum et maximum configurées avec des valeurs optimales définies par les AWS services pour différents APIs. Vous pouvez annuler la configuration du serveur en fournissant des options fonctionnelles lors de la construction du serveur ou en invoquant une opération du serveur.
Par exemple, pour annuler la configuration du serveur pendant la construction du serveur
```
import "context"
import "fmt"
import "log"
import "time"
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/dynamodb"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
client := dynamodb.NewFromConfig(cfg)
// we create a waiter instance by directly passing in a client
// that satisfies the waiters client Interface.
waiter := dynamodb.NewTableExistsWaiter(client, func (o *dynamodb.TableExistsWaiterOptions) {
// override minimum delay to 10 seconds
o.MinDelay = 10 * time.Second
// override maximum default delay to 300 seconds
o.MaxDelay = 300 * time.Second
})
```
La `Wait` fonction de chaque serveur inclut également des options fonctionnelles. Comme dans l'exemple ci-dessus, vous pouvez annuler la configuration du serveur par demande. `Wait`
```
// params is the input to api operation used by the waiter
params := &dynamodb.DescribeTableInput {
TableName: aws.String("test-table")
}
// maxWaitTime is the maximum wait time, the waiter will wait for
// the resource status.
maxWaitTime := 5 * time.Minutes
// Wait will poll until it gets the resource status, or max wait time
// expires.
err := waiter.Wait(context.TODO(), params, maxWaitTime, func (o *dynamodb.TableExistsWaiterOptions) {
// override minimum delay to 5 seconds
o.MinDelay = 5 * time.Second
// override maximum default delay to 120 seconds
o.MaxDelay = 120 * time.Second
})
if err != nil {
log.Printf("error: %v", err)
return
}
fmt.Println("Dynamodb table is now ready for write operations")
```
### Annulation de la configuration avancée des serveurs
Vous pouvez également personnaliser le comportement par défaut du serveur en fournissant une fonction réessayable personnalisée. Les options spécifiques au serveur permettent également de [personnaliser](middleware.md#writing-a-custom-middleware) les intergiciels `APIOptions` d'exploitation.
Par exemple, pour configurer les remplacements avancés des serveurs.
```
import "context"
import "fmt"
import "log"
import "time"
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/dynamodb"
import "github.com/aws/aws-sdk-go-v2/service/dynamodb/types"
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Printf("error: %v", err)
return
}
client := dynamodb.NewFromConfig(cfg)
// custom retryable defines if a waiter state is retryable or a terminal state.
// For example purposes, we will configure the waiter to not wait
// if table status is returned as `UPDATING`
customRetryable := func(ctx context.Context, params *dynamodb.DescribeTableInput,
output *dynamodb.DescribeTableOutput, err error) (bool, error) {
if output.Table != nil {
if output.Table.TableStatus == types.TableStatusUpdating {
// if table status is `UPDATING`, no need to wait
return false, nil
}
}
}
// we create a waiter instance by directly passing in a client
// that satisfies the waiters client Interface.
waiter := dynamodb.NewTableExistsWaiter(client, func (o *dynamodb.TableExistsWaiterOptions) {
// override the service defined waiter-behavior
o.Retryable = customRetryable
})
```