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 endpoints de cliente no AWS SDK para Rust

Quando o AWS SDK para Rust chama um AWS service (Serviço da AWS), uma das 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:

Os endpoints personalizados podem ser definidos globalmente para uso em todas as solicitações de serviço, ou você pode definir um endpoint personalizado para um AWS service (Serviço da AWS) específico.

Os endpoints personalizados podem ser configurados usando variáveis de ambiente ou configurações no arquivo compartilhado AWS config. Para obter informações sobre essa abordagem, consulte Service-specific endpoints no AWS SDKs and Tools Reference Guide. Para ver a lista completa de configurações do arquivo config compartilhado e variáveis de ambiente para todos os Serviços da AWS, consulte Identifiers for service-specific endpoints.

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:

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 EndpointFuture 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);

Parâmetros do ResolveEndpoint

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:

O Serviços da AWS poderá especificar propriedades adicionais necessárias para a resolução. Por exemplo, os parâmetros de endpoint 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:

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 está disponível no GitHub.

Use o LocalStack usando o arquivo config

Você pode definir endpoints específicos do serviço em seu arquivo AWS config compartilhado. O perfil de configuração a seguir define endpoint_url para conexão com localhost na porta 4566. Para obter mais informações sobre a configuração do LocalStack, consulte Accessing LocalStack via the endpoint URL no site de documentos do LocalStack.

[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 está disponível no GitHub.