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.
Temas
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 NewFromConfig
Cada 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
NewFromConfig
La función proporciona una interfaz coherente para crear clientes de servicio mediante AWS.config.aws.Config
puede cargar mediante la configuración. LoadDefaultConfigaws.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
NewFromConfig
puede 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
New
se 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.
New
La 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
New
puede 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<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, AWSFrom<Type>
Por ejemplo, AWS.String*string
tipo string
para los parámetros de entrada que requieren un puntero en una cadena. A la inversa, aws. ToString*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.Metadatamiddleware.Metadata
lo 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
HasMorePages
devuelve 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. NextPage
toma 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 })