기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# MongoDB Java 드라이버를 사용하여 Amazon DocumentDB에 연결
이 섹션에서는 Java 드라이버를 사용하여 Amazon DocumentDB에 연결하기 위한 단계별 설명서를 제공합니다. 이를 통해 DocumentDB를 Java 애플리케이션에 통합하는 작업을 시작할 수 있습니다.
**Topics**
+ [1단계: 프로젝트 설정](#step1-set-up)
+ [2단계: 연결 문자열 생성](#step2-create-connection-string)
+ [3단계: 연결 코드 작성](#step3-write-connect-code)
+ [4단계: 연결 예외 처리](#step4-handle-connect-exceptions)
+ [5단계: 코드 실행](#step5-running-code)
+ [연결 모범 사례](#java-connect-best-practices)
## 1단계: 프로젝트 설정
1. Maven을 사용하여 java 프로젝트를 생성합니다.
```
mvn archetype:generate -DgroupId=com.docdb.guide -DartifactId=my-docdb-project -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false
```
1. MongoDB Java 드라이버를 'pom.xml' 파일의 프로젝트에 대한 종속성으로 추가합니다.
```
org.mongodb
mongodb-driver-sync
5.3.0
```
## 2단계: 연결 문자열 생성
Amazon DocumentDB 연결 문자열은 애플리케이션과 DocumentDB 클러스터 간에 연결을 설정하는 데 필수적입니다. 이 문자열은 클러스터 엔드포인트, 포트, 인증 세부 정보 및 다양한 연결 옵션과 같은 중요한 정보를 캡슐화합니다. DocumentDB 연결 문자열을 빌드하려면 일반적으로 기본 형식으로 시작합니다.
```
"mongodb://{{username}}:{{password}}@cluster-endpoint:port/?[connection options]"
```
‘사용자 이름’ 및 ‘암호’를 실제 자격 증명으로 바꿔야 합니다. AWS Management Console 와를 통해 클러스터의 엔드포인트 및 포트 번호를 찾을 수 있습니다 AWS CLI. 클러스터의 클러스터 엔드포인트를 찾으려면 [클러스터 엔드포인트 찾기](db-cluster-endpoints-find.md) 섹션을 참조하세요. Amazon DocumentDB의 기본 포트는 27017은 입니다.
**연결 문자열 예제**
+ 전송 중 암호화를 사용하여 DocumentDB에 연결하고 읽기 요청이 읽기 복제본으로 이동하고 쓰기 요청이 기본 인스턴스로 이동하도록 합니다.
```
"mongodb://username:password@cluster-endpoint:27017/?tls=true&
tlsCAFile=global-bundle.pem&
readPreference=secondaryPreferred&
retryWrites=false"
```
+ IAM 인증을 사용하여 DocumentDB에 연결:
```
"mongodb://cluster-endpoint:27017/?tls=true&
tlsCAFile=global-bundle.pem&
readPreference=secondaryPreferred&
retryWrites=false&
authSource=%24external&
authMechanism=MONGODB-AWS"
```
연결 문자열에 사용할 수 있는 다양한 옵션은 다음과 같습니다.
+ [TLS 인증서](#connection-string-tls)
+ [읽기 복제본에서 읽기](#connection-string-read-rep)
+ [쓰기 문제 및 저널링](#connection-string-write-journal)
+ [RetryWrites](#connection-string-retry-writes)
+ [IAM 인증](#connection-string-iam-auth)
+ [연결 풀](#connection-string-pool)
+ [연결 제한 시간 파라미터](#connection-string-timeout)
### TLS 인증서
**`tls=true|false`** - 이 옵션은 Transport Layer Security(TLS)을 활성화하거나 비활성화합니다. 기본적으로 Amazon DocumentDB 클러스터에서 전송 중 암호화가 활성화되므로 클러스터 수준에서 TLS가 비활성화되지 않는 한 이 옵션의 값은 `true`여야 합니다.
TLS를 사용하는 경우 DocumentDB 클러스터에 대한 연결을 생성할 때 코드는 SSL 인증서를 제공해야 합니다. 클러스터에 안전하게 연결하는 데 필요한 인증서를 다운로드합니다([https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)). `global-bundle.pem` 파일을 사용하는 방법에는 두 가지가 있습니다.
+ **옵션 1** - `global-bundle.pem` 파일에서 모든 인증서를 추출하고 Java의 keytool을 사용하여 나중에 코드에서 사용할 수 있는 `.jks` 파일에 저장합니다. 이 작업을 수행하는 방법을 보여주는 스크립트는 [TLS가 활성화된 상태에서 연결](connect_programmatically.md#connect_programmatically-tls_enabled)의 Java 탭을 참조하세요.
+ **옵션 2** - 코드에 `global-bundle.pem` 파일을 동적으로 추가하고, 인 메모리 키 스토어를 빌드하고, `SSLContext`를 사용하여 연결의 일부로 인증서를 제공합니다.
### 읽기 복제본에서 읽기
**`replicaSet=rs0&readPreference=secondaryPreferred`** - 이 두 옵션을 지정하면 모든 읽기 요청이 읽기 복제본으로 라우팅되고 쓰기 요청이 기본 인스턴스로 라우팅됩니다. 연결 문자열에서 `replicaSet=rs0`을 사용하면 MongoDB 드라이버가 클러스터 토폴로지의 자동으로 업데이트된 보기를 유지 관리할 수 있으므로 인스턴스가 추가되거나 제거될 때 애플리케이션이 현재 노드 구성의 가시성을 유지할 수 있습니다. 이러한 옵션을 제공하지 않거나 `readPreference=primary`를 지정하지 않으면 모든 읽기 및 쓰기가 기본 인스턴스로 전송됩니다. `readPreference`에 대한 더 많은 옵션은 [읽기 기본 설정 옵션](how-it-works.md#durability-consistency-isolation) 섹션을 참조하세요.
### 쓰기 문제 및 저널링
쓰기 문제에 따라 쓰기 작업을 위해 데이터베이스에서 요청된 승인 수준이 결정됩니다. MongoDB 드라이버는 쓰기 문제 및 저널 파일을 조정할 수 있는 옵션을 제공합니다. Amazon DocumentDB는 쓰기 문제 및 저널을 설정할 것으로 예상하지 않으며 `w` 및 `j`(`writeConcern` 및 `journal`)에 대해 전송된 값을 무시합니다. DocumentDB는 항상 `writeConcern`: `majority` 및 `journal`: `true`를 사용하여 데이터를 기록하므로 클라이언트에 승인을 보내기 전에 대부분의 노드에 쓰기가 안정적으로 기록됩니다.
### RetryWrites
**`retryWrites=false`** - DocumentDB는 재시도 가능한 쓰기를 지원하지 않으므로 이 속성은 항상 `false`로 설정해야 합니다.
### IAM 인증
**`authSource=%24external` 및 `authMechanism=MONGODB-AWS`** -이 두 파라미터는를 사용하여 인증하는 데 사용됩니다 AWS Identity and Access Management. IAM 인증은 현재 인스턴스 기반 클러스터 버전 5.0에서만 사용할 수 있습니다. 자세한 내용은 [IAM 자격 증명을 사용한 인증](iam-identity-auth.md) 단원을 참조하십시오.
### 연결 풀
연결 풀링에 사용할 수 있는 옵션은 다음과 같습니다.
+ **`maxPoolSize`** - 풀에서 생성할 수 있는 최대 연결 수를 설정합니다. 모든 연결이 사용 중이고 새 요청이 들어오면 연결을 사용할 수 있을 때까지 기다립니다. MongoDB Java 드라이버의 기본값은 100입니다.
+ **`minPoolSize`** - 풀에서 항상 유지해야 하는 최소 연결 수를 나타냅니다. MongoDB Java 드라이버의 기본값은 0입니다.
+ **`maxIdleTimeMS`** - 연결을 닫고 제거하기 전에 풀에서 연결을 유휴 상태로 유지할 수 있는 시간을 결정합니다. MongoDB Java 드라이버의 기본값은 100밀리초입니다.
+ **`waitQueueTimeoutMS`** - 풀이 최대 크기일 때 스레드가 연결을 사용할 수 있을 때까지 기다려야 하는 시간을 구성합니다. 이 시간 내에 연결을 사용할 수 없는 경우 예외가 발생합니다. MongoDB Java 드라이버의 기본값은 120,000밀리초(2분)입니다.
### 연결 제한 시간 파라미터
제한 시간은 작업 또는 연결 시도가 실패로 간주되기까지 걸릴 수 있는 시간을 제한하는 메커니즘입니다. 무기한 대기를 방지하고 리소스 할당을 관리하는 데 사용할 수 있는 제한 시간 파라미터는 다음과 같습니다.
+ **`connectTimeoutMS`** - 드라이버가 클러스터에 대한 연결을 설정하기 위해 기다리는 시간을 구성합니다. 기본값은 10,000밀리초(10초)입니다.
+ **`socketTimeoutMS`** - 드라이버가 쓰기 작업이 아닌 작업을 위해 서버의 응답을 기다리는 시간을 지정합니다. 기본값은 0입니다(제한 시간 없음 또는 무한).
+ **`serverSelectionTimeoutMS`** - 드라이버가 클러스터에서 사용할 수 있는 서버를 찾기 위해 기다리는 시간을 지정합니다. 이 설정의 기본값은 30초이며 장애 조치 중에 새 기본 인스턴스를 선택하기에 충분합니다.
## 3단계: 연결 코드 작성
다음 코드 예제에서는 Amazon DocumentDB에 TLS를 연결하는 방법을 보여줍니다.
+ Java [https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html](https://docs.oracle.com/javase/8/docs/api/java/security/KeyStore.html) 및 [`SSLContext`>](https://docs.oracle.com/javase/8/docs/api/javax/net/ssl/SSLContext.html) 객체를 생성합니다.
+ 또한 [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/ConnectionString.html) 객체에 전달하여 [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-core/com/mongodb/MongoClientSettings.html) 객체를 생성합니다. TLS 연결을 만들려면 `MongoClientSettings` 객체를 사용하여 `connectionstring` 및 `sslcontext`를 바인딩해야 합니다.
+ [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClients.html)를 사용하여 [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html) 객체를 가져옵니다.
```
public static MongoClient makeDbConnection(String dbName, String DbUserName, String DbPassword,
String DbClusterEndPoint, String keyStorePass) throws Exception {
MongoClient connectedClient;
String connectionOptions = "?replicaSet=rs0&readPreference=secondaryPreferred&retryWrites=false";
String connectionUrl = "mongodb://" + DbUserName + ":" + DbPassword + "@" + DbClusterEndPoint + ":27017/" +
dbName + connectionOptions;
try {
KeyStore trustStore = KeyStore.getInstance(KeyStore.getDefaultType());
try (FileInputStream fis = new FileInputStream("src/main/resources/certs/truststore.jks")) {
trustStore.load(fis, keyStorePass.toCharArray());
TrustManagerFactory tmf = TrustManagerFactory.getInstance(TrustManagerFactory.getDefaultAlgorithm());
tmf.init(trustStore);
SSLContext sslContext = SSLContext.getInstance("TLSv1.2");
sslContext.init(null, tmf.getTrustManagers(), new SecureRandom());
ConnectionString connectionString = new ConnectionString(connectionUrl);
MongoClientSettings settings = MongoClientSettings.builder()
.applyConnectionString(connectionString)
.applyToSslSettings(builder - > {
builder.enabled(true);
builder.context(sslContext);
})
.build();
connectedClient = MongoClients.create(settings);
}
return connectedClient;
} catch (MongoException e5) {
throw new RuntimeException(e5);
} catch (Exception e) {
throw new RuntimeException(e);
}
}
```
## 4단계: 연결 예외 처리
Java 애플리케이션에서 DocumentDB로 작업할 때 강력하고 안정적인 데이터베이스 작업을 유지하려면 연결 예외 처리가 중요합니다. 이러한 예외를 적절하게 관리하면 문제를 신속하게 진단하는 데 도움이 될 뿐만 아니라 애플리케이션이 임시 네트워크 중단 또는 서버 가용성을 정상적으로 처리할 수 있으므로 안정성과 사용자 경험이 향상됩니다. 연결 설정과 관련된 몇 가지 중요한 예외는 다음과 같습니다.
+ **`MongoException`** - 일반적인 예외는 보다 구체적인 예외가 적용되지 않는 다양한 시나리오에서 발행될 수 있습니다. 이 예외는 모든 MongoDB 예외를 일반적으로 포착하므로 다른 모든 특정 예외 이후에 처리되어야 합니다.
+ **`MongoTimeoutException`** - 작업 시간이 초과되는 경우에 발생합니다. 존재하지 않는 클러스터 엔드포인트를 쿼리하는 경우를 예로 들 수 있습니다.
+ **`MongoSocketException`** - 네트워크 관련 문제가 있는 경우에 발생합니다. 작업 중 갑작스럽게 네트워크 연결이 해제되는 경우를 예로 들 수 있습니다.
+ **`MongoSecurityException`** - 인증이 실패하는 경우에 발생합니다. 잘못된 자격 증명으로 연결하는 경우를 예로 들 수 있습니다.
+ **`MongoConfigurationException`** - 클라이언트 구성에 오류가 있는 경우에 발생합니다. 잘못된 연결 문자열을 사용하는 경우를 예로 들 수 있습니다.
## 5단계: 코드 실행
다음 코드 샘플은 Amazon DocumentDB 연결을 생성하고 모든 데이터베이스를 인쇄합니다.
```
public static void TestConnection() {
try (MongoClient mongoClient = makeDbConnection(DATABASE_NAME, DB_USER_NAME, DB_PASSWORD, DB_CLUSTER_ENDPOINT, KEYSTORE_PASSWORD)) {
List < String > databases = mongoClient.listDatabaseNames().into(new ArrayList < > ());
System.out.println("Databases: " + databases);
} catch (MongoException e) {
System.err.println("MongoDB error: " + e.getMessage());
throw new RuntimeException(e);
}
}
```
## 연결 모범 사례
다음은 MongoDB Java 드라이버를 사용하여 Amazon DocumentDB에 연결할 때 고려해야 할 모범 사례입니다.
+ 클라이언트가 더 이상 리소스를 릴리스할 필요가 없는 경우 항상 [https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html](https://mongodb.github.io/mongo-java-driver/5.3/apidocs/mongodb-driver-sync/com/mongodb/client/MongoClient.html)를 닫습니다.
+ 예외를 적절하게 처리하고 적절한 오류 로깅을 구현합니다.
+ 환경 변수 또는 AWS Secrets Manager 를 사용하여 사용자 이름 및 암호와 같은 민감한 정보를 저장합니다.