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 clientes de serviço no AWS SDK para Rust
Para acessar os Serviços da AWS de forma programática, o AWS SDK para Rust usa uma estrutura de cliente para cada AWS service (Serviço da AWS). Por exemplo, se a aplicação precisar de acesso ao Amazon EC2, ela cria uma estrutura de cliente do EC2 para interagir com esse serviço. Em seguida, você usa o cliente de serviço para fazer solicitações para esse AWS service (Serviço da AWS).
Para fazer requisições a um AWS service (Serviço da AWS), você primeiro cria um cliente de serviço. Para cada AWS service (Serviço da AWS) que seu código usa, ele tem sua própria caixa e seu próprio tipo dedicado para interagir com ela. O cliente expõe um método para cada operação de API exposta pelo serviço.
Há muitas maneiras alternativas de configurar o comportamento do SDK, mas tudo está relacionado ao comportamento dos clientes de serviço. Nenhuma configuração tem efeito até que um cliente de serviço criado com base nela seja utilizado.
Você precisa estabelecer como seu código faz a autenticação com a AWS ao desenvolver com os Serviços da AWS. Você também deve definir a Região da AWS que deseja usar.
O [Guia de referência de SDKs e ferramentas da AWS](https://docs.aws.amazon.com/sdkref/latest/guide/) também contém configurações, recursos e outros conceitos fundamentais comuns entre muitos dos AWS SDKs.
**Topics**
+ [Configurar cliente externamente](config-external.md)
+ [Configuração do cliente no código](config-code.md)
+ [Região da AWS](region.md)
+ [Provedores de credenciais](credproviders.md)
+ [Versões de comportamento](behavior-versions.md)
+ [Novas tentativas](retries.md)
+ [Tempos limite](timeouts.md)
+ [Observabilidade](observability.md)
+ [Endpoints de cliente](endpoints.md)
+ [Substituir uma configuração de operação](peroperation.md)
+ [HTTP](http.md)
+ [Interceptores](interceptors.md)
# Configurar clientes do serviço AWS SDK para Rust externamente
Muitas configurações podem ser tratadas fora do código. Quando a configuração é tratada externamente, ela é aplicada a todas as suas aplicações. A maioria das configurações pode ser definida como variáveis de ambiente ou em um arquivo AWS `config` compartilhado distinto. O arquivo `config` compartilhado pode manter conjuntos separados de configurações, chamados de perfis, para fornecer configurações diferentes para ambientes ou testes distintos.
As configurações de variáveis de ambiente e do arquivo `config` compartilhado são padronizadas e compartilhadas entre os SDKs e ferramentas da AWS para comportar a funcionalidade consistente em diferentes linguagens de programação e aplicações.
Consulte o *Guia de referência de ferramentas e AWS SDKs* para saber como configurar a aplicação por meio desses métodos, além de detalhes sobre cada configuração entre SDKs. Consulte todas as configurações que podem ser tratadas pelo SDK com base nas variáveis de ambiente ou nos arquivos de configuração na [Referência de configurações](https://docs.aws.amazon.com/sdkref/latest/guide/settings-reference.html) no *Guia de referência de ferramentas e AWS SDKs*.
Para fazer uma solicitação a um AWS service (Serviço da AWS), primeiro você instancia um cliente para esse serviço. Você pode definir configurações comuns para clientes de serviço, como tempos limite, o cliente HTTP e configuração de repetição.
Cada cliente de serviço exige uma Região da AWS e um provedor de credenciais. O SDK usa esses valores para enviar solicitações à região correta para seus recursos e para assinar solicitações com as credenciais corretas. Você pode especificar esses valores de modo programático no código ou fazer com que sejam carregados automaticamente do ambiente.
O SDK tem uma série de locais (ou fontes) que ele confere para encontrar um valor para as configurações.
1. Qualquer configuração explícita definida no código ou no próprio cliente de serviço tem precedência sobre qualquer outra coisa.
1. Variáveis de ambiente
+ Para ver detalhes sobre a configuração de variáveis de ambiente, consulte [variáveis de ambiente](https://docs.aws.amazon.com/sdkref/latest/guide/environment-variables.html) no *Guia de referência de ferramentas e AWS SDKs*.
+ Observe que você pode configurar variáveis de ambiente para um shell em diferentes níveis de escopo: em todo o sistema, para o usuário e para uma sessão de terminal específica.
1. Arquivos `config` e `credentials` compartilhados
+ Consulte detalhes sobre como configurar esses arquivos em [Arquivos de `config` e `credentials` compartilhados](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) no *Guia de referência de ferramentas e AWS SDKs*.
1. Qualquer valor padrão fornecido pelo próprio código-fonte do SDK é usado por último.
+ Algumas propriedades, como região, não têm um padrão. Você deve especificá-las explicitamente no código, em uma configuração de ambiente ou no arquivo `config` compartilhado. Se o SDK não conseguir resolver a configuração exigida, as solicitações de API poderão falhar no runtime.
# Configurando o AWS SDK para clientes do serviço Rust em código
Quando a configuração é tratada diretamente no código, o escopo da configuração é limitado à aplicação que usa esse código. Dentro dessa aplicação, há opções para a configuração global de todos os clientes de serviço, a configuração para todos os clientes de determinado tipo de AWS service (Serviço da AWS) ou a configuração para uma instância específica do cliente de serviço.
Para fazer uma solicitação a um AWS service (Serviço da AWS), primeiro você instancia um cliente para esse serviço. Você pode definir configurações comuns para clientes de serviço, como tempos limite, o cliente HTTP e configuração de repetição.
Cada cliente de serviço exige um Região da AWS e um provedor de credenciais. O SDK usa esses valores para enviar solicitações à região correta para seus recursos e para assinar solicitações com as credenciais corretas. Você pode especificar esses valores de modo programático no código ou fazer com que sejam carregados automaticamente do ambiente.
**nota**
Os clientes de serviços podem ser caros para construir e geralmente devem ser compartilhados. Para facilitar isso, todas as estruturas `Client` implementam `Clone`.
## Configurar um cliente do ambiente
Para criar um cliente com configuração baseada no ambiente, use métodos estáticos da caixa `aws-config`:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
Criar um cliente dessa forma é útil quando executado no Amazon Elastic Compute Cloud ou em qualquer outro contexto em que a configuração de um cliente de serviço esteja disponível diretamente do ambiente. AWS Lambda Isso separa seu código do ambiente em que ele está sendo executado e facilita a implantação de seu aplicativo em vários Regiões da AWS sem alterar o código.
Você pode substituir explicitamente propriedades específicas. A configuração explícita tem precedência sobre a configuração resolvida no ambiente de execução. O seguinte exemplo carrega a configuração do ambiente, mas substitui explicitamente a Região da AWS:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
**nota**
Nem todos os valores de configuração são fornecidos pelo cliente no momento da criação. As configurações relacionadas a credenciais, como chaves de acesso temporárias e configuração do Centro de Identidade do IAM, são acessadas pela camada do provedor de credenciais quando o cliente é usado para fazer uma solicitação.
O código `BehaviorVersion::latest()` mostrado nos exemplos anteriores indica a versão do SDK a ser usada como padrão. O `BehaviorVersion::latest()`é adequado para a maioria dos casos. Para obter detalhes, consulte [Usando versões de comportamento no AWS SDK para Rust](behavior-versions.md).
## Use o padrão do builder para configurações específicas do serviço
Há algumas opções que só podem ser configuradas em um tipo específico de cliente de serviço. No entanto, na maioria das vezes, será importante carregar a maioria das configurações do ambiente e, em seguida, adicionar especificamente as opções adicionais. O padrão do construtor é um padrão comum dentro das AWS SDK para Rust caixas. Primeiro, você carrega a configuração geral usando `aws_config::defaults` e, em seguida, usa o método `from` para carregar essa configuração no construtor do serviço com o qual você está trabalhando. Em seguida, você pode definir valores de configuração exclusivos para esse serviço e chamada `build`. Por fim, o cliente é criado com base nessa configuração modificada.
```
// Call a static method on aws-config that sources default config values.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// Use the Builder for S3 to create service-specific config from the default config.
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.accelerate(true) // Set an S3-only configuration option
.build();
// Create the client.
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
Uma forma de descobrir métodos adicionais disponíveis para um tipo específico de cliente de serviço é usar a documentação da API, como para [https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/struct.Builder.html).
## Configuração avançada explícita do cliente
Para configurar um cliente de serviço com valores específicos em vez de carregar uma configuração do ambiente, você pode especificá-los no builder `Config` do cliente, conforme mostrado abaixo:
```
let conf = aws_sdk_s3::Config::builder()
.region("us-east-1")
.endpoint_resolver(my_endpoint_resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(conf);
```
Quando você cria uma configuração de serviço como `aws_sdk_s3::Config::builder()`, *nenhuma configuração padrão é carregada*. Os padrões só são carregados ao criar uma configuração baseada em `aws_config::defaults`.
Há algumas opções que só podem ser configuradas em um tipo específico de cliente de serviço. O exemplo anterior mostra um exemplo disso usando a função `endpoint_resolver` em um cliente Amazon S3.
# Configurando o Região da AWS para o AWS SDK para Rust
Você pode acessar Serviços da AWS essa operação em uma área geográfica específica usando Regiões da AWS. Isso pode ser útil para redundância e para manter os dados e as aplicações em execução próximo ao lugar onde você e os usuários as acessarão. Para obter mais informações sobre como as regiões são usadas, consulte [Região da AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)o *Guia de referência de ferramentas AWS SDKs e ferramentas*.
**Importante**
A maioria dos recursos reside em um local específico Região da AWS e você deve fornecer a região correta para o recurso ao usar o SDK.
Você deve definir um padrão Região da AWS para o SDK do Rust usar nas solicitações AWS . Esse padrão é usado para todas as chamadas do método de serviço do SDK que não são especificadas com uma região.
Para obter exemplos de como definir a região padrão por meio do AWS `config` arquivo compartilhado ou das variáveis de ambiente, consulte [Região da AWS](https://docs.aws.amazon.com/sdkref/latest/guide/feature-region.html)o *Guia de referência de ferramentas AWS SDKs e ferramentas*.
## Região da AWS cadeia de fornecedores
O processo de pesquisa a seguir é usado ao carregar a configuração de um cliente de serviço do ambiente de execução. O primeiro valor que o SDK encontra como definido é usado na configuração do cliente. Para obter mais informações sobre a criação de clientes de serviço, consulte [Configurar um cliente do ambiente](config-code.md#configure-a-client-from-the-environment).
1. Qualquer região explícita é definida programaticamente.
1. A variável de ambiente `AWS_REGION` está marcada.
+ Se você estiver usando o AWS Lambda serviço, essa variável de ambiente será definida automaticamente pelo AWS Lambda contêiner.
1. A `region` propriedade no AWS `config` arquivo compartilhado é verificada.
+ A variável de ambiente `AWS_CONFIG_FILE` pode ser usada para alterar o local do arquivo de configuração `config` compartilhado. Para saber mais sobre onde esse arquivo é mantido, consulte [Localização dos `credentials` arquivos compartilhados `config`AWS SDKs e](https://docs.aws.amazon.com/sdkref/latest/guide/file-location.html) *do Guia de referência de ferramentas*.
+ A variável de ambiente `AWS_PROFILE` pode ser usada para selecionar um perfil nomeado em vez do padrão. Para saber mais sobre como configurar perfis diferentes, consulte [Compartilhados `config` e `credentials` arquivos](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) no *Guia de referência de ferramentas AWS SDKs e ferramentas*.
1. O SDK tenta usar o serviço de metadados da instância do Amazon EC2 para determinar a região da instância do Amazon EC2 em execução no momento.
+ Os AWS SDK para Rust únicos suportes IMDSv2.
O `RegionProviderChain` é usado automaticamente sem código adicional ao criar uma configuração básica para ser usada com um cliente de serviço:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
```
## Configurando o código Região da AWS de entrada
### Definir explicitamente a região no código
Use `Region::new()` diretamente na sua configuração quando quiser definir explicitamente a região.
A cadeia de fornecedores da região não é usada. Ela não verifica o ambiente, o arquivo compartilhado `config` ou o serviço de metadados da instância do Amazon EC2.
```
use aws_config::{defaults, BehaviorVersion};
use aws_sdk_s3::config::Region;
#[tokio::main]
async fn main() {
let config = defaults(BehaviorVersion::latest())
.region(Region::new("us-west-2"))
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
Certifique-se de inserir uma string válida para um Região da AWS; o valor fornecido não está validado.
### Personalizar o `RegionProviderChain`
Use [Região da AWS cadeia de fornecedores](#region-provider-chain) quando quiser injetar uma região condicionalmente, substituí-la ou personalizar a cadeia de resolução.
```
use aws_config::{defaults, BehaviorVersion};
use aws_config::meta::region::RegionProviderChain;
use aws_sdk_s3::config::Region;
use std::env;
#[tokio::main]
async fn main() {
let region_provider = RegionProviderChain::first_try(env::var("CUSTOM_REGION").ok().map(Region::new))
.or_default_provider()
.or_else(Region::new("us-east-2"));
let config = aws_config::defaults(BehaviorVersion::latest())
.region(region_provider)
.load()
.await;
println!("Using Region: {}", config.region().unwrap());
}
```
A configuração anterior irá:
1. Ver se há uma string definida na variável de ambiente `CUSTOM_REGION`.
1. Se isso não estiver disponível, retornar à cadeia de fornecedores padrão da região.
1. Se isso falhar, usar “us-east-2" como o fallback final.
# Usando o AWS SDK para provedores de credenciais Rust
Todas as solicitações AWS devem ser assinadas criptograficamente usando credenciais emitidas por. AWS No runtime, o SDK recupera os valores de configuração para credenciais conferindo vários locais.
Se a configuração recuperada incluir [configurações de acesso de SSO do Centro de Identidade do AWS IAM](credentials.md), o SDK trabalhará com o Centro de Identidade do IAM para recuperar as credenciais temporárias que ele usa para fazer solicitações para Serviços da AWS.
Se a configuração recuperada incluir [credenciais temporárias](https://docs.aws.amazon.com/sdkref/latest/guide/access-temp-idc.html), o SDK as usará para fazer chamadas. AWS service (Serviço da AWS) As credenciais temporárias consistem em chaves de acesso e um token de sessão.
A autenticação com AWS pode ser feita fora da sua base de código. Muitos métodos de autenticação podem ser detectados, usados e atualizados automaticamente pelo SDK usando a cadeia de provedores de credenciais.
Para opções guiadas para começar a AWS autenticar seu projeto, consulte [Autenticação e acesso](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) no *AWS SDKs Guia de referência de ferramentas*.
## Cadeia de provedores de credenciais
Se, ao criar um cliente, você não especificar explicitamente um provedor de credenciais, o SDK para Rust usará uma cadeia de provedores de credenciais que vai conferir uma série de locais onde você pode fornecer credenciais. Depois que o SDK encontra as credenciais em um desses locais, a pesquisa é interrompida. Para obter detalhes sobre a construção de clientes, consulte [Configurando o AWS SDK para clientes do serviço Rust em código](config-code.md).
O exemplo a seguir não especifica um provedor de credenciais no código. O SDK usa a cadeia de provedores de credenciais para detectar a autenticação configurada no ambiente de hospedagem e usa essa autenticação para chamadas para Serviços da AWS.
```
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3 = aws_sdk_s3::Client::new(&config);
```
### Ordem de recuperação de credenciais
A cadeia de provedores de credenciais pesquisa as credenciais usando a seguinte sequência predefinida:
1. **Variáveis de ambiente de chave de acesso**
O SDK tenta carregar credenciais das variáveis de ambiente `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY` e `AWS_SESSION_TOKEN`.
1. **O compartilhado AWS `config` e `credentials` os arquivos**
O SDK tenta carregar as credenciais do `[default]` perfil nos arquivos compartilhados AWS `config` e`credentials`. É possível usar a variável de ambiente `AWS_PROFILE` para escolher um perfil nomeado a ser carregado pelo SDK em vez de usar `[default]`. Os `credentials` arquivos `config` e são compartilhados por várias AWS SDKs ferramentas. Para obter mais informações sobre esses arquivos, consulte [Compartilhados `config` e `credentials` arquivos](https://docs.aws.amazon.com/sdkref/latest/guide/file-format.html) no *Guia de referência de ferramentas AWS SDKs e ferramentas*. Para obter mais informações sobre provedores padronizados que você pode especificar em um perfil, consulte [Ferramentas AWS SDKs e provedores de credenciais padronizados](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html).
1. **AWS STS identidade na web**
Ao criar aplicativos móveis ou aplicativos web baseados em clientes que exigem acesso a AWS, AWS Security Token Service (AWS STS) retorna um conjunto de credenciais de segurança temporárias para usuários federados que são autenticados por meio de um provedor de identidade público (IdP).
+ Quando você especifica isso em um perfil, o SDK ou a ferramenta tenta recuperar credenciais temporárias usando AWS STS `AssumeRoleWithWebIdentity` o método de API. Para obter detalhes sobre esse método, consulte [AssumeRoleWithWebIdentity](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithWebIdentity.html)a *Referência AWS Security Token Service da API*.
+ *Para obter orientação sobre como configurar esse provedor, consulte [Federate with web identity ou OpenID Connect](https://docs.aws.amazon.com/sdkref/latest/guide/access-assume-role.html#webidentity) no Guia de referência de ferramentas AWS SDKs .*
+ Para obter detalhes sobre as propriedades de configuração do SDK para esse provedor, consulte [Assumir a função de provedor de credenciais](https://docs.aws.amazon.com/sdkref/latest/guide/feature-assume-role-credentials.html) no Guia de *referência de ferramentas AWS SDKs e ferramentas*.
1. **Credenciais de contêiner do Amazon ECS e do Amazon EKS **
Suas tarefas do Amazon Elastic Container Service e as contas de serviço do Kubernetes podem ter um perfil do IAM associado a elas. As permissões concedidas no perfil do IAM são assumidas pelos contêineres em execução na tarefa ou pelos contêineres do pod. Esse perfil permite que o código da aplicação SDK para Rust (no contêiner) use outros Serviços da AWS.
O SDK tenta recuperar credenciais das variáveis de ambiente `AWS_CONTAINER_CREDENTIALS_RELATIVE_URI` ou `AWS_CONTAINER_CREDENTIALS_FULL_URI`, que podem ser definidas automaticamente pelo Amazon ECS e pelo Amazon EKS.
+ Para ver detalhes sobre como configurar esse perfil para o Amazon ECS, consulte [Perfil do IAM para tarefas do Amazon ECS](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) no *Guia do desenvolvedor do Amazon Elastic Container Service*.
+ Para receber informações de configuração do Amazon EKS, consulte [Configurar o atendente de identidade de pods do Amazon EKS](https://docs.aws.amazon.com/eks/latest/userguide/pod-id-agent-setup.html) no **Guia do usuário do Amazon EKS**.
+ Para obter detalhes sobre as propriedades de configuração do SDK para esse provedor, consulte Provedor de [credenciais de contêiner](https://docs.aws.amazon.com/sdkref/latest/guide/feature-container-credentials.html) no Guia de *referência de ferramentas AWS SDKs e ferramentas*.
1. **Serviço de metadados da instância do Amazon EC2 **
Crie um perfil do IAM e anexe-o à instância. A aplicação SDK para Rust na instância tenta recuperar as credenciais fornecidas pelo perfil nos metadados da instância.
+ O SDK para Rust é compatível apenas com. [IMDSv2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/configuring-instance-metadata-service.html)
+ Para ver detalhes sobre como configurar esse perfil e usar metadados, consulte [Perfis do IAM para o Amazon EC2](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-roles-for-amazon-ec2.html) e [Trabalhar com metadados de instância](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-instance-metadata.html) no *Guia do usuário do Amazon EC2*.
+ Para obter detalhes sobre as propriedades de configuração do SDK para esse provedor, consulte o provedor de [credenciais IMDS no Guia de](https://docs.aws.amazon.com/sdkref/latest/guide/feature-imds-credentials.html) referência de *ferramentas AWS SDKs e ferramentas*.
1. Se as credenciais ainda não tiverem sido resolvidas nesse ponto, a operação panics com um erro.
Para obter detalhes sobre as configurações do provedor de AWS credenciais, consulte [Provedores de credenciais padronizados](https://docs.aws.amazon.com/sdkref/latest/guide/standardized-credentials.html) na referência de *configurações do Guia de referência AWS * *SDKs de ferramentas*.
## Provedor de credenciais explícito
Em vez de confiar na cadeia de provedores de credenciais para detectar seu método de autenticação, você pode especificar um provedor de credenciais específico a ser utilizado pelo SDK. Ao carregar sua configuração geral usando `aws_config::defaults`, você pode especificar um provedor de credenciais personalizado, conforme mostrado abaixo:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.credentials_provider(MyCredentialsProvider::new())
.load()
.await;
```
Você pode implementar seu próprio provedor de credenciais implementando a característica [https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html](https://docs.rs/aws-credential-types/latest/aws_credential_types/provider/trait.ProvideCredentials.html).
## Armazenamento de identidade em cache
O SDK armazenará em cache as credenciais e outros tipos de identidade, como tokens de SSO. Por padrão, o SDK usa uma implementação de cache lento que carrega as credenciais na primeira solicitação, as armazena em cache e, depois, tenta atualizá-las durante outra solicitação quando elas estão prestes a expirar. Clientes criados com base no mesmo `SdkConfig` compartilharão um [https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html](https://docs.rs/aws-smithy-runtime/latest/aws_smithy_runtime/client/identity/struct.IdentityCache.html).
# Usando versões de comportamento no AWS SDK para Rust
AWS SDK para Rust os desenvolvedores esperam e confiam no comportamento robusto e previsível que a linguagem e suas principais bibliotecas oferecem. Para ajudar os desenvolvedores que usam o SDK para Rust a obter o comportamento esperado, as configurações do cliente devem incluir uma `BehaviorVersion`. A `BehaviorVersion` especifica a versão do SDK cujos padrões são esperados. Isso permite que o SDK evolua com o tempo, alterando as práticas recomendadas para atender aos novos padrões e oferecer suporte a novos recursos sem impacto adverso inesperado no comportamento da aplicação.
**Atenção**
Se você tentar configurar o SDK ou criar um cliente sem especificar explicitamente uma `BehaviorVersion`, o construtor entrará no estado panic.
Por exemplo, imagine que uma nova versão do SDK seja lançada com uma nova política de nova tentativa padrão. Se a aplicação usa uma `BehaviorVersion` que corresponde a uma versão anterior do SDK, essa configuração anterior será usada em vez da nova configuração padrão.
Sempre que uma nova versão comportamental do SDK para Rust é lançada, a `BehaviorVersion` anterior é marcada com o atributo `deprecated` do SDK para Rust e a nova versão é adicionada. Isso faz com que os avisos ocorram em tempo de compilação, mas permite que a compilação continue normalmente. O `BehaviorVersion::latest()` também é atualizado para indicar o comportamento padrão da nova versão.
**nota**
Se seu código não depende de características de comportamento extremamente específicas, você deve usar `BehaviorVersion::latest()` no código ou usar o sinalizador de recurso `behavior-version-latest` no arquivo `Cargo.toml`. Se você estiver escrevendo um código sensível à latência ou que ajusta os comportamentos do SDK do Rust, considere fixa `BehaviorVersion` em uma versão principal específica.
## Definir a versão do comportamento em `Cargo.toml`
Você pode especificar a versão do comportamento do SDK e dos módulos individuais, como `aws-sdk-s3` ou `aws-sdk-iam`, incluindo um sinalizador de recurso apropriado no arquivo `Cargo.toml`. No momento, somente a versão `latest` do SDK é compatível com `Cargo.toml`:
```
[dependencies]
aws-config = { version = "1", features = ["behavior-version-latest"] }
aws-sdk-s3 = { version = "1", features = ["behavior-version-latest"] }
```
## Definir a versão do comportamento no código
Seu código pode alterar a versão do comportamento conforme necessário, especificando-a ao configurar o SDK ou um cliente:
```
let config = aws_config::load_defaults(BehaviorVersion::v2023_11_09()).await;
```
Este exemplo cria uma configuração que usa o ambiente para configurar o SDK, mas define a `BehaviorVersion` como `v2023_11_09()`.
# Configurando novas tentativas no AWS SDK para Rust
O AWS SDK para Rust fornece um comportamento de repetição padrão para solicitações de serviço e opções de configuração personalizáveis. Ligações para retornar Serviços da AWS ocasionalmente exceções inesperadas. Determinados tipos de erros, como erros transitórios ou de controle de utilização, podem ser bem-sucedidos se a chamada for repetida.
O comportamento de repetição pode ser configurado globalmente usando variáveis de ambiente ou configurações no AWS `config` arquivo compartilhado. Para obter informações sobre essa abordagem, consulte o [comportamento de repetição](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) no *Guia de referência de ferramentas AWS SDKs e ferramentas*. Ele também inclui informações detalhadas sobre implementações de estratégias de novas tentativas e como escolher uma em vez da outra.
Como alternativa, essas opções também podem ser configuradas no código, conforme mostrado nas seções a seguir.
## Configuração padrão de novas tentativas
Cada cliente de serviço usa por padrão a configuração de estratégia de novas tentativas `standard` fornecida pela estrutura [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html). Por padrão, uma chamada será tentada três vezes (*a tentativa inicial, mais duas tentativas*). Além disso, cada nova tentativa será adiada por um período curto e aleatório para evitar tempestades de novas tentativas. Essa convenção é adequada para a maioria dos casos de uso, mas pode ser inadequada em circunstâncias específicas, como em sistemas de alto throughput.
Somente alguns tipos de erros são considerados passíveis de nova tentativa pelo. SDKs Exemplos de erros que podem ser repetidos são:
+ tempos limite de soquetes
+ controle de utilização do lado do serviço
+ erros de serviço transitórios, como respostas HTTP 5XX
Os exemplos a seguir **não** podem ser repetidos:
+ Parâmetros ausentes ou inválidos
+ erros de autenticação/segurança
+ exceções de configuração incorreta
É possível personalizar a estratégia `standard` de novas tentativas definindo o máximo de tentativas, atrasos e configuração de recuo.
## Máximo de tentativas
Você pode personalizar o máximo de tentativas em seu código fornecendo uma modificação [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) para `aws_config::defaults`:
```
const CUSTOM_MAX_ATTEMPTS: u32 = 5;
let retry_config = RetryConfig::standard()
// Set max attempts. When max_attempts is 1, there are no retries.
// This value MUST be greater than zero.
// Defaults to 3.
.with_max_attempts(CUSTOM_MAX_ATTEMPTS);
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## Atrasos e recuo
Se uma nova tentativa for necessária, a estratégia de nova tentativa padrão aguarda antes de fazer a tentativa subsequente. O atraso na primeira tentativa é pequeno, mas cresce exponencialmente nas tentativas posteriores. A quantidade máxima de atraso é limitada para não aumentar muito.
A instabilidade aleatória é aplicada aos atrasos em todas as tentativas. A instabilidade ajuda a mitigar o efeito de grandes frotas que podem causar tempestades de novas tentativas. Para uma discussão mais aprofundada sobre recuo exponencial e instabilidade, consulte [Exponential Backoff And Jitter](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) no *blog AWS Architecture*.
Você pode personalizar as configurações de atraso em seu código fornecendo um [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) modificado ao `aws_config::defaults`. O código a seguir define a configuração para atrasar a primeira nova tentativa em até 100 milissegundos e definir que o tempo máximo entre qualquer tentativa seja de 5 segundos.
```
let retry_config = RetryConfig::standard()
// Defaults to 1 second.
.with_initial_backoff(Duration::from_millis(100))
// Defaults to 20 seconds.
.with_max_backoff(Duration::from_secs(5));
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(retry_config)
.load()
.await;
```
## Modo de nova tentativa adaptável
Como alternativa à estratégia de nova tentativa do modo `standard`, a estratégia de nova tentativa do modo `adaptive` é uma abordagem avançada que busca a taxa ideal de solicitações para minimizar os erros de controle de utilização.
**nota**
As novas tentativas adaptáveis são um modo de nova tentativa avançado. Normalmente é recomendável usar esta estratégia. Consulte o [comportamento de repetição](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html#standardvsadaptive) no *Guia de referência de ferramentas AWS SDKs e ferramentas*.
As novas tentativas adaptáveis incluem todos os recursos das novas tentativas padrão. Isso adiciona um limitador de taxa do lado do cliente que mede a taxa de solicitações de controle de utilização em comparação com solicitações sem o controle. Também limita o tráfego para tentar permanecer em uma largura de banda segura, o que, idealmente, não causa nenhum erro de controle de utilização.
A taxa se adapta em tempo real às mudanças nas condições de serviço e nos padrões de tráfego e pode aumentar ou diminuir a taxa de tráfego de acordo. Fundamentalmente, o limitador de taxa pode atrasar as tentativas iniciais em cenários de tráfego intenso.
Você pode selecionar a estratégia `adaptive` de novas tentativas no código fornecendo uma [https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/retry/struct.RetryConfig.html) modificada:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.retry_config(RetryConfig::adaptive())
.load()
.await;
```
# Configurando tempos limite no AWS SDK para Rust
O AWS SDK para Rust fornece várias configurações para gerenciar tempos limite de AWS service (Serviço da AWS) solicitação e fluxos de dados paralisados. Isso ajuda sua aplicação a se comportar de maneira ideal quando ocorrem atrasos e falhas inesperadas na rede.
## Tempos limite da API
Quando há problemas transitórios que podem fazer com que as tentativas de solicitação demorem muito ou falhem completamente, é importante revisar e definir tempos limite a aplicação poder antecipar-se à falha rapidamente e se comportar de maneira ideal. Solicitações que falham podem ser automaticamente repetidas pelo SDK. Uma prática recomendada é definir tempos limite para as tentativas individuais e para toda a solicitação.
O SDK para Rust fornece um tempo limite padrão para estabelecer uma conexão para uma solicitação. O SDK não tem nenhum tempo de espera máximo padrão definido para receber uma resposta para uma tentativa de solicitação ou para toda a solicitação. As seguintes opções de tempo limite estão disponíveis:
| Parâmetro | Valor padrão | Description |
| --- | --- | --- |
| Tempo limite de conexão | 3,1 segundos | O tempo máximo de espera para estabelecer uma conexão antes de desistir. |
| Tempo limite de operação | Nenhum | O tempo máximo de espera antes de receber uma resposta do SDK para Rust, incluindo todas as novas tentativas. |
| Tempo limite de tentativa de operação | Nenhum | O tempo máximo de espera para uma única tentativa de HTTP, após o qual a chamada de API pode ser repetida. |
| Tempo limite de leitura | Nenhum | O tempo máximo de espera para ler o primeiro byte de uma resposta a partir do momento em que a solicitação é iniciada. |
O seguinte exemplo exibe a configuração de um cliente do Amazon S3 com valores de tempo limite personalizados:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.timeout_config(
TimeoutConfig::builder()
.operation_timeout(Duration::from_secs(5))
.operation_attempt_timeout(Duration::from_millis(1500))
.build()
)
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
```
Ao usar os tempos limite de operação e tentativa juntos, você define um limite rígido para o tempo total gasto em todas as novas tentativas. Você também configura uma solicitação HTTP individual para se antecipar à falha rapidamente em uma solicitação lenta.
Como alternativa para definir esses valores de tempo limite no cliente de serviço para todas as operações, você pode configurar ou [substituí-las por uma única solicitação](peroperation.md).
**Importante**
Os tempos limite de operação e tentativa não se aplicam aos dados de streaming consumidos após o SDK para Rust ter retornado uma resposta. Por exemplo, o consumo de dados de um membro do `ByteStream` de uma resposta não está sujeito aos tempos limite de operação.
## Proteção de fluxo paralisado
O SDK para Rust fornece outra forma de tempo limite relacionada à detecção de fluxos paralisados. Um fluxo paralisado é um fluxo de upload ou download que não produz dados por mais do que um período de carência configurado. Isso ajuda a evitar que as aplicações sejam interrompidas indefinidamente e nunca progridam.
A proteção de fluxo paralisado retornará um erro quando um fluxo ficar inativo por mais tempo do que o período aceitável.
Por padrão, o SDK para Rust permite a proteção de streams paralisados para uploads e downloads e procura pelo menos 1% byte/sec da atividade com um generoso período de carência de 20 segundos.
O seguinte exemplo exibe um `StalledStreamProtectionConfig` personalizado que desabilita a proteção de upload e altera o período de carência para nenhuma atividade para 10 segundos:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(
StalledStreamProtectionConfig::enabled()
.upload_enabled(false)
.grace_period(Duration::from_secs(10))
.build()
)
.load()
.await;
```
**Atenção**
A proteção de fluxo paralisado é uma opção de configuração avançada. Recomendamos alterar esses valores somente se a aplicação precisar de um desempenho melhor ou se estiver causando algum outro problema.
### Desabilitar a proteção de fluxo paralisado
O seguinte exemplo mostra como desabilitar completamente a proteção de fluxo parado:
```
let config = aws_config::defaults(BehaviorVersion::latest())
.stalled_stream_protection(StalledStreamProtectionConfig::disabled())
.load()
.await;
```
# Configurar recursos de observabilidade no AWS SDK para Rust
Observabilidade é a medida em que o estado atual de um sistema pode ser identificado com base nos dados que ele emite. Os dados emitidos são chamados, com frequência, de telemetria.
**Topics**
+ [Registro em log](logging.md)
# Configurar e usar o registro em log no AWS SDK para Rust
O AWS SDK para Rust usa a estrutura de [rastreamento](http://tracing.rs/) para registro em log. Para habilitar o registro em log, adicione a caixa `tracing-subscriber` e inicialize-a na aplicação do Rust. Os logs incluem registros de data e hora, níveis de log e caminhos de módulos, ajudando a depurar solicitações de API e comportamento do SDK. Use a variável de ambiente `RUST_LOG` para controlar o detalhamento do log, filtrando por módulo, se necessário.
## Como habilitar o registro em log no AWS SDK para Rust
1. Em um prompt de comando para o diretório do projeto, adicione a caixa [tracing-subscriber](https://crates.io/crates/tracing-subscriber) como uma dependência:
```
$ cargo add tracing-subscriber --features tracing-subscriber/env-filter
```
Isso adiciona a caixa à seção `[dependencies]` do seu arquivo `Cargo.toml`.
1. Inicialize o assinante. Normalmente, isso é feito no início da função `main`, antes de chamar qualquer operação de SDK para Rust:
```
use aws_config::BehaviorVersion;
type BoxError = Box;
#[tokio::main]
async fn main() -> Result<(), BoxError> {
tracing_subscriber::fmt::init(); // Initialize the subscriber.
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
let _resp = s3.list_buckets()
.send()
.await?;
Ok(())
}
```
1. Habilite o registro em log usando a variável de ambiente `RUST_LOG`. Para habilitar a exibição de informações do registro em log, em um prompt de comando, defina a variável de ambiente `RUST_LOG` para o nível em que você deseja registrar. O seguinte exemplo define o nível de registro em log como `debug`:
------
#### [ Linux/macOS ]
```
$ RUST_LOG=debug
```
------
#### [ Windows ]
Se você estiver usando o VSCode, a janela do terminal geralmente usa PowerShell como padrão. Verifique o tipo de prompt que você está usando.
```
C:\> set RUST_LOG=debug
```
------
#### [ PowerShell ]
```
PS C:\> $ENV:RUST_LOG="debug"
```
------
1. Execute o programa:
```
$ cargo run
```
Uma saída adicional na janela do console ou do terminal deve ser exibida.
Para obter mais informações, consulte [filtragem de eventos com variáveis de ambiente](https://docs.rs/tracing-subscriber/0.3.18/tracing_subscriber/fmt/index.html#filtering-events-with-environment-variables) na documentação do `tracing-subscriber`.
## Interpretar a saída do log
Após habilitar o registro em log seguindo as etapas da seção anterior, as informações adicionais de log serão impressas de forma padronizada por padrão.
Se você estiver usando o formato de saída de log padrão (chamado de “completo” pelo módulo de rastreamento), as informações que você vê na saída do log serão semelhantes a estas:
```
2024-06-25T16:10:12.367482Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt:lazy_load_identity: aws_smithy_runtime::client::identity::cache::lazy: identity cache miss occurred; added new identity (took 480.892ms) new_expiration=2024-06-25T23:07:59Z valid_for=25066.632521s partition=IdentityCachePartition(7)
2024-06-25T16:10:12.367602Z DEBUG invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::identity::cache::lazy: loaded identity
2024-06-25T16:10:12.367643Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: resolved identity identity=Identity { data: Credentials {... }, expiration: Some(SystemTime { tv_sec: 1719356879, tv_nsec: 0 }) }
2024-06-25T16:10:12.367695Z TRACE invoke{service=s3 operation=ListBuckets sdk_invocation_id=3434933}:try_op:try_attempt: aws_smithy_runtime::client::orchestrator::auth: signing request
```
Cada entrada inclui o seguinte:
+ O carimbo de data/hora da entrada do log.
+ O nível de log da entrada. É uma palavra como `INFO`, `DEBUG` ou `TRACE`.
+ O conjunto aninhado de [extensões](https://docs.rs/tracing/latest/tracing/span/index.html) a partir das quais a entrada do log foi gerada, separados por dois pontos (“:”). Isso ajuda você a identificar a origem da entrada de log.
+ O caminho do módulo do Rust que contém o código que gerou a entrada de log.
+ O texto da mensagem de log.
Os formatos de saída padrão do módulo de rastreamento usam códigos de escape ANSI para colorir a saída. Lembre-se dessas sequências de escape ao filtrar ou pesquisar a saída.
**nota**
O `sdk_invocation_id` que aparece no conjunto aninhado de extensões é um ID exclusivo gerado no lado do cliente pelo SDK para ajudar a correlacionar as mensagens de log. Ele não está relacionado ao ID da solicitação encontrado na resposta de um AWS service (Serviço da AWS).
## Ajustar os níveis de registro em log
Se você usar uma caixa que ofereça suporte a uma filtragem de ambiente, como `tracing_subscriber`, é possível controlar o detalhamento dos logs por módulo.
Você pode habilitar o mesmo nível de registro em log para cada módulo. O seguinte define o nível de registro em log para `trace` em cada módulo:
```
$ RUST_LOG=trace cargo run
```
Você pode habilitar o registro em log em nível de rastreamento em um módulo específico. No exemplo a seguir, somente os logs provenientes de `aws_smithy_runtime` entrarão no nível `trace`.
```
$ RUST_LOG=aws_smithy_runtime=trace
```
É possível especificar um nível de log diferente para vários módulos separando-os por vírgulas. O exemplo a seguir define o módulo `aws_smithy_runtime` para o nível `debug` de registro em log, e o módulo `aws_config` para o nível `trace` de registro em log.
```
$ RUST_LOG=aws_config=trace,aws_smithy_runtime=debug cargo run
```
A seguinte tabela descreve alguns dos módulos que você pode usar para filtrar mensagens de log:
| Prefixo | Descrição |
| --- | --- |
| `aws_smithy_runtime` | Registro em log de conexões de solicitações e respostas |
| `aws_config` | Carregamento de credenciais |
| `aws_sigv4` | Solicitar assinatura e solicitações canônicas |
Uma maneira de descobrir quais módulos você precisa incluir na saída do log é primeiro registrar tudo e, em seguida, encontrar o nome da caixa na saída do log para obter as informações necessárias. Em seguida, você pode definir a variável de ambiente de acordo e executar o programa novamente.
# Configurando endpoints do cliente no AWS SDK para Rust
Quando ele AWS SDK para Rust chama um AWS service (Serviço da AWS), uma de suas primeiras etapas é determinar para onde encaminhar a solicitação. O processo é conhecido como resolução de endpoint.
Você pode configurar a resolução de endpoint para o SDK ao criar um cliente de serviço. A configuração padrão para resolução de endpoints geralmente é boa, mas há vários motivos pelos quais você pode querer modificar a configuração padrão. Estes são dois exemplos de motivos:
+ Para fazer solicitações para uma versão de pré-lançamento de um serviço ou para uma implantação local de um serviço.
+ Para acessar recursos de serviço específicos ainda não modelados no SDK.
**Atenção**
A resolução de endpoints é um tópico avançado do SDK. Se você alterar as configurações padrão, corre o risco de quebrar seu código. As configurações padrão se aplicam à maioria dos usuários em ambientes de produção.
Os endpoints personalizados podem ser definidos globalmente para que sejam usados em todas as solicitações de serviço, ou você pode definir um endpoint personalizado para um específico. AWS service (Serviço da AWS)
Os endpoints personalizados podem ser configurados usando variáveis de ambiente ou configurações no AWS `config` arquivo compartilhado. Para obter informações sobre essa abordagem, consulte [Endpoints específicos do serviço](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html) no Guia de referência de *ferramentas AWS SDKs e ferramentas*. Para obter a lista completa de configurações de `config` arquivos compartilhados e variáveis de ambiente para todos Serviços da AWS, consulte [Identificadores para endpoints específicos do serviço](https://docs.aws.amazon.com/sdkref/latest/guide/ss-endpoints-table.html).
Como alternativa, essa personalização também pode ser configurada no código, conforme mostrado nas seções a seguir.
## Configuração personalizada
Você pode personalizar a resolução do endpoint de um cliente de serviço com dois métodos que estão disponíveis ao criar o cliente:
1. `endpoint_url(url: Into)`
1. `endpoint_resolver(resolver: impl crate::config::endpoint::ResolveEndpoint + `static)`
Você pode definir ambas as propriedades. No entanto, na maioria das vezes você fornece apenas um. Para uso geral, o `endpoint_url` é personalizado com mais frequência.
### Configurar URL do endpoint
Você pode definir um valor para `endpoint_url` para indicar um nome de host “base” para o serviço. Esse valor, no entanto, não é final, pois é passado como parâmetro para a instância `ResolveEndpoint` do cliente. A implementação `ResolveEndpoint` pode então inspecionar e potencialmente modificar esse valor para determinar o endpoint final.
### Definir o endpoint do resolvedor
A implementação `ResolveEndpoint` de um cliente de serviço determina o endpoint final resolvido que o SDK usa para qualquer solicitação específica. Um cliente de serviço chama o método `resolve_endpoint` para cada solicitação e usa o valor [https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/endpoint/struct.EndpointFuture.html) retornado pelo resolvedor sem mais alterações.
O exemplo a seguir demonstra o fornecimento de uma implementação personalizada de resolvedor de endpoint para um cliente do Amazon S3 que resolve um endpoint diferente por estágio, como preparação e produção:
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug)]
struct StageResolver { stage: String }
impl ResolveEndpoint for StageResolver {
fn resolve_endpoint(&self, params: &Params) -> EndpointFuture<'_> {
let stage = &self.stage;
EndpointFuture::ready(Ok(Endpoint::builder().url(format!("{stage}.myservice.com")).build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
let resolver = StageResolver { stage: std::env::var("STAGE").unwrap() };
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(resolver)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
**nota**
Os resolvedores de endpoint e, por extensão, a característica `ResolveEndpoint`, são específicos para cada serviço e, portanto, só podem ser configurados na configuração do cliente de serviço. O URL do endpoint, por outro lado, pode ser configurado usando configuração compartilhada (aplicável a todos os serviços derivados dela) ou para um serviço específico.
#### ResolveEndpoint parâmetros
O método `resolve_endpoint` aceita parâmetros específicos do serviço que contêm propriedades usadas na resolução de endpoints.
Cada serviço inclui as seguintes propriedades de base:
| Nome | Tipo | Description |
| --- | --- | --- |
| region | String | Do cliente Região da AWS |
| endpoint | String | Uma representação de string conjunto de valores de endpointUrl |
| use\$1fips | Booleano | Se os endpoints FIPS estiverem habilitados na configuração do cliente |
| use\$1dual\$1stack | Booleano | Se os endpoints de pilha dupla estiverem habilitados na configuração do cliente |
Serviços da AWS pode especificar propriedades adicionais necessárias para a resolução. Por exemplo, os [parâmetros de endpoint](https://docs.rs/aws-sdk-s3/latest/aws_sdk_s3/config/endpoint/struct.Params.html) do Amazon S3 incluem o nome do bucket e também várias configurações de recursos específicos do Amazon S3. Por exemplo, a propriedade `force_path_style` determina se o endereço do host virtual pode ser usado.
Se você implementar seu próprio provedor, não precisará construir sua própria instância de parâmetros de endpoint. O SDK fornece as propriedades de cada solicitação e as passa para sua implementação do `resolve_endpoint`.
### Compare o uso de `endpoint_url` com o uso de `endpoint_resolver`
É importante entender que as duas configurações a seguir, uma que usa `endpoint_url` e outra que usa `endpoint_resolver`, NÃO produzem clientes com comportamento de resolução de endpoint equivalente.
```
use aws_sdk_s3::config::endpoint::{ResolveEndpoint, EndpointFuture, Params, Endpoint};
#[derive(Debug, Default)]
struct CustomResolver;
impl ResolveEndpoint for CustomResolver {
fn resolve_endpoint(&self, _params: &Params) -> EndpointFuture<'_> {
EndpointFuture::ready(Ok(Endpoint::builder().url("https://endpoint.example").build()))
}
}
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// use endpoint url
aws_sdk_s3::config::Builder::from(&config)
.endpoint_url("https://endpoint.example")
.build();
// Use endpoint resolver
aws_sdk_s3::config::Builder::from(&config)
.endpoint_resolver(CustomResolver::default())
.build();
```
O cliente que define o `endpoint_url` especifica um URL de *base* passado para o provedor (padrão), que pode ser modificado como parte da resolução do endpoint.
O cliente que define o `endpoint_resolver` especifica o URL *final* que o cliente do Amazon S3 usa.
## Exemplos
Os endpoints personalizados são frequentemente usados para testes. Em vez de fazer chamadas para o serviço baseado em nuvem, as chamadas são roteadas para um serviço simulado hospedado localmente. Duas dessas opções são:
+ [DynamoDB local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html): uma versão local do serviço Amazon DynamoDB.
+ [LocalStack](https://github.com/localstack/localstack)— um emulador de serviços em nuvem que é executado em um contêiner em sua máquina local.
Os exemplos a seguir ilustram duas maneiras diferentes de especificar um endpoint personalizado para usar essas duas opções de teste.
### Use o DynamoDB local diretamente no código
Conforme descrito nas seções anteriores, você pode definir o `endpoint_url` diretamente no código para substituir o endpoint de base para apontar para o servidor local do DynamoDB. No seu código:
```
let config = aws_config::defaults(aws_config::BehaviorVersion::latest())
.test_credentials()
// DynamoDB run locally uses port 8000 by default.
.endpoint_url("http://localhost:8000")
.load()
.await;
let dynamodb_local_config = aws_sdk_dynamodb::config::Builder::from(&config).build();
let client = aws_sdk_dynamodb::Client::from_conf(dynamodb_local_config);
```
O [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/dynamodb/src/bin/list-tables-local.rs) está disponível em GitHub.
### Use LocalStack usando o `config` arquivo
Você pode definir [endpoints específicos do serviço](https://docs.aws.amazon.com/sdkref/latest/guide/feature-ss-endpoints.html) em seu arquivo compartilhado. AWS `config` O perfil de configuração a seguir define `endpoint_url` para conexão com `localhost` na porta `4566`. Para obter mais informações sobre LocalStack configuração, consulte [Acesso LocalStack por meio da URL do endpoint no site](https://docs.localstack.cloud/references/network-troubleshooting/endpoint-url/) de *LocalStackdocumentos.*
```
[profile localstack]
region=us-east-1
endpoint_url = http://localhost:4566
```
O SDK coletará as alterações no arquivo `config` compartilhado e as aplicará aos seus clientes do SDK quando você usar o perfil `localstack`. Usando essa abordagem, seu código não precisa incluir nenhuma referência aos endpoints e teria a seguinte aparência:
```
// set the environment variable `AWS_PROFILE=localstack` when running
// the application to source `endpoint_url` and point the SDK at the
// localstack instance
let config = aws_config::defaults(BehaviorVersion::latest()).load().await;
let s3_config = aws_sdk_s3::config::Builder::from(&config)
.force_path_style(true)
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_config);
```
O [exemplo completo](https://github.com/awsdocs/aws-doc-sdk-examples/tree/main/rustv1/examples/localstack) está disponível em GitHub.
# Substituindo uma única configuração de operação de um cliente no AWS SDK para Rust
Após [criar um cliente de serviço](config-code.md), a configuração se torna imutável e será aplicada a todas as operações subsequentes. Embora a configuração não possa ser modificada neste momento, ela pode ser substituída com base na operação.
Cada construtor de operações tem um método `customize` disponível para criar um `CustomizableOperation` para que você possa substituir uma cópia individual da configuração existente. A configuração original do cliente permanecerá inalterada.
O exemplo a seguir mostra a criação de um cliente do Amazon S3 que chama duas operações, a segunda das quais é substituída para ser enviada para outra Região da AWS. Todas as invocações de objetos do Amazon S3 usam a região `us-east-1`, exceto quando a chamada de API é explicitamente substituída para usar a `us-west-2` modificada.
```
use aws_config::{BehaviorVersion, Region};
let config = aws_config::defaults(BehaviorVersion::latest())
.region("us-east-1")
.load()
.await;
let s3 = aws_sdk_s3::Client::new(&config);
// Request will be sent to "us-east-1"
s3.list_buckets()
.send()
.await?;
// Unset fields default to using the original config value
let modified = aws_sdk_s3::Config::builder()
.region(Region::from_static("us-west-2"));
// Request will be sent to "us-west-2"
s3.list_buckets()
// Creates a CustomizableOperation
.customize()
.config_override(modified)
.send()
.await?;
```
**nota**
O exemplo anterior é para o Amazon S3, mas o conceito é o mesmo para todas as operações. Certas operações podem ter métodos adicionais em `CustomizeableOperation`.
Para obter um exemplo de adição de um interceptor usando o `customize` para uma única operação, consulte [Interceptor apenas para uma operação específica](interceptors.md#interceptors-registration-specific).
# Definindo configurações de nível HTTP dentro do SDK para Rust AWS
O AWS SDK para Rust fornece a funcionalidade HTTP integrada que é usada pelos AWS service (Serviço da AWS) clientes que você cria em seu código.
Por padrão, o SDK para Rust usa um cliente HTTPS baseado em `hyper`, `rustls` e `aws-lc-rs`. Esse cliente deve funcionar bem na maioria dos casos de uso sem configuração adicional.
+ [https://docs.rs/hyper/latest/hyper/](https://docs.rs/hyper/latest/hyper/)é uma biblioteca HTTP de nível inferior para Rust que pode ser usada com o AWS SDK para Rust para fazer chamadas de serviço de API.
+ [https://github.com/rustls/rustls](https://github.com/rustls/rustls) é uma biblioteca TLS moderna escrita em Rust que tem opções integradas para provedores criptográficos.
+ [https://github.com/aws/aws-lc](https://github.com/aws/aws-lc) é uma biblioteca criptográfica de uso geral com algoritmos necessários para TLS e aplicações comuns.
+ [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) é um wrapper idiomático da biblioteca `aws-lc` em Rust.
A caixa `aws-smithy-http-client` fornece algumas opções e configurações adicionais se você quiser escolher um provedor TLS ou criptográfico diferente. Para casos de uso mais avançados, recomendamos que você traga sua própria implementação de cliente HTTP ou envie uma solicitação de recurso para consideração.
## Escolher um provedor de TLS alternativo
A caixa `aws-smithy-http-client` fornece alguns provedores alternativos de TLS.
Os seguintes provedores estão disponíveis:
**`rustls` com `aws-lc`**
Um provedor de TLS baseado em [https://github.com/rustls/rustls](https://github.com/rustls/rustls) usa [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) para criptografia.
Esse é o comportamento HTTP padrão para o SDK para Rust. Se você quiser usar essa opção, você não precisa realizar nenhuma ação adicional em seu código.
**`s2n-tls`**
Um provedor de TLS baseado em [https://github.com/aws/s2n-tls](https://github.com/aws/s2n-tls).
**`rustls` com `aws-lc-fips`**
Um provedor de TLS baseado em [https://github.com/rustls/rustls](https://github.com/rustls/rustls) usa uma versão compatível com FIPS do [https://github.com/aws/aws-lc-rs](https://github.com/aws/aws-lc-rs) para criptografia
**`rustls` com `ring`**
Um provedor de TLS baseado em [https://github.com/rustls/rustls](https://github.com/rustls/rustls) usa [https://github.com/briansmith/ring](https://github.com/briansmith/ring) para criptografia.
### Pré-requisitos
Usar `aws-lc-rs` ou `s2n-tls` exige um compilador C (Clang ou GCC) para compilação. Para algumas plataformas, a compilação também pode exigir CMake. Construir com o recurso “fips” em qualquer plataforma requer CMake e pronto. Para obter mais informações, consulte o repositório [AWS Libcrypto for Rust (`aws-lc-rs`)](https://github.com/aws/aws-lc-rs/blob/main/aws-lc-rs/README.md) e as instruções de compilação.
### Como usar um provedor de TLS alternativo
A caixa `aws-smithy-http-client` fornece opções adicionais de TLS. Para que seus clientes do AWS service (Serviço da AWS) usem um provedor TLS diferente, substitua o `http_client` usando o carregador da caixa `aws_config`. O cliente HTTP é usado para provedores de Serviços da AWS e credenciais.
O exemplo a seguir mostra como usar a o provedor TLS `s2n-tls`. No entanto, uma abordagem semelhante também funciona para outros fornecedores.
Para compilar o código de exemplo, execute o seguinte comando para adicionar dependências ao seu projeto:
```
cargo add aws-smithy-http-client -F s2n-tls
```
Código de exemplo:
```
use aws_smithy_http_client::{tls, Builder};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::S2nTls)
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## Habilitar o suporte a FIPS
A caixa `aws-smithy-http-client` oferece uma opção para habilitar uma implementação de criptografia compatível com FIPS. Para que seus AWS service (Serviço da AWS) clientes usem o provedor compatível com FIPS, substitua o `http_client` uso do carregador da caixa. `aws_config` O cliente HTTP é usado tanto para provedores de credenciais Serviços da AWS quanto para provedores de credenciais.
**nota**
O suporte ao FIPS requer dependências adicionais em seu ambiente de compilação. Veja as instruções de [compilação](https://github.com/aws/aws-lc/blob/main/BUILDING.md) da caixa `aws-lc`.
Para compilar o código de exemplo, execute o seguinte comando para adicionar dependências ao seu projeto:
```
cargo add aws-smithy-http-client -F rustls-aws-lc-fips
```
O código de exemplo a seguir habilita o suporte ao FIPS:
```
// file: main.rs
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder,
};
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLcFips))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
## Priorizar a troca de chaves pós-quântica
O provedor TLS padrão é baseado no `rustls` usando `aws-lc-rs`, o que oferece suporte ao algoritmo de troca de chaves pós-quântica `X25519MLKEM768`. Para fazer do `X25519MLKEM768` o algoritmo de maior prioridade, você precisa adicionar o pacote `rustls` à sua caixa e ativar o sinalizador de recursos `prefer-post-quantum`. Caso contrário, ele está disponível, mas não com a prioridade mais alta. Consulte a [Documentação do `rustls`](https://docs.rs/rustls/0.23.23/rustls/manual/_05_defaults/index.html#about-the-post-quantum-secure-key-exchange-x25519mlkem768) para obter mais informações.
**nota**
Esse sinalizador se tornará o padrão em uma versão futura.
## Substituir o resolvedor de DNS
O resolvedor de DNS padrão pode ser substituído configurando o cliente HTTP manualmente.
Para compilar o código de exemplo, execute os seguintes comandos para adicionar dependências ao seu projeto:
```
cargo add aws-smithy-http-client -F rustls-aws-lc
cargo add aws-smithy-runtime-api -F client
```
O código de exemplo a seguir substitui o resolvedor de DNS:
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use aws_smithy_runtime_api::client::dns::{DnsFuture, ResolveDns};
use std::net::{IpAddr, Ipv4Addr};
/// A DNS resolver that returns a static IP address (127.0.0.1)
#[derive(Debug, Clone)]
struct StaticResolver;
impl ResolveDns for StaticResolver {
fn resolve_dns<'a>(&'a self, _name: &'a str) -> DnsFuture<'a> {
DnsFuture::ready(Ok(vec![IpAddr::V4(Ipv4Addr::new(127, 0, 0, 1))]))
}
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.build_with_resolver(StaticResolver);
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
**nota**
Por padrão, o Amazon Linux 2023 (AL2023) não armazena em cache o DNS no nível do sistema operacional.
## Personalizar certificados CA raiz
Por padrão, o provedor TLS carrega os certificados raiz nativos do sistema para a plataforma em questão. Para personalizar esse comportamento para carregar um pacote de CA personalizado, você pode configurar um `TlsContext` com o seu próprio `TrustStore`.
Para compilar o código de exemplo, execute os seguintes comandos para adicionar dependências ao seu projeto:
```
cargo add aws-smithy-http-client -F rustls-aws-lc
```
O exemplo a seguir usa `rustls` com `aws-lc`, mas funcionará para qualquer provedor de TLS compatível:
```
use aws_smithy_http_client::{
tls::{self, rustls_provider::CryptoMode},
Builder
};
use std::fs;
/// read the PEM encoded root CA (bundle) and return a custom TLS context
fn tls_context_from_pem(filename: &str) -> tls::TlsContext {
let pem_contents = fs::read(filename).unwrap();
// Create a new empty trust store (this will not load platform native certificates)
let trust_store = tls::TrustStore::empty()
.with_pem_certificate(pem_contents.as_slice());
tls::TlsContext::builder()
.with_trust_store(trust_store)
.build()
.expect("valid TLS config")
}
#[tokio::main]
async fn main() {
let http_client = Builder::new()
.tls_provider(tls::Provider::Rustls(CryptoMode::AwsLc))
.tls_context(tls_context_from_pem("my-custom-ca.pem"))
.build_https();
let sdk_config = aws_config::defaults(
aws_config::BehaviorVersion::latest()
)
.http_client(http_client)
.load()
.await;
// create client(s) using sdk_config
// e.g. aws_sdk_s3::Client::new(&sdk_config);
}
```
# Configurando interceptores no AWS SDK para Rust
Você pode usar interceptores para se conectar à execução de solicitações e respostas de API. Os interceptores são mecanismos abertos nos quais o SDK chama o código que você grava para injetar comportamento no ciclo de vida. request/response Dessa forma, você pode modificar uma solicitação em andamento, depurar o processamento da solicitação, ver erros e muito mais.
O seguinte exemplo mostra um interceptor simples que adiciona um cabeçalho adicional a todas as solicitações de saída antes que o loop de repetição seja inserido:
```
use std::borrow::Cow;
use aws_smithy_runtime_api::client::interceptors::{
Intercept,
context::BeforeTransmitInterceptorContextMut,
};
use aws_smithy_runtime_api::client::runtime_components::RuntimeComponents;
use aws_smithy_types::config_bag::ConfigBag;
use aws_smithy_runtime_api::box_error::BoxError;
#[derive(Debug)]
struct AddHeaderInterceptor {
key: Cow<'static, str>,
value: Cow<'static, str>,
}
impl AddHeaderInterceptor {
fn new(key: &'static str, value: &'static str) -> Self {
Self {
key: Cow::Borrowed(key),
value: Cow::Borrowed(value),
}
}
}
impl Intercept for AddHeaderInterceptor {
fn name(&self) -> &'static str {
"AddHeader"
}
fn modify_before_retry_loop(
&self,
context: &mut BeforeTransmitInterceptorContextMut<'_>,
_runtime_components: &RuntimeComponents,
_cfg: &mut ConfigBag,
) -> Result<(), BoxError> {
let headers = context.request_mut().headers_mut();
headers.insert(self.key.clone(), self.value.clone());
Ok(())
}
}
```
Para obter mais informações e os hooks interceptores disponíveis, consulte a característica [Intercept](https://docs.rs/aws-smithy-runtime-api/latest/aws_smithy_runtime_api/client/interceptors/trait.Intercept.html).
## Registro de interceptor
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.
### Interceptor para todas as operações em um cliente de serviço
Para registrar um interceptor para todo o cliente, adicione o interceptor usando o padrão `Builder`.
```
let config = aws_config::defaults(BehaviorVersion::latest())
.load()
.await;
// All service operations invoked using 's3' will have the header added.
let s3_conf = aws_sdk_s3::config::Builder::from(&config)
.interceptor(AddHeaderInterceptor::new("x-foo-version", "2.7"))
.build();
let s3 = aws_sdk_s3::Client::from_conf(s3_conf);
```
### Interceptor apenas para uma operação específica
Para registrar um interceptor para apenas uma única operação, use a extensão `customize`. Você pode substituir as configurações do seu cliente de serviço no nível por operação usando esse método. Para obter mais informações sobre operações personalizáveis, consulte [Substituindo uma única configuração de operação de um cliente no AWS SDK para Rust](peroperation.md).
```
// Only the list_buckets operation will have the header added.
s3.list_buckets()
.customize()
.interceptor(AddHeaderInterceptor::new("x-bar-version", "3.7"))
.send()
.await?;
```