Uso del AWS SDK para Go - AWS SDK para Go v2

Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés.

Uso del AWS SDK para Go

Aprenda las formas comunes y recomendadas de programar con AWS SDK para Go In your Applications.

Construyendo un cliente de servicio

Los clientes de servicio se pueden construir utilizando las New NewFromConfig funciones disponibles en el paquete Go del cliente de servicio. Cada función devolverá un tipo de Client estructura que contiene los métodos para invocar el servicio. APIs NewFromConfigCada una de ellas proporciona el mismo conjunto de opciones configurables para crear un cliente de servicio, pero proporciona patrones de construcción ligeramente diferentes que veremos en las siguientes secciones. New

NewFromConfig

NewFromConfigLa función proporciona una interfaz coherente para crear clientes de servicio mediante AWS.config. Y se aws.Config puede cargar mediante la configuración. LoadDefaultConfig. Para obtener más información sobre la construcción de unaws.Config, consulteConfigurar el SDK. El siguiente ejemplo muestra cómo construir un cliente de servicio Amazon S3 mediante la NewFromConfig función aws.Config y:

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)

Configuración sustitutiva

NewFromConfigpuede tomar uno o más argumentos funcionales que pueden mutar la estructura de configuración Options de un cliente. Esto le permite realizar anulaciones específicas, como cambiar la región o modificar opciones específicas del servicio, como la UseAccelerate opción Amazon S3. Por ejemplo:

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 })

Las anulaciones del Options valor del cliente vienen determinadas por el orden en que se asignan los argumentos funcionales. NewFromConfig

New

nota

Newse considera una forma más avanzada de construcción de clientes. Le recomendamos que la utilice NewFromConfig para la construcción de un cliente, ya que permite la construcción utilizando la aws.Config estructura. Esto elimina la necesidad de construir una instancia de Options estructura para cada cliente de servicio que requiera su aplicación.

NewLa función es un constructor de clientes que proporciona una interfaz para construir clientes utilizando solo la Options estructura de paquetes de clientes para definir las opciones de configuración del cliente. Por ejemplo, para crear un cliente Amazon S3 medianteNew:

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, "")), })

Configuración sustitutiva

Newpuede tomar uno o más argumentos funcionales que pueden mutar la estructura de configuración Options de un cliente. Esto le permite realizar anulaciones específicas, como cambiar la región o modificar opciones específicas del servicio, como la UseAccelerate opción Amazon S3. Por ejemplo:

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 })

Las anulaciones del Options valor del cliente vienen determinadas por el orden en que se asignan los argumentos funcionales. New

Operaciones del servicio de llamadas

Una vez que tenga una instancia de cliente de servicio, podrá utilizarla para llamar a las operaciones de un servicio. Por ejemplo, para llamar a la GetObject operación Amazon S3:

response, err := client.GetObject(context.TODO(), &s3.GetObjectInput{ Bucket: aws.String("amzn-s3-demo-bucket"), Key: aws.String("obj-key"), })

Cuando llamas a una operación de servicio, el SDK valida de forma sincrónica la entrada, serializa la solicitud, la firma con tus credenciales, la envía a AWS y, a continuación, deserializa una respuesta o un error. En la mayoría de los casos, puede llamar directamente a las operaciones de servicio. Cada método cliente de operación de servicio devolverá una estructura de respuesta a la operación y un tipo de interfaz de error. Siempre debe comprobar el error tipo para determinar si se ha producido un error antes de intentar acceder a la estructura de respuesta de la operación de servicio.

Pasar parámetros a una operación de servicio

Cada método de operación de servicio utiliza un valor de Context.Context que se puede utilizar para establecer los plazos de solicitud que cumplirá el SDK. Además, cada operación de servicio utilizará una <OperationName>Input estructura que se encuentra en el paquete Go correspondiente del servicio. Los parámetros de entrada de la API se transfieren mediante la estructura de entrada de la operación.

Las estructuras de entrada de las operaciones pueden tener parámetros de entrada, como los tipos estándar de Go, numéricos, booleanos, de cadenas, de mapas y de listas. En operaciones de API más complejas, un servicio puede tener un modelado más complejo de los parámetros de entrada. Estos otros tipos, como las estructuras específicas del servicio y los valores de enumeración, se encuentran en el paquete types Go del servicio.

Además, los servicios pueden distinguir entre el valor predeterminado de un tipo Go y si el usuario lo estableció o no. En estos casos, los parámetros de entrada pueden requerir que pases una referencia de puntero al tipo en cuestión. En el caso de los tipos Go estándar, como los numéricos, los booleanos y las <Type> cadenas, AWS dispone de funciones prácticas que facilitan la conversión. From<Type> Por ejemplo, AWS.String se puede usar para convertir a en un *string tipo string para los parámetros de entrada que requieren un puntero en una cadena. A la inversa, aws. ToStringse puede utilizar para transformar un *string punto en uno string mientras proporciona protección contra la desreferenciación de un puntero nulo. Las To<Type> funciones son útiles a la hora de gestionar las respuestas del servicio.

Veamos un ejemplo de cómo podemos usar un cliente de Amazon S3 para llamar a la GetObject API y construir nuestra entrada con el types paquete y los aws.<Type> ayudantes.

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, })

Anulación de las opciones de cliente para Operation Call

De forma similar a como se pueden modificar las opciones de operación del cliente durante la construcción de un cliente mediante argumentos funcionales, las opciones del cliente se pueden modificar en el momento en que se llama al método de operación proporcionando uno o más argumentos funcionales al método de operación del servicio. Esta acción es segura para la simultaneidad y no afectará a otras operaciones simultáneas en el cliente.

Por ejemplo, para anular la región del cliente de «us-west-2" a «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" })

Gestión de las respuestas de las operaciones

Cada operación de servicio tiene una estructura de salida asociada que contiene los miembros de la respuesta a la operación del servicio. La estructura de salida sigue el siguiente patrón de nomenclatura. <OperationName>Output Es posible que algunas operaciones no tengan miembros definidos para el resultado de la operación. Tras llamar a una operación de servicio, siempre se debe comprobar el tipo de error argumento devuelto para determinar si se ha producido un error al invocar la operación de servicio. Los errores devueltos pueden ir desde errores de validación de entradas del lado del cliente hasta respuestas de error del lado del servicio devueltas al cliente. No se debe acceder a la estructura de salida de la operación en caso de que el cliente devuelva un error que no sea nulo.

Por ejemplo, para registrar un error de operación y volver prematuramente de la función de llamada:

response, err := client.GetObject(context.TODO()) if err != nil { log.Printf("GetObject error: %v", err) return }

Para obtener más información sobre la gestión de errores, incluida la forma de inspeccionar tipos de errores específicos, consulte TODO

Respuestas con io.ReadCloser

Algunas operaciones de la API devuelven una estructura de respuesta que contiene un miembro de salida que es unio.ReadCloser. Este será el caso de las operaciones de API que expongan algún elemento de su salida en el cuerpo de la propia respuesta HTTP.

Por ejemplo, la GetObject operación Amazon S3 devuelve una respuesta cuyo Body miembro es un io.ReadCloser para acceder a la carga útil del objeto.

aviso

SIEMPRE DEBE incluir Close() cualquier miembro io.ReadCloser de salida, independientemente de si ha consumido o no su contenido. De lo contrario, se pueden perder recursos y, potencialmente, crear problemas a la hora de leer los organismos de respuesta para las operaciones convocadas en el futuro.

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 }

Metadatos de respuesta

Todas las estructuras de salida de las operaciones de servicio incluyen un ResultMetadata miembro del tipo Middleware.Metadata. middleware.Metadatalo utiliza el middleware del SDK para proporcionar información adicional a partir de una respuesta de servicio que no está modelada por el servicio. Esto incluye metadatos como. RequestID Por ejemplo, para recuperar la respuesta RequestID asociada a un servicio para ayudar a AWS Support a solucionar una solicitud:

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)

Uso simultáneo de clientes de servicio

Puede crear rutinas que utilicen simultáneamente el mismo cliente de servicio para enviar varias solicitudes. Puedes usar un cliente de servicio con tantas gorrutinas como desees.

En el siguiente ejemplo, se utiliza un cliente de servicio Amazon S3 en varias rutinas. En este ejemplo, se cargan simultáneamente dos objetos en un bucket de 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)) }

Uso de paginadores de operaciones

Por lo general, cuando recuperas una lista de elementos, es posible que tengas que comprobar la estructura de salida en busca de un token o marcador para confirmar si el AWS servicio ha devuelto todos los resultados de tu solicitud. Si el token o el marcador están presentes, se utilizan para solicitar la siguiente página de resultados. En lugar de administrar estos símbolos o marcadores, puedes usar los tipos de paginadores disponibles en el paquete de servicios.

Los ayudantes de Paginator están disponibles para las operaciones de servicio compatibles y se encuentran en el paquete Go del cliente del servicio. Para construir un paginador para una operación compatible, utilice la función. New<OperationName>Paginator Las funciones de construcción del paginador utilizan el servicioClient, los parámetros de <OperationName>Input entrada de la operación y un conjunto opcional de argumentos funcionales que permiten configurar otros ajustes opcionales del paginador.

El tipo de paginador de operaciones devuelto proporciona una forma cómoda de recorrer una operación paginada hasta llegar a la última página o hasta encontrar los elementos que buscaba la aplicación. Un tipo de paginador tiene dos métodos: y. HasMorePages NextPage HasMorePagesdevuelve un valor booleano true si no se ha recuperado la primera página o si hay páginas adicionales disponibles para recuperarlas mediante la operación. Para recuperar la primera página o las siguientes de la operación, se debe llamar a la NextPage operación. NextPagetoma context.Context y devuelve el resultado de la operación y cualquier error correspondiente. Al igual que los parámetros de retorno del método operativo del cliente, el error devuelto siempre debe comprobarse antes de intentar utilizar la estructura de respuesta devuelta. Consulte Gestión de las respuestas de las operaciones.

En el siguiente ejemplo, se utiliza el ListObjectsV2 paginador para enumerar hasta tres páginas de claves de objetos de la ListObjectV2 operación. Cada página consta de un máximo de 10 claves, lo que se define mediante la opción de Limit paginador.

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++ }

Al igual que en el método de operación del cliente, las opciones del cliente, como la región de solicitud, se pueden modificar proporcionando uno o más argumentos funcionales a. NextPage Para obtener más información sobre cómo anular las opciones del cliente al llamar a una operación, consulteAnulación de las opciones de cliente para Operation Call.

Uso de esperadores

Al interactuar con AWS APIs un recurso de forma asíncrona, a menudo es necesario esperar a que un recurso en particular esté disponible para poder realizar más acciones en él.

Por ejemplo, la API Amazon CreateTable DynamoDB regresa inmediatamente con TableStatus un de CREATING y no puede invocar operaciones de lectura o escritura hasta que se haya cambiado el estado de la tabla a. ACTIVE

Escribir la lógica para sondear continuamente el estado de la tabla puede resultar engorroso y propenso a errores. Los camareros ayudan a eliminar la complejidad y son simples APIs y se encargan de la tarea de votar por usted.

Por ejemplo, puede utilizar los camareros para sondear si se ha creado una tabla de DynamoDB y si está lista para una operación de escritura.

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")

Anular la configuración del camarero

De forma predeterminada, el SDK usa el valor de retraso mínimo y máximo configurados con valores óptimos definidos por los AWS servicios para diferentes tipos. APIs Puede anular la configuración del camarero proporcionando opciones funcionales durante la construcción del camarero o al invocar una operación de camarero.

Por ejemplo, para anular la configuración del camarero durante la construcción del camarero

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 función de cada camarero también incluye opciones funcionales. Al igual que en el ejemplo anterior, puede anular la configuración del camarero por solicitud. 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")

La configuración avanzada del camarero anula

Además, puede personalizar el comportamiento predeterminado del camarero proporcionando una función personalizada que se pueda volver a intentar. Las opciones específicas para camareros también permiten personalizar los middlewares de operaciónAPIOptions.

Por ejemplo, para configurar anulaciones avanzadas de camarero.

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 })