Versión mínima de Go Modularización Carga de la configuración Simulación e *iface Credenciales y proveedores de credenciales Clientes de servicio Personalización de solicitudes Características Cambios en las personalizaciones de servicios

Migre a la AWS SDK para Go versión 2

Versión mínima de Go

AWS SDK para Go Requiere una versión mínima de Go 1.23. La última versión de Go se puede descargar en la página de descargas. Consulte el historial de versiones para obtener más información sobre cada lanzamiento de versión de Go, así como la información pertinente necesaria para la actualización.

Modularización

Se AWS SDK para Go ha actualizado para aprovechar los módulos Go, que se convirtieron en el modo de desarrollo predeterminado en Go 1.13. Varios de los paquetes proporcionados por el SDK se han modularizado y ahora se versionan y publican de forma independiente. Gracias a este cambio, puede mejorarse el modelado de dependencias de las aplicaciones y se permite que el SDK proporcione nuevas características y funcionalidades que siguen la estrategia de control de versiones de los módulos de Go.

En la lista siguiente se incluyen algunos módulos de Go proporcionados por el SDK:

Módulo	Description (Descripción)
`github.com/aws/aws-sdk-go-v2`	El núcleo del SDK
`github.com/aws/aws-sdk-go-v2/config`	Carga de la configuración compartida
`github.com/aws/aws-sdk-go-v2/credentials`	AWS Proveedores de credenciales
`github.com/aws/aws-sdk-go-v2/feature/ec2/imds`	Cliente de Amazon EC2 Instance Metadata Service

Los clientes de servicio y los módulos de utilidades de nivel superior del SDK se anidan en las siguientes rutas de importación:

Raíz de la importación	Description (Descripción)
`github.com/aws/aws-sdk-go-v2/service/`	Módulos del cliente de servicio
`github.com/aws/aws-sdk-go-v2/feature/`	Utilidades de alto nivel para servicios como el administrador de transferencia de Amazon S3

Carga de la configuración

El paquete session y la funcionalidad asociada se sustituyen por un sistema de configuración simplificado que proporciona el paquete config. El paquete config es un módulo de Go independiente y se puede incluir en las dependencias de la aplicación con go get.


go get github.com/aws/aws-sdk-go-v2/config

La sesión. Nueva, sesión.NewSessionNewSessionWithOptions , y session.MUST deben migrarse a config. LoadDefaultConfig.

El paquete config proporciona varias funciones auxiliares que contribuyen a reemplazar la configuración compartida que se carga mediante programación. Estos nombres de función llevan el prefijo With, seguido de la opción que reemplazan. Veamos algunos ejemplos de cómo migrar el uso del paquete session.

Para obtener más información sobre cómo cargar la configuración compartida, consulte Configurar el SDK.

Ejemplos

Migrar de a NewSession LoadDefaultConfig

En el ejemplo siguiente se muestra cómo se migra el uso de session.NewSession sin parámetros de argumento adicionales a config.LoadDefaultConfig.


// V1 using NewSession

import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}


// V2 using LoadDefaultConfig

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
    // handle error
}

Migrar desde NewSession con las opciones de AWS.config

En el ejemplo se muestra cómo migrar el reemplazo de valores aws.Config durante la carga de la configuración. Se pueden proporcionar una o varias funciones auxiliares config.With* a config.LoadDefaultConfig para reemplazar los valores de configuración cargados. En este ejemplo, se anula AWS la región para usar la configuración. us-west-2 WithRegionfunción auxiliar.


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSession(aws.Config{
    Region: aws.String("us-west-2")
})
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithRegion("us-west-2"),
)
if err != nil {
    // handle error
}

Migrando desde NewSessionWithOptions

En este ejemplo se muestra cómo migrar el reemplazo de valores durante la carga de la configuración. Se pueden proporcionar cero o más funciones auxiliares config.With* a config.LoadDefaultConfig para anular los valores de configuración cargados. En este ejemplo, mostramos cómo anular el perfil de destino que se utiliza al cargar la configuración compartida del AWS SDK.


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"

// ...

sess, err := session.NewSessionWithOptions(aws.Config{
    Profile: "my-application-profile"
})
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/config"

// ...

cfg, err := config.LoadDefaultConfig(context.TODO(),
    config.WithSharedConfigProfile("my-application-profile"),
)
if err != nil {
    // handle error
}

Simulación e `*iface`

Los paquetes *iface y las interfaces incluidas (por ejemplo, s3iface.S3API) se han eliminado. Estas definiciones de interfaz no son estables, ya que se invalidan cada vez que un servicio agrega una nueva operación.

Para las operaciones de servicio que se utilizan, se debe sustituir el uso de *iface por interfaces definidas por el intermediario con un ámbito específico:


// V1

import "io"

import "github.com/aws/aws-sdk-go/service/s3"
import "github.com/aws/aws-sdk-go/service/s3/s3iface"

func GetObjectBytes(client s3iface.S3API, bucket, key string) ([]byte, error) {
    object, err := client.GetObject(&s3.GetObjectInput{
        Bucket: &bucket,
        Key:    &key,
    })
    if err != nil {
        return nil, err
    }
    defer object.Body.Close()

    return io.ReadAll(object.Body)
}


// V2

import "context"
import "io"

import "github.com/aws/aws-sdk-go-v2/service/s3"

type GetObjectAPIClient interface {
    GetObject(context.Context, *s3.GetObjectInput, ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}

func GetObjectBytes(ctx context.Context, client GetObjectAPIClient, bucket, key string) ([]byte, error) {
    object, err := client.GetObject(ctx, &s3.GetObjectInput{
        Bucket: &bucket,
        Key:    &key,
    })
    if err != nil {
        return nil, err
    }
    defer object.Body.Close()

    return io.ReadAll(object.Body)
}

Consulte Pruebas unitarias con AWS SDK para Go v2 para obtener más información.

Credenciales y proveedores de credenciales

El paquete aws/credenciales y los proveedores de credenciales asociados se han reubicado en el emplazamiento del paquete credentials. El paquete credentials es un módulo de Go que se recupera mediante go get.


go get github.com/aws/aws-sdk-go-v2/credentials

La versión AWS SDK para Go v2 actualiza los proveedores de AWS credenciales para proporcionar una interfaz coherente para recuperar AWS las credenciales. Cada proveedor implementa las leyes. CredentialsProviderinterfaz, que define un Retrieve método que devuelve un(aws.Credentials, error). AWS.Credentials , que es análogo al tipo AWS SDK para Go v1 Credentials.value.

Debe empaquetar los objetos con aws. aws.CredentialsProvider CredentialsCachepara permitir que se almacene en caché las credenciales. Se usa NewCredentialsCachepara construir un aws.CredentialsCache objeto. De forma predeterminada, las credenciales configuradas por config.LoadDefaultConfig se encapsulan con aws.CredentialsCache.

La siguiente tabla muestra los cambios de ubicación de los proveedores de AWS credenciales de la AWS SDK para Go versión 1 a la versión 2.

Name	Importación de V1	Importación de V2
Credenciales de rol de Amazon EC2 IAM	`github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds`	`github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds`
Credenciales de los puntos de conexión	`github.com/aws/aws-sdk-go/aws/credentials/endpointcreds`	`github.com/aws/aws-sdk-go-v2/credentials/endpointcreds`
Credenciales de proceso	`github.com/aws/aws-sdk-go/aws/credentials/processcreds`	`github.com/aws/aws-sdk-go-v2/credentials/processcreds`
AWS Security Token Service	`github.com/aws/aws-sdk-go/aws/credentials/stscreds`	`github.com/aws/aws-sdk-go-v2/credentials/stscreds`

Credenciales estáticas

Aplicaciones que utilizan credenciales. NewStaticCredentialspara construir una credencial estática mediante programación debe usar credenciales. NewStaticCredentialsProvider.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/credentials"

// ...

appCreds := credentials.NewStaticCredentials(accessKey, secretKey, sessionToken)
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials"

// ...

appCreds := aws.NewCredentialsCache(credentials.NewStaticCredentialsProvider(accessKey, secretKey, sessionToken))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

Credenciales de rol de Amazon EC2 IAM

Debe migrar el uso de NewCredentialsy NewCredentialsWithClientusar New.

El ec2rolecreds paquete ec2rolecreds.New toma las opciones funcionales de EC2Rolecreds.options como entrada, lo que le permite anular el cliente específico de Amazon EC2 Instance Metadata Service que va a utilizar o anular la ventana de caducidad de las credenciales.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/ec2rolecreds"

// ...

appCreds := ec2rolecreds.NewCredentials(sess)
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds"

// ...

// New returns an object of a type that satisfies the aws.CredentialProvider interface
appCreds := aws.NewCredentialsCache(ec2rolecreds.New())
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

Credenciales de los puntos de conexión

Debe migrar el uso de New y usar New. NewCredentialsClient NewProviderClient

La función New del paquete endpointcreds utiliza un argumento de cadena que contiene la dirección URL de un punto de conexión HTTP o HTTPS del que se recuperan las credenciales, así como opciones funcionales de endpointcreds.Options para mutar el proveedor de credenciales y reemplazar opciones de configuración específicas.

Credenciales de proceso

Debe migrar el uso de NewCredentials NewCredentialsCommand, y NewCredentialsTimeoutpara usar NewProvidero NewProviderCommand.

La función NewProvider del paquete processcreds toma un argumento de cadena que es el comando que se va a ejecutar en el intérprete de comandos del entorno de host, así como opciones funcionales de Options para mutar el proveedor de credenciales y reemplazar opciones de configuración específicas.

NewProviderCommandadopta una implementación de la NewCommandBuilderinterfaz que define comandos de proceso más complejos que pueden aceptar uno o más argumentos de línea de comandos o tener ciertos requisitos de entorno de ejecución. DefaultNewCommandBuilderimplementa esta interfaz y define un generador de comandos para un proceso que requiere varios argumentos de línea de comandos.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/processcreds"

// ...

appCreds := processcreds.NewCredentials("/path/to/command")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/processcreds"

// ...

appCreds := aws.NewCredentialsCache(processcreds.NewProvider("/path/to/command"))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

AWS Security Token Service Credenciales

AssumeRole

Debe migrar el uso de NewCredentialsy NewCredentialsWithClientpara usar. NewAssumeRoleProvider

Se debe llamar a la NewAssumeRoleProvider función del stscreds paquete con un STS.Client y el AWS Identity and Access Management ARN del rol debe asumirse a partir de las credenciales configuradas del proveedor. sts.Client También puede proporcionar un conjunto de opciones funcionales AssumeRoleOptionspara modificar otras configuraciones opcionales del proveedor.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/stscreds"

// ...

appCreds := stscreds.NewCredentials(sess, "arn:aws:iam::123456789012:role/demo")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/credentials/stscreds"
import "github.com/aws/aws-sdk-go-v2/service/sts"

// ...

client := sts.NewFromConfig(cfg)

appCreds := stscreds.NewAssumeRoleProvider(client, "arn:aws:iam::123456789012:role/demo")
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

AssumeRoleWithWebIdentity

Debe migrar el uso de NewWebIdentityCredentials NewWebIdentityRoleProvider, y NewWebIdentityRoleProviderWithTokenpara usar NewWebIdentityRoleProvider.

Se debe llamar a la NewWebIdentityRoleProvider función del stscreds paquete con un STS.Client y se debe asumir el AWS Identity and Access Management ARN del rol utilizando las credenciales configuradas sts.Client del proveedor, y una implementación de a IdentityTokenRetrieverpara proporcionar el token 2.0 o OAuth OpenID Connect ID. IdentityTokenFilees una IdentityTokenRetriever que se puede utilizar para proporcionar el token de identidad web desde un archivo ubicado en el sistema de archivos host de la aplicación. También puede proporcionar un conjunto de opciones funcionales WebIdentityRoleOptionspara modificar otras configuraciones opcionales para el proveedor.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/credentials/stscreds"

// ...

appCreds := stscreds.NewWebIdentityRoleProvider(sess, "arn:aws:iam::123456789012:role/demo", "sessionName", "/path/to/token")
value, err := appCreds.Get()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/aws"
import "github.com/aws/aws-sdk-go-v2/credentials/stscreds"
import "github.com/aws/aws-sdk-go-v2/service/sts"

// ...

client := sts.NewFromConfig(cfg)

appCreds := aws.NewCredentialsCache(stscreds.NewWebIdentityRoleProvider(
        client,
        "arn:aws:iam::123456789012:role/demo",
        stscreds.IdentityTokenFile("/path/to/file"),
        func(o *stscreds.WebIdentityRoleOptions) {
            o.RoleSessionName = "sessionName"
        }))
value, err := appCreds.Retrieve(context.TODO())
if err != nil {
    // handle error
}

Clientes de servicio

AWS SDK para Go proporciona módulos de cliente de servicio anidados en la ruta de github.com/aws/aws-sdk-go-v2/service importación. Cada cliente de servicio está incluido en un paquete Go que utiliza el identificador único de cada servicio. En la tabla siguiente se muestran algunos ejemplos de rutas de importación de servicios en AWS SDK para Go.

Nombre del servicio	Ruta de importación de V1	Ruta de importación de V2
Amazon S3	`github.com/aws/aws-sdk-go/service/s3`	`github.com/aws/aws-sdk-go-v2/service/s3`
Amazon DynamoDB	`github.com/aws/aws-sdk-go/service/dynamodb`	`github.com/aws/aws-sdk-go-v2/service/dynamodb`
Amazon CloudWatch Logs	`github.com/aws/aws-sdk-go/service/cloudwatchlogs`	`github.com/aws/aws-sdk-go-v2/service/cloudwatchlogs`

Cada paquete de clientes de servicio es un módulo Go versionado de forma independiente. Para agregar el cliente de servicio como dependencia de su aplicación, use el comando go get con la ruta de importación del servicio. Por ejemplo, para agregar el cliente de Amazon S3 a sus dependencias, utilice:


go get github.com/aws/aws-sdk-go-v2/service/s3

Creación de clientes

Puede crear clientes AWS SDK para Go utilizando las funciones New o NewFromConfig constructoras del paquete del cliente. Al migrar desde la AWS SDK para Go versión 1, le recomendamos que utilice la NewFromConfig variante, que devolverá un nuevo cliente de servicio con los valores de anaws.Config. El valor aws.Config se habrá creado al cargar la configuración compartida del SDK mediante config.LoadDefaultConfig. Para obtener más información sobre la creación de clientes de servicio, consulte Uso de AWS SDK para Go v2 con los servicios de AWS.

Ejemplo 1


// V1

import "github.com/aws/aws-sdk-go/aws/session"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}

client := s3.New(sess)


// V2

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 {
    // handle error
}

client := s3.NewFromConfig(cfg)

Ejemplo 2: Reemplazo de la configuración del cliente


// V1

import "github.com/aws/aws-sdk-go/aws"
import "github.com/aws/aws-sdk-go/aws/session"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

sess, err := session.NewSession()
if err != nil {
    // handle error
}

client := s3.New(sess, &aws.Config{
    Region: aws.String("us-west-2"),
})


// V2

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 {
    // handle error
}

client := s3.NewFromConfig(cfg, func(o *s3.Options) {
    o.Region = "us-west-2"
})

Puntos de conexión

El paquete de puntos de conexión ya no existe en AWS SDK para Go. Cada cliente de servicio ahora incorpora los metadatos de AWS punto final necesarios en el paquete del cliente. Esto reduce el tamaño binario global de las aplicaciones compiladas al dejar de incluir los metadatos de punto de conexión de los servicios que la aplicación no utiliza.

Además, ahora cada servicio expone su propia interfaz para la resolución de puntos de conexión en EndpointResolverV2. Cada API toma un conjunto único de parámetros para un servicio EndpointParameters, cuyos valores los obtiene el SDK de varias ubicaciones al invocarse una operación.

De forma predeterminada, los clientes de servicio utilizan su AWS región configurada para resolver el punto final del servicio en la región de destino. Si su aplicación requiere un punto de conexión personalizado, puede especificar un comportamiento personalizado en el campo EndpointResolverV2 de la estructura aws.Config. Si la aplicación implementa un objeto endpoints.Resolver personalizado, debe migrarlo para que se ajuste a esta nueva interfaz por servicio.

Para obtener más información acerca de los puntos de conexión y de cómo implementar un solucionador personalizado, consulte Configuración de puntos de conexión del cliente.

Autenticación

AWS SDK para Go Admite un comportamiento de autenticación más avanzado, lo que permite el uso de funciones de AWS servicio más recientes, como codecatalyst y S3 Express One Zone. Además, este comportamiento se puede personalizar para cada cliente.

Invocación de operaciones de la API

La cantidad de métodos de operación del cliente de servicio se ha reducido significativamente. Los métodos <OperationName>Request, <OperationName>WithContext y <OperationName> se han consolidado en un solo método de operación, <OperationName>.

Ejemplo

El siguiente ejemplo muestra cómo se migrarían las llamadas a la PutObject operación Amazon S3 de la AWS SDK para Go versión 1 a la versión 2.


// V1

import "context"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

// Pattern 1
output, err := client.PutObject(&s3.PutObjectInput{
    // input parameters
})

// Pattern 2
output, err := client.PutObjectWithContext(context.TODO(), &s3.PutObjectInput{
    // input parameters
})

// Pattern 3
req, output := client.PutObjectRequest(context.TODO(), &s3.PutObjectInput{
    // input parameters
})
err := req.Send()


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

client := s3.NewFromConfig(cfg)

output, err := client.PutObject(context.TODO(), &s3.PutObjectInput{
    // input parameters
})

Tipos de datos de servicio

Los tipos de entrada y salida de nivel superior de una operación se encuentran en el paquete de clientes de servicio. El tipo de entrada y salida de una operación determinada sigue el patrón de <OperationName>Input y <OperationName>Output, donde OperationName es el nombre de la operación que invoca. Por ejemplo, las formas de entrada y salida de la PutObject operación de Amazon S3 son PutObjectInputy PutObjectOutput, respectivamente.

Todos los demás tipos de datos de servicio, excepto los tipos de entrada y salida, se han migrado al paquete types, ubicado en la jerarquía de rutas de importación del paquete de clientes de servicio. Por ejemplo, el s3. AccessControlPolicyel tipo ahora se encuentra en types. AccessControlPolicy.

Valores de enumeración

Ahora el SDK proporciona una experiencia con tipos para todos los campos de enumeración de las API. En lugar de usar un valor literal de cadena copiado de la documentación de referencia de la API del servicio, ahora puede usar uno de los tipos concretos que se encuentran en el paquete types del cliente de servicio. Por ejemplo, puede proporcionar a la PutObjectInput operación Amazon S3 una ACL para aplicarla a un objeto. En la AWS SDK para Go versión 1, este parámetro era un *string tipo. En el AWS SDK para Go, este parámetro ahora es un tipo. ObjectCannedACL. El paquete types proporciona constantes generadas para los valores de enumeración válidos que pueden asignarse a este campo. Por ejemplo, tipos. ObjectCannedACLPrivatees la constante del valor de la ACL predefinida «privada». Este valor se puede usar en lugar de administrar constantes de cadena en la aplicación.

Parámetros de puntero

La AWS SDK para Go versión 1 exigía que se pasaran referencias de puntero para todos los parámetros de entrada a las operaciones de servicio. La AWS SDK para Go versión 2 ha simplificado la experiencia con la mayoría de los servicios al eliminar la necesidad de pasar los valores de entrada como punteros siempre que es posible. Este cambio significa que muchas de las operaciones de clientes de servicio ya no requieren que la aplicación pase referencias de puntero para los tipos siguientes: uint8, uint16, uint32, int8, int16, int32, float32, float64 y bool. Del mismo modo, los tipos de elementos de sector y mapa se han actualizado en consecuencia para reflejar si sus elementos deben pasarse como referencias del puntero.

El paquete aws contiene funciones auxiliares destinadas a crear punteros para los tipos integrados de Go. Estas funciones deben utilizarse con el fin de gestionar la creación de tipos de puntero para estos tipos Go de forma más fácil. Del mismo modo, se proporcionan métodos auxiliares para eliminar de forma segura toda referencia a los valores de puntero de estos tipos. Por ejemplo, la función aws.String convierte de string a *string. A la inversa, las leyes. ToStringconvierte desde *string ⇒string. Al actualizar su aplicación de AWS SDK para Go v1 a la versión 2, debe migrar el uso de los elementos auxiliares para convertir de los tipos de puntero a las variantes sin puntero. Por ejemplo, aws. StringValuedebe actualizarse aaws.ToString.

Tipos de errores

AWS SDK para Go Aprovecha al máximo la funcionalidad de corrección de errores introducida en Go 1.13. Los servicios que modelan respuestas de error han generado tipos disponibles en el paquete types del cliente que pueden utilizarse para probar si alguno de estos tipos ha sido responsable de provocar un error de operación de cliente. Por ejemplo, la operación GetObject de Amazon S3 puede devolver un error NoSuchKey si se intenta recuperar una clave de objeto que no existe. Puedes usar Errors.as para comprobar si el error de operación devuelto es un tipo. NoSuchKeyerror. En el caso de que un servicio no modele un tipo específico para un error, puede utilizar la herrería. APIErrortipo de interfaz para inspeccionar el código de error y el mensaje devueltos por el servicio. Esta funcionalidad reemplaza a Aserr.error y a las demás funciones de awserr de la versión 1. AWS SDK para Go Para obtener más información sobre la gestión de errores, consulte Gestión de errores en AWS SDK para Go V2.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/awserr"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

output, err := s3.GetObject(&s3.GetObjectInput{
    // input parameters
})
if err != nil {
    if awsErr, ok := err.(awserr.Error); ok {
        if awsErr.Code() == "NoSuchKey" {
            // handle NoSuchKey
        } else {
            // handle other codes
        }
        return
    }
    // handle a error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/service/s3"
import "github.com/aws/aws-sdk-go-v2/service/s3/types"
import "github.com/aws/smithy-go"

// ...

client := s3.NewFromConfig(cfg)

output, err := client.GetObject(context.TODO(), &s3.GetObjectInput{
    // input parameters
})
if err != nil {
    var nsk *types.NoSuchKey
    if errors.As(err, &nsk) {
        // handle NoSuchKey error
        return
    }
    var apiErr smithy.APIError
    if errors.As(err, &apiErr) {
        code := apiErr.ErrorCode()
        message := apiErr.ErrorMessage()
        // handle error code
        return
    }
    // handle error
    return
}

Paginadores

Los paginadores de operaciones de servicio ya no se invocan como métodos en el cliente de servicio. A fin de usar un paginador para una operación, debe crear un paginador con este fin mediante uno de los métodos del creador de paginadores. Por ejemplo, para usar paginate sobre la ListObjectsV2 operación Amazon S3, debe construir su paginador con s3. NewListObjectsV2Paginator. Este constructor devuelve un ListObjectsV2Paginator que proporciona los métodos HasMorePages y permite determinar si hay más páginas que recuperar e NextPage invocar la operación para recuperar la página siguiente, respectivamente. En Uso de paginadores de operaciones encontrará más detalles sobre el uso de los paginadores del SDK.

Veamos un ejemplo de cómo migrar de un paginador de la versión 1 al equivalente de la AWS SDK para Go versión 2. AWS SDK para Go

Ejemplo


// V1

import "fmt"
import "github.com/aws/aws-sdk-go/service/s3"

// ...

client := s3.New(sess)

params := &s3.ListObjectsV2Input{
    // input parameters
}

totalObjects := 0
err := client.ListObjectsV2Pages(params, func(output *s3.ListObjectsV2Output, lastPage bool) bool {
    totalObjects += len(output.Contents)
    return !lastPage
})
if err != nil {
    // handle error
}
fmt.Println("total objects:", totalObjects)


// V2

import "context"
import "fmt"
import "github.com/aws/aws-sdk-go-v2/service/s3"

// ...

client := s3.NewFromConfig(cfg)

params := &s3.ListObjectsV2Input{
    // input parameters
}

totalObjects := 0
paginator := s3.NewListObjectsV2Paginator(client, params)
for paginator.HasMorePages() {
    output, err := paginator.NextPage(context.TODO())
    if err != nil {
        // handle error
    }
    totalObjects += len(output.Contents)
}
fmt.Println("total objects:", totalObjects)

Waiters

Los esperadores de operaciones de servicio ya no se invocan como métodos en el cliente de servicio. Para utilizar un esperador, primero debe crear el tipo de esperador deseado y, a continuación, invocar el método de espera. Por ejemplo, para esperar a que exista un bucket de Amazon S3, debe crear un esperador BucketExists. Usa el s3. NewBucketExistsWaiterconstructor para crear un s3. BucketExistsWaiter. s3.BucketExistsWaiter proporciona un método Wait que se puede utilizar para esperar a que un bucket se encuentre disponible.

Solicitudes prefirmadas

Técnicamente, el SDK de la versión V1 permitía prefirmar cualquier operación del AWS SDK; sin embargo, esto no representa con precisión lo que realmente se admite a nivel de servicio (y, en realidad, la mayoría de las operaciones de AWS servicio no admiten la prefirma).

AWS SDK para Go resuelve este problema exponiendo PresignClient implementaciones específicas en paquetes de servicios con operaciones predefinidas específicas APIs para cada tipo de soporte.

Nota: Si a un servicio no se le permite prefirmar una operación que estabas utilizando correctamente en el SDK v1, comunícanoslo mediante la notificación de problemas. GitHub

Utiliza Presign y PresignRequestdebe convertirse para utilizar clientes de presignación específicos del servicio.

El siguiente ejemplo muestra cómo migrar la prefirma de una solicitud de S3: GetObject


// V1

import (
    "fmt"
    "time"

    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

func main() {
    sess := session.Must(session.NewSessionWithOptions(session.Options{
        SharedConfigState: session.SharedConfigEnable,
    }))

    svc := s3.New(sess)
    req, _ := svc.GetObjectRequest(&s3.GetObjectInput{
        Bucket: aws.String("amzn-s3-demo-bucket"),
        Key:    aws.String("key"),
    })

    // pattern 1
    url1, err := req.Presign(20 * time.Minute)
    if err != nil {
        panic(err)
    }
    fmt.Println(url1)

    // pattern 2
    url2, header, err := req.PresignRequest(20 * time.Minute)
    if err != nil {
        panic(err)
    }
    fmt.Println(url2, header)
}


// V2

import (
    "context"
    "fmt"
    "time"

    "github.com/aws/aws-sdk-go-v2/aws"
    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
)

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        panic(err)
    }

    svc := s3.NewPresignClient(s3.NewFromConfig(cfg))
    req, err := svc.PresignGetObject(context.Background(), &s3.GetObjectInput{
        Bucket: aws.String("amzn-s3-demo-bucket"),
        Key:    aws.String("key"),
    }, func(o *s3.PresignOptions) {
        o.Expires = 20 * time.Minute
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(req.Method, req.URL, req.SignedHeader)
}

Personalización de solicitudes

La API request.Request monolítica se ha vuelto a compartimentar.

Entrada/salida de la operación

Ahora se puede acceder a los campos Request opacos Params y Data, que contienen las estructuras de entrada y salida de la operación, respectivamente, en fases del middleware específicas como entrada/salida:

Los controladores de solicitudes que hagan referencia a Request.Params y Request.Data deben migrarse al middleware.

migración de `Params`


// V1

import (
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/request"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

func withPutObjectDefaultACL(acl string) request.Option {
    return func(r *request.Request) {
        in, ok := r.Params.(*s3.PutObjectInput)
        if !ok {
            return
        }

        if in.ACL == nil {
            in.ACL = aws.String(acl)
        }
        r.Params = in
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Validate.PushBack(withPutObjectDefaultACL(s3.ObjectCannedACLBucketOwnerFullControl))

    // ...
}


// V2

import (
    "context"

    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/aws-sdk-go-v2/service/s3/types"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type withPutObjectDefaultACL struct {
    acl types.ObjectCannedACL
}

// implements middleware.InitializeMiddleware, which runs BEFORE a request has
// been serialized and can act on the operation input
var _ middleware.InitializeMiddleware = (*withPutObjectDefaultACL)(nil)

func (*withPutObjectDefaultACL) ID() string {
    return "withPutObjectDefaultACL"
}

func (m *withPutObjectDefaultACL) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) (
    out middleware.InitializeOutput, metadata middleware.Metadata, err error,
) {
    input, ok := in.Parameters.(*s3.PutObjectInput)
    if !ok {
        return next.HandleInitialize(ctx, in)
    }

    if len(input.ACL) == 0 {
        input.ACL = m.acl
    }
    in.Parameters = input
    return next.HandleInitialize(ctx, in)
}

// create a helper function to simplify instrumentation of our middleware
func WithPutObjectDefaultACL(acl types.ObjectCannedACL) func (*s3.Options) {
    return func(o *s3.Options) {
        o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
            return s.Initialize.Add(&withPutObjectDefaultACL{acl: acl}, middleware.After)
        })
    }
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithPutObjectDefaultACL(types.ObjectCannedACLBucketOwnerFullControl))
    // ...
}

migración de `Data`


// V1

import (
    "github.com/aws/aws-sdk-go/aws"
    "github.com/aws/aws-sdk-go/aws/request"
    "github.com/aws/aws-sdk-go/aws/session"
    "github.com/aws/aws-sdk-go/service/s3"
)

func readPutObjectOutput(r *request.Request) {
        output, ok := r.Data.(*s3.PutObjectOutput)
        if !ok {
            return
        }

        // ...
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Unmarshal.PushBack(readPutObjectOutput)

    svc := s3.New(sess)
    // ...
}


// V2

import (
    "context"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type readPutObjectOutput struct{}

var _ middleware.DeserializeMiddleware = (*readPutObjectOutput)(nil)

func (*readPutObjectOutput) ID() string {
    return "readPutObjectOutput"
}

func (*readPutObjectOutput) HandleDeserialize(ctx context.Context, in middleware.DeserializeInput, next middleware.DeserializeHandler) (
    out middleware.DeserializeOutput, metadata middleware.Metadata, err error,
) {
    out, metadata, err = next.HandleDeserialize(ctx, in)
    if err != nil {
        // ...
    }

    output, ok := in.Parameters.(*s3.PutObjectOutput)
    if !ok {
        return out, metadata, err
    }

    // inspect output...

    return out, metadata, err
}

func WithReadPutObjectOutput(o *s3.Options) {
    o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
        return s.Initialize.Add(&withReadPutObjectOutput{}, middleware.Before)
    })
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithReadPutObjectOutput)
    // ...
}

Solicitud/respuesta HTTP

Ahora, los campos HTTPRequest y HTTPResponse de Request se exponen en fases específicas del middleware. Como el middleware es independiente del transporte, debe realizar una aserción de tipo en la entrada o salida del middleware para revelar la solicitud o la respuesta HTTP subyacente.

Los controladores de solicitudes que hagan referencia a Request.HTTPRequest y Request.HTTPResponse deben migrarse al middleware.

migración de `HTTPRequest`


// V1

import (
    "github.com/aws/aws-sdk-go/aws/request"
    "github.com/aws/aws-sdk-go/aws/session"
)

func withHeader(header, val string) request.Option {
    return func(r *request.Request) {
        request.HTTPRequest.Header.Set(header, val)
    }
}

func main() {
    sess := session.Must(session.NewSession())
    sess.Handlers.Build.PushBack(withHeader("x-user-header", "..."))

    svc := s3.New(sess)
    // ...
}


// V2

import (
    "context"
    "fmt"

    "github.com/aws/aws-sdk-go-v2/config"
    "github.com/aws/aws-sdk-go-v2/service/s3"
    "github.com/aws/smithy-go/middleware"
    smithyhttp "github.com/aws/smithy-go/transport/http"
)

type withHeader struct {
    header, val string
}

// implements middleware.BuildMiddleware, which runs AFTER a request has been
// serialized and can operate on the transport request
var _ middleware.BuildMiddleware = (*withHeader)(nil)

func (*withHeader) ID() string {
    return "withHeader"
}

func (m *withHeader) HandleBuild(ctx context.Context, in middleware.BuildInput, next middleware.BuildHandler) (
    out middleware.BuildOutput, metadata middleware.Metadata, err error,
) {
    req, ok := in.Request.(*smithyhttp.Request)
    if !ok {
        return out, metadata, fmt.Errorf("unrecognized transport type %T", in.Request)
    }

    req.Header.Set(m.header, m.val)
    return next.HandleBuild(ctx, in)
}

func WithHeader(header, val string) func (*s3.Options) {
    return func(o *s3.Options) {
        o.APIOptions = append(o.APIOptions, func (s *middleware.Stack) error {
            return s.Build.Add(&withHeader{
                header: header,
                val: val,
            }, middleware.After)
        })
    }
}

func main() {
    cfg, err := config.LoadDefaultConfig(context.Background())
    if err != nil {
        // ...
    }

    svc := s3.NewFromConfig(cfg, WithHeader("x-user-header", "..."))
    // ...
}

Fases del controlador

Las fases del middleware del SDK v2 son las sucesoras de las fases del controlador de la versión 1.

En la tabla siguiente se proporciona una correspondencia aproximada entre las fases del controlador de la versión 1 y su ubicación equivalente en la pila de middleware de la versión 2:

Nombre del controlador de v1	Fase de middleware de v2
Valide	Initialize
Build	Serialize
Sign	Finalize
Send	n/a (1)
ValidateResponse	Deserialize
Unmarshal	Deserialize
UnmarshalMetadata	Deserialize
UnmarshalError	Deserialize
Retry	Finalize, posterior al middleware `"Retry"` (2)
AfterRetry	Finalize, anterior al middleware `"Retry"`, posterior a `next.HandleFinalize()` (2, 3)
CompleteAttempt	Finalize, final del paso
Completado	Initialize, comienzo del paso, posterior a `next.HandleInitialize()` (3)

(1) La fase Send de la versión 1 es, en efecto, el ciclo de ida y vuelta del cliente HTTP encapsulado de la versión 2. El campo HTTPClient controla este comportamiento en las opciones de cliente.

(2) Cualquier middleware posterior al middleware "Retry" del paso Finalize formará parte del bucle de reintentos.

(3) Durante la operación, la “pila” de middleware se integra en una función de controlador repetidamente decorada. Cada controlador es responsable de llamar al siguiente de la cadena. Esto significa implícitamente que un paso de middleware también puede actuar DESPUÉS de que se haya llamado a su siguiente paso.

Por ejemplo, en el caso del paso Initialize, que se encuentra en la parte superior de la pila, significa que los middlewares de Initialize que actúan tras llamar al siguiente controlador funcionan de manera efectiva al final de la solicitud:


// V2

import (
    "context"

    "github.com/aws/smithy-go/middleware"
)

type onComplete struct{}

var _ middleware.InitializeMiddleware = (*onComplete)(nil)

func (*onComplete) ID() string {
    return "onComplete"
}

func (*onComplete) HandleInitialize(ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler) (
    out middleware.InitializeOutput, metadata middleware.Metadata, err error,
) {
    out, metadata, err = next.HandleInitialize(ctx, in)

    // the entire operation was invoked above - the deserialized response is
    // available opaquely in out.Result, run post-op actions here...

    return out, metadata, err
}

Características

Servicio de metadatos de EC2 instancias de Amazon

AWS SDK para Go Proporciona un cliente de Amazon EC2 Instance Metadata Service (IMDS) que puede utilizar para consultar el IMDS local al ejecutar la aplicación en una instancia de Amazon EC2 . El cliente IMDS es un módulo de Go independiente que se puede agregar a la aplicación mediante:


go get github.com/aws/aws-sdk-go-v2/feature/ec2/imds

El creador de clientes y las operaciones de método se han actualizado para ajustarse al diseño de los demás clientes de servicio del SDK.

Ejemplo


// V1

import "github.com/aws/aws-sdk-go/aws/ec2metadata"

// ...

client := ec2metadata.New(sess)

region, err := client.Region()
if err != nil {
    // handle error
}


// V2

import "context"
import "github.com/aws/aws-sdk-go-v2/feature/ec2/imds"

// ...

client := imds.NewFromConfig(cfg)

region, err := client.GetRegion(context.TODO())
if err != nil {
    // handle error
}

Amazon S3 Transfer Manager

El administrador de transferencias de Amazon S3 está disponible para administrar cargas y descargas de objetos de forma simultánea. Este paquete se encuentra en un módulo de Go fuera de la ruta de importación del cliente de servicio. Este módulo se puede recuperar mediante go get github.com/aws/aws-sdk-go-v2/feature/s3/manager.

s3. NewUploadery s3. NewUploaderWithClienthan sido reemplazados por el administrador de métodos del constructor. NewUploaderpara crear un cliente de gestión de subidas.

s3. NewDownloadery s3. NewDownloaderWithClienthan sido reemplazados por un único administrador de métodos de construcción. NewDownloaderpara crear un cliente gestor de descargas.

Utilidades de CloudFront firma de Amazon

AWS SDK para Go Proporciona las utilidades de CloudFront firma de Amazon en un módulo Go fuera de la ruta de importación del cliente del servicio. Este módulo se puede recuperar mediante go get.


go get github.com/aws/aws-sdk-go-v2/feature/cloudfront/sign

Cliente de cifrado de Amazon S3

A partir de AWS SDK para Go ahora, el cliente de cifrado Amazon S3 es un módulo independiente de AWS Crypto Tools. La última versión del cliente de cifrado S3 para Go, 3.x, ya está disponible en GitHub. Este módulo se puede recuperar mediante go get:


go get github.com/aws/amazon-s3-encryption-client-go/v3

Las versiones independientes EncryptionClient (v1, v2) y DecryptionClient (v1, v2) se APIs han sustituido por un único cliente, el S3 EncryptionClient V3, que ofrece funciones tanto de cifrado como de descifrado.

Al igual que otros clientes de servicios AWS SDK para Go, la operación APIs se ha reducido:

El GetObjectGetObjectRequest, y el GetObjectWithContext descifrado APIs se sustituyen por GetObject.
El PutObjectPutObjectRequest, y el PutObjectWithContext cifrado APIs se sustituyen por PutObject.

Para obtener información sobre cómo migrar a la versión principal del cliente de cifrado (3.x), consulte esta guía.

Cambios en las personalizaciones de servicios

Amazon S3

Al migrar de la versión AWS SDK para Go 1 a la versión 2, un cambio importante que hay que tener en cuenta es el manejo del material SSECustomerKey utilizado para el cifrado del lado del servidor con claves proporcionadas por el cliente (SSE-C). En la AWS SDK para Go versión 1, el SDK gestionaba internamente la codificación SSECustomerKey para Base64. En el SDK v2, esta codificación automática se ha eliminado y ahora es necesario codificar SSECustomerKey de forma manual en Base64 antes de pasarlo al SDK.

Ajuste de ejemplo:


// V1

import (
  "context"
  "encoding/base64"
  "github.com/aws/aws-sdk-go-v2/config"
  "github.com/aws/aws-sdk-go-v2/service/s3"
)
// ... more code

plainTextKey := "12345678901234567890123456789012" // 32 bytes in length

// calculate md5..

_, err = client.PutObjectWithContext(context.Background(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("your-object-key"),
    Body:                 strings.NewReader("hello-world"),
    SSECustomerKey:       &plainTextKey,
    SSECustomerKeyMD5:    &base64Md5,
    SSECustomerAlgorithm: aws.String("AES256"),
})

// ... more code


// V2

import (
  "github.com/aws/aws-sdk-go/aws"
  "github.com/aws/aws-sdk-go/aws/session"
  "github.com/aws/aws-sdk-go/service/s3"
)

// ... more code

plainTextKey := "12345678901234567890123456789012" // 32 bytes in length
base64EncodedKey := base64.StdEncoding.EncodeToString([]byte(plainTextKey))

// calculate md5..

_, err = client.PutObject(context.Background(), &s3.PutObjectInput{
    Bucket: aws.String("amzn-s3-demo-bucket"),
    Key:    aws.String("your-object-key"),
    Body:                 strings.NewReader("hello-world"),
    SSECustomerKey:       &base64EncodedKey,
    SSECustomerKeyMD5:    &base64Md5,
    SSECustomerAlgorithm: aws.String("AES256"),
})

// ... more code

Aviso JavaScript está desactivado o no está disponible en su navegador.

Para utilizar la documentación de AWS, debe estar habilitado JavaScript. Para obtener más información, consulte las páginas de ayuda de su navegador.

Convenciones del documento

Amazon SQS

Seguridad

Migre a la AWS SDK para Go versión 2

Versión mínima de Go

Modularización

Carga de la configuración

Ejemplos

Migrar de a NewSession LoadDefaultConfig

Migrar desde NewSession con las opciones de AWS.config

Migrando desde NewSessionWithOptions

Simulación e *iface

Credenciales y proveedores de credenciales

Credenciales estáticas

Ejemplo

Credenciales de rol de Amazon EC2 IAM

Ejemplo

Credenciales de los puntos de conexión

Credenciales de proceso

Ejemplo

AWS Security Token Service Credenciales

AssumeRole

Ejemplo

AssumeRoleWithWebIdentity

Ejemplo

Clientes de servicio

Creación de clientes

Ejemplo 1

Ejemplo 2: Reemplazo de la configuración del cliente

Puntos de conexión

Autenticación

Invocación de operaciones de la API

Ejemplo

Tipos de datos de servicio

Valores de enumeración

Parámetros de puntero

Tipos de errores

Ejemplo

Paginadores

Ejemplo

Waiters

Solicitudes prefirmadas

Personalización de solicitudes

Entrada/salida de la operación

migración de Params

migración de Data

Solicitud/respuesta HTTP

migración de HTTPRequest

Fases del controlador

Características

Servicio de metadatos de EC2 instancias de Amazon

Ejemplo

Amazon S3 Transfer Manager

Utilidades de CloudFront firma de Amazon

Cliente de cifrado de Amazon S3

Cambios en las personalizaciones de servicios

Amazon S3

Simulación e `*iface`

migración de `Params`

migración de `Data`

migración de `HTTPRequest`