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.
# Configurar el SDK
En la AWS SDK para Go versión 2, puede configurar los ajustes comunes para los clientes de servicio, como el registrador, el nivel de registro y la configuración de reintentos. La mayoría de los ajustes son opcionales. Sin embargo, para cada cliente de servicio, debe especificar una AWS región y sus credenciales. El SDK usa estos valores para enviar solicitudes a la región correcta y firmar las solicitudes con las credenciales correctas. Puede especificar estos valores mediante programación en el código o a través del entorno de ejecución.
## Cargando archivos de configuración AWS compartidos
Existen varias formas de inicializar un cliente de API de servicio, pero el siguiente patrón es el más común que se recomienda a los usuarios.
Para configurar el SDK para que utilice los archivos de configuración AWS compartidos, utilice el siguiente código:
```
import (
"context"
"log"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
log.Fatalf("failed to load configuration, %v", err)
}
```
`config.LoadDefaultConfig(context.TODO())`construirá un [AWS.config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) utilizando las fuentes de configuración AWS compartidas. Esto incluye configurar un proveedor de credenciales, configurar la AWS región y cargar la configuración específica del servicio. Los clientes de servicio se pueden crear mediante la instancia de `aws.Config` cargada, lo que proporciona un patrón coherente para la creación de clientes.
Para obtener más información sobre los archivos de configuración AWS compartidos, consulte [Configuración](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) en la Guía de referencia de herramientas AWS SDKs y herramientas.
## Especificación de la AWS región
A especificar la región, se especifica dónde enviar las solicitudes, por ejemplo, `us-west-2` o `us-east-2`. Para ver una lista de regiones para cada servicio, consulte [Puntos de conexión de servicio y cuotas](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) en la Referencia general de Amazon Web Services.
El SDK no tiene ninguna región predeterminada. Para especificar una región:
+ Establezca la variable de entorno `AWS_REGION` en la región predeterminada.
+ Establezca la región de forma explícita mediante la [configuración. WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127)como argumento `config.LoadDefaultConfig` al cargar la configuración.
Revisión: Si establece una región mediante todas estas técnicas, el SDK utilizará la región que haya especificado de forma explícita.
### Configuración de la región con una variable de entorno
#### Linux, macOS o Unix
```
export AWS_REGION=us-west-2
```
#### Windows
```
set AWS_REGION=us-west-2
```
### Especificación de la región mediante programación
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## Especificación de credenciales
AWS SDK para Go Requiere credenciales (una clave de acceso y una clave de acceso secreta) para firmar las solicitudes AWS. Puede especificar sus credenciales en varias ubicaciones, en función de su caso de uso concreto. Para obtener más información sobre cómo obtener las credenciales, consulte [Empiece a utilizar AWS SDK para Go](getting-started.md).
Al inicializar una `aws.Config` instancia mediante`config.LoadDefaultConfig`, el SDK utiliza su cadena de credenciales predeterminada para buscar AWS las credenciales. Esta cadena de credenciales predeterminada busca las credenciales en este orden:
1. Variables de entorno.
1. Credenciales estáticas (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` y `AWS_SESSION_TOKEN`)
1. Token de identidad web (`AWS_WEB_IDENTITY_TOKEN_FILE`)
1. Archivos de configuración compartida
1. El SDK tiene como valor predeterminado el archivo `credentials` de la carpeta `.aws` que se encuentra en la carpeta de inicio de su computadora.
1. El SDK tiene como valor predeterminado el archivo `config` de la carpeta `.aws` que se encuentra en la carpeta de inicio de su computadora.
1. Si su aplicación utiliza una definición de tareas o una operación de RunTask API de Amazon ECS, la función de IAM para las tareas.
1. Si la aplicación se ejecuta en una instancia de Amazon EC2, el rol de IAM para Amazon EC2.
El SDK detecta y utiliza los proveedores integrados de forma automática, sin necesidad de realizar configuraciones manuales. Por ejemplo, si utiliza roles de IAM para las instancias de Amazon EC2, sus aplicaciones utilizarán las credenciales de la instancia de forma automática. No es necesario configurar manualmente las credenciales en la aplicación.
Como práctica recomendada, se AWS recomienda especificar las credenciales en el siguiente orden:
1. Utilice funciones de IAM para las tareas si su aplicación utiliza una definición de tarea o una operación de RunTask API de Amazon ECS.
1. Use roles de IAM para Amazon EC2 (si la aplicación se ejecuta en una instancia de Amazon EC2).
Los roles de IAM proporcionan a las aplicaciones de la instancia credenciales de seguridad temporales para realizar AWS llamadas. Los roles de IAM ofrecen una forma sencilla de distribuir y administrar credenciales en varias instancias de Amazon EC2.
1. Utilice archivos de configuración o credenciales compartidos.
Las credenciales y los archivos de configuración se comparten entre otras AWS SDKs y AWS CLI. Como práctica recomendada de seguridad, recomendamos utilizar un archivo de credenciales para configurar valores confidenciales, como la clave de acceso IDs y las claves secretas. Estos son los [requisitos de formato](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) para cada uno de estos archivos.
1. Utilice variables de entorno.
La configuración de las variables de entorno es útil si está realizando trabajos de desarrollo en un equipo que no sea una instancia de Amazon EC2.
### Roles de IAM para las tareas
Si su aplicación utiliza una definición de tarea de Amazon ECS o una operación `RunTask`, utilice [roles de IAM para las tareas](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) a fin de especificar un rol de IAM que los contenedores puedan utilizar en una tarea.
### Roles de IAM para las instancias de Amazon EC2
Si ejecuta una aplicación en una instancia de Amazon EC2, utilice el [rol de IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) de la instancia a fin de obtener credenciales de seguridad temporales para realizar llamadas a AWS.
Si ha configurado la instancia para que utilice roles de IAM, el SDK utiliza estas credenciales para su aplicación de forma automática. No es necesario especificar las credenciales manualmente.
### Credenciales y configuración compartidas
Las credenciales compartidas y los archivos de configuración se pueden usar para compartir configuraciones comunes AWS SDKs entre otras herramientas. Si utiliza credenciales distintas para cada herramienta o aplicación, puede utilizar *perfiles* para configurar varias claves de acceso en el mismo archivo de configuración.
Puede proporcionar varias ubicaciones de archivos de credenciales y de configuración mediante `config.LoadOptions`. De forma predeterminada, el SDK carga los archivos almacenados en las ubicaciones predeterminadas que se indican en [Especificación de credenciales](#specifying-credentials).
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg , err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedCredentialsFiles(
[]string{"test/credentials", "data/credentials"},
),
config.WithSharedConfigFiles(
[]string{"test/config", "data/config"},
)
)
```
Al trabajar con archivos de credenciales y configuración compartidas, en caso de especificarse perfiles duplicados estos se fusionan para resolver un perfil. En caso de conflicto al fusionar:
1. Si se especifican perfiles duplicados en un mismo credentials/config archivo, prevalecen las propiedades del perfil especificadas en este último perfil.
1. Si se especifican perfiles duplicados en varios archivos de credenciales o de configuración, las propiedades de perfil se resolverán según el orden de entrada del archivo en `config.LoadOptions`. Las propiedades de perfil de los últimos archivos tienen prioridad.
1. Si existe un perfil tanto en el archivo de credenciales como en el de configuración, las propiedades del archivo de credenciales tendrán prioridad.
Si es necesario, puede habilitar `LogConfigurationWarnings` en `config.LoadOptions` y registrar los pasos de resolución de perfiles.
#### Creación del archivo de credenciales
Si no tiene un archivo de credenciales compartido (`.aws/credentials`), puede usar cualquier editor de texto para crear uno en su directorio principal. Añada el siguiente contenido a su archivo de credenciales, sustituyendo ** y ** por sus credenciales.
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
El encabezado `[default]` define las credenciales para el perfil predeterminado, que el SDK utilizará a menos que lo configure para usar otro perfil.
También puede utilizar credenciales de seguridad temporales mediante la adición de los tokens de sesión a su perfil, como se muestra en el ejemplo siguiente:
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
El nombre de la sección correspondiente a un perfil no predeterminado en un archivo de credenciales no debe empezar por la palabra `profile`. Puede obtener más información en la [Guía AWS SDKs de referencia de herramientas](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds).
#### Creación del archivo de configuración
Si no tiene un archivo de credenciales compartido (`.aws/config`), puede usar cualquier editor de texto para crear uno en su directorio principal. Añada el siguiente contenido a su archivo de configuración y ** sustitúyalo por la región deseada.
```
[default]
region =
```
El encabezado `[default]` define la configuración para el perfil predeterminado, que el SDK utilizará a menos que lo configure para usar otro perfil.
Puede utilizar perfiles con nombre, como se muestra en el ejemplo siguiente:
```
[profile named-profile]
region =
```
El nombre de sección de un perfil no predeterminado de un archivo de configuración siempre debe empezar por la palabra `profile`, seguida del nombre de perfil previsto. Puede obtener más información en la [Guía de referencia de herramientas AWS SDKs y herramientas](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config).
#### Especificación de perfiles
Puede incluir varias claves de acceso en el mismo archivo de configuración; para ello, asocie cada conjunto de claves de acceso a un perfil. Por ejemplo, en el archivo de credenciales, puede declarar varios perfiles, de la siguiente manera.
```
[default]
aws_access_key_id =
aws_secret_access_key =
[test-account]
aws_access_key_id =
aws_secret_access_key =
[prod-account]
; work profile
aws_access_key_id =
aws_secret_access_key =
```
De forma predeterminada, el SDK comprueba la variable de entorno `AWS_PROFILE` para determinar qué perfil se va a utilizar. Si no se ha establecido ninguna variable `AWS_PROFILE`, el SDK usa el perfil `default`.
Puede que a veces quiera utilizar un perfil diferente con su aplicación. Por ejemplo, desea usar las credenciales `test-account` con su aplicación `myapp`. Puede usar este perfil mediante el siguiente comando:
```
$ AWS_PROFILE=test-account myapp
```
También puede indicar al SDK que seleccione un perfil mediante una llamada a `os.Setenv("AWS_PROFILE", "test-account")` antes de llamar a `config.LoadDefaultConfig`, o mediante la transferencia de un perfil explícito como argumento, como se muestra en el ejemplo siguiente:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**nota**
Si especifica las credenciales en variables de entorno, el SDK siempre usará esas credenciales, independientemente del perfil que especifique.
### Variables de entorno
De forma predeterminada, el SDK detecta AWS las credenciales configuradas en su entorno y las utiliza para firmar las solicitudes AWS. De ese modo, no es necesario administrar las credenciales en las aplicaciones.
El SDK busca credenciales en las siguientes variables de entorno:
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (opcional)
En los ejemplos siguientes se muestra cómo configurar las variables de entorno:
#### Linux, OS X o Unix
```
$ export AWS_ACCESS_KEY_ID=YOUR_AKID
$ export AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
$ export AWS_SESSION_TOKEN=TOKEN
```
#### Windows
```
> set AWS_ACCESS_KEY_ID=YOUR_AKID
> set AWS_SECRET_ACCESS_KEY=YOUR_SECRET_KEY
> set AWS_SESSION_TOKEN=TOKEN
```
### Especificación de credenciales mediante programación
`config.LoadDefaultConfig`le permite proporcionar una [AWS explícita. CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)al cargar las fuentes de configuración compartidas. Para pasar un proveedor de credenciales explícito al cargar la configuración compartida, utilice [config. WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider). Por ejemplo, si `customProvider` hace referencia a una instancia de implementación de `aws.CredentialProvider`, se puede transferir durante la carga de la configuración de la siguiente manera:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
Si proporciona credenciales de forma explícita, como en este ejemplo, el SDK solo usa esas credenciales.
**nota**
Todos los proveedores de credenciales transferidos o devueltos `LoadDefaultConfig` se incluyen de forma [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache)automática. Esto permite un almacenamiento en caché y una rotación de credenciales seguros para el uso simultáneo. Si configuras explícitamente un proveedor `aws.Config` directamente, también debes empaquetar explícitamente el proveedor con este tipo mediante [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache).
#### Credenciales estáticas
Puede codificar de forma rígida las credenciales en su aplicación mediante las [credenciales. NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider)proveedor de credenciales para establecer de forma explícita las claves de acceso que se van a utilizar. Por ejemplo:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**aviso**
No incruste credenciales dentro de una aplicación. Use este método solo con fines de prueba.
#### Credenciales de inicio de sesión único
El SDK proporciona un proveedor de credenciales para recuperar credenciales temporales AWS mediante. AWS IAM Identity Center Con el AWS CLI, se autentica en el portal de acceso y se autoriza el AWS acceso a las credenciales temporales. AWS A continuación, configuras la aplicación para que cargue el perfil de inicio de sesión único (SSO) y el SDK utiliza tus credenciales de SSO para recuperar las AWS credenciales temporales que se renovarán automáticamente si caducan. Si sus credenciales de SSO caducan, debe renovarlas de forma explícita. Para ello, vuelva a iniciar sesión en su cuenta del Centro de Identidad de IAM mediante. AWS CLI
Por ejemplo, puede crear un perfil`dev-profile`, autenticar y autorizar ese perfil mediante la AWS CLI aplicación y configurar su aplicación como se muestra a continuación.
1. Primero, cree los elementos `profile` y `sso-session`.
```
[profile dev-profile]
sso_session = dev-session
sso_account_id = 012345678901
sso_role_name = Developer
region = us-east-1
[sso-session dev-session]
sso_region = us-west-2
sso_start_url = https://company-sso-portal.awsapps.com/start
sso_registration_scopes = sso:account:access
```
1. Inicie sesión con el AWS CLI para autenticar y autorizar el perfil de inicio de sesión único.
```
$ aws --profile dev-profile sso login
Attempting to automatically open the SSO authorization page in your default browser.
If the browser does not open or you wish to use a different device to authorize this request, open the following URL:
https://device.sso.us-west-2.amazonaws.com/
Then enter the code:
ABCD-EFGH
Successully logged into Start URL: https://company-sso-portal.awsapps.com/start
```
1. A continuación, configure la aplicación para que utilice el perfil de SSO.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Para obtener más información sobre la configuración de los perfiles de SSO y la autenticación mediante el uso, AWS CLI consulte [Configuración del uso AWS IAM Identity Center en la AWS CLI Guía del](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) usuario. AWS CLI Para obtener más información sobre cómo crear el proveedor de credenciales de SSO mediante programación, consulte la documentación de referencia de la API [ssocreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds).
#### Credenciales de acceso
Puede usar sus credenciales de inicio de sesión AWS de Management Console actuales para acceder a AWS los servicios mediante programación. Tras un flujo de autenticación basado en un navegador, AWS genera credenciales temporales que funcionan en todas las herramientas de desarrollo local, como la AWS CLI y Herramientas de AWS para PowerShell . AWS SDKs Esta función simplifica el proceso de configuración y administración de las credenciales de AWS CLI, especialmente si prefiere la autenticación interactiva en lugar de administrar las claves de acceso a largo plazo.
1. Inicie el flujo de inicio de sesión mediante la AWS CLI y siga las instrucciones del navegador. En este ejemplo, guardamos la sesión de inicio de sesión en un perfil nuevo**dev-profile**, pero esto es opcional.
```
$ aws --profile dev-profile login
```
1. (Opcional) Inspeccione el archivo de configuración AWS compartido para comprobar que la sesión se ha establecido.
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. A continuación, configure la aplicación para que utilice el perfil de inicio de sesión.
```
import "github.com/aws/aws-sdk-go-v2/config"
// ...
cfg, err := config.LoadDefaultConfig(
context.Background(),
// only necessary if login session is saved to a non-default profile
config.WithSharedConfigProfile("dev-profile"),
)
if err != nil {
return err
}
```
Para obtener más información sobre la configuración de los perfiles de inicio de sesión y la autenticación mediante la AWS CLI, consulte [Inicio de sesión para el desarrollo AWS local con credenciales de consola](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html).
#### Otros proveedores de credenciales
El SDK proporciona otros métodos para recuperar credenciales en el módulo [credentials](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials). Por ejemplo, puede recuperar credenciales de seguridad temporales AWS Security Token Service o credenciales de un almacenamiento cifrado.
**Proveedores de credenciales disponibles**:
+ [ec2rolecreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds): recupere credenciales de roles de instancias de Amazon EC2 a través de servicios de metadatos de instancias (IMDS) de Amazon EC2.
+ [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds): recupere credenciales de un punto de conexión HTTP arbitrario.
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds): recupere credenciales de un proceso externo que invocará el intérprete de comandos del entorno de host.
+ [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds): recupera credenciales de AWS STS
# Configuración de la autenticación
AWS SDK para Go ofrece la posibilidad de configurar el servicio de comportamiento de autenticación. En la mayoría de los casos, la configuración predeterminada será suficiente, pero la configuración de autenticación personalizada permite un comportamiento adicional, como trabajar con características del servicio previas al lanzamiento.
## Definiciones
En esta sección se proporciona una descripción detallada de los componentes de autenticación de AWS SDK para Go.
### AuthScheme
[AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme) es la interfaz que define el flujo de trabajo a través del cual el SDK recupera la identidad del intermediario y la asocia a una solicitud de operación.
Un esquema de autenticación utiliza los componentes siguientes, que se describen en detalle más adelante:
+ Un ID único que identifica el esquema
+ Un solucionador de identidades, que devuelve la identidad del intermediario utilizada en el proceso de firma (por ejemplo, sus credenciales de AWS)
+ Un firmante, que es el que realmente inyecta la identidad del intermediario en la solicitud de transporte de la operación (por ejemplo, el encabezado HTTP `Authorization`)
Cada opción de cliente de servicio incluye un campo `AuthSchemes` que, de forma predeterminada, se rellena con la lista de esquemas de autenticación compatibles con ese servicio.
### AuthSchemeResolver
Cada opción de cliente de servicio incluye un campo `AuthSchemeResolver`. Esta interfaz, definida por servicio, es la API a la que llama el SDK para determinar las opciones de autenticación posibles para cada operación.
**importante**
El solucionador de esquemas de autenticación NO dicta qué esquema de autenticación se usa. Devuelve una lista de esquemas que se *pueden* usar (“opciones”); el esquema final se selecciona a través de un algoritmo fijo que se describe [aquí](#auth-scheme-resolution-workflow).
### Opción
Un valor [Option](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option), devuelto de una llamada a `ResolverAuthSchemes`, representa una posible opción de autenticación.
Una opción consta de tres conjuntos de información:
+ Un identificador que representa el posible esquema
+ Un conjunto opaco de propiedades que se proporcionará al solucionador de identidades del esquema
+ Un conjunto opaco de propiedades que se proporcionará al firmante del esquema
#### Nota sobre las propiedades
En el 99 % de los casos de uso, los intermediarios no tienen por qué preocuparse por las propiedades opacas para la resolución de identidades y la firma. El SDK extraerá las propiedades necesarias para cada esquema y las pasará a las interfaces con establecimiento inflexible de tipos expuestas en el SDK. Por ejemplo, el solucionador de autenticación predeterminado para servicios codifica la opción SigV4 de modo que tenga propiedades del firmante para la región y el nombre de la firma, cuyos valores se pasan a la implementación de [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) configurada del cliente al seleccionarse SigV4.
### Identidad
[Identity](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) es una representación abstracta de quién es el intermediario del SDK.
El tipo de identidad más común que se utiliza en el SDK es un conjunto de `aws.Credentials`. En la mayoría de los casos de uso, el intermediario no tiene por qué preocuparse de `Identity` como abstracción y puede trabajar directamente con los tipos concretos.
**nota**
Para conservar la compatibilidad con versiones anteriores y evitar confusiones en relación con la API, el tipo de identidad `aws.Credentials` específico del SDK de AWS no cumple directamente con la interfaz `Identity`. Esta asignación se gestiona de forma interna.
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver) es la interfaz a través de la cual se recupera un valor `Identity`.
Existen versiones concretas de `IdentityResolver` en el SDK con establecimiento inflexible de tipos (por ejemplo, [aws.CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)). El SDK gestiona esta asignación de forma interna.
Un intermediario solo tendrá que implementar directamente la interfaz `IdentityResolver` al definir un esquema de autenticación externo.
### Signer
[Signer](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) es la interfaz a través de la cual se complementa una solicitud con el valor `Identity` del intermediario recuperado.
Existen versiones concretas de `Signer` en el SDK con establecimiento inflexible de tipos (por ejemplo, [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner)). El SDK gestiona esta asignación de forma interna.
Un intermediario solo tendrá que implementar directamente la interfaz `Signer` al definir un esquema de autenticación externo.
### AuthResolverParameters
Cada servicio toma un conjunto específico de entradas que se pasan a su función de resolución, definida en cada paquete de servicios como `AuthResolverParameters`.
Los parámetros base del solucionador son los siguientes:
| nombre | tipo | description |
| --- | --- | --- |
| Operation | string | El nombre de la operación que se invoca. |
| Region | string | La región de AWS del cliente. Solo está presente para los servicios que utilizan SigV4[A]. |
Si implementa su propio solucionador, no debería tener que crear una instancia propia de sus parámetros en ningún caso. El SDK obtendrá estos valores por solicitud y los pasará a su implementación.
## Flujo de trabajo de resolución de esquemas de autenticación
Cuando llama a una operación de servicio de AWS a través del SDK, la siguiente secuencia de acciones se produce una vez serializada la solicitud:
1. El SDK llama a la API `AuthSchemeResolver.ResolveAuthSchemes()` del cliente y obtiene los parámetros de entrada según sea necesario, a fin de conseguir una lista de posibles valores [Option](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) para la operación.
1. El SDK recorre en iteración esa lista y selecciona el primer esquema que cumple con las siguientes condiciones:
+ En la propia lista `AuthSchemes` del cliente hay un esquema con un ID coincidente.
+ El solucionador de identidades del esquema existe (no es `nil`) en las opciones del cliente (si se comprueba mediante el método `GetIdentityResolver` del esquema, la asignación a los tipos de solucionador de identidades concretos descritos anteriormente se gestiona de forma interna). (1)
1. Suponiendo que se haya seleccionado un esquema viable, el SDK invoca su API `GetIdentityResolver()` para recuperar la identidad del intermediario. Por ejemplo, el esquema de autenticación SigV4 integrado se asignará internamente al proveedor de `Credentials` del cliente de forma interna.
1. El SDK llama a `GetIdentity()` del solucionador de identidades (por ejemplo, `aws.CredentialProvider.Retrieve()` para SigV4).
1. El SDK llama a `ResolveEndpoint()` del solucionador de puntos de conexión para encontrar el punto de conexión de la solicitud. El punto de conexión puede incluir metadatos adicionales que influyan en el proceso de firma (por ejemplo, un nombre de firma único para S3 Object Lambda).
1. El SDK llama a la API `Signer()` del esquema de autenticación para recuperar su firmante y usa su API `SignRequest()` para firmar la solicitud con la identidad del intermediario recuperada anteriormente.
(1) Si el SDK encuentra la opción anónima (ID `smithy.api#noAuth`) en la lista, se selecciona de forma automática, ya que no existe un solucionador de identidades correspondiente.
## `AuthScheme` compatibles de forma nativa
Los esquemas de autenticación siguientes son compatibles de forma nativa con AWS SDK para Go.
| Nombre | ID de esquema | Solucionador de identidades | Signer | Notas |
| --- | --- | --- | --- | --- |
| [SigV4](https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_aws-signing.html) | aws.auth\$1sigv4 | [aws.CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Credentials) | [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#Signer) | El valor predeterminado actual de la mayoría de las operaciones de servicio de AWS. |
| SigV4A | aws.auth\$1sigv4a | aws.CredentialsProvider | n/a | El uso de SigV4A es limitado en este momento, la implementación del firmante es interna. Consulte este [anuncio](https://github.com/aws/aws-sdk-go-v2/discussions/2812) para ver un nuevo módulo de inclusión aws-http-auth que expone las API de uso general para firmar solicitudes HTTP. |
| SigV4Express | com.amazonaws.s3\$1sigv4express | [s3.ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4.HTTPSigner | Se utiliza para [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). |
| HTTP Bearer | smithy.api\$1httpBearerAuth | [smithybearer.TokenProvider](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#TokenProvider) | [smithybearer.Signer](https://pkg.go.dev/github.com/aws/smithy-go/auth/bearer#Signer) | Utilizado por [codecatalyst](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst). |
| Anonymous | smithy.api\$1noAuth | n/a | n/a | Sin autenticación: no se requiere identidad y la solicitud no se firma ni se autentica. |
### Configuración de identidades
En AWS SDK para Go, los componentes de identidad de un esquema de autenticación se configuran en `Options` del cliente del SDK. El SDK recogerá y utilizará de forma automática los valores de estos componentes para el esquema que seleccione cuando se llame a una operación.
**nota**
Por motivos de compatibilidad con versiones anteriores, el SDK permite de forma implícita el uso del esquema de autenticación anónimo si no se ha configurado ningún solucionador de identidades. Esto se puede lograr de forma manual mediante el establecimiento de todos los solucionadores de identidades del elemento `Options` de un cliente en `nil` (el solucionador de identidades sigv4 también se puede establecer en `aws.AnonymousCredentials{}`).
### Configuración del firmante
En AWS SDK para Go, los componentes del firmante correspondientes a un esquema de autenticación se configuran en `Options` en el cliente del SDK. El SDK recogerá y utilizará de forma automática los valores de estos componentes para el esquema que seleccione cuando se llame a una operación. No es necesaria ninguna configuración adicional.
#### Esquema de autenticación personalizado
Para definir un esquema de autenticación personalizado y configurarlo para su uso, el intermediario debe hacer lo siguiente:
1. Definir una implementación [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)
1. Registrar el esquema en la lista `AuthSchemes` del cliente del SDK
1. Instrumentar el `AuthSchemeResolver` del cliente del SDK para que devuelva un valor `Option` de autenticación con el ID del esquema, cuando proceda.
**aviso**
Los servicios siguientes tienen un comportamiento de autenticación único o personalizado. Recomendamos que delegue en la implementación predeterminada y la encapsule en consecuencia si necesita un comportamiento de autenticación personalizado:
| Servicio | Notas |
| --- | --- |
| S3 | Uso condicional de SigV4A y SigV4Express en función de la entrada de la operación. |
| EventBridge | Uso condicional de SigV4A en función de la entrada de la operación. |
| Cognito | Algunas operaciones son únicamente anónimas. |
| SSO | Algunas operaciones son únicamente anónimas. |
| STS | Algunas operaciones son únicamente anónimas. |
# Configuración de puntos de conexión del cliente
**aviso**
La resolución de puntos de conexión es un tema avanzado del SDK. Al cambiar esta configuración, corre el riesgo de invalidar el código. La configuración predeterminada debe poder aplicarse a la mayoría de los usuarios en entornos de producción.
AWS SDK para Go Ofrece la posibilidad de configurar un punto final personalizado para usarlo en un servicio. En muchos casos, la configuración predeterminada será suficiente. La configuración de puntos de conexión personalizados permite un comportamiento adicional, como trabajar con versiones previas al lanzamiento de un servicio.
## Personalización
Existen dos “versiones” de la configuración de resolución de puntos de conexión en el SDK:
+ v2, publicada en el tercer trimestre de 2023, configurada mediante:
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1, publicada junto con el SDK, configurada mediante:
+ `EndpointResolver`
Recomendamos a los usuarios de la resolución de puntos de conexión v1 que migren a la versión 2 para obtener acceso a características del servicio más recientes relacionadas con estos.
## V2: `EndpointResolverV2` \$1 `BaseEndpoint`
En la versión 2 de la resolución, `EndpointResolverV2` es el mecanismo definitivo a través del cual se produce la resolución de puntos de conexión. El método `ResolveEndpoint` del solucionador se invoca como parte del flujo de trabajo para cada solicitud que realice en el SDK. El nombre de host del `Endpoint` devuelto por el solucionador se usa **tal cual** al realizar la solicitud (sin embargo, los serializadores de operaciones pueden seguir asociando elementos a la ruta HTTP).
En la resolución v2 se incluye una configuración adicional de nivel de cliente, `BaseEndpoint`, que se utiliza a fin de especificar un nombre de host “base” para la instancia de su servicio. El valor establecido aquí no es definitivo: se transfiere en última instancia como parámetro al `EndpointResolverV2` del cliente cuando se produce la resolución final (siga leyendo para obtener más información sobre los parámetros `EndpointResolverV2`). La implementación del solucionador tiene entonces la oportunidad de inspeccionar y, posiblemente, modificar ese valor para determinar el punto de conexión final.
Por ejemplo, si realiza una solicitud `GetObject` de S3 en un bucket determinado con un cliente en el que ha especificado un `BaseEndpoint`, el solucionador predeterminado inyectará el bucket en el nombre del host si es compatible con el host virtual (suponiendo que no haya desactivado el alojamiento virtual en la configuración del cliente).
En la práctica, lo más probable es que `BaseEndpoint` se utilice para dirigir al cliente a una instancia de desarrollo o de vista previa de un servicio.
### Parámetros `EndpointResolverV2`
Cada servicio toma un conjunto específico de entradas que se transfieren a su función de resolución, definida en cada paquete de servicios como `EndpointParameters`.
Cada servicio incluye los siguientes parámetros base, que se utilizan para facilitar la resolución de puntos de conexión general en AWS:
| name | type | description |
| --- | --- | --- |
| Region | string | La AWS región del cliente |
| Endpoint | string | Indica el valor establecido para BaseEndpoint en la configuración del cliente. |
| UseFips | bool | Indica si los puntos de conexión de FIPS están habilitados en la configuración del cliente. |
| UseDualStack | bool | Indica si los puntos de conexión de doble pila están habilitados en la configuración del cliente. |
Los servicios pueden especificar parámetros adicionales necesarios para la resolución. Por ejemplo, los `EndpointParameters` de S3 incluyen el nombre del bucket, así como varios ajustes de características específicos de S3 (por ejemplo, si el direccionamiento de host virtual está habilitado).
Si implementa su propio `EndpointResolverV2`, no debería tener que crear una instancia propia de `EndpointParameters` en ningún caso. El SDK obtendrá los valores por solicitud y los transferirá a su implementación.
### Nota acerca de Amazon S3
Amazon S3 es un servicio complejo con muchas de sus características modeladas a través de complejas personalizaciones de puntos de conexión, como el alojamiento virtual de buckets o el punto de acceso multirregional de S3, entre otras.
Por ello, recomendamos que no reemplace la implementación de `EndpointResolverV2` en su cliente de S3. Si necesita ampliar su comportamiento de resolución (por ejemplo, mediante el envío de solicitudes a una pila de desarrollo local con consideraciones adicionales sobre los puntos de conexión), recomendamos encapsular la implementación predeterminada de forma que se delegue de nuevo en esta como alternativa (como se muestra en los ejemplos que aparecen a continuación).
### Ejemplos
#### Con `BaseEndpoint`
El fragmento de código siguiente muestra cómo apuntar su cliente de S3 a la instancia local de un servicio, que en este ejemplo se aloja en el dispositivo de bucle invertido en el puerto 8080.
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### Con `EndpointResolverV2`
El fragmento de código siguiente muestra cómo inyectar un comportamiento personalizado en la resolución de puntos de conexión de S3 mediante `EndpointResolverV2`.
```
import (
"context"
"net/url"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {
// you could inject additional application context here as well
}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
if /* input params or caller context indicate we must route somewhere */ {
u, err := url.Parse("https://custom.service.endpoint/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
// delegate back to the default v2 resolver otherwise
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
// load config...
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.EndpointResolverV2 = &resolverV2{
// ...
}
})
}
```
#### Con ambos
El programa de ejemplo siguiente demuestra la interacción entre `BaseEndpoint` y `EndpointResolverV2`. **Este es un caso de uso avanzado:**
```
import (
"context"
"fmt"
"log"
"net/url"
"github.com/aws/aws-sdk-go-v2"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/s3"
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type resolverV2 struct {}
func (*resolverV2) ResolveEndpoint(ctx context.Context, params s3.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// s3.Options.BaseEndpoint is accessible here:
fmt.Printf("The endpoint provided in config is %s\n", *params.Endpoint)
// fallback to default
return s3.NewDefaultEndpointResolverV2().ResolveEndpoint(ctx, params)
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if (err != nil) {
log.Fatal(err)
}
client := s3.NewFromConfig(cfg, func (o *s3.Options) {
o.BaseEndpoint = aws.String("https://endpoint.dev/")
o.EndpointResolverV2 = &resolverV2{}
})
// ignore the output, this is just for demonstration
client.ListBuckets(context.Background(), nil)
}
```
Cuando se ejecuta, el programa anterior genera lo siguiente:
```
The endpoint provided in config is https://endpoint.dev/
```
## V1: `EndpointResolver`
**aviso**
La resolución de puntos de conexión v1 se conserva por motivos de compatibilidad con versiones anteriores y está aislada del comportamiento moderno de la resolución de puntos de conexión v2. Solo se usará si el intermediario establece el campo `EndpointResolver`.
Lo más probable es que el uso de la versión 1 le impida acceder a las características del servicio relacionadas con los puntos de conexión que se introdujeron con el lanzamiento de la resolución v2 o después de este. Consulte “Migración” para obtener instrucciones sobre cómo actualizar.
A se [EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver)puede configurar para proporcionar una lógica de resolución de puntos finales personalizada para los clientes del servicio. Puede utilizar un solucionador de puntos de conexión personalizado para reemplazar la lógica de resolución de puntos de conexión de un servicio para todos los puntos de conexión o solo para un punto de conexión regional específico. La resolución de puntos finales personalizada puede activar la lógica de resolución de puntos finales del servicio como alternativa si una resolución personalizada no desea resolver un punto final solicitado. [EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc)se puede utilizar para agrupar fácilmente las funciones a fin de adaptarlas a la `EndpointResolverWithOptions` interfaz.
A se `EndpointResolver` puede configurar fácilmente pasando el solucionador incluido en el [WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions)paquete [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), lo que permite anular los puntos finales al cargar las credenciales, así como configurar el resultado `aws.Config` con un solucionador de puntos final personalizado.
El solucionador de puntos de conexión recibe el servicio y la región en forma de cadena, lo que le permite controlar su comportamiento de forma dinámica. Cada paquete de clientes de servicio tiene una constante `ServiceID` exportada que se puede utilizar para determinar qué cliente de servicio invoca el solucionador de puntos de conexión.
Un solucionador de terminales puede utilizar el valor del error [EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError)centinela para activar la resolución alternativa según la lógica de resolución predeterminada del cliente del servicio. Esto permite reemplazar de forma selectiva uno o varios puntos de conexión sin problemas y sin tener que gestionar una lógica alternativa.
Si la implementación del solucionador de puntos de conexión devuelve un error distinto de `EndpointNotFoundError`, la resolución de puntos de conexión se detiene y la operación del servicio devuelve un error a la aplicación.
### Ejemplos
#### Con alternativa
El fragmento de código siguiente muestra cómo se puede reemplazar un único punto de conexión de servicio para DynamoDB con un comportamiento alternativo para otros puntos de conexión:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
// returning EndpointNotFoundError will allow the service to fallback to it's default resolution
return aws.Endpoint{}, &aws.EndpointNotFoundError{}
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
#### Sin alternativa
El fragmento de código siguiente muestra cómo se puede reemplazar un único punto de conexión de servicio para DynamoDB sin un comportamiento alternativo para otros puntos de conexión:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
### Puntos de conexión inmutables
**aviso**
Establecer un punto de conexión como inmutable puede impedir que algunas de las características del cliente de servicio funcionen correctamente, lo que podría provocar un comportamiento indefinido. Se debe tener cuidado a la hora de definir un punto de conexión como inmutable.
Algunos clientes de servicio, como Amazon S3, pueden modificar el punto de conexión devuelto por el solucionador para determinadas operaciones de servicio. Por ejemplo, Amazon S3 gestionará de forma automática el [direccionamiento virtual de buckets](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) al mutar el punto de conexión resuelto. Puedes evitar que el SDK modifique tus puntos de conexión personalizados configurándolos en. [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)`true` Por ejemplo:
```
customResolver := aws.EndpointResolverWithOptionsFunc(func(service, region string, options ...interface{}) (aws.Endpoint, error) {
if service == dynamodb.ServiceID && region == "us-west-2" {
return aws.Endpoint{
PartitionID: "aws",
URL: "https://test.us-west-2.amazonaws.com",
SigningRegion: "us-west-2",
HostnameImmutable: true,
}, nil
}
return aws.Endpoint{}, fmt.Errorf("unknown endpoint requested")
})
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithEndpointResolverWithOptions(customResolver))
```
## Migración
Al migrar de la versión 1 a la versión 2 de la resolución de puntos de conexión, se aplican los siguientes principios generales:
+ Devolver un [punto final](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) con el valor [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)establecido en `false` equivale aproximadamente `BaseEndpoint` a configurarlo en la URL devuelta originalmente desde la versión 1 y dejarlo `EndpointResolverV2` como predeterminado.
+ Devolver un punto final con el valor HostnameImmutable establecido en `true` equivale aproximadamente a implementar un punto final `EndpointResolverV2` que devuelva la URL devuelta originalmente desde la versión 1.
+ La excepción principal se da en el caso de las operaciones con prefijos de punto de conexión modelados. Más adelante se incluye una nota al respecto.
A continuación, se proporcionan ejemplos de estos casos.
**aviso**
Los puntos de conexión inmutables de la versión 1 y la resolución de la versión 2 no tienen un comportamiento equivalente. Por ejemplo, los reemplazos de firma para características personalizadas como S3 Object Lambda seguirían estableciéndose para los puntos de conexión inmutables devueltos mediante código de la versión 1, pero no se haría lo mismo en el caso de la versión 2.
### Nota sobre los prefijos de host
Algunas operaciones se modelan con prefijos de host que se anteponen al punto de conexión resuelto. Este comportamiento debe funcionar en conjunto con el resultado de la ResolveEndpoint V2 y, por lo tanto, el prefijo de host se seguirá aplicando a ese resultado.
Puede deshabilitar el prefijo de host del punto de conexión de forma manual mediante la aplicación de un middleware (consulte la sección de ejemplos).
### Ejemplos
#### Punto de conexión mutable
En el ejemplo de código siguiente se muestra cómo migrar un solucionador de puntos de conexión básico de la versión 1 que devuelve un punto de conexión modificable:
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/")
})
// v2
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
// the value of BaseEndpoint is passed to the default EndpointResolverV2
// implementation, which will handle routing for features such as S3 accelerate,
// MRAP, etc.
o.BaseEndpoint = aws.String("https://custom.endpoint.api/")
})
```
#### Punto de conexión inmutable
```
// v1
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolver = svc.EndpointResolverFromURL("https://custom.endpoint.api/", func (e *aws.Endpoint) {
e.HostnameImmutable = true
})
})
// v2
import (
smithyendpoints "github.com/aws/smithy-go/endpoints"
)
type staticResolver struct {}
func (*staticResolver) ResolveEndpoint(ctx context.Context, params svc.EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
// This value will be used as-is when making the request.
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{
URI: *u,
}, nil
}
client := svc.NewFromConfig(cfg, func (o *svc.Options) {
o.EndpointResolverV2 = &staticResolver{}
})
```
#### Deshabilitación del prefijo de host
```
import (
"context"
"fmt"
"net/url"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/"
smithyendpoints "github.com/aws/smithy-go/endpoints"
"github.com/aws/smithy-go/middleware"
smithyhttp "github.com/aws/smithy-go/transport/http"
)
// disableEndpointPrefix applies the flag that will prevent any
// operation-specific host prefix from being applied
type disableEndpointPrefix struct{}
func (disableEndpointPrefix) ID() string { return "disableEndpointPrefix" }
func (disableEndpointPrefix) HandleInitialize(
ctx context.Context, in middleware.InitializeInput, next middleware.InitializeHandler,
) (middleware.InitializeOutput, middleware.Metadata, error) {
ctx = smithyhttp.SetHostnameImmutable(ctx, true)
return next.HandleInitialize(ctx, in)
}
func addDisableEndpointPrefix(o *.Options) {
o.APIOptions = append(o.APIOptions, (func(stack *middleware.Stack) error {
return stack.Initialize.Add(disableEndpointPrefix{}, middleware.After)
}))
}
type staticResolver struct{}
func (staticResolver) ResolveEndpoint(ctx context.Context, params .EndpointParameters) (
smithyendpoints.Endpoint, error,
) {
u, err := url.Parse("https://custom.endpoint.api/")
if err != nil {
return smithyendpoints.Endpoint{}, err
}
return smithyendpoints.Endpoint{URI: *u}, nil
}
func main() {
cfg, err := config.LoadDefaultConfig(context.Background())
if err != nil {
panic(err)
}
svc := .NewFromConfig(cfg, func(o *.Options) {
o.EndpointResolverV2 = staticResolver{}
})
_, err = svc.(context.Background(), &.{ /* ... */ },
addDisableEndpointPrefix)
if err != nil {
panic(err)
}
}
```
# Personalización del cliente HTTP
AWS SDK para Go utiliza un cliente HTTP predeterminado con valores de configuración predeterminados. Si bien puede cambiar algunos de estos valores de configuración, el cliente y el transporte HTTP predeterminados no están suficientemente configurados para aquellos clientes que usan AWS SDK para Go en un entorno con requisitos de alto rendimiento y baja latencia. Para obtener más información, consulte la sección [Preguntas frecuentes](faq-gosdk.md), ya que las recomendaciones de configuración varían en función de las cargas de trabajo específicas. En esta sección se describe cómo configurar un cliente HTTP personalizado y cómo usarlo para crear llamadas a AWS SDK para Go.
Para ayudarle a crear un cliente HTTP personalizado, en esta sección se describe cómo usar [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient) a fin de configurar ajustes personalizados y cómo utilizar ese cliente con un cliente de servicio de AWS SDK para Go.
Vamos a definir qué queremos personalizar.
## Reemplazo durante la carga de la configuración
Se pueden proporcionar clientes HTTP personalizados al llamar a [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig) mediante la encapsulación del cliente con [WithHTTPClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) y la transferencia del valor resultante a `LoadDefaultConfig`. Por ejemplo, para pasar `customClient` como nuestro cliente:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## Tiempo de espera
El objeto `BuildableHTTPClient` se puede configurar con un límite de tiempo de espera para las solicitudes. En este tiempo de espera se incluye el tiempo necesario para conectarse, procesar cualquier redireccionamiento y leer el cuerpo de respuesta completo. Por ejemplo, para modificar el tiempo de espera del cliente:
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## Dialer
El objeto `BuildableHTTPClient` proporciona una mecánica de creación para crear clientes con opciones [Dialer](https://golang.org/pkg/net/#Dialer) modificadas. En el ejemplo siguiente se muestra cómo establecer la configuración `Dialer` de un cliente:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net"
// ...
httpClient := awshttp.NewBuildableClient().WithDialerOptions(func(d *net.Dialer) {
d.KeepAlive = -1
d.Timeout = time.Millisecond*500
})
```
### Configuración
#### Dialer.KeepAlive
Esta configuración representa el período de conservación de una conexión de red activa.
Establézcala en un valor negativo para deshabilitar estos períodos.
Establézcala en **0** para habilitar los períodos de conservación si el protocolo y el sistema operativo los admiten.
Los protocolos de red o sistemas operativos que no admiten los períodos de conservación omiten este campo. De forma predeterminada, TCP habilita el período de conservación.
Consulte [https://golang.org/pkg/net/\$1Dialer.KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive).
Establezca `KeepAlive` como **time.Duration**.
#### Dialer.Timeout
Esta configuración representa el tiempo máximo de espera de marcado para la creación de una conexión.
El valor predeterminado es de 30 segundos.
Consulte [https://golang.org/pkg/net/\$1Dialer.Timeout](https://golang.org/pkg/net/#Dialer.Timeout)
Establezca `Timeout` como **time.Duration**.
## Transporte
El objeto `BuildableHTTPClient` proporciona una mecánica de creación destinada a crear clientes con opciones [Transport](https://golang.org/pkg/net/http#Transport) modificadas.
### Configuración de un proxy
Si no puede conectarse directamente a Internet, puede utilizar variables de entorno compatibles con Go (`HTTP_PROXY`/`HTTPS_PROXY`) o crear un cliente HTTP personalizado para configurar el proxy. En el ejemplo siguiente se configura el cliente para usar `PROXY_URL` como punto de conexión del proxy:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
proxyURL, err := url.Parse("PROXY_URL")
if err != nil {
log.Fatal(err)
}
tr.Proxy = http.ProxyURL(proxyURL)
})
```
### Otras configuraciones
A continuación, se muestran otras configuraciones de `Transport` que se pueden modificar para ajustar el cliente HTTP. En la documentación del tipo [Transport](https://golang.org/pkg/net/http/#Transport) encontrará configuraciones adicionales que no se describen aquí. Estas configuraciones se pueden aplicar como se muestra en el ejemplo siguiente:
```
import awshttp "github.com/aws/aws-sdk-go-v2/aws/transport/http"
import "net/http"
// ...
httpClient := awshttp.NewBuildableClient().WithTransportOptions(func(tr *http.Transport) {
tr.ExpectContinueTimeout = 0
tr.MaxIdleConns = 10
})
```
#### Transport.ExpectContinueTimeout
Si la solicitud tiene el encabezado “Expect: 100-continue”, esta configuración representa el tiempo máximo de espera para los primeros encabezados de respuesta de un servidor después de escribir por completo los encabezados de solicitud. En este tiempo no se incluye el tiempo necesario para enviar el encabezado de solicitud. El cliente HTTP envía su carga útil después de agotarse este tiempo de espera.
El valor predeterminado es de un segundo.
Establézcala en **0** para no definir ningún tiempo de espera y enviar la carga útil de la solicitud sin esperar. Un caso de uso se produce cuando tiene problemas con proxies o servicios de terceros que toman una sesión similar al uso de Amazon S3 en la función que se muestra más adelante.
Consulte [https://golang.org/pkg/net/http/\$1Transport.ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout).
Establezca `ExpectContinue` como **time.Duration**.
#### Transport.IdleConnTimeout
Esta configuración representa el tiempo máximo para mantener activa una conexión de red inactiva entre solicitudes HTTP.
Establézcala en **0** para que no haya límite.
Consulte [https://golang.org/pkg/net/http/\$1Transport.IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout).
Establezca `IdleConnTimeout` como **time.Duration**.
#### Transport.MaxIdleConns
Esta configuración representa el número máximo de conexiones inactivas (con mantenimiento activo) en todos los hosts. Un caso de uso para aumentar este valor es cuando se dan muchas conexiones de los mismos clientes en un período breve.
**0** significa que no hay límite.
Consulte [https://golang.org/pkg/net/http/\$1Transport.MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns).
Establezca `MaxIdleConns` como **int**.
#### Transport.MaxIdleConnsPerHost
Esta configuración representa el número máximo de conexiones inactivas (con mantenimiento activo) que se conservan por host. Un caso de uso para aumentar este valor es cuando se dan muchas conexiones de los mismos clientes en un período breve.
El valor predeterminado es de dos conexiones inactivas por host.
Establézcala en **0** para usar DefaultMaxIdleConnsPerHost (2).
Consulte [https://golang.org/pkg/net/http/\$1Transport.MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost).
Establezca `MaxIdleConnsPerHost` como **int**.
#### Transport.ResponseHeaderTimeout
Esta configuración representa el tiempo máximo de espera para que un cliente lea el encabezado de respuesta.
Si el cliente no puede leer el encabezado de la respuesta dentro de este período, se producirá un error de tiempo de espera de la solicitud.
Tenga cuidado al establecer este valor cuando utilice funciones de Lambda de ejecución prolongada, ya que la operación no devolverá ningún encabezado de respuesta hasta que la función de Lambda haya finalizado o se haya agotado su tiempo de espera. Sin embargo, puede seguir usando esta opción con la operación de la API \$1\$1 InvokeAsync\$1\$1.
El valor predeterminado es no establecer un tiempo de espera, es decir, una espera indefinida.
Consulte [https://golang.org/pkg/net/http/\$1Transport.ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout).
Establezca `ResponseHeaderTimeout` como **time.Duration**.
#### Transport.TLSHandshakeTimeout
Esta configuración representa el tiempo máximo de espera para que se complete un establecimiento de comunicación TLS.
El valor predeterminado es de diez segundos.
Cero significa que no hay tiempo de espera.
Consulte [https://golang.org/pkg/net/http/\$1Transport.TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout).
Establezca `TLSHandshakeTimeout` como **time.Duration**.
# Interceptores HTTP
Puede usar interceptores para conectarse a la ejecución de las solicitudes y respuestas de la API. Los interceptores son mecanismos abiertos en los que el SDK llama al código que escribe para inyectar un comportamiento en el ciclo de vida de las solicitudes o respuestas. De esta forma puede modificar una solicitud en tránsito, depurar el procesamiento de las solicitudes, ver las excepciones y mucho más.
## Interceptores frente a middleware
AWS SDK para Go v2 proporciona tanto interceptores como middleware para personalizar el procesamiento de las solicitudes. Si bien ambos cumplen propósitos similares, están pensados para diferentes audiencias y casos de uso:
+ Los **interceptores** están diseñados para los usuarios del SDK que desean personalizar el procesamiento de solicitudes y respuestas con una API sencilla y centrada en HTTP. Proporcionan puntos de enlace específicos en el ciclo de vida de las solicitudes y trabajan directamente con las solicitudes y las respuestas HTTP.
+ El **middleware** es un sistema más avanzado e independiente del transporte que el SDK utiliza principalmente de forma interna. Si bien es potente, el middleware requiere un conocimiento más profundo de los aspectos internos del SDK e implica interfaces más complejas.
Las principales ventajas de los interceptores respecto al middleware para los casos de uso habituales son las siguientes:
+ **Centrados en HTTP**: los interceptores trabajan directamente con las solicitudes y las respuestas HTTP, lo que elimina la necesidad de comprobar el tipo de transporte que requiere el middleware.
+ **Interfaces más sencillas**: cada enlace de interceptor tiene una interfaz específica y centrada, en lugar del patrón de middleware genérico.
+ **Modelo de ejecución más claro**: los interceptores se ejecutan en puntos bien definidos del ciclo de vida de las solicitudes sin necesidad de conocer la ordenación de pila del middleware.
**nota**
Los interceptores se basan en el sistema de middleware existente, por lo que ambos pueden coexistir en la misma aplicación. El middleware sigue estando disponible para casos de uso avanzados que requieren un comportamiento independiente del transporte o una manipulación compleja de la pila.
## Enlaces de interceptor disponibles
AWS SDK para Go v2 proporciona enlaces de interceptor en varias etapas del ciclo de vida de las solicitudes. Cada enlace corresponde a una interfaz específica que puede implementar:
+ `BeforeExecution`: primer enlace al que se llama durante la ejecución de la operación
+ `BeforeSerialization`: antes de que el mensaje de entrada se serialice en una solicitud de transporte
+ `AfterSerialization`: después de que el mensaje de entrada se serialice en una solicitud de transporte
+ `BeforeRetryLoop`: antes de entrar en el bucle de reintentos
+ `BeforeAttempt`: primer enlace al que se llama dentro del bucle de reintentos
+ `BeforeSigning`: antes de firmarse la solicitud de transporte
+ `AfterSigning`: después de firmarse la solicitud de transporte
+ `BeforeTransmit`: antes de enviarse la solicitud de transporte
+ `AfterTransmit`: después de recibir la respuesta del transporte
+ `BeforeDeserialization`: antes de deserializar la respuesta del transporte
+ `AfterDeserialization`: después de deserializar la respuesta del transporte
+ `AfterAttempt`: último enlace al que se llama dentro del bucle de reintentos
+ `AfterExecution`: último enlace al que se llama durante la ejecución de la operación
Puede implementar varias interfaces en un solo interceptor para conectarse a varias etapas del ciclo de vida de las solicitudes.
## Registro de interceptores
Los interceptores se registran cuando se crea un cliente de servicio o cuando se anula la configuración de una operación específica. El registro varía en función de si desea que el interceptor se aplique a todas las operaciones de su cliente o solo a operaciones específicas.
Los interceptores se administran a través de un registro de interceptores en el que se proporcionan métodos para agregar y eliminar interceptores. En el siguiente ejemplo se muestra un interceptor sencillo que agrega un encabezado de ID de rastro AWS X-Ray a las solicitudes salientes antes del proceso de firma:
```
type recursionDetection struct{}
func (recursionDetection) BeforeSigning(ctx context.Context, in *smithyhttp.InterceptorContext) error {
if traceID := os.Getenv("_X_AMZN_TRACE_ID"); traceID != "" {
in.Request.Header.Set("X-Amzn-Trace-Id", traceID)
}
return nil
}
// use it on the client
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
El registro de interceptores se agrega a las opciones de cliente, lo que permite la configuración del interceptor por operación:
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## Configuración global del interceptor
También puede registrar interceptores a nivel global mediante la función `config.LoadDefaultConfig` con las opciones `With*` adecuadas para cada tipo de interceptor. Esto aplica el interceptor a todos los clientes de servicio de AWS creados a partir de esa configuración:
```
type myExecutionInterceptor struct{}
func (*myExecutionInterceptor) AfterExecution(ctx context.Context, in *smithyhttp.InterceptorContext) error {
// Add your custom logic here
return nil
}
cfg, err := config.LoadDefaultConfig(context.Background(),
config.WithAfterExecution(&myExecutionInterceptor{}))
if err != nil {
panic(err)
}
// every service client created from the above config
// will include this interceptor
svc := s3.NewFromConfig(cfg)
```
# Registro
AWS SDK para Go cuenta con servicios de registro que permiten a la aplicación habilitar información de depuración a fin de depurar y diagnosticar problemas o errores relacionados con las solicitudes. La interfaz [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) y [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) son los principales componentes disponibles para determinar cómo y qué deben registrar los clientes.
## Logger
Al crear un objeto [Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) mediante [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), se configura un objeto `Logger` predeterminado para enviar mensajes de registro al error estándar del proceso (stderr). Un registrador que cumpla con la interfaz [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) se puede pasar como argumento a `LoadDefaultConfig` mediante su encapsulación con [config.WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger).
Por ejemplo, para configurar nuestros clientes de forma que usen nuestro `applicationLogger`:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
Ahora, los clientes configurados mediante la instancia de `aws.Config` creada enviarán mensajes de registro a `applicationLogger`.
### Registradores dependientes del contexto
Una implementación de registrador puede implementar la interfaz [ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger) opcional. Los métodos `WithContext` de los registradores que implementen esta interfaz se invocan con el contexto actual. Esto permite que sus implementaciones de registro devuelvan un `Logger` nuevo que puede escribir metadatos de registro adicionales en función de los valores presentes en el contexto.
## ClientLogMode
De forma predeterminada, los clientes de servicio no generan mensajes de registro. Para configurar los clientes de forma que envíen mensajes de registro con fines de depuración, utilice el miembro [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) en `Config`. `ClientLogMode` se puede configurar para habilitar la mensajería de depuración para:
+ Firma de Signature Version 4 (SigV4)
+ Reintentos de solicitud
+ Solicitudes HTTP
+ Respuestas HTTP
Por ejemplo, para habilitar el registro de solicitudes y reintentos HTTP:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
Consulte [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) para ver los diferentes modos de registro de clientes disponibles.
# Rastros y métricas
AWS SDK para Go Está diseñado para registrar los intervalos de rastreo y las métricas del lado del cliente para las operaciones del SDK. De forma predeterminada, los clientes utilizan implementaciones no operativas tanto para el seguimiento como para las métricas, lo que significa que no se recopilan datos a menos que se configure un proveedor.
Los clientes de servicio tienen dos opciones de configuración para la observabilidad:
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider)— Punto de entrada para crear rastreadores y registrar los intervalos de rastreo de los clientes.
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider)— Punto de entrada para crear contadores y registrar las métricas del lado del cliente.
Si bien se inspiran en las especificaciones OpenTelemetry (OTel), APIs se definen de forma independiente en. `smithy-go` El SDK proporciona módulos adaptadores para conectar implementaciones concretas OTel del SDK a las interfaces de los proveedores del SDK.
## Rastreo
Utilice el módulo adaptador [smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) para conectar y a un cliente de servicio. OTel `trace.TracerProvider`
El siguiente ejemplo muestra cómo configurar el seguimiento para un cliente de Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/tracing/smithyoteltracing"
"go.opentelemetry.io/otel/trace"
)
// provider is an OTel trace.TracerProvider that you have configured.
var provider trace.TracerProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.TracerProvider = smithyoteltracing.Adapt(provider)
})
```
Las operaciones del SDK se estructuran con una jerarquía de intervalos que abarca los componentes de alto nivel del ciclo de vida de la operación, como la serialización de las solicitudes, la firma y el ciclo de reintentos.
## Métricas
Utilice el módulo adaptador [smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) para conectarse y a un cliente de servicio. OTel `metric.MeterProvider`
El siguiente ejemplo muestra cómo configurar las métricas para un cliente de Amazon S3:
```
import (
"github.com/aws/aws-sdk-go-v2/service/s3"
"github.com/aws/smithy-go/metrics/smithyotelmetrics"
"go.opentelemetry.io/otel/metric"
)
// provider is an OTel metric.MeterProvider that you have configured.
var provider metric.MeterProvider
svc := s3.NewFromConfig(cfg, func(o *s3.Options) {
o.MeterProvider = smithyotelmetrics.Adapt(provider)
})
```
### Métricas admitidas
Los clientes del SDK recopilan las siguientes métricas:
| Nombre de métrica | Unidad | Tipo | Description (Descripción) |
| --- | --- | --- | --- |
| client.call.duration | s | Histograma | Duración total de la llamada, incluidos los reintentos y el tiempo de envío o recepción de la solicitud y el cuerpo de la respuesta. |
| client.call.attempts | \$1attempt\$1 | MonotonicCounter | El número de intentos de una operación individual. |
| client.call.errors | \$1error\$1 | MonotonicCounter | El número de errores de una operación. |
| client.call.attempt\$1duration | s | Histograma | El tiempo necesario para conectarse al servicio, enviar la solicitud y recuperar el código de estado HTTP y los encabezados (incluido el tiempo de espera para ser enviado). |
| client.call.resolve\$1endpoint\$1duration | s | Histograma | El tiempo necesario para resolver un punto final (resolución de puntos finales, no DNS) para la solicitud. |
| client.call.deserialization\$1duration | s | Histograma | El momento de deserializar el cuerpo de un mensaje. |
| client.call.auth.signing\$1duration | s | Histograma | Hora de firmar una solicitud. |
| client.call.auth.resolve\$1identity\$1duration | s | Histograma | El momento necesario para adquirir una identidad (AWS credenciales, identificador de portador, etc.) de un proveedor de identidad. |
Cuando proceda, se incluyen los siguientes atributos (dimensiones) con cada métrica:
+ `rpc.service`— El nombre del servicio.
+ `rpc.method`— El nombre de la operación.
+ `exception.type`— El tipo de error (incluido con`client.call.errors`).
+ `auth.scheme_id`— El esquema de autenticación (incluido en las métricas relacionadas con la autenticación).
### Métricas de clientes HTTP
El cliente HTTP del SDK recopila las siguientes métricas adicionales relacionadas con el ciclo de vida de la conexión HTTP subyacente:
| Nombre de métrica | Unidad | Tipo | Description (Descripción) |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | s | Histograma | El tiempo que tarda una solicitud en adquirir una conexión. |
| client.http.connections.dns\$1lookup\$1duration | s | Histograma | El tiempo que se tarda en realizar una búsqueda de DNS. |
| client.http.connections.tls\$1handshake\$1duration | s | Histograma | El tiempo que se tarda en realizar un apretón de manos de TLS. |
| client.http.connections.usage | \$1conexión\$1 | UpDownCounter | El estado actual de las conexiones del grupo. Utiliza una state dimensión con un valor de idle oacquired. |
| client.http.do\$1request\$1duration | s | Histograma | El tiempo total dedicado a realizar la solicitud HTTP. |
| client.http.time\$1to\$1first\$1byte | s | Histograma | El tiempo transcurrido desde el envío de la solicitud hasta la recepción del primer byte de respuesta. |
# Reintentos y tiempos de espera
AWS SDK para Go Le permite configurar el comportamiento de reintento de las solicitudes a los servicios HTTP. De forma predeterminada, los clientes de servicio utilizan [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) como elemento de reintento predeterminado. Si la configuración o el comportamiento predeterminado no cumple con los requisitos de la aplicación, puede ajustar la configuración del elemento de reintento o proporcionar su propia implementación del mismo.
AWS SDK para Go Proporciona una interfaz [AWS.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) que define el conjunto de métodos que debe implementar una implementación de reintento. [El SDK proporciona dos implementaciones para los reintentos: retry.standard y aws.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) [ NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer).
## Elemento de reintento estándar
El elemento de reintento [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) es la implementación de `aws.Retryer` predeterminada que utilizan los clientes del SDK. El elemento de reintento estándar tiene ciertas limitaciones, con un número máximo de intentos configurable y la posibilidad de ajustar la política de retroceso de las solicitudes.
En la tabla siguiente se definen los valores predeterminados de este elemento de reintento:
| Propiedad | Predeterminado |
| --- | --- |
| Número máximo de intentos | 3 |
| Retardo de retroceso máximo | 20 segundos |
Cuando se produzca un error reintentable al invocar la solicitud, el elemento de reintento estándar utilizará la configuración proporcionada a fin de retrasar la solicitud y reintentarla más adelante. Los reintentos se agregan a la latencia general de la solicitud y debe configurar el elemento de reintento si la configuración predeterminada no cumple los requisitos de la aplicación.
Consulte la documentación del paquete [retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry) para obtener más información sobre los errores que la implementación del elemento de reintento estándar considera reintentables.
## NopRetryer
Las [leyes. NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer)es una `aws.Retryer` implementación que se proporciona si desea deshabilitar todos los reintentos. Al invocar una operación de cliente de servicio, este elemento de reintento solo permite que la solicitud se intente una vez y cualquier error resultante se devolverá a la aplicación que realiza la llamada.
## Personalización del comportamiento
El SDK proporciona un conjunto de utilidades auxiliares que encapsulan una implementación de `aws.Retryer` y devuelve el elemento de reintento que se proporciona, encapsulado con el comportamiento de reintento deseado. Puede reemplazar el elemento de reintento predeterminado para todos los clientes, por cliente o por operación, en función de los requisitos de las aplicaciones. Para ver más ejemplos en los que se muestra cómo realizar esta acción, consulte los ejemplos de la documentación del paquete [retry](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
**aviso**
Si especifica una implementación de `aws.Retryer` global mediante `config.WithRetryer`, debe asegurarse de que se devuelva una nueva instancia de `aws.Retryer` en cada invocación. De esta forma, se garantiza que no se cree un bucket de tokens de reintentos global en todos los clientes de servicio.
### Limitación del número máximo de intentos
Usas [retry. AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts)para ajustar una `aws.Retryer` implementación a fin de establecer el número máximo de intentos en el valor deseado.
**aviso**
Si se usa `retry.AddWithMaxAttempts` con un valor de cero, el SDK podrá volver a intentar todos los errores reintentables hasta que la solicitud se realice correctamente o se devuelva un error que no sea reintentable. **Permitir que el SDK realice reintentos de forma infinita puede provocar cargas de trabajo fuera de control y ciclos de facturación desorbitados.**
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will be infinite (will retry indefinitely)
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxAttempts(retry.NewStandard(), 0)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
Tenga en cuenta que crear una instancia de un retryer utilizando opciones funcionales para configurarlo MaxAttempts directamente tendrá un comportamiento ligeramente diferente. En concreto, si se establece un valor menor que cero o cero, el elemento de reintento utilizará el máximo predeterminado de tres intentos, en lugar de hacer reintentos de forma infinita:
```
import "context"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
import "github.com/aws/aws-sdk-go-v2/config"
import "github.com/aws/aws-sdk-go-v2/service/s3"
// ...
// MaxAttempts will default to 3
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.MaxAttempts = 0
})
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Limitación del retardo de retroceso máximo
[Usas retry. AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay)para completar una `aws.Retryer` implementación y limitar el tiempo máximo de espera que se puede producir entre el reintento de una solicitud fallida.
Por ejemplo, puede usar el código siguiente para encapsular el elemento de reintento del cliente estándar con un retraso máximo deseado de cinco segundos:
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
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(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithMaxBackoffDelay(retry.NewStandard(), time.Second*5)
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Reintento de códigos de error adicionales de la API
Se usa [reintentar. AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes)para empaquetar una `aws.Retryer` implementación e incluir códigos de error de API adicionales que deberían considerarse reintentables.
Por ejemplo, puede usar el código siguiente para encapsular el elemento de reintento del cliente estándar e incluir la excepción `NoSuchBucketException` de Amazon S3 como reintentable.
```
import "context"
import "time"
import "github.com/aws/aws-sdk-go-v2/aws/retry"
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(), config.WithRetryer(func() aws.Retryer {
return retry.AddWithErrorCodes(retry.NewStandard(), (*types.NoSuchBucketException)(nil).ErrorCode())
}))
if err != nil {
return err
}
client := s3.NewFromConfig(cfg)
```
### Limitación de la tasa del cliente
AWS SDK para Go Introduce un nuevo mecanismo de limitación de la velocidad por parte del cliente en la política de reintentos estándar para adaptarlo al comportamiento de la tecnología moderna. SDKs [Este comportamiento lo controla el [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter)campo de las opciones de un retryer.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions)
A RateLimiter funciona como un depósito de fichas con una capacidad determinada, en el que los intentos fallidos de operación consumen fichas. Si se vuelve a intentar consumir más fichas de las disponibles, se produce un error en la operación con un [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError).
La implementación predeterminada está parametrizada de la siguiente forma (cómo modificar cada configuración):
+ una capacidad de 500 (establece el valor de RateLimiter al StandardOptions usarla [NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit))
+ un reintento provocado por un tiempo de espera cuesta 10 fichas (un número fijo RetryTimeoutCost ) StandardOptions
+ un reintento provocado por otros errores cuesta 5 fichas (activado) RetryCost StandardOptions
+ una operación que se realiza correctamente en el primer intento añade 1 ficha (activada NoRetryIncrement ) StandardOptions
+ Las operaciones que se realizan correctamente en el segundo intento o en un intento posterior no agregan tokens
Si considera que el comportamiento predeterminado no se ajusta a las necesidades de su aplicación, puede deshabilitarlo con [ratelimit.None](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables).
#### Ejemplo: Limitador de tasa modificado
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
// Makes the rate limiter more permissive in general. These values are
// arbitrary for demonstration and may not suit your specific
// application's needs.
o.RateLimiter = ratelimit.NewTokenRateLimit(1000)
o.RetryCost = 1
o.RetryTimeoutCost = 3
o.NoRetryIncrement = 10
})
}))
```
#### Ejemplo: Sin límite de tasa con ratelimit.None
```
import (
"context"
"github.com/aws/aws-sdk-go-v2/aws"
"github.com/aws/aws-sdk-go-v2/aws/ratelimit"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
)
// ...
cfg, err := config.LoadDefaultConfig(context.Background(), config.WithRetryer(func() aws.Retryer {
return retry.NewStandard(func(o *retry.StandardOptions) {
o.RateLimiter = ratelimit.None
})
}))
```
## Tiempos de espera
El paquete [context](https://golang.org/pkg/context/) se utiliza para establecer tiempos de espera o plazos al invocar una operación de cliente de servicio. Usa el [contexto. WithDeadline](https://golang.org/pkg/context/#WithDeadline)para resumir el contexto de su solicitud y establecer una fecha límite en un momento específico para completar la operación invocada. Para establecer un tiempo de espera después de un determinado [contexto de `time.Duration` uso. WithTimeout](https://golang.org/pkg/context/#WithTimeout). El SDK pasa el elemento `context.Context` proporcionado al cliente de transporte HTTP al invocar una API de servicio. Si el contexto que se pasa al SDK se cancela, o se produce su cancelación durante la invocación de la operación, el SDK no reintentará realizar la solicitud y volverá a la aplicación que realiza la llamada. La cancelación del contexto debe gestionarse de forma adecuada en la aplicación en los casos en los que se haya cancelado el contexto proporcionado al SDK.
### Establecimiento de un tiempo de espera
En el ejemplo siguiente se muestra cómo establecer un tiempo de espera para una operación de cliente de servicio.
```
import "context"
import "time"
// ...
ctx := context.TODO() // or appropriate context.Context value for your application
client := s3.NewFromConfig(cfg)
// create a new context from the previous ctx with a timeout, e.g. 5 seconds
ctx, cancel := context.WithTimeout(ctx, 5*time.Second)
defer cancel()
resp, err := client.GetObject(ctx, &s3.GetObjectInput{
// input parameters
})
if err != nil {
// handle error
}
```