AWS SDK for Java 2.x에서 클라이언트 엔드포인트 구성 - AWS SDK for Java 2.x
엔드포인트 구성 옵션코드 내 엔드포인트 구성요청 수준 엔드포인트 구성외부 엔드포인트 구성구성 우선 순위서비스별 엔드포인트 구성모범 사례

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS SDK for Java 2.x에서 클라이언트 엔드포인트 구성

SDK for Java 2.x는 서비스 엔드포인트를 구성하는 다양한 방법을 제공합니다. 엔드포인트는 SDK가 AWS 서비스에 대한 API 호출을 만드는 데 사용되는 URL입니다. 기본적으로 SDK는 구성한 AWS 리전에 따라 각 서비스에 적절한 엔드포인트를 자동으로 결정합니다. 그러나 이러한 엔드포인트를 사용자 지정하거나 재정의해야 하는 시나리오가 있습니다.

  • 로컬 또는 서드 파티 서비스 구현 작업(예: LocalStack)

  • 프록시 또는 VPC 엔드포인트를 통해 AWS 서비스에 연결

  • 베타 또는 시험판 서비스 엔드포인트에 대한 테스트

엔드포인트 구성 옵션

AWS SDK for Java 2.x는 엔드포인트를 구성하는 몇 가지 방법을 제공합니다.

  • 서비스 클라이언트 빌더를 사용한 코드 내 구성

  • 환경 변수를 사용한 외부 구성

  • JVM 시스템 속성을 사용한 외부 구성

  • 공유 AWS 구성 파일을 사용한 외부 구성

코드 내 엔드포인트 구성

endpointOverride 사용하기

엔드포인트를 구성하는 가장 직접적인 방법은 서비스 클라이언트 빌더에서 endpointOverride 메서드를 사용하는 것입니다. 이 메서드는 사용자 지정 엔드포인트 URL을 나타내는 URI 객체를 허용합니다.

예 Amazon S3 클라이언트에 대한 사용자 지정 엔드포인트 설정

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

endpointOverride를 사용할 때 엔드포인트가 명시적으로 설정되더라도 클라이언트의 리전을 지정해야 합니다. 리전은 요청에 서명하는 데 사용됩니다.

엔드포인트 검색

일부 AWS 서비스는 SDK가 사용할 최적의 엔드포인트를 자동으로 검색할 수 있는 엔드포인트 검색을 지원합니다. 서비스 클라이언트 빌더에서 endpointDiscoveryEnabled 메서드를 사용하여 이 기능을 사용하거나 사용 해제할 수 있습니다.

예 DynamoDB 클라이언트에 대한 엔드포인트 검색 사용

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

요청 수준 엔드포인트 구성

경우에 따라 기본 엔드포인트가 있는 다른 요청에 동일한 클라이언트를 사용하는 동안 특정 요청에 대해 엔드포인트를 재정의해야 할 수 있습니다. AWS SDK for Java 2.x는 요청 재정의를 통해 이를 지원합니다.

예 특정 요청에 대한 엔드포인트 재정의

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

요청 수준 엔드포인트 재정의는 제한되며 일부 서비스 또는 시나리오에서는 작동하지 않을 수 있습니다. 대부분의 경우 클라이언트 수준 엔드포인트 구성을 사용하는 것이 좋습니다.

외부 엔드포인트 구성

환경 변수 사용

환경 변수를 사용하여 엔드포인트를 구성합니다. SDK는 AWS_ENDPOINT_URL_[SERVICE] 형식의 환경 변수를 통해 서비스별 엔드포인트 구성을 지원하며, 여기서 [SERVICE]는 대문자 서비스 식별자입니다.

예 환경 변수를 사용한 S3 엔드포인트 설정

# 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

또는 다음 환경 변수를 사용하여 글로벌 엔드포인트 URL 접두사 또는 접미사를 설정할 수 있습니다.

  • AWS_ENDPOINT_URL - 모든 서비스에 대한 글로벌 엔드포인트를 설정합니다.

  • AWS_ENDPOINT_URL_PREFIX - 모든 서비스 엔드포인트에 접두사를 추가합니다.

  • AWS_ENDPOINT_URL_SUFFIX - 모든 서비스 엔드포인트에 접미사를 추가합니다.

JVM 시스템 속성 사용

또한 JVM 시스템 속성을 사용하여 엔드포인트를 구성할 수 있습니다. 형식은 환경 변수와 비슷하지만 다른 이름 지정 규칙을 사용합니다.

예 JVM 시스템 속성을 사용하여 S3 엔드포인트 설정

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

또한 글로벌 엔드포인트 구성은 시스템 속성을 통해서 사용할 수 있습니다.

  • aws.endpointUrl - 모든 서비스에 대한 글로벌 엔드포인트를 설정합니다.

  • aws.endpointUrl.prefix - 모든 서비스 엔드포인트에 접두사를 추가합니다.

  • aws.endpointUrl.suffix - 모든 서비스 엔드포인트에 접미사를 추가합니다.

공유 AWS 구성 파일 사용

또한 AWS SDK for Java 2.x는 일반적으로 ~/.aws/config(Linux/macOS) 또는 %USERPROFILE%\.aws\config(Windows)에 있는 공유 AWS 구성 파일을 통해 엔드포인트 구성을 지원합니다. 자세한 내용과 예제는 AWS SDK 및 도구 참조 안내서를 참조하세요.

구성 우선 순위

여러 엔드포인트 구성이 있는 경우 SDK는 다음 우선순위(가장 높음에서 가장 낮음)를 따릅니다.

  1. 요청 수준 재정의(해당하는 경우)

  2. endpointOverride를 통한 클라이언트 수준 구성

  3. 환경 변수

  4. JVM 시스템 속성

  5. 공유 AWS 구성 파일

  6. 구성된 AWS 리전을 기반으로 하는 기본 엔드포인트

서비스별 엔드포인트 구성

일부 AWS 서비스에는 해당 서비스와 관련된 추가 엔드포인트 구성 옵션이 있습니다. 다음은 몇 가지 예입니다.

Amazon S3 엔드포인트 구성

Amazon S3는 S3Configuration 클래스를 통해 여러 엔드포인트 구성을 지원합니다.

  • dualstackEnabled - IPv6 지원 사용

  • accelerateModeEnabled - S3 Transfer Acceleration 사용

  • pathStyleAccessEnabled - 가상 호스팅식 대신 경로식 액세스 사용

  • useArnRegionEnabled - 크로스 리전 요청에 ARN의 리전 사용

  • fipsModeEnabled - 요청을 FIPS 준수 엔드포인트로 라우팅

예 S3별 엔드포인트 옵션 구성

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

DynamoDB 엔드포인트 구성

DynamoDB의 경우 엔드포인트 검색을 사용하거나 DynamoDB 로컬에 연결하여 테스트할 수 있습니다.

예 DynamoDB 로컬에 연결

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

또한 DynamoDB는 코드에서 구성하거나 외부 설정을 사용하여 구성할 수 있는 계정 기반 엔드포인트 사용을 지원합니다. 다음 예제에서는 클라이언트를 만들 때 코드에서 계정 기반 엔드포인트 사용을 사용 해제하는 방법을 보여줍니다(기본 설정: 선호).

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

모범 사례

AWS SDK for Java 2.x에서 엔드포인트를 구성할 때 다음 모범 사례를 고려하세요.

  • 환경별 엔드포인트에 외부 구성 사용 - 환경 변수, 시스템 속성 또는 환경(개발, 테스트, 프로덕션) 간에 다른 엔드포인트에 AWS 구성 파일을 사용합니다.

  • 애플리케이션별 엔드포인트에 코드 내 구성 사용 - 애플리케이션의 설계에 맞는 엔드포인트에 클라이언트 빌더의 endpointOverride 메서드를 사용합니다.

  • 항상 리전 지정 - 엔드포인트를 재정의할 때도 항상 요청 서명에 사용되는 리전을 지정합니다.

  • 글로벌 엔드포인트 재정의에 주의 - 글로벌 엔드포인트 재정의는 모든 서비스에 영향을 미칠 수 있으며, 이는 의도한 것과 다를 수 있습니다.

  • 보안 영향 고려 - 사용자 지정 엔드포인트를 사용할 경우 특히 프로덕션 워크로드에 적절한 보안 조치가 있는지 확인합니다.