Configuração de endpoints de cliente no AWS SDK for Java 2.x

O SDK para Java 2.x fornece várias maneiras de configurar os endpoints de serviço. Um endpoint é o URL que o SDK usa para fazer chamadas de API para Serviços da AWS. Por padrão, o SDK determina automaticamente o endpoint apropriado para cada serviço com base na Região da AWS que você configurou. No entanto, há cenários em que talvez seja necessário personalizar ou substituir esses endpoints:

Opções de configuração do endpoint

O AWS SDK for Java 2.x oferece várias maneiras de configurar endpoints:

Configuração do endpoint no código

Usar o endpointOverride

A forma mais direta de configurar um endpoint é usando o método endpointOverride no compilador do cliente de serviço. Esse método aceita um objeto URI que representa o URL personalizado do endpoint.

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import java.net.URI;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .endpointOverride(URI.create("https://my-custom-s3-endpoint.example.com"))
        .build();
                

Ao usar o endpointOverride, você ainda deve especificar uma região para o cliente, mesmo que o endpoint esteja sendo definido explicitamente. A região é usada para assinar solicitações.

Descoberta de endpoint

Alguns Serviços da AWS permitem descoberta de endpoints, em que o SDK pode descobrir automaticamente o endpoint ideal a ser usado. É possível habilitar ou desabilitar esse recurso usando o método endpointDiscoveryEnabled no compilador do cliente de serviço.

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .region(Region.US_WEST_2)
        .endpointDiscoveryEnabled(true)
        .build();
                

Configuração do endpoint no nível de solicitação

Em alguns casos, talvez seja necessário substituir o endpoint de uma solicitação específica enquanto usa o mesmo cliente para outras solicitações com o endpoint padrão. O AWS SDK for Java 2.x viabiliza isso por meio de substituições de solicitações.

import software.amazon.awssdk.core.SdkRequest;
import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.model.GetObjectRequest;
import software.amazon.awssdk.http.SdkHttpRequest;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .build();

// Create a request
GetObjectRequest getObjectRequest = GetObjectRequest.builder()
        .bucket("amzn-s3-demo-bucket")
        .key("my-key")
        .overrideConfiguration(c -> c.putHeader("Host", "custom-endpoint.example.com"))
        .build();

// Execute the request with the custom endpoint
s3.getObject(getObjectRequest);
            

Observe que as substituições de endpoint no nível da solicitação são limitadas e podem não funcionar em todos os serviços ou cenários. Na maioria dos casos, é recomendável usar a configuração do endpoint no nível do cliente.

Configuração de endpoint externa

Usar variáveis de ambiente

É possível configurar endpoints usando variáveis de ambiente. O SDK permite a configuração do endpoint específico do serviço por meio de variáveis de ambiente no formato AWS_ENDPOINT_URL_[SERVICE], em que [SERVICE] é o identificador de serviço em maiúsculas.

# For Linux/macOS
export AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com

# For Windows
set AWS_ENDPOINT_URL_S3=https://my-custom-s3-endpoint.example.com
                

Você também pode definir um prefixo ou sufixo de URL de endpoint global usando as seguintes variáveis de ambiente:

Usar as propriedades do sistema de JVM

Você também pode configurar endpoints usando as propriedades do sistema de JVM. O formato é semelhante às variáveis de ambiente, mas usa uma convenção de nomenclatura diferente.

java -Daws.endpointUrl.s3=https://my-custom-s3-endpoint.example.com -jar your-application.jar
                

A configuração do endpoint global também está disponível por meio das propriedades do sistema:

Usar o arquivo de configuração compartilhado da AWS

O AWS SDK for Java 2.x também permite a configuração do endpoint por meio do arquivo de configuração compartilhado da AWS, normalmente localizado em ~/.aws/config (Linux/macOS) ou %USERPROFILE%\.aws\config (Windows). Consulte informações e exemplos no Guia de referência de AWS SDKs e ferramentas.

Precedência de configuração

Quando várias configurações do endpoint estão presentes, o SDK segue essa ordem de precedência (da maior para a menor):

Configuração do endpoint específico do serviço

Alguns Serviços da AWS têm opções adicionais de configuração do endpoint específicas desse serviço. Veja a seguir alguns exemplos:

Configurações do endpoint do Amazon S3

O Amazon S3 permite várias configurações do endpoint por meio da classe S3Configuration:

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.s3.S3Client;
import software.amazon.awssdk.services.s3.S3Configuration;

S3Client s3 = S3Client.builder()
        .region(Region.US_WEST_2)
        .serviceConfiguration(S3Configuration.builder()
                .accelerateModeEnabled(true)
                .dualstackEnabled(true)
                .pathStyleAccessEnabled(false)
                .fipsModeEnabled(true)
                .build())
        .build();
                

Configuração do endpoint do DynamoDB

Para o DynamoDB, talvez você queira usar a descoberta de endpoints ou conectar-se ao DynamoDB local para testes:

import software.amazon.awssdk.regions.Region;
import software.amazon.awssdk.services.dynamodb.DynamoDbClient;
import java.net.URI;

DynamoDbClient dynamoDb = DynamoDbClient.builder()
        .endpointOverride(URI.create("http://localhost:8000"))
        // The region is meaningless for DynamoDB local but required for the client builder.
        .region(Region.US_WEST_2)
        .build();
                

O DynamoDB também permite o uso de endpoints baseados em contas, que você pode configurar no código ou usando configurações externas. O exemplo a seguir mostra como desabilitar o uso de endpoints baseados em conta no código ao criar o cliente (as configurações padrão são preferenciais):

DynamoDbClient dynamoDbClient = DynamoDbClient.builder()
    .region(Region.US_EAST_1)
    .accountIdEndpointMode(AccountIdEndpointMode.DISABLED)
    .build();

Práticas recomendadas

Ao configurar endpoints no AWS SDK for Java 2.x, considere estas práticas recomendadas: