As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.
# Configurar o SDK
Na AWS SDK para Go V2, você pode definir configurações comuns para clientes de serviço, como registrador, nível de registro e configuração de repetição. A maioria das configurações é opcional. No entanto, para cada cliente de serviço, você deve especificar uma AWS região e suas credenciais. O SDK usa esses valores para enviar solicitações à região correta e assinar solicitações com as credenciais corretas. Você pode especificar esses valores de forma programática no código ou por meio do ambiente de execução.
## Carregando AWS arquivos de configuração compartilhados
Há várias maneiras de inicializar um cliente de API de serviço, mas o padrão mais comum recomendado aos usuários é o indicado a seguir.
Para configurar o SDK para usar os arquivos de configuração AWS compartilhados, use o código a seguir:
```
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á um [AWS.config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) usando as fontes de configuração AWS compartilhadas. Isso inclui configurar um provedor de credenciais, configurar a AWS região e carregar a configuração específica do serviço. Os clientes de serviço podem ser construídos usando o `aws.Config` carregado, fornecendo um padrão consistente para a construção de clientes.
Para obter mais informações sobre arquivos de configuração AWS compartilhados, consulte [Configuração](https://docs.aws.amazon.com/sdkref/latest/guide/creds-config-files.html) no Guia de Referência de Ferramentas AWS SDKs e Ferramentas.
## Especificando a região AWS
Ao especificar a região, você determina para onde enviar solicitações, como `us-west-2` ou `us-east-2`. Consulte uma lista de regiões para cada serviço em [Cotas e endpoints de serviço](https://docs.aws.amazon.com/general/latest/gr/aws-service-information.html) na Referência geral da Amazon Web Services.
O SDK não tem uma região padrão. Como especificar uma região:
+ Defina a variável de ambiente `AWS_REGION` para a região padrão.
+ Defina a região explicitamente usando a [configuração. WithRegion](https://github.com/aws/aws-sdk-go-v2/blob/config/v0.2.2/config/provider.go#L127)como argumento para `config.LoadDefaultConfig` carregar a configuração.
REVISÃO: se você definir uma região usando todas essas técnicas, o SDK usará a região que você especificou explicitamente.
### Configurar a região com variável de ambiente
#### Linux, macOS ou Unix
```
export AWS_REGION=us-west-2
```
#### Windows
```
set AWS_REGION=us-west-2
```
### Especificar a região de forma programática
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithRegion("us-west-2"))
```
## Especificação de credenciais
As credenciais AWS SDK para Go necessárias (uma chave de acesso e uma chave de acesso secreta) para assinar solicitações. AWSÉ possível especificar as credenciais em vários locais, dependendo do caso de uso específico. Consulte mais informações sobre como obter as credenciais em [Conceitos básicos do AWS SDK para Go](getting-started.md).
Quando você inicializa uma `aws.Config` instância usando`config.LoadDefaultConfig`, o SDK usa sua cadeia de credenciais padrão para encontrar credenciais. AWS Essa cadeia de credenciais padrão procura credenciais na seguinte ordem:
1. Variáveis de ambiente.
1. Credenciais estáticas (`AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, `AWS_SESSION_TOKEN`)
1. Token de identidade da web (`AWS_WEB_IDENTITY_TOKEN_FILE`)
1. Arquivos de configuração compartilhados.
1. O SDK usa como padrão o arquivo `credentials` na pasta `.aws` que é colocada na pasta inicial do computador.
1. O SDK usa como padrão o arquivo `config` na pasta `.aws` que é colocada na pasta inicial do computador.
1. Se seu aplicativo usa uma definição de tarefa ou operação de RunTask API do Amazon ECS, a função do IAM para tarefas.
1. Se a aplicação está sendo executada em uma instância do Amazon EC2, use o perfil do IAM para o Amazon EC2.
O SDK detecta e usa os provedores integrados automaticamente, sem exigir configurações manuais. Por exemplo, se você usa perfis do IAM para instâncias do Amazon EC2, as aplicações usam automaticamente as credenciais da instância. Você não precisa configurar credenciais manualmente na aplicação.
Como prática recomendada, AWS recomenda que você especifique as credenciais na seguinte ordem:
1. Use funções do IAM para tarefas se seu aplicativo usar uma definição de tarefa ou operação de RunTask API do Amazon ECS.
1. Use perfis do IAM para o Amazon EC2 (se a aplicação está sendo executada em uma instância do Amazon EC2).
As funções do IAM fornecem aos aplicativos na instância credenciais de segurança temporárias para fazer AWS chamadas. Os perfis do IAM permitem distribuir e gerenciar facilmente credenciais em várias instâncias do Amazon EC2.
1. Use arquivos configurações ou credenciais compartilhados.
As credenciais e os arquivos de configuração são compartilhados entre outros e. AWS SDKs AWS CLI Como prática recomendada de segurança, recomendamos o uso do arquivo de credenciais para definir valores confidenciais, como chave de acesso IDs e chaves secretas. Aqui estão os [requisitos de formatação](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) para cada um desses arquivos.
1. Use variáveis de ambiente.
Configurar variáveis de ambiente é útil se você estiver realizando um trabalho de desenvolvimento em uma máquina que não seja uma instância do Amazon EC2.
### Funções do IAM para tarefas
Se a aplicação usa uma definição de tarefa do Amazon ECS ou a operação `RunTask`, use [Perfis do IAM para tarefas](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) para especificar um perfil do IAM que pode ser usado pelos contêineres em uma tarefa.
### Perfis do IAM para instâncias do Amazon EC2
Se estiver executando a aplicação em uma instância do Amazon EC2, use o [perfil do IAM](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) da instância para obter credenciais de segurança temporárias a fim de fazer chamadas para a AWS.
Se você configurou a instância para usar perfis do IAM, o SDK usa essas credenciais para a aplicação automaticamente. Você não precisa especificar essas credenciais manualmente.
### Credenciais e configurações compartilhadas
As credenciais compartilhadas e os arquivos de configuração podem ser usados para compartilhar configurações comuns entre outras AWS SDKs ferramentas. Se usar credenciais diferentes para diferentes ferramentas ou aplicativos, você poderá usar *perfis* para configurar várias chaves de acesso no mesmo arquivo de configuração.
Você pode fornecer vários locais de arquivos de configurações ou credenciais usando `config.LoadOptions`, por padrão, o SDK carrega arquivos armazenados nos locais padrão mencionados em [Especificação de credenciais](#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"},
)
)
```
Ao trabalhar com arquivos de configurações e credenciais compartilhados, se perfis duplicados forem especificados, eles serão combinados para resolver um perfil. Em caso de conflito de combinação,
1. Se perfis duplicados forem especificados em um mesmo credentials/config arquivo, as propriedades do perfil especificadas no último perfil terão precedência.
1. Se perfis duplicados forem especificados em vários arquivos de credenciais ou em vários arquivos de configurações, as propriedades do perfil serão resolvidas de acordo com a ordem de entrada do arquivo em `config.LoadOptions`. As propriedades do perfil nos últimos arquivos têm precedência.
1. Se existir um perfil no arquivo de credenciais e no arquivo de configurações, as propriedades do arquivo de credenciais terão precedência.
Se necessário, você pode habilitar `LogConfigurationWarnings` em `config.LoadOptions` e registrar em log as etapas de resolução do perfil.
#### Criar o arquivo de credenciais
Se você não tem um arquivo de credenciais compartilhado (`.aws/credentials`), use qualquer editor de texto para criar um em seu diretório inicial. Adicione o conteúdo a seguir ao seu arquivo de credenciais, substituindo-o por ** suas credenciais. **
```
[default]
aws_access_key_id =
aws_secret_access_key =
```
O cabeçalho `[default]` define as credenciais do perfil padrão, que o SDK usará a menos que você o configure para usar outro perfil.
Você também pode usar credenciais de segurança temporárias adicionando os tokens da sessão ao perfil, conforme mostrado no seguinte exemplo:
```
[temp]
aws_access_key_id =
aws_secret_access_key =
aws_session_token =
```
O nome da seção de um perfil não padrão em um arquivo de credenciais não deve começar com a palavra `profile`. Você pode ler mais em [AWS SDKs e no Guia de referência de ferramentas](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html#file-format-creds).
#### Criar o arquivo de configurações
Se você não tem um arquivo de credenciais compartilhado (`.aws/config`), use qualquer editor de texto para criar um em seu diretório inicial. Adicione o conteúdo a seguir ao seu arquivo de configuração, ** substituindo-o pela região desejada.
```
[default]
region =
```
O cabeçalho `[default]` define as configurações do perfil padrão, que o SDK usará a menos que você o configure para usar outro perfil.
Você pode usar perfis nomeados, conforme mostrado no seguinte exemplo:
```
[profile named-profile]
region =
```
O nome da seção de um perfil não padrão em um arquivo de configurações deve sempre começar com a palavra `profile`, seguida pelo nome do perfil pretendido. Você pode ler mais no [Guia de referência de ferramentas AWS SDKs e ferramentas](https://docs.aws.amazon.com/credref/latest/refdocs/file-format.html#file-format-config).
#### Especificar perfis
Você pode incluir várias chaves de acesso no mesmo arquivo de configuração associando cada conjunto de chaves de acesso a um perfil. Por exemplo, no arquivo de credenciais, você pode declarar vários perfis, conforme indicado a seguir.
```
[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 =
```
Por padrão, o SDK verifica a variável de ambiente `AWS_PROFILE` para determinar qual perfil usar. Se nenhuma variável `AWS_PROFILE` for definida, o SDK usará o perfil `default`.
Às vezes, você pode querer usar um perfil diferente com a aplicação. Por exemplo, você quer usar as credenciais `test-account` com a aplicação `myapp`. Você pode usar esse perfil utilizando o seguinte comando:
```
$ AWS_PROFILE=test-account myapp
```
Você também pode instruir o SDK a selecionar um perfil chamando `os.Setenv("AWS_PROFILE", "test-account")` antes de chamar `config.LoadDefaultConfig` ou passando um perfil explícito como um argumento, conforme mostrado no seguinte exemplo:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithSharedConfigProfile("test-account"))
```
**nota**
Se você especificar credenciais em variáveis de ambiente, o SDK sempre usará essas credenciais, independentemente do perfil especificado.
### Variáveis de ambiente
Por padrão, o SDK detecta as AWS credenciais definidas em seu ambiente e as usa para assinar solicitações. AWS Dessa maneira, você não precisa gerenciar credenciais nas aplicações.
O SDK procura credenciais nas seguintes variáveis de ambiente:
+ `AWS_ACCESS_KEY_ID`
+ `AWS_SECRET_ACCESS_KEY`
+ `AWS_SESSION_TOKEN` (opcional)
Os exemplos a seguir mostram como configurar as variáveis de ambiente.
#### Linux, OSX ou 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
```
### Especificar credenciais de forma programática
`config.LoadDefaultConfig`permite que você forneça uma lei explícita[. CredentialProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)ao carregar as fontes de configuração compartilhadas. [Para passar um provedor de credencial explícito ao carregar a configuração compartilhada, use config. WithCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithCredentialsProvider). Por exemplo, se `customProvider` fizer referência a uma instância de implementação `aws.CredentialProvider`, ela poderá ser passada durante o carregamento da configuração da seguinte forma:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(customProvider))
```
Se você fornecer credenciais explicitamente, como neste exemplo, o SDK usará somente essas credenciais.
**nota**
Todos os provedores de credenciais passados ou devolvidos `LoadDefaultConfig` são [CredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsCache)automaticamente agrupados em um. Isso permite o armazenamento em cache e a rotação de credenciais de forma segura para simultaneidade. Se você configurar explicitamente um provedor `aws.Config` diretamente, também deverá agrupar explicitamente o provedor com esse tipo usando. [NewCredentialsCache](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NewCredentialsCache)
#### Credenciais estáticas
[Você pode codificar as credenciais em seu aplicativo usando as credenciais. NewStaticCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials#NewStaticCredentialsProvider)provedor de credenciais para definir explicitamente as chaves de acesso a serem usadas. Por exemplo:
```
cfg, err := config.LoadDefaultConfig(context.TODO(),
config.WithCredentialsProvider(credentials.NewStaticCredentialsProvider("AKID", "SECRET_KEY", "TOKEN")),
)
```
**Atenção**
Não incorpore credenciais em uma aplicação. Use esse método apenas para fins de teste.
#### Credenciais de autenticação única
O SDK fornece um provedor de credenciais para recuperar credenciais temporárias AWS usando. Centro de Identidade do AWS IAM Usando o AWS CLI, você se autentica com o portal de AWS acesso e autoriza o acesso às credenciais temporárias AWS . Em seguida, você configura seu aplicativo para carregar o perfil de login único (SSO), e o SDK usa suas credenciais de SSO para recuperar AWS credenciais temporárias que serão renovadas automaticamente se expirarem. Se suas credenciais de SSO expirarem, você deverá renová-las explicitamente fazendo login na sua conta do IAM Identity Center novamente usando o. AWS CLI
Por exemplo, você pode criar um perfil`dev-profile`, autenticar e autorizar esse perfil usando o AWS CLI e configurar seu aplicativo conforme mostrado abaixo.
1. Primeiro, crie `profile` e `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. Faça login usando o AWS CLI para autenticar e autorizar o perfil SSO.
```
$ 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. Depois, configure a aplicação para usar o 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 obter mais informações sobre como configurar perfis de SSO e autenticar usando o, AWS CLI consulte [Configurando o AWS CLI para uso Centro de Identidade do AWS IAM no Guia do](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sso.html) usuário. AWS CLI Consulte mais informações sobre a construção programática do provedor de credenciais de SSO na documentação de referência da API [ssocreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ssocreds).
#### Credenciais de login
Você pode usar suas credenciais de login existentes do AWS Management Console para acesso programático aos serviços. AWS Depois de um fluxo de autenticação baseado em navegador, AWS gera credenciais temporárias que funcionam em ferramentas de desenvolvimento locais, como a CLI e. AWS Ferramentas da AWS para PowerShell AWS SDKs Esse recurso simplifica o processo de configuração e gerenciamento de credenciais de AWS CLI, especialmente se você preferir a autenticação interativa em vez de gerenciar chaves de acesso de longo prazo.
1. Inicie o fluxo de login usando a AWS CLI e siga as instruções do navegador. Neste exemplo, salvamos a sessão de login em um novo perfil**dev-profile**, mas isso é opcional.
```
$ aws --profile dev-profile login
```
1. (Opcional) Inspecione seu arquivo de configuração AWS compartilhado para verificar se a sessão foi estabelecida.
```
[profile dev-profile]
login_session = arn:aws:sts::account id>:role
```
1. Em seguida, configure seu aplicativo para usar o perfil de login.
```
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 obter mais informações sobre como configurar perfis de login e autenticar usando a AWS CLI, consulte [Login para desenvolvimento AWS local](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-sign-in.html) usando credenciais de console.
#### Outros provedores de credenciais
O SDK fornece outros métodos para recuperar credenciais no módulo de [credenciais](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials). Por exemplo, você pode recuperar credenciais de segurança temporárias de AWS Security Token Service ou credenciais do armazenamento criptografado.
**Provedores de credenciais disponíveis**:
+ [ec2rolecreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/ec2rolecreds): recupere credenciais de perfis de instâncias do Amazon EC2 por meio do IMDS do Amazon EC2.
+ [endpointcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/endpointcreds): recupere credenciais de um endpoint HTTP arbitrário.
+ [processcreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/processcreds): recupere credenciais de um processo externo que será invocado pelo shell do ambiente de host.
+ [stscreds](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/credentials/stscreds) — Recupere credenciais de AWS STS
# Configurar autenticação
O AWS SDK para Go permite configurar o serviço de comportamento de autenticação. Na maioria dos casos, a configuração padrão será suficiente, mas a configuração da autenticação personalizada permite definir um comportamento adicional, como trabalhar com recursos de serviço de pré-lançamento.
## Definições
Esta seção fornece uma descrição geral dos componentes da autenticação no AWS SDK para Go.
### AuthScheme
Um [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme) é a interface que define o fluxo de trabalho por meio do qual o SDK recupera a identidade do chamador e a anexa a uma solicitação de operação.
Um esquema de autenticação usa os seguintes componentes, descritos em detalhes abaixo:
+ Um ID exclusivo que identifica o esquema
+ Um resolvedor de identidade, que retorna uma identidade de chamador usada no processo de assinatura (por exemplo, suas credenciais da AWS)
+ Um signatário, que executa a injeção real da identidade do chamador na solicitação de transporte da operação (por exemplo, o cabeçalho HTTP `Authorization`)
Cada opção de cliente de serviço inclui um campo `AuthSchemes` que, por padrão, é preenchido com a lista de esquemas de autenticação compatíveis com esse serviço.
### AuthSchemeResolver
Cada opção de cliente de serviço inclui um campo `AuthSchemeResolver`. Essa interface, definida por serviço, é a API chamada pelo SDK para determinar as possíveis opções de autenticação para cada operação.
**Importante**
O resolvedor do esquema de autenticação NÃO determina qual esquema de autenticação deve ser usado. Ele retorna uma lista de esquemas que *podem* ser usados (“opções”). O esquema final é selecionado por meio de um algoritmo fixo descrito [aqui](#auth-scheme-resolution-workflow).
### Opção
Retornada de uma chamada para `ResolverAuthSchemes`, uma [Opção](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) representa uma possível opção de autenticação.
Uma opção consiste em três conjuntos de informações:
+ Um ID representando o possível esquema
+ Um conjunto opaco de propriedades a serem fornecidas ao resolvedor de identidade do esquema
+ Um conjunto opaco de propriedades a serem fornecidas ao signatário do esquema
#### Uma nota sobre propriedades
Em 99% dos casos de uso, os chamadores não precisam se preocupar com as propriedades opacas de assinatura e resolução de identidade. O SDK extrai as propriedades necessárias para cada esquema e as passa para as interfaces fortemente tipadas expostas no SDK. Por exemplo, o resolvedor de autenticação padrão para serviços codifica a opção do SigV4 para ter propriedades de signatário de nome e região de assinatura, cujos valores são passados à implementação [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) configurada do cliente quando o SigV4 é selecionado.
### Identidade
Uma [identidade](https://pkg.go.dev/github.com/aws/smithy-go/auth#Identity) é uma representação abstrata de quem é o chamador do SDK.
O tipo mais comum de identidade usado no SDK é um conjunto de `aws.Credentials`. Na maioria dos casos de uso, o chamador não precisa se preocupar com `Identity` como uma abstração e pode trabalhar diretamente com os tipos concretos.
**nota**
Para preservar a compatibilidade com versões anteriores e evitar confusão na API, o tipo de identidade `aws.Credentials` específico do AWS SDK não satisfaz diretamente a interface `Identity`. Esse mapeamento é feito internamente.
### IdentityResolver
[IdentityResolver](https://pkg.go.dev/github.com/aws/smithy-go/auth#IdentityResolver) é a interface por meio da qual uma `Identity` é recuperada.
Existem versões concretas de `IdentityResolver` no SDK em formato fortemente tipado (por exemplo, [aws.CredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#CredentialsProvider)). O SDK gerencia esse mapeamento internamente.
O chamador só precisa implementar diretamente a interface `IdentityResolver` ao definir um esquema de autenticação externo.
### Signer
[Signatário](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#Signer) é a interface por meio da qual uma solicitação é complementada com o chamador recuperado `Identity`.
Existem versões concretas de `Signer` no SDK em formato fortemente tipado (por exemplo, [v4.HTTPSigner](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/signer/v4#HTTPSigner)). O SDK gerencia esse mapeamento internamente.
O chamador só precisa implementar diretamente a interface `Signer` ao definir um esquema de autenticação externo.
### AuthResolverParameters
Cada serviço usa um conjunto específico de entradas que são passadas para sua função de resolução, definida em cada pacote de serviços como `AuthResolverParameters`.
Os parâmetros básicos do resolvedor são os seguintes:
| nome | type | description |
| --- | --- | --- |
| Operation | string | O nome da operação que está sendo invocada. |
| Region | string | A região da AWS do cliente. Presente somente para serviços que usam o SigV4[A]. |
Se você estiver implementando seu próprio resolvedor, nunca será necessário construir sua própria instância com seus parâmetros. O SDK fornece esses valores por solicitação e os transmite para sua implementação.
## Fluxo de trabalho de resolução do esquema de autenticação
Quando você chama uma operação de serviço da AWS por meio do SDK, a seguinte sequência de ações ocorre após a serialização da solicitação:
1. O SDK chama a API `AuthSchemeResolver.ResolveAuthSchemes()` do cliente, fornecendo os parâmetros de entrada conforme necessário, para obter uma lista de [Opções](https://pkg.go.dev/github.com/aws/smithy-go/auth#Option) possíveis para a operação.
1. O SDK repete essa lista e seleciona o primeiro esquema que satisfaz as condições a seguir.
+ Um esquema com ID correspondente está presente na própria lista `AuthSchemes` do cliente
+ O resolvedor de identidade do esquema existe (não é `nil`) nas Opções do cliente (verificado por meio do método `GetIdentityResolver` do esquema, o mapeamento para os tipos concretos de resolvedor de identidade descritos acima é gerenciado internamente) (1)
1. Supondo que um esquema viável tenha sido selecionado, o SDK invoca sua API `GetIdentityResolver()` para recuperar a identidade do chamador. Por exemplo, o esquema de autenticação do SigV4 integrado será mapeado internamente para o provedor de `Credentials` do cliente.
1. O SDK chama o resolvedor de identidade `GetIdentity()` (por exemplo, `aws.CredentialProvider.Retrieve()` para o SigV4).
1. O SDK chama o `ResolveEndpoint()` do resolvedor do endpoint para encontrar o endpoint da solicitação. O endpoint pode incluir metadados adicionais que influenciam o processo de assinatura (por exemplo, nome de assinatura exclusivo do S3 Object Lambda).
1. O SDK chama a API `Signer()` do esquema de autenticação para recuperar o signatário e usa a API `SignRequest()` para assinar a solicitação com a identidade do chamador recuperada anteriormente.
(1) Se o SDK encontrar a opção anônima (ID `smithy.api#noAuth`) na lista, ela será selecionada automaticamente, pois não há um resolvedor de identidade correspondente.
## `AuthScheme`s com suporte nativo
Os seguintes esquemas de autenticação têm suporte nativo do AWS SDK para Go.
| Name | ID do esquema | Resolvedor de identidade | Signer | Observações |
| --- | --- | --- | --- | --- |
| [SigV4 da4](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) | O padrão atual para a maioria das operações de serviço da AWS. |
| SigV4A | aws.auth\$1sigv4a | aws.CredentialsProvider | n/a | O uso do SigV4A é limitado no momento, a implementação do signatário é interna. Veja este [anúncio](https://github.com/aws/aws-sdk-go-v2/discussions/2812) de um novo módulo opcional aws-http-auth que expõe APIs de uso geral para assinar solicitações HTTP. |
| SigV4Express | com.amazonaws.s3\$1sigv4express | [s3.ExpressCredentialsProvider](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/s3#ExpressCredentialsProvider) | v4.HTTPSigner | Usado para [Express One Zone](https://aws.amazon.com/s3/storage-classes/express-one-zone/). |
| Portador de HTTP | 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) | Usado pelo [CodeCatalyst](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/service/codecatalyst). |
| Anônimo | smithy.api\$1noAuth | n/a | n/a | Sem autenticação: nenhuma identidade é necessária e a solicitação não está assinada ou autenticada. |
### Configuração de identidade
No AWS SDK para Go, os componentes de identidade de um esquema de autenticação são configurados em `Options` do cliente do SDK. O SDK seleciona e usa automaticamente os valores desses componentes para o esquema selecionado quando uma operação é chamada.
**nota**
Por motivos de compatibilidade com versões anteriores, o SDK permite implicitamente o uso do esquema de autenticação anônima caso nenhum resolvedor de identidade esteja configurado. Isso pode ser feito manualmente configurando todos os resolvedores de identidade em `Options` do cliente como `nil` (o resolvedor de identidade do SigV4 também pode ser definido como `aws.AnonymousCredentials{}`).
### Configuração do signatário
No AWS SDK para Go, os componentes de signatário de um esquema de autenticação são configurados em `Options` do cliente do SDK. O SDK seleciona e usa automaticamente os valores desses componentes para o esquema selecionado quando uma operação é chamada. Nenhuma configuração adicional é necessária.
#### Esquema de autenticação personalizado
Para definir um esquema de autenticação personalizado e configurá-lo para uso, o chamador deve fazer o seguinte:
1. Definir uma implementação do [AuthScheme](https://pkg.go.dev/github.com/aws/smithy-go/transport/http#AuthScheme)
1. Registrar o esquema na lista `AuthSchemes` do cliente do SDK
1. Instrumentar o `AuthSchemeResolver` do cliente do SDK para retornar uma `Option` de autenticação com o ID do esquema, quando aplicável
**Atenção**
Os serviços a seguir têm um comportamento de autenticação exclusivo ou personalizado. Recomendamos que você delegue à implementação padrão e encapsule adequadamente se precisar de um comportamento de autenticação personalizado:
| Serviço | Observações |
| --- | --- |
| S3 | Uso condicional do SigV4A e SigV4Express dependendo da entrada da operação. |
| EventBridge | Uso condicional do SigV4a dependendo da entrada da operação. |
| Cognito | Algumas operações são somente anônimas. |
| SSO | Algumas operações são somente anônimas. |
| STS | Algumas operações são somente anônimas. |
# Configurar endpoints de cliente
**Atenção**
A resolução de endpoints é um tópico avançado do SDK. Ao alterar essas configurações, você corre o risco de quebrar seu código. As configurações padrão devem ser aplicáveis à maioria dos usuários em ambientes de produção.
AWS SDK para Go Ele fornece a capacidade de configurar um endpoint personalizado para ser usado em um serviço. Na maioria dos casos, a configuração padrão é suficiente. A configuração de endpoints personalizados permite um comportamento adicional, como trabalhar com versões de pré-lançamento de um serviço.
## Personalização
Há duas “versões” da configuração de resolução de endpoints no SDK.
+ v2, lançada no terceiro trimestre de 2023, configurada por meio de:
+ `EndpointResolverV2`
+ `BaseEndpoint`
+ v1, lançada junto com o SDK, configurada por meio de:
+ `EndpointResolver`
Recomendamos que os usuários da resolução de endpoint v1 migrem para a v2 para ter acesso aos novos recursos de serviço relacionados ao endpoint.
## V2: `EndpointResolverV2` \$1 `BaseEndpoint`
Na resolução v2, `EndpointResolverV2` é o mecanismo definitivo pelo qual ocorre a resolução do endpoint. O método `ResolveEndpoint` do resolvedor é invocado como parte do fluxo de trabalho para cada solicitação que você faz no SDK. O nome do host do `Endpoint` retornado pelo resolvedor é usado **como está** ao fazer a solicitação (no entanto, os serializadores de operação ainda podem ser anexados ao caminho HTTP).
A resolução v2 inclui uma configuração adicional no nível do cliente, `BaseEndpoint`, que é usada para especificar um nome de host “base” para a instância do serviço. O valor definido aqui não é definitivo. Em última análise, ele é passado como um parâmetro para o `EndpointResolverV2` do cliente quando a resolução final ocorre (continue lendo para obter mais informações sobre os parâmetros `EndpointResolverV2`). A implementação do resolvedor então tem a oportunidade de inspecionar e possivelmente modificar esse valor para determinar o endpoint final.
Por exemplo, se você realizar uma solicitação `GetObject` do S3 em determinado bucket com um cliente em que você especificou um `BaseEndpoint`, o resolvedor padrão injetará o bucket no nome do host se ele for compatível com o host virtual (supondo que você não tenha desativado a hospedagem virtual na configuração do cliente).
Na prática, provavelmente `BaseEndpoint` será usado para direcionar o cliente a uma instância de desenvolvimento ou prévia de um serviço.
### Parâmetros do `EndpointResolverV2`
Cada serviço usa um conjunto específico de entradas que são passadas para sua função de resolução, definida em cada pacote de serviços como `EndpointParameters`.
Cada serviço inclui os seguintes parâmetros básicos, que são usados para facilitar a resolução geral de endpoints na AWS:
| name | type | descrição |
| --- | --- | --- |
| Region | string | A AWS região do cliente |
| Endpoint | string | O valor definido de BaseEndpoint na configuração do cliente |
| UseFips | bool | Se os endpoints FIPS estão habilitados na configuração do cliente |
| UseDualStack | bool | Se os endpoints de pilha dupla estão habilitados na configuração do cliente |
Os serviços podem especificar parâmetros adicionais necessários para a resolução. Por exemplo, `EndpointParameters` do S3 incluem o nome do bucket, bem como várias configurações de recursos específicos do S3, como se o endereçamento de host virtual está habilitado.
Se você estiver implementando seu próprio `EndpointResolverV2`, nunca será necessário construir sua própria instância de `EndpointParameters`. O SDK fornece os valores por solicitação e os transmite para sua implementação.
### Uma observação sobre o Amazon S3
O Amazon S3 é um serviço complexo com muitos de seus recursos modelados por meio de personalizações complexas de endpoints, como hospedagem virtual de bucket, S3 MRAP e muito mais.
Por isso, recomendamos não substituir a implementação `EndpointResolverV2` no cliente do S3. Se você precisar estender seu comportamento de resolução, talvez enviando solicitações a uma pilha de desenvolvimento local com considerações adicionais de endpoint, recomendamos encapsular a implementação padrão de forma que ela retorne ao padrão como alternativa (conforme mostrado nos exemplos abaixo).
### Exemplos
#### Com `BaseEndpoint`
O trecho de código a seguir mostra como direcionar o cliente do S3 para uma instância local de um serviço, que neste exemplo está hospedada no dispositivo de loopback na porta 8080.
```
client := s3.NewFromConfig(cfg, func (o *svc.Options) {
o.BaseEndpoint = aws.String("https://localhost:8080/")
})
```
#### Com `EndpointResolverV2`
O trecho de código a seguir mostra como injetar um comportamento personalizado na resolução do endpoint do S3 usando `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{
// ...
}
})
}
```
#### Com ambos
O exemplo de programa a seguir demonstra a interação entre `BaseEndpoint` e `EndpointResolverV2`. **Este é um caso de uso avançado:**
```
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)
}
```
Quando executado, o programa acima gera o seguinte:
```
The endpoint provided in config is https://endpoint.dev/
```
## V1: `EndpointResolver`
**Atenção**
A resolução de endpoint da v1 é mantida para fins de compatibilidade com versões anteriores e é isolada do comportamento moderno na resolução de endpoint da v2. Ela só será usada se o campo `EndpointResolver` for definido pelo chamador.
O uso da v1 provavelmente impedirá que você acesse os recursos de serviço relacionados ao endpoint introduzidos com ou após o lançamento da resolução v2. Consulte instruções sobre como fazer upgrade em “Migração”.
A [EndpointResolver](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolver)pode ser configurado para fornecer uma lógica de resolução de endpoint personalizada para clientes de serviço. Você pode usar um resolvedor de endpoint personalizado a fim de substituir a lógica de resolução de endpoint de um serviço para todos os endpoints ou apenas para um endpoint regional específico. O resolvedor de endpoint personalizado pode acionar a lógica de resolução de endpoint do serviço para recuar se um resolvedor personalizado não quiser resolver um endpoint solicitado. [EndpointResolverWithOptionsFunc](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointResolverWithOptionsFunc)pode ser usado para agrupar facilmente funções para satisfazer a `EndpointResolverWithOptions` interface.
A `EndpointResolver` pode ser facilmente configurado passando o resolvedor empacotado com [WithEndpointResolverWithOptions](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithEndpointResolverWithOptions)to [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), permitindo a capacidade de substituir os endpoints ao carregar as credenciais, bem como configurar o resultado `aws.Config` com seu resolvedor de endpoint personalizado.
O resolvedor de endpoint recebe o serviço e a região como uma string, permitindo que o resolvedor conduza dinamicamente seu comportamento. Cada pacote de cliente de serviço tem uma constante `ServiceID` exportada que pode ser usada para determinar qual cliente de serviço está invocando o resolvedor de endpoint.
Um resolvedor de endpoint pode usar o valor do erro [EndpointNotFoundError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#EndpointNotFoundError)sentinela para acionar a resolução alternativa para a lógica de resolução padrão do cliente do serviço. Isso permite substituir seletivamente um ou mais endpoints sem precisar lidar com a lógica de fallback.
Se a implementação do resolvedor de endpoint retornar um erro diferente de `EndpointNotFoundError`, a resolução do endpoint será interrompida e a operação de serviço retornará um erro para a aplicação.
### Exemplos
#### Com fallback
O trecho de código a seguir mostra como um único endpoint de serviço pode ser substituído para o DynamoDB pelo comportamento com fallback para outros endpoints:
```
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))
```
#### Sem fallback
O trecho de código a seguir mostra como um único endpoint de serviço pode ser substituído para o DynamoDB pelo comportamento sem fallback para outros endpoints:
```
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))
```
### Endpoints imutáveis
**Atenção**
Definir um endpoint como imutável pode impedir que alguns recursos do cliente de serviço funcionem corretamente e pode resultar em um comportamento indefinido. Deve-se ter cautela ao definir um endpoint como imutável.
Alguns clientes de serviço, como o Amazon S3, podem modificar o endpoint retornado pelo resolvedor para determinadas operações de serviço. Por exemplo, o Amazon S3 gerencia automaticamente o [Endereçamento de bucket virtual](https://docs.aws.amazon.com/AmazonS3/latest/dev/VirtualHosting.html) alterando o endpoint resolvido. Você pode evitar que o SDK altere seus endpoints personalizados configurando como. [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)`true` Por exemplo:
```
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))
```
## Migração
Ao migrar da v1 para v2 da resolução de endpoint, os seguintes princípios gerais se aplicam:
+ Retornar um [endpoint](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint) com [HostnameImmutable](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Endpoint.HostnameImmutable)set to `false` é aproximadamente equivalente `BaseEndpoint` a configurar o URL originalmente retornado da v1 e deixá-lo `EndpointResolverV2` como padrão.
+ Retornar um endpoint com HostnameImmutable set to `true` é aproximadamente equivalente à implementação de um `EndpointResolverV2` que retorna a URL originalmente retornada da v1.
+ A principal exceção é para operações com prefixos de endpoint modelados. Há uma nota sobre isso mais abaixo.
Exemplos desses casos são fornecidos abaixo.
**Atenção**
Os endpoints imutáveis da V1 e a resolução V2 não são equivalentes em comportamento. Por exemplo, substituições de assinatura para recursos personalizados, como o S3 Object Lambda, ainda seriam definidas para endpoints imutáveis retornados por meio do código da v1, mas o mesmo não será feito para a v2.
### Nota sobre prefixos de host
Algumas operações são modeladas com prefixos de host a serem anexados ao endpoint resolvido. Esse comportamento deve funcionar em conjunto com a saída da ResolveEndpoint V2 e, portanto, o prefixo do host ainda será aplicado a esse resultado.
Você pode desativar manualmente o prefixo do host do endpoint aplicando um middleware. Consulte a seção de exemplos.
### Exemplos
#### Endpoint mutável
O exemplo de código a seguir demonstra como migrar um resolvedor de endpoint básico da v1 que retorna um endpoint modificável:
```
// 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/")
})
```
#### Endpoint imutável
```
// 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{}
})
```
#### Desativar o prefixo do 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)
}
}
```
# Personalizar o cliente HTTP
O AWS SDK para Go usa um cliente HTTP padrão com valores de configuração padrão. Embora você possa alterar alguns desses valores de configuração, o transporte e o cliente HTTP padrão não estão suficientemente configurados para clientes que o usam AWS SDK para Go em um ambiente com requisitos de alto throughput e baixa latência. Consulte mais informações em [Perguntas frequentes](faq-gosdk.md), já que as recomendações de configuração variam com base em workloads específicas. Esta seção descreve como configurar um cliente HTTP personalizado e usar esse cliente para criar chamadas do AWS SDK para Go.
Para ajudar a criar um cliente HTTP personalizado, esta seção descreve como usar [NewBuildableClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/transport/http#NewBuildableClient) para definir configurações personalizadas e usar esse cliente com um cliente de serviço do AWS SDK para Go.
Vamos definir o que queremos personalizar.
## Substituição durante o carregamento da configuração
Clientes HTTP personalizados podem ser fornecidos ao chamar [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig) encapsulando o cliente usando [WithHTTPClient](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithHTTP) e passando o valor resultante para `LoadDefaultConfig`. Por exemplo, para passar `customClient` como nosso cliente:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithHTTPClient(customClient))
```
## Tempo limite
O `BuildableHTTPClient` pode ser configurado com um limite de tempo limite de solicitação. Esse tempo limite inclui o tempo para se conectar, processar qualquer redirecionamento e ler o corpo completo da resposta. Por exemplo, para modificar o tempo limite do cliente:
```
import "github.com/aws/aws-sdk-go-v2/aws/transport/http"
// ...
httpClient := http.NewBuildableClient().WithTimeout(time.Second*5)
```
## Dialer
O `BuildableHTTPClient` fornece uma mecânica de compilador para construir clientes com opções modificadas do [Dialer](https://golang.org/pkg/net/#Dialer). O exemplo a seguir mostra como definir as configurações de `Dialer` de um 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
})
```
### Configurações
#### Dialer.KeepAlive
Essa configuração representa o período de keep-alive de uma conexão de rede ativa.
Defina como um valor negativo para desativar os keep-alives.
Defina como **0** para ativar o keep-alives, se compatível com o protocolo e o sistema operacional.
Protocolos de rede ou sistemas operacionais que não são compatíveis com keep-alives ignoram esse campo. Por padrão, o TCP ativa o keep-alive.
Consulte [https://golang.org/pkg/net/\$1Dialer.KeepAlive](https://golang.org/pkg/net/#Dialer.KeepAlive)
Defina `KeepAlive` como **time.Duration**.
#### Dialer.Timeout
Essa configuração representa o tempo máximo que um dial espera pela criação de uma conexão.
O padrão é 30 segundos.
Consulte [https://golang.org/pkg/net/\$1Dialer.Timeout](https://golang.org/pkg/net/#Dialer.Timeout)
Defina `Timeout` como **time.Duration**.
## Transport
O `BuildableHTTPClient` fornece uma mecânica de compilador para construir clientes com opções modificadas de [Transport](https://golang.org/pkg/net/http#Transport).
### Configurar um proxy
Se não conseguir se conectar diretamente à internet, você poderá usar variáveis de ambiente compatíveis com Go (`HTTP_PROXY`/`HTTPS_PROXY`) ou criar um cliente HTTP personalizado para configurar o proxy. O exemplo a seguir configura o cliente para usar `PROXY_URL` como endpoint do 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)
})
```
### Outras configurações
Veja a seguir algumas outras configurações de `Transport` que podem ser modificadas para ajustar o cliente HTTP. Qualquer configuração adicional não descrita aqui pode ser encontrada na documentação do tipo de [Transport](https://golang.org/pkg/net/http/#Transport). Essas configurações podem ser aplicadas conforme mostrado no exemplo a seguir:
```
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
Se a solicitação tiver um cabeçalho “Expect: 100-continue”, essa configuração representa o tempo máximo de espera pelos cabeçalhos da primeira resposta de um servidor após a gravação completa dos cabeçalhos da solicitação. Esse tempo não inclui o tempo para enviar o cabeçalho da solicitação. O cliente HTTP envia sua carga útil depois que esse tempo limite se esgota.
Padrão de 1 segundo.
Defina como **0** para desabilitar o tempo limite e enviar a carga útil da solicitação sem esperar. Um caso de uso é quando você se depara com problemas com proxies ou serviços de terceiros que realizam uma sessão semelhante ao uso do Amazon S3 na função mostrada posteriormente.
Consulte [https://golang.org/pkg/net/http/\$1Transport.ExpectContinueTimeout](https://golang.org/pkg/net/http/#Transport.ExpectContinueTimeout)
Defina `ExpectContinue` como **time.Duration**.
#### Transport.IdleConnTimeout
Essa configuração representa o tempo máximo para manter uma conexão de rede ociosa ativa entre as solicitações HTTP.
Defina como **0** para desabilitar o limite.
Consulte [https://golang.org/pkg/net/http/\$1Transport.IdleConnTimeout](https://golang.org/pkg/net/http/#Transport.IdleConnTimeout)
Defina `IdleConnTimeout` como **time.Duration**.
#### Transport.MaxIdleConns
Essa configuração representa o número máximo de conexões ociosas (keep-alive) em todos os hosts. Um caso de uso para aumentar esse valor é quando você vê muitas conexões dos mesmos clientes em um curto período.
**0** significa que não há limite.
Consulte [https://golang.org/pkg/net/http/\$1Transport.MaxIdleConns](https://golang.org/pkg/net/http/#Transport.MaxIdleConns)
Defina `MaxIdleConns` como **int**.
#### Transport.MaxIdleConnsPerHost
Essa configuração representa o número máximo de conexões ociosas (keep-alive) a serem mantidas por host. Um caso de uso para aumentar esse valor é quando você vê muitas conexões dos mesmos clientes em um curto período.
O padrão é duas conexões ociosas por host.
Defina como **0** para usar DefaultMaxIdleConnsPerHost (2).
Consulte [https://golang.org/pkg/net/http/\$1Transport.MaxIdleConnsPerHost](https://golang.org/pkg/net/http/#Transport.MaxIdleConnsPerHost)
Defina `MaxIdleConnsPerHost` como **int**.
#### Transport.ResponseHeaderTimeout
Essa configuração representa o tempo máximo de espera para que um cliente leia o cabeçalho de resposta.
Se o cliente não conseguir ler o cabeçalho da resposta dentro desse período, a solicitação falhará com um erro de tempo limite.
Tenha cuidado ao definir esse valor ao usar funções do Lambda de longa duração, pois a operação não retorna nenhum cabeçalho de resposta até que a função do Lambda tenha terminado ou atingido o tempo limite. No entanto, você ainda pode usar essa opção com a operação da API \$1\$1 InvokeAsync\$1\$1.
O padrão é sem tempo limite; esperar indefinidamente.
Consulte [https://golang.org/pkg/net/http/\$1Transport.ResponseHeaderTimeout](https://golang.org/pkg/net/http/#Transport.ResponseHeaderTimeout)
Defina `ResponseHeaderTimeout` como **time.Duration**.
#### Transport.TLSHandshakeTimeout
Essa configuração representa o tempo máximo de espera pela conclusão de um handshake TLS.
O padrão é 10 segundos.
Zero significa que não há tempo limite.
Consulte [https://golang.org/pkg/net/http/\$1Transport.TLSHandshakeTimeout](https://golang.org/pkg/net/http/#Transport.TLSHandshakeTimeout)
Defina `TLSHandshakeTimeout` como **time.Duration**.
# Interceptadores HTTP
Você pode usar interceptadores para adicionar um hook à execução de solicitações e respostas de API. Os interceptadores são mecanismos abertos nos quais o SDK chama o código que você escreve para injetar comportamento no ciclo de vida da solicitação/resposta. Dessa maneira, é possível modificar uma solicitação em andamento, depurar o processamento da solicitação, visualizar exceções e muito mais.
## Comparação entre interceptadores e middleware
O AWS SDK para Go v2 fornece interceptadores e middleware para personalizar o processamento de solicitações. Embora ambos tenham propósitos semelhantes, eles foram projetados para públicos e casos de uso diferentes:
+ Os **interceptadores** foram projetados para usuários do SDK que desejam personalizar o processamento de solicitações/respostas com uma API simples e focada em HTTP. Eles fornecem pontos de hook específicos no ciclo de vida da solicitação e trabalham diretamente com solicitações e respostas HTTP.
+ O **middleware** é um sistema mais avançado, independente do tipo de transporte, usado principalmente de forma interna pelo SDK. Embora seja potente, o middleware exige um conhecimento mais profundo dos componentes internos do SDK e envolve interfaces mais complexas.
Principais vantagens dos interceptadores em relação ao middleware para casos de uso comuns:
+ **Foco em HTTP**: os interceptadores trabalham diretamente com solicitações e respostas HTTP, eliminando a necessidade de verificação do tipo de transporte exigida pelo middleware.
+ **Interfaces mais simples**: cada hook do interceptador tem uma interface específica e focada, em vez do padrão genérico de middleware.
+ **Modelo de execução mais claro**: os interceptadores executam em pontos bem definidos no ciclo de vida da solicitação sem exigir conhecimento da ordenação da pilha de middleware.
**nota**
Os interceptadores são construídos sobre o sistema de middleware existente, para que ambos possam coexistir na mesma aplicação. O middleware permanece disponível para casos de uso avançados que exigem comportamento independente de transporte ou manipulação complexa de pilhas.
## Hooks de interceptadores disponíveis
O AWS SDK para Go v2 fornece hooks de interceptadores em vários estágios do ciclo de vida da solicitação. Cada hook corresponde a uma interface específica que você pode implementar:
+ `BeforeExecution`: primeiro hook chamado durante a execução da operação
+ `BeforeSerialization`: antes de a mensagem de entrada ser serializada na solicitação de transporte
+ `AfterSerialization`: depois de a mensagem de entrada ser serializada na solicitação de transporte
+ `BeforeRetryLoop`: antes de entrar no loop de novas tentativas
+ `BeforeAttempt`: primeiro hook chamado dentro do loop de novas tentativas
+ `BeforeSigning`: antes da assinatura da solicitação de transporte
+ `AfterSigning`: depois da assinatura da solicitação de transporte
+ `BeforeTransmit`: antes da assinatura da solicitação de transporte
+ `AfterTransmit`: depois de receber a resposta de transporte
+ `BeforeDeserialization`: antes de a resposta de transporte ser desserializada
+ `AfterDeserialization`: depois de fazer unmarshalling da resposta de transporte
+ `AfterAttempt`: último hook chamado dentro do loop de novas tentativas
+ `AfterExecution`: último hook chamado durante a execução da operação
Você pode implementar várias interfaces em um único interceptador para fazer hook em vários estágios do ciclo de vida da solicitação.
## Registro do interceptador
Você registra interceptadores ao construir um cliente de serviço ou ao substituir a configuração de uma operação específica. O registro difere dependendo se você deseja que o interceptador se aplique a todas as operações do cliente ou apenas a operações específicas.
Os interceptadores são gerenciados por meio de um registro de interceptadores que fornece métodos para adicioná-los e removê-los. O exemplo a seguir mostra um interceptador simples que adiciona um cabeçalho de ID de rastreamento do AWS X-Ray às solicitações enviadas antes do processo de assinatura:
```
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{})
})
```
O registro do interceptador é adicionado às opções do cliente, o que viabiliza a configuração do interceptador por operação:
```
// ... or use it per-operation
s3.ListBuckets(context.Background(), &s3.ListBucketsInput{
}, func(o *s3.Options) {
o.Interceptors.AddBeforeSigning(recursionDetection{})
})
```
## Configuração do interceptador global
Você também pode registrar interceptadores globalmente usando a função `config.LoadDefaultConfig` com as opções `With*` apropriadas para cada tipo de interceptador. Isso aplica o interceptador a todos os clientes de serviço da AWS criados com base nessa configuração:
```
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 em log
O AWS SDK para Go tem recursos de registro em log disponíveis que permitem que a aplicação habilite informações de depuração para depurar e diagnosticar falhas ou problemas de solicitação. A interface [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) e o [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) são os principais componentes disponíveis para você determinar como e o que deve ser registrado em log pelos clientes.
## Logger
Ao construir um [Config](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Config) usando [LoadDefaultConfig](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#LoadDefaultConfig), um `Logger` padrão é configurado para enviar mensagens de log ao erro padrão do processo (stderr). Um logger personalizado que satisfaça a interface do [Logger](https://pkg.go.dev/github.com/aws/smithy-go/logging#Logger) pode ser passado como argumento para `LoadDefaultConfig` encapsulando-o com [config.WithLogger](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/config#WithLogger).
Por exemplo, para configurar nossos clientes para usar nosso `applicationLogger`:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithLogger(applicationLogger))
```
Agora, os clientes configurados usando o `aws.Config` construído enviam mensagens de log para `applicationLogger`.
### Loggers cientes do contexto
Uma implementação do Logger pode implementar a interface opcional [ContextLogger](https://pkg.go.dev/github.com/aws/smithy-go/logging#ContextLogger). Os loggers que implementam essa interface terão seus métodos `WithContext` invocados com o contexto atual. Isso permite que as implementações de registro em log retornem um novo `Logger` que pode gravar metadados de registro em log adicionais com base nos valores presentes no contexto.
## ClientLogMode
Por padrão, os clientes do serviço não geram mensagens de log. Para configurar clientes para enviar mensagens de log para fins de depuração, use o membro [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) em `Config`. `ClientLogMode` pode ser configurado para ativar a depuração de mensagens para:
+ Assinatura do Signature Version 4 (SigV4)
+ Novas tentativas de solicitação
+ Solicitações de HTTP
+ Respostas HTTP
Por exemplo, para ativar o registro em log de solicitações HTTP e novas tentativas:
```
cfg, err := config.LoadDefaultConfig(context.TODO(), config.WithClientLogMode(aws.LogRetries | aws.LogRequest))
```
Consulte em [ClientLogMode](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#ClientLogMode) os diferentes modos de log em do cliente disponíveis.
# Traços e métricas
AWS SDK para Go É instrumentado para registrar extensões de rastreamento e métricas do lado do cliente para operações do SDK. Por padrão, os clientes usam implementações autônomas para rastreamento e métricas, o que significa que nenhum dado é coletado, a menos que você configure um provedor.
Os clientes de serviço têm duas opções de configuração para observabilidade:
+ [TracerProvider](https://pkg.go.dev/github.com/aws/smithy-go/tracing#TracerProvider)— Ponto de entrada para criar rastreadores e registrar extensões de rastreamento do cliente.
+ [MeterProvider](https://pkg.go.dev/github.com/aws/smithy-go/metrics#MeterProvider)— Ponto de entrada para criar medidores e registrar métricas do lado do cliente.
Embora inspiradas nas especificações OpenTelemetry (OTel), elas APIs são definidas de forma independente em`smithy-go`. O SDK fornece módulos adaptadores para conectar implementações concretas do OTel SDK às interfaces do provedor do SDK.
## Rastreamento
Use o módulo adaptador [smithyoteltracing](https://pkg.go.dev/github.com/aws/smithy-go/tracing/smithyoteltracing) para conectar e a um cliente de serviço. OTel `trace.TracerProvider`
O exemplo a seguir mostra como configurar o rastreamento para um cliente 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)
})
```
As operações do SDK são instrumentadas com uma hierarquia de abrangência que abrange os componentes de alto nível do ciclo de vida da operação, como serialização de solicitações, assinatura e o ciclo de repetição.
## Metrics
Use o módulo adaptador [smithyotelmetrics](https://pkg.go.dev/github.com/aws/smithy-go/metrics/smithyotelmetrics) para conectar e a um OTel `metric.MeterProvider` cliente de serviço.
O exemplo a seguir mostra como configurar métricas para um cliente 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 compatíveis
Os clientes do SDK coletam as seguintes métricas:
| Nome da métrica | Unidade | Tipo | Description |
| --- | --- | --- | --- |
| client.call.duration | s | Histograma | Duração geral da chamada, incluindo novas tentativas e tempo para enviar ou receber a solicitação e o corpo da resposta. |
| client.call.attempts | \$1attempt\$1 | MonotonicCounter | O número de tentativas de uma operação individual. |
| client.call.errors | \$1error\$1 | MonotonicCounter | O número de erros de uma operação. |
| client.call.attempt\$1duration | s | Histograma | O tempo para se conectar ao serviço, enviar a solicitação e recuperar o código de status e os cabeçalhos HTTP (incluindo o tempo na fila de espera para ser enviado). |
| client.call.resolve\$1endpoint\$1duration | s | Histograma | A hora de resolver um endpoint (resolvedor de endpoint, não DNS) para a solicitação. |
| client.call.deserialization\$1duration | s | Histograma | A hora de desserializar o corpo da mensagem. |
| client.call.auth.signing\$1duration | s | Histograma | A hora de assinar uma solicitação. |
| client.call.auth.resolve\$1identity\$1duration | s | Histograma | O momento de adquirir uma identidade (AWS credenciais, token do portador etc.) de um provedor de identidade. |
Os seguintes atributos (dimensões) estão incluídos em cada métrica, quando aplicável:
+ `rpc.service`— O nome do serviço.
+ `rpc.method`— O nome da operação.
+ `exception.type`— O tipo de erro (incluído com`client.call.errors`).
+ `auth.scheme_id`— O esquema de autenticação (incluído nas métricas relacionadas à autenticação).
### Métricas do cliente HTTP
O cliente HTTP do SDK coleta as seguintes métricas adicionais relacionadas ao ciclo de vida da conexão HTTP subjacente:
| Nome da métrica | Unidade | Tipo | Description |
| --- | --- | --- | --- |
| client.http.connections.acquire\$1duration | s | Histograma | O tempo necessário para que uma solicitação adquira uma conexão. |
| client.http.connections.dns\$1lookup\$1duration | s | Histograma | O tempo necessário para realizar uma pesquisa de DNS. |
| client.http.connections.tls\$1handshake\$1duration | s | Histograma | O tempo necessário para realizar um handshake TLS. |
| client.http.connections.usage | \$1conexão\$1 | UpDownCounter | O estado atual das conexões no pool. Usa uma state dimensão com um valor de idle ouacquired. |
| client.http.do\$1request\$1duration | s | Histograma | O tempo total gasto executando a solicitação HTTP. |
| client.http.time\$1to\$1first\$1byte | s | Histograma | O tempo desde o envio da solicitação até o recebimento do primeiro byte de resposta. |
# Tentativas e tempos limite
O AWS SDK para Go permite que você configure o comportamento de repetição de solicitações para serviços HTTP. Por padrão, os clientes de serviço usam [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) como mecanismo padrão de novas tentativas. Se a configuração ou o comportamento padrão não atenderem aos requisitos da aplicação, você poderá ajustar a configuração do mecanismo de novas tentativas ou fornecer sua própria implementação desse mecanismo.
O AWS SDK para Go fornece uma interface [AWS.Retryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#Retryer) que define o conjunto de métodos exigidos pela implementação de uma nova tentativa. [O SDK fornece duas implementações para novas tentativas: [retry.standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) e aws. NoOpRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NoOpRetryer).
## Mecanismo padrão de novas tentativas
O mecanismo de novas tentativas [retry.Standard](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#Standard) é a implementação `aws.Retryer` padrão usada por clientes do SDK. O mecanismo padrão de novas tentativas tem taxas limitadas, com um número máximo configurável de tentativas e a capacidade de ajustar a política de espera entre as solicitações.
A tabela a seguir define os valores padrão para esse mecanismo de novas tentativas:
| Propriedade | Padrão |
| --- | --- |
| Número máximo de tentativas | 3 |
| Atraso máximo entre tentativas | 20 segundos |
Quando ocorre um erro de novas tentativas ao invocar a solicitação, o mecanismo padrão de novas tentativas usa a configuração fornecida para adiar e, posteriormente, tentar novamente a solicitação. As novas tentativas aumentam a latência geral da solicitação, e você deverá configurar o mecanismo de novas tentativas se a configuração padrão não atender aos requisitos da aplicação.
Consulte detalhes sobre quais erros são considerados passíveis de nova tentativa pela implementação do mecanismo padrão de novas tentativas na documentação do pacote de [novas tentativas](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
## NopRetryer
As [leis. NopRetryer](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws#NopRetryer)é uma `aws.Retryer` implementação fornecida se você quiser desativar todas as tentativas de repetição. Ao invocar uma operação de cliente de serviço, essa nova tentativa só permitirá que a solicitação seja tentada uma vez, e qualquer erro resultante será retornado à aplicação de chamada.
## Personalizar comportamento
O SDK fornece um conjunto de utilitários auxiliares que encapsulam uma implementação `aws.Retryer` e retorna o mecanismo de novas tentativas fornecido encapsulado com o comportamento desejado de novas tentativas. É possível substituir o mecanismo padrão de novas tentativas para todos os clientes, por cliente ou por operação, dependendo dos requisitos das aplicações. Consulte mais exemplos que mostram como fazer isso na documentação do pacote de [novas tentativas](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry).
**Atenção**
Ao especificar uma implementação `aws.Retryer` global usando `config.WithRetryer`, você deve garantir o retorno de uma nova instância de `aws.Retryer` a cada invocação. Isso garante que você não crie um bucket global de tokens de novas tentativas em todos os clientes de serviço.
### Limitar o número máximo de tentativas
Você usa a [repetição. AddWithMaxAttempts](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxAttempts)para empacotar uma `aws.Retryer` implementação para definir o número máximo de tentativas para o valor desejado.
**Atenção**
Usar `retry.AddWithMaxAttempts` com um valor zero permitirá que o SDK tente novamente todos os erros passíveis de novas tentativas até que a solicitação seja bem-sucedida ou que um erro que não possa ter uma nova tentativa seja retornado. **Permitir que o SDK tente novamente indefinidamente pode resultar em workloads descontroladas e ciclos de faturamento inflados.**
```
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)
```
Observe que instanciar uma nova tentativa usando opções funcionais para definir MaxAttempts diretamente terá um comportamento um pouco diferente. Mais especificamente, definir um valor menor ou igual a zero fará com que o mecanismo de novas tentativas use o máximo padrão de três tentativas, em vez de tentar novamente indefinidamente:
```
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)
```
### Limitar o atraso máximo de backoff
Você usa a [repetição. AddWithMaxBackoffDelay](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithMaxBackoffDelay)para encerrar uma `aws.Retryer` implementação e limitar o atraso máximo que pode ocorrer entre a repetição de uma solicitação com falha.
Por exemplo, você pode usar o código a seguir para encapsular o mecanismo padrão de novas tentativas do cliente com um atraso máximo desejado 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)
```
### Tentar novamente códigos de erro adicionais da API
Você usa a [repetição. AddWithErrorCodes](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#AddWithErrorCodes)para empacotar uma `aws.Retryer` implementação e incluir códigos de erro de API adicionais que devem ser considerados passíveis de nova tentativa.
Por exemplo, você pode usar o código a seguir para encapsular o mecanismo padrão de novas tentativas do cliente para incluir a exceção `NoSuchBucketException` do Amazon S3 como passível de novas tentativas.
```
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)
```
### Limitação de taxa do lado do cliente
O AWS SDK para Go introduz um novo mecanismo de limitação de taxa do lado do cliente na política de repetição padrão para se alinhar ao comportamento moderno. SDKs [Esse comportamento é controlado pelo [RateLimiter](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#RateLimiter)campo nas opções de um repetidor.](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/retry#StandardOptions)
RateLimiter A opera como um token bucket com uma capacidade definida, em que falhas na tentativa de operação consomem tokens. Uma nova tentativa que tenta consumir mais tokens do que os disponíveis resulta em falha na operação com um [QuotaExceededError](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#QuotaExceededError).
A implementação padrão é parametrizada da seguinte forma (como modificar cada configuração):
+ uma capacidade de 500 (defina o valor de RateLimiter ao StandardOptions usar [NewTokenRateLimit](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#NewTokenRateLimit))
+ uma nova tentativa causada por um tempo limite custa 10 tokens (ativado RetryTimeoutCost ) StandardOptions
+ uma nova tentativa causada por outros erros custa 5 tokens ( RetryCostativada StandardOptions)
+ uma operação bem-sucedida na 1ª tentativa adiciona 1 token ( NoRetryIncrement ativado StandardOptions)
+ operações bem-sucedidas na segunda tentativa ou posterior não adicionam de volta nenhum token
Se você perceber que o comportamento padrão não atende às necessidades da aplicação, você pode desativá-lo com [ratelimit.None](https://pkg.go.dev/github.com/aws/aws-sdk-go-v2/aws/ratelimit#pkg-variables).
#### Exemplo: limitador de taxa 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
})
}))
```
#### Exemplo: sem limite de taxa usando 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
})
}))
```
## Tempos limite
Você usa o pacote de [contexto](https://golang.org/pkg/context/) para definir tempos limite ou prazos ao invocar uma operação de cliente de serviço. Use o [contexto. WithDeadline](https://golang.org/pkg/context/#WithDeadline)para encapsular o contexto de seus aplicativos e definir um prazo para um horário específico em que a operação invocada deve ser concluída. Para definir um tempo limite após um determinado [contexto de `time.Duration` uso. WithTimeout](https://golang.org/pkg/context/#WithTimeout). O SDK passa o `context.Context` fornecido para o cliente de transporte HTTP ao invocar uma API de serviço. Se o contexto passado para o SDK for cancelado ou se tornar cancelado ao invocar a operação, o SDK não tentará novamente a solicitação e retornará à aplicação que fez a chamada. Você deve lidar com o cancelamento de contexto de forma adequada na aplicação nos casos em que o contexto fornecido ao SDK tenha sido cancelado.
### Definir um tempo limite
O código de exemplo a seguir mostra como definir um tempo limite para uma operação de cliente de serviço.
```
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
}
```