Configurando endpoints do cliente no AWS SDK for Java 2.x

O SDK for Java 2.x fornece várias maneiras de configurar endpoints de serviço. Um endpoint é a URL que o SDK usa para fazer chamadas de API. Serviços da AWS Por padrão, o SDK determina automaticamente o endpoint apropriado para cada serviço com base no que Região da AWS 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

AWS SDK for Java 2.x Ele fornece várias maneiras de configurar endpoints:

Configuração de endpoint em código

Usar o endpointOverride

A maneira mais direta de configurar um endpoint é usando o endpointOverride método no construtor do cliente de serviço. Esse método aceita um URI objeto que representa a URL personalizada 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 usarendpointOverride, 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 oferecem suporte à descoberta de endpoints, em que o SDK pode descobrir automaticamente o endpoint ideal a ser usado. Você pode ativar ou desativar esse recurso usando o endpointDiscoveryEnabled método no construtor 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 de endpoint em 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 suporta 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("my-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 de endpoint no nível do cliente.

Configuração de endpoint externo

Usar variáveis de ambiente do

Você pode configurar endpoints usando variáveis de ambiente. O SDK oferece suporte à configuração de endpoint específico do serviço por meio de variáveis de ambiente no formatoAWS_ENDPOINT_URL_[SERVICE], onde [SERVICE] está 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:

Usando propriedades do sistema JVM

Você também pode configurar endpoints usando as propriedades do sistema 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 global do endpoint também está disponível por meio das propriedades do sistema:

Usando o arquivo de AWS configuração compartilhado

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

Precedência de configuração

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

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

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

Configuração do endpoint Amazon S3

O Amazon S3 oferece suporte a várias configurações de endpoints 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 suporta o uso de endpoints baseados em contas, que você pode configurar em código ou usando configurações externas. O exemplo a seguir mostra como desativar o uso de endpoints baseados em conta no código ao criar o cliente (as configurações padrão são preferidas):

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 melhores práticas: