Utiliser la AWS SDK pour Go v2 avec les AWS services - AWS SDK pour Go v2

Création d'un client de service Opérations du service d'appel Utilisation simultanée de clients de service Utilisation des paginateurs d'opérations Utilisation de programmes d'attente

Utiliser la AWS SDK pour Go v2 avec les AWS services

Pour appeler un AWS service, vous devez d'abord créer une instance de client de service. Un client de service fournit un accès de bas niveau à chaque action d'API pour ce service. Par exemple, vous créez un client de service Amazon S3 pour passer des appels à Amazon S3 APIs.

Lorsque vous appelez des opérations de service, vous transmettez les paramètres d'entrée sous forme de structure. Un appel réussi produira une structure de sortie contenant la réponse de l'API de service. Par exemple, une fois que vous avez appelé avec succès une action de création de compartiment Amazon S3, l'action renvoie une structure de sortie indiquant l'emplacement du compartiment.

Pour obtenir la liste des clients du service, y compris leurs méthodes et paramètres, consultez la référence des AWS SDK pour Go API.

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 NewFromConfigChacun 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

NewFromConfigLa fonction fournit une interface cohérente pour créer des clients de service à l'aide du fichier AWS.config. Un aws.Config peut être chargé à l'aide de la configuration. LoadDefaultConfig. Pour plus d'informations sur la construction d'unaws.Config, consultezConfigurer l'SDK. 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

NewFromConfigpeut 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'UseAccelerateoption 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

Newest 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.

Newfunction 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

Newpeut 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'UseAccelerateoption 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'GetObjectopé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 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 <OperationName>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<Type> pratiques sont <Type> disponibles dans l'aws pour faciliter cette conversion. Par exemple, 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. ToStringpeut ê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<Type> 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'GetObjectAPI et construire notre entrée à l'aide du types package et des aws.<Type> 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 <OperationName>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'errorargument 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 unio.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'GetObjectopé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. middleware.Metadataest 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 queRequestID. 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 New<OperationName>Paginator fonction. Les fonctions de construction du paginateur utilisent le serviceClient, les paramètres <OperationName>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 HasMorePagesrenvoie 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'NextPageopération doit être appelée. NextPageprend context.Context et renvoie le résultat de l'opération et toute erreur correspondante. Tout 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.

L'exemple suivant utilise le ListObjectsV2 paginateur pour répertorier jusqu'à trois pages de clés d'objet issues de l'ListObjectV2opé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, consultezRemplacer les options du client pour Operation Call.

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 lors de l'invocation d'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 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
})

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Migrer vers la version v2

Sommes de contrôle Amazon S3

Sélectionner vos préférences de cookies

Personnaliser les préférences de cookies

Essentiels

Performances

Fonctionnels

Publicitaires

Impossible d'enregistrer les préférences concernant les cookies

Utiliser la AWS SDK pour Go v2 avec les AWS services

Création d'un client de service

NewFromConfig

Configuration de remplacement

New

Note

Configuration de remplacement

Opérations du service d'appel

Transmission de paramètres à une opération de service

Remplacer les options du client pour Operation Call

Gestion des réponses aux opérations

Réponses avec `io.ReadCloser`

Avertissement

Métadonnées de réponse

Utilisation simultanée de clients de service

Utilisation des paginateurs d'opérations

Utilisation de programmes d'attente

Modification de la configuration du serveur

Annulation de la configuration avancée des serveurs

Cette page vous a-t-elle été utile ?

Rubrique suivante :

Rubrique précédente :

Avez-vous besoin d’aide ?

Sélectionner vos préférences de cookies

Utiliser la AWS SDK pour Go v2 avec les AWS services

Création d'un client de service

NewFromConfig

Configuration de remplacement

New

Note

Configuration de remplacement

Opérations du service d'appel

Transmission de paramètres à une opération de service

Remplacer les options du client pour Operation Call

Gestion des réponses aux opérations

Réponses avec io.ReadCloser

Avertissement

Métadonnées de réponse

Utilisation simultanée de clients de service

Utilisation des paginateurs d'opérations

Utilisation de programmes d'attente

Modification de la configuration du serveur

Annulation de la configuration avancée des serveurs

Cette page vous a-t-elle été utile ?

Rubrique suivante :

Rubrique précédente :

Avez-vous besoin d’aide ?

Réponses avec `io.ReadCloser`