# 고급 연결 파라미터
<a name="jdbc-v3-driver-advanced-connection-parameters"></a>

다음 섹션에서는 JDBC 3.x 드라이버의 고급 연결 파라미터에 대해 설명합니다.

**Topics**
+ [결과 암호화 파라미터](#jdbc-v3-driver-result-encryption-parameters)
+ [결과 가져오기 파라미터](#jdbc-v3-driver-result-fetching-parameters)
+ [결과 구성 파라미터](#jdbc-v3-driver-result-config)
+ [쿼리 결과 재사용 파라미터](#jdbc-v3-driver-query-result-reuse-parameters)
+ [쿼리 실행 폴링 파라미터](#jdbc-v3-driver-query-execution-polling-parameters)
+ [엔드포인트 재정의 파라미터](#jdbc-v3-driver-endpoint-override-parameters)
+ [프록시 구성 파라미터](#jdbc-v3-driver-proxy-configuration-parameters)
+ [로깅 파라미터](#jdbc-v3-driver-logging-parameters)
+ [애플리케이션 이름](#jdbc-v3-driver-application-name)
+ [연결 테스트](#jdbc-v3-driver-connection-test)
+ [재시도 횟수](#jdbc-v3-driver-number-of-retries)
+ [네트워크 제한 시간](#jdbc-v3-driver-networktimeoutmillis)

## 결과 암호화 파라미터
<a name="jdbc-v3-driver-result-encryption-parameters"></a>

다음 사항에 주의하세요.
+ `EncryptionOption`이 `SSE_KMS` 또는 `CSE_KMS`인 경우 AWS KMS 키를 지정해야 합니다.
+ `EncryptionOption`이 지정되지 않거나 `EncryptionOption`이 `SSE_S3`인 경우 AWS KMS 키를 지정할 수 없습니다.

### 암호화 옵션
<a name="jdbc-v3-driver-encryption-option"></a>

Amazon S3에 저장되는 쿼리 결과에 사용할 암호화 유형입니다. 쿼리 결과 암호화에 대한 자세한 내용은 **Amazon Athena API 참조의 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 가능한 값 | 
| --- | --- | --- | --- | --- | 
| EncryptionOption | S3OutputEncOption(사용되지 않음) | 선택 사항 | 없음 | SSE\$1S3, SSE\$1KMS, CSE\$1KMS | 

### KMS 키
<a name="jdbc-v3-driver-kms-key"></a>

암호화 옵션으로 `SSE_KMS` 또는 `CSE_KMS`가 선택된 경우 KMS 키 ARN 또는 ID입니다. 자세한 내용은 **Amazon Athena API 참조의 [EncryptionConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_EncryptionConfiguration.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| KmsKey | S3OutputEncKMSKey(사용되지 않음) | 선택 사항 | 없음 | 

## 결과 가져오기 파라미터
<a name="jdbc-v3-driver-result-fetching-parameters"></a>

### 결과 페처
<a name="jdbc-v3-driver-result-fetcher"></a>

쿼리 결과를 다운로드하는 데 사용될 페처입니다.

기본 결과 페처인 `auto`는 Athena API를 사용하지 않고 Amazon S3에서 직접 쿼리 결과를 다운로드합니다. `CSE_KMS` 옵션으로 쿼리 결과가 암호화되는 경우와 같이 직접 S3 다운로드가 불가능한 경우 `GetQueryResultsStream` API를 사용하기 위해 자동으로 폴백합니다.

대부분의 상황에서 `auto` 페처를 사용하는 것이 좋습니다. IAM 정책 또는 S3 버킷 정책이 [s3:CalledVia](security-iam-athena-calledvia.md) 조건을 사용하여 Athena의 S3 객체 요청에 대한 액세스를 제한하는 경우, `auto` 페처는 먼저 S3에서 결과를 다운로드하려고 시도한 다음 `GetQueryResultsStream` API를 사용하기 위해 폴백합니다. 이 경우 추가 API 직접 호출을 방지하기 위해 ResultFetcher를 `GetQueryResultsStream`으로 설정할 수 있습니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 가능한 값 | 
| --- | --- | --- | --- | --- | 
| ResultFetcher | 없음 | 선택 사항 | auto | auto, S3, GetQueryResults, GetQueryResultsStream | 

### 가져오기 크기
<a name="jdbc-v3-driver-fetch-size"></a>

이 파라미터의 값은 내부 버퍼의 최솟값 및 결과를 가져올 때 대상 페이지 크기로 사용됩니다. 값 0은 드라이버가 아래에 설명된 대로 기본값을 사용해야 함을 의미합니다. 최댓값은 100만입니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| FetchSize | RowsToFetchPerBlock(사용되지 않음) | 선택 사항 | 0 | 
+ `GetQueryResults` 페처는 항상 API 호출에서 지원하는 최댓값인 1,000(페이지 크기)을 사용합니다. 가져오기 크기가 1,000보다 크면 버퍼를 최솟값 이상으로 채우기 위해 여러 개의 연속 API 호출이 수행됩니다.
+ `GetQueryResultsStream` 페처는 구성된 가져오기 크기를 페이지 크기로 사용하거나 기본적으로 10,000을 사용합니다.
+ `S3` 페처는 구성된 가져오기 크기를 페이지 크기로 사용하거나 기본적으로 10,000을 사용합니다.

## 결과 구성 파라미터
<a name="jdbc-v3-driver-result-config"></a>

### 예상 버킷 소유자
<a name="jdbc-v3-driver-exp-bucket-owner"></a>

예상되는 s3 버킷 소유자의 계정 ID입니다. 제공한 계정 ID가 버킷의 실제 소유자와 일치하지 않으면 요청이 실패합니다. s3 버킷 소유자 확인에 대한 자세한 내용은 [버킷 소유권 확인](https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucket-owner-condition.html#bucket-owner-condition-use)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ExpectedBucketOwner | 없음 | 선택 사항 | 없음 | 

### Acl 옵션
<a name="jdbc-v3-driver-acl"></a>

저장된 쿼리 결과의 소유권을 제어하려면 Amazon S3 미리 준비된 ACL을 설정해야 함을 나타냅니다. `AclOption`에 대한 자세한 내용은 [AclConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_AclConfiguration.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 가능한 값 | 
| --- | --- | --- | --- | --- | 
| AclOption | 없음 | 선택 사항 | 없음 | BUCKET\$1OWNER\$1FULL\$1CONTROL | 

## 쿼리 결과 재사용 파라미터
<a name="jdbc-v3-driver-query-result-reuse-parameters"></a>

### 결과 재사용 활성화
<a name="jdbc-v3-driver-enable-result-reuse"></a>

쿼리가 실행될 때 동일한 쿼리에 대한 이전 결과를 재사용할 수 있는지 여부를 지정합니다. 쿼리 결과 재사용에 대한 자세한 내용은 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| EnableResultReuseByAge | 없음 | 선택 사항 | FALSE | 

### 결과 재사용 최대 수명
<a name="jdbc-v3-driver-result-reuse-max-age"></a>

Athena에서 재사용을 고려해야 하는 이전 쿼리 결과의 최대 수명(분)입니다. 결과 재사용 최대 기간에 대한 자세한 내용은 [ResultReuseByAgeConfiguration](https://docs.aws.amazon.com/athena/latest/APIReference/API_ResultReuseByAgeConfiguration.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| MaxResultReuseAgeInMinutes | 없음 | 선택 사항 | 60 | 

## 쿼리 실행 폴링 파라미터
<a name="jdbc-v3-driver-query-execution-polling-parameters"></a>

### 최소 쿼리 실행 폴링 간격
<a name="jdbc-v3-driver-minimum-query-execution-polling-interval"></a>

쿼리 실행 상태에 대해 Athena를 폴링하기 전에 기다릴 최솟값(밀리초)입니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| MinQueryExecutionPollingIntervalMillis | MinQueryExecutionPollingInterval(사용되지 않음) | 선택 사항 | 100 | 

### 최대 쿼리 실행 폴링 간격
<a name="jdbc-v3-driver-maximum-query-execution-polling-interval"></a>

쿼리 실행 상태에 대해 Athena를 폴링하기 전에 기다릴 최댓값(밀리초)입니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| MaxQueryExecutionPollingIntervalMillis | MaxQueryExecutionPollingInterval(사용되지 않음) | 선택 사항 | 5000 | 

### 쿼리 실행 폴링 간격 승수
<a name="jdbc-v3-driver-query-execution-polling-interval-multiplier"></a>

폴링 기간을 늘리는 요인입니다. 기본적으로 폴링은 `MinQueryExecutionPollingIntervalMillis` 값으로 시작하고 `MaxQueryExecutionPollingIntervalMillis` 값에 도달할 때까지 각 폴링의 두 배가 됩니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| QueryExecutionPollingIntervalMultiplier | 없음 | 선택 사항 | 2 | 

## 엔드포인트 재정의 파라미터
<a name="jdbc-v3-driver-endpoint-override-parameters"></a>

### Athena 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-endpoint-override"></a>

드라이버가 Athena에 대한 API 호출을 수행하는 데 사용할 엔드포인트입니다.

다음 사항에 주의하세요.
+ 제공된 URL에 `https://` 또는 `http://` 프로토콜이 지정되지 않은 경우 드라이버는 `https://` 접두사를 삽입합니다.
+ 이 파라미터가 지정되지 않으면 드라이버는 기본 엔드포인트를 사용합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| AthenaEndpoint | EndpointOverride(사용되지 않음) | 선택 사항 | 없음 | 

### Athena 스트리밍 서비스 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-streaming-service-endpoint-override"></a>

드라이버가 Athena 스트리밍 서비스를 사용할 때 쿼리 결과를 다운로드하는 데 사용할 엔드포인트입니다. Athena 스트리밍 서비스는 포트 444에서 사용할 수 있습니다.

다음 사항에 주의하세요.
+ 제공된 URL에 `https://` 또는 `http://` 프로토콜이 지정되지 않은 경우 드라이버는 `https://` 접두사를 삽입합니다.
+ 제공된 URL에 포트가 지정되지 않은 경우 드라이버는 스트리밍 서비스 포트 444를 삽입합니다.
+ `AthenaStreamingEndpoint` 파라미터가 지정되지 않은 경우 드라이버는 `AthenaEndpoint` 재정의를 사용합니다. `AthenaStreamingEndpoint`와 `AthenaEndpoint` 재정의가 모두 지정되지 않은 경우 드라이버는 기본 스트리밍 엔드포인트를 사용합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| AthenaStreamingEndpoint | StreamingEndpointOverride(사용되지 않음) | 선택 사항 | 없음 | 

### LakeFormation 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-lake-formation-endpoint-override"></a>

AWS Lake Formation [AssumeDecoratedRoleWithSAML](https://docs.aws.amazon.com/lake-formation/latest/APIReference/API_AssumeDecoratedRoleWithSAML.html) API를 사용하여 임시 보안 인증을 검색할 때 드라이버가 Lake Formation 서비스에 사용할 엔드포인트입니다. 이 파라미터가 지정되지 않으면 드라이버는 기본 Lake Formation 엔드포인트를 사용합니다.

다음 사항에 주의하세요.
+ 제공된 URL에 `https://` 또는 `http://` 프로토콜이 지정되지 않은 경우 드라이버는 `https://` 접두사를 삽입합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| LakeFormationEndpoint |  LfEndpointOverride(사용되지 않음)  | 선택 사항 | 없음 | 

### S3 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-s3-endpoint-override"></a>

드라이버가 Amazon S3 페처를 사용할 때 쿼리 결과를 다운로드하는 데 사용할 엔드포인트입니다. 이 파라미터가 지정되지 않으면 드라이버는 기본 Amazon S3 엔드포인트를 사용합니다.

다음 사항에 주의하세요.
+ 제공된 URL에 `https://` 또는 `http://` 프로토콜이 지정되지 않은 경우 드라이버는 `https://` 접두사를 삽입합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| S3Endpoint | 없음 | 선택 사항 | 없음 | 

### STS 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-sts-endpoint-override"></a>

AWS STS [AssumeRoleWithSAML](https://docs.aws.amazon.com/STS/latest/APIReference/API_AssumeRoleWithSAML.html) API를 사용하여 임시 보안 인증을 검색할 때 드라이버가 AWS STS 서비스에 사용할 엔드포인트입니다. 이 파라미터가 지정되지 않으면 드라이버는 기본 AWS STS 엔드포인트를 사용합니다.

다음 사항에 주의하세요.
+ 제공된 URL에 `https://` 또는 `http://` 프로토콜이 지정되지 않은 경우 드라이버는 `https://` 접두사를 삽입합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| StsEndpoint | StsEndpointOverride(사용되지 않음) | 선택 사항 | 없음 | 

### SSO OIDC 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-sso-oidc-endpoint-override"></a>

`ClientConfiguration.endpointOverride`을(를) 사용하여 SSO OIDC 클라이언트의 기본 HTTP 엔드포인트를 재정의할 때 드라이버가 사용할 엔드포인트입니다. 자세한 내용은 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| SSOOIDCEndpointOverride |  | 선택 사항 | 없음 | 

### SSO 관리자 엔드포인트 재정의
<a name="jdbc-v3-driver-athena-sso-admin-endpoint-override"></a>

`ClientConfiguration.endpointOverride`을(를) 사용하여 SSO 관리자 클라이언트의 기본 HTTP 엔드포인트를 재정의할 때 드라이버가 사용할 엔드포인트입니다. 자세한 내용은 [ClientConfiguration](https://docs.aws.amazon.com/sdk-for-cpp/v1/developer-guide/client-config.html)을 참조하세요.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| SSOAdminEndpointOverride |  | 선택 사항 | 없음 | 

## 프록시 구성 파라미터
<a name="jdbc-v3-driver-proxy-configuration-parameters"></a>

### 프록시 호스트
<a name="jdbc-v3-driver-proxy-host"></a>

프록시 호스트의 URL입니다. Athena 요청이 프록시를 통과해야 하는 경우 이 파라미터를 사용합니다.

**참고**  
 `ProxyHost`의 URL 시작 부분에 프로토콜 `https://` 또는 `http://`를 포함해야 합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyHost | 없음 | 선택 사항 | 없음 | 

### 프록시 포트
<a name="jdbc-v3-driver-proxy-port"></a>

프록시 호스트에서 사용할 포트입니다. Athena 요청이 프록시를 통과해야 하는 경우 이 파라미터를 사용합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyPort | 없음 | 선택 사항 | 없음 | 

### 프록시 사용자 이름
<a name="jdbc-v3-driver-proxy-username"></a>

프록시 서버에서 인증할 사용자 이름입니다. Athena 요청이 프록시를 통과해야 하는 경우 이 파라미터를 사용합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyUsername | ProxyUID(사용되지 않음) | 선택 사항 | 없음 | 

### 프록시 비밀번호
<a name="jdbc-v3-driver-proxy-password"></a>

프록시 서버에서 인증할 암호입니다. Athena 요청이 프록시를 통과해야 하는 경우 이 파라미터를 사용합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyPassword | ProxyPWD(사용되지 않음) | 선택 사항 | 없음 | 

### 프록시 제외 호스트
<a name="jdbc-v3-driver-proxy-exempt-hosts"></a>

프록시가 활성화된 경우(즉, `ProxyHost` 및 `ProxyPort` 연결 파라미터가 설정된 경우) 드라이버가 프록시를 사용하지 않고 연결하는 호스트 이름의 세트입니다. 호스트는 파이프(`|`) 문자로 구분되어야 합니다(예: `host1.com|host2.com`).


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyExemptHosts | NonProxyHosts | 선택 사항 | 없음 | 

### ID 제공업체에 프록시 활성화
<a name="jdbc-v3-driver-proxy-enabled-for-identity-providers"></a>

드라이버가 ID 제공업체에 연결할 때 프록시를 사용해야 하는지 여부를 지정합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ProxyEnabledForIdP | UseProxyForIdP | 선택 사항 | FALSE | 

## 로깅 파라미터
<a name="jdbc-v3-driver-logging-parameters"></a>

이 섹션에서는 로깅과 관련된 파라미터를 설명합니다.

### 로그 수준
<a name="jdbc-v3-driver-logging-parameters-log-level"></a>

드라이버 로깅 수준을 지정합니다. `LogPath` 파라미터도 설정되지 않으면 아무 것도 로깅되지 않습니다.

**참고**  
특별한 요구 사항이 없으면 `LogPath` 파라미터만 설정하는 것이 좋습니다. `LogPath` 파라미터만 설정하면 로깅이 활성화되고 기본 `TRACE` 로그 수준이 사용됩니다. `TRACE` 로그 수준은 가장 자세한 로깅을 제공합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 가능한 값 | 
| --- | --- | --- | --- | --- | 
| LogLevel | 없음 | 선택 사항 | TRACE | OFF, ERROR, WARN, INFO, DEBUG, TRACE | 

### 로그 경로
<a name="jdbc-v3-driver-logging-parameters-log-path"></a>

드라이버 로그가 저장될 드라이버를 실행하는 컴퓨터의 디렉터리 경로입니다. 지정된 디렉터리 내에 고유한 이름을 가진 로그 파일이 생성됩니다. 설정하면 드라이버 로깅이 활성화됩니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| LogPath | 없음 | 선택 사항 | 없음 | 

## 애플리케이션 이름
<a name="jdbc-v3-driver-application-name"></a>

드라이버를 사용하는 애플리케이션의 이름입니다. 이 파라미터의 값이 지정되면 드라이버가 Athena에 대해 수행하는 API 호출의 사용자 에이전트 문자열에 값이 포함됩니다.

**참고**  
`DataSource` 객체에서 `setApplicationName`을 직접적으로 호출하여 애플리케이션 이름을 설정할 수도 있습니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ApplicationName | 없음 | 선택 사항 | 없음 | 

## 연결 테스트
<a name="jdbc-v3-driver-connection-test"></a>

`TRUE`로 설정하면 드라이버는 연결에 대해 쿼리가 실행되지 않더라도 JDBC 연결이 생성될 때마다 연결 테스트를 수행합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| ConnectionTest | 없음 | 선택 사항 | TRUE | 

**참고**  
연결 테스트는 연결이 제대로 구성되었는지 확인하기 위해 Athena에 `SELECT 1` 쿼리를 제출합니다. 즉, Amazon S3에 두 개의 파일(결과 세트와 메타데이터)이 저장되며 [Amazon Athena 요금](https://aws.amazon.com/athena/pricing) 정책에 따라 추가 요금이 부과될 수 있습니다.

## 재시도 횟수
<a name="jdbc-v3-driver-number-of-retries"></a>

드라이버가 Athena에 재시도 가능한 요청을 다시 보내야 하는 최대 횟수입니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
| NumRetries | MaxErrorRetry(사용되지 않음) | 선택 사항 | 없음 | 

## 네트워크 제한 시간
<a name="jdbc-v3-driver-networktimeoutmillis"></a>

네트워크 제한 시간은 드라이버가 네트워크 연결이 설정될 때까지 기다리는 시간을 제어합니다. 여기에는 API 요청을 보내는 데 걸리는 시간이 포함됩니다. 일부 드문 경우에는 네트워크 제한 시간을 변경하는 것이 유용할 수 있습니다. 예를 들어, 가비지 수집 대기 시간이 긴 경우 제한 시간을 늘릴 수 있습니다. 이 연결 파라미터를 설정하는 것은 `Connection` 객체에 `setNetworkTimeout` 메서드를 사용하는 것과 동일합니다.


****  

| 파라미터 이름 | 별칭 | 파라미터 유형 | 기본값  | 
| --- | --- | --- | --- | 
|  NetworkTimeoutMillis  | 없음 | 선택 사항 | 없음 |