# Amazon RDS Data API 사용
RDS 데이터 API(데이터 API)를 사용하면 Aurora DB 클러스터에 대한 웹 서비스 인터페이스로 작업할 수 있습니다. 데이터 API에서 DB 클러스터에 지속적으로 연결하지 않아도 됩니다. 대신에 AWS SDK와의 통합과 보안 HTTP 엔드포인트를 제공합니다. 연결을 관리하지 않고 엔드포인트를 사용하여 SQL 문을 실행할 수 있습니다.
데이터 API는 AWS Secrets Manager에 저장된 데이터베이스 보안 인증 정보를 사용하기 때문에 사용자는 데이터 API 호출과 함께 보안 인증 정보를 전달할 필요가 없습니다. Secrets Manager에 보안 인증 정보를 저장하려면 사용자에게 Secrets Manager 및 데이터 API를 사용할 수 있는 적절한 권한을 부여해야 합니다. 사용자 인증에 대한 자세한 내용은 [Amazon RDS Data API에 대한 액세스 권한 부여](data-api.access.md) 단원을 참조하세요.
또한 데이터 API를 사용하여 Amazon Aurora를 다른 AWS 애플리케이션(예: AWS Lambda, AWS AppSync, AWS Cloud9)과 통합할 수 있습니다 데이터 API는 AWS Lambda를 사용하는 더 안전한 방법도 제공합니다. Virtual Private Cloud(VPC)의 리소스에 액세스하는 Lambda 함수를 구성할 필요 없이 DB 클러스터에 액세스할 수 있습니다. 자세한 내용은 [AWS Lambda](https://aws.amazon.com/lambda/), [AWS AppSync](https://aws.amazon.com/appsync/), [AWS Cloud9](https://aws.amazon.com/cloud9/) 단원을 참조하십시오.
Aurora DB 클러스터를 생성할 때 데이터 API를 활성화할 수 있습니다. 나중에 구성을 수정할 수도 있습니다. 자세한 내용은 [Amazon RDS Data API 활성화](data-api.enabling.md) 섹션을 참조하세요.
데이터 API를 활성화하면 VPC에서 Aurora에 액세스하도록 쿼리 도구를 구성하지 않고도 쿼리 편집기를 사용하여 임시 쿼리를 실행할 수 있습니다. 자세한 내용은 [Aurora 쿼리 편집기 사용하기](query-editor.md) 섹션을 참조하세요.
**Topics**
+ [
# Amazon RDS Data API의 리전 및 버전 가용성
](data-api.regions.md)
+ [
# Amazon RDS Data API에서 IPv6 사용
](data-api.ipv6.md)
+ [
# Amazon RDS Data API에 대한 제한 사항
](data-api.limitations.md)
+ [
# Aurora Serverless v2 및 프로비저닝된 클러스터와 Aurora Serverless v1 클러스터에 대한 Amazon RDS Data API 동작 비교
](data-api.differences.md)
+ [
# Amazon RDS Data API에 대한 액세스 권한 부여
](data-api.access.md)
+ [
# Amazon RDS Data API 활성화
](data-api.enabling.md)
+ [
# Amazon RDS Data API에 대한 Amazon VPC 엔드포인트(AWS PrivateLink) 만들기
](data-api.vpc-endpoint.md)
+ [
# Amazon RDS Data API 직접 호출
](data-api.calling.md)
+ [
# RDS 데이터 API용 Java 클라이언트 라이브러리 사용
](data-api.java-client-library.md)
+ [
# JSON 형식의 Amazon RDS Data API 쿼리 결과 처리
](data-api-json.md)
+ [
# Amazon RDS Data API 문제 해결
](data-api.troubleshooting.md)
+ [
# AWS CloudTrail을 사용하여 Amazon RDS Data API 직접 호출 로깅
](logging-using-cloudtrail-data-api.md)
+ [
# 성능 개선 도우미를 사용한 RDS 데이터 API 쿼리 모니터링
](monitoring-using-performance-insights-data-api.md)
# Amazon RDS Data API의 리전 및 버전 가용성
데이터 API에 사용할 수 있는 리전 및 엔진 버전에 대한 자세한 내용은 다음 섹션을 참조하세요.
| 클러스터 유형 | 리전 및 버전 사용 가능 여부 |
| --- | --- |
| Aurora PostgreSQL 프로비저닝 및 Serverless v2 | [Aurora PostgreSQL Serverless v2를 사용하고 프로비저닝된 Data API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL 프로비저닝 및 Serverless v2 | [Aurora MySQL Serverless v2 및 프로비저닝과 함께 데이터 API 사용](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL Serverless v1 | [Aurora PostgreSQL Serverless v1을 사용하는 Data API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL Serverless v1 | [Aurora MySQL Serverless v1을 사용하는 Data API](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
명령줄 인터페이스 또는 API를 통해 데이터 API에 액세스할 때 FIPS 140-2에서 유효성을 검사한 암호화 모듈이 필요한 경우 FIPS 엔드포인트를 사용합니다. 사용 가능한 FIPS 엔드포인트에 대한 자세한 내용은 [Federal Information Processing Standard(FIPS) 140-2](https://aws.amazon.com/compliance/fips/)를 참조하세요.
# Amazon RDS Data API에서 IPv6 사용
Amazon RDS Data API는 듀얼 스택 엔드포인트를 통한 IPv6 연결을 지원합니다. 이를 통해 IPv4와의 이전 버전과의 호환성을 유지하면서 IPv6 주소를 사용하여 데이터 API에 연결할 수 있습니다.
## IPv6 엔드포인트 지원
데이터 API는 IPv4 및 IPv6 연결을 모두 지원하는 듀얼 스택 엔드포인트를 제공합니다. 이러한 엔드포인트는 기존 `.aws` 도메인 대신 `.amazonaws.com` 도메인을 사용합니다.
### 사용 가능한 엔드포인트 유형
퍼블릭 듀얼 스택 엔드포인트
형식: `rds-data.region.api.aws`
예시: `rds-data.us-east-1.api.aws`
FIPS 듀얼 스택 엔드포인트
형식: `rds-data-fips.region.api.aws`
예시: `rds-data-fips.us-east-1.api.aws`
PrivateLink IPv6 엔드포인트
IPv6를 지원하는 VPC 엔드포인트를 통해 사용 가능
VPC 내에서 프라이빗 IPv6 연결 허용
### 레거시 IPv4 전용 엔드포인트
기존 `.amazonaws.com` 엔드포인트는 IPv4 전용 연결을 계속 지원합니다.
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**참고**
레거시 엔드포인트는 기존 애플리케이션과의 이전 버전과의 호환성을 보장하기 위해 변경되지 않습니다.
## IPv6 엔드포인트 사용
데이터 API와 함께 IPv6를 사용하려면 새 듀얼 스택 엔드포인트를 사용하도록 애플리케이션을 업데이트합니다. 사용 가능한 경우, 애플리케이션은 자동으로 IPv6를 사용하거나 IPv4로 돌아갑니다.
VPC에서 IPv6를 설정하는 방법에 대한 일반적인 지침은 *Amazon VPC 사용 설명서*의 [ IPv6로 마이그레이션](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html)을 참조하세요.
다음 두 가지 방법으로 IPv6 엔드포인트를 구성할 수 있습니다.
+ **환경 변수 사용**: IPv6 환경에서 `AWS_USE_DUALSTACK_ENDPOINT=true`를 설정합니다. AWS CLI 및 AWS SDK는 `api.aws` 엔드포인트 URL을 수동으로 지정할 필요 없이 적절한 엔드포인트를 자동으로 구성합니다.
+ **명시적 엔드포인트 URL 사용**: 아래 예제와 같이 AWS CLI 명령 또는 SDK 구성에서 직접 듀얼 스택 엔드포인트 URL을 지정합니다.
### AWS CLI 구성
엔드포인트 URL을 지정하여 IPv6 엔드포인트를 사용하도록 AWS CLI를 구성합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
Windows의 경우:
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### AWS SDK 구성
듀얼 스택 엔드포인트를 사용하도록 AWS SDK를 구성합니다.
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## IPv6과 함께 AWS PrivateLink 사용
VPC 내에서 IPv6 연결을 지원하는 데이터 API용 VPC 엔드포인트를 생성할 수 있습니다. 데이터 API용 VPC 엔드포인트 생성에 대한 자세한 지침은 [Amazon RDS Data API에 대한 Amazon VPC 엔드포인트(AWS PrivateLink) 만들기](data-api.vpc-endpoint.md) 섹션을 참조하세요.
IPv6 지원을 위한 VPC 엔드포인트를 생성할 때 다음을 확인합니다.
+ VPC 및 서브넷은 IPv6을 지원하도록 구성됩니다.
+ 보안 그룹은 필요한 포트에서 IPv6 트래픽을 허용합니다(일반적으로 HTTPS의 경우 443).
+ 네트워크 ACL IPv6 트래픽을 허용하도록 구성됩니다.
## 마이그레이션 고려 사항
IPv6 엔드포인트로 마이그레이션할 때는 다음 사항을 고려하세요.
+ **점진적 마이그레이션**: 엔드포인트 URL 한 번에 한 애플리케이션씩 업데이트하여 애플리케이션을 점진적으로 마이그레이션할 수 있습니다.
+ **네트워크 호환성**: 마이그레이션하기 전에 네트워크 인프라가 IPv6를 지원하는지 확인합니다.
+ **보안 정책**: 필요한 경우 IPv6 트래픽을 허용하도록 보안 그룹 규칙 및 네트워크 ACL을 업데이트합니다.
+ **모니터링**: IPv6 주소를 처리하도록 모니터링 및 로깅 구성을 업데이트합니다.
**참고**
**데이터베이스 연결 주소**: 데이터 API에 IPv6 엔드포인트를 사용하는 경우 기본 데이터베이스 연결 및 데이터베이스 로그에 여전히 IPv4 주소가 표시됩니다. 이는 예상되는 동작이며 IPv6 지원 애플리케이션의 기능에 영향을 주지 않습니다.
## IPv6 연결 문제 해결
IPv6 연결에 문제가 있는 경우 다음을 확인하세요.
네트워크 구성
네트워크가 IPv6를 지원하고 IPv6 라우팅이 올바르게 구성되었는지 확인합니다.
DNS 확인
DNS 해석기가 듀얼 스택 엔드포인트에 대한 AAAA 레코드를 확인할 수 있는지 확인합니다.
보안 그룹
필요한 포트(일반적으로 HTTPS의 경우 443)에서 IPv6 트래픽을 허용하도록 보안 그룹 규칙을 업데이트합니다.
클라이언트 라이브러리
HTTP 클라이언트 라이브러리가 IPv6 및 듀얼 스택 연결을 지원하는지 확인합니다.
# Amazon RDS Data API에 대한 제한 사항
RDS 데이터 API에는 다음과 같은 제한 사항이 적용됩니다.
+ DB 클러스터의 라이터 인스턴스에서만 데이터 API 쿼리를 실행할 수 있습니다. 하지만 라이터 인스턴스는 쓰기 쿼리와 읽기 쿼리를 모두 수락할 수 있습니다.
+ Aurora Global Database를 사용하면 기본 및 보조 DB 클러스터 모두에서 데이터 API를 활성화할 수 있습니다. 하지만 보조 클러스터는 기본 클러스터로 승격되기 전까지는 라이터 인스턴스를 갖지 않습니다. 데이터 API를 사용하려면 읽기 전용 쿼리를 포함한 쿼리 처리를 위해 라이터 인스턴스에 액세스해야 합니다. 따라서 라이터 인스턴스가 없는 동안 보조 클러스터로 전송된 읽기 및 쓰기 쿼리가 실패합니다. 보조 클러스터가 승격되고 사용 가능한 라이터 인스턴스를 갖게 되면 해당 DB 인스턴스에 대한 데이터 API 쿼리가 성공합니다.
+ T DB 인스턴스 클래스에서는 데이터 API가 지원되지 않습니다.
+ Aurora Serverless v2 및 프로비저닝된 DB 클러스터의 경우 RDS 데이터 API는 일부 데이터 유형을 지원하지 않습니다. 지원되는 유형 목록은 [Aurora Serverless v2 및 프로비저닝된 클러스터와 Aurora Serverless v1 클러스터에 대한 Amazon RDS Data API 동작 비교](data-api.differences.md) 섹션을 참조하세요.
+ Aurora PostgreSQL 버전 14 이상의 데이터베이스에서는 데이터 API가 암호 암호화에 `scram-sha-256`만 지원합니다.
+ 응답 크기 제한은 1MiB입니다. 호출이 1MiB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.
+ Aurora Serverless v1의 경우 초당 최대 요청 수는 1,000개입니다. 지원되는 다른 모든 데이터베이스의 경우 제한이 없습니다.
+ 데이터 API는 데이터베이스에서 반환되는 결과 집합에서 각 행의 크기를 64KB로 제한합니다. 결과 집합의 각 행 크기를 64KB 이하로 유지해야 합니다.
# Aurora Serverless v2 및 프로비저닝된 클러스터와 Aurora Serverless v1 클러스터에 대한 Amazon RDS Data API 동작 비교
Amazon RDS Data API의 최신 개선 사항을 통해 최신 버전의 PostgreSQL 또는 MySQL 엔진을 사용하는 클러스터에서도 Data API를 사용할 수 있습니다. 이러한 클러스터는 `db.r6g` 또는 `db.r6i` 등의 프로비저닝된 인스턴스 클래스나 Aurora Serverless v2를 사용하도록 구성할 수 있습니다.
다음 섹션에는 Aurora Serverless v2 및 프로비저닝된 DB 클러스터와 Aurora Serverless v1 DB 클러스터 간의 Amazon RDS Data API에 대한 차이점이 나와 있습니다. Aurora Serverless v1 DB 클러스터는 `serverless` 엔진 모드를 사용합니다. 프로비저닝 DB 클러스터는 `provisioned` 엔진 모드를 사용합니다. 또한 Aurora Serverless v2 DB 클러스터는 `provisioned` 엔진 모드를 사용하며, `db.serverless` 인스턴스 클래스와 함께 하나 이상의 Aurora Serverless v2 DB 인스턴스를 포함합니다.
## 초당 최대 요청 수
**Aurora Serverless v1**
Data API는 초당 최대 1,000개의 요청을 생성할 수 있습니다.
**Aurora Serverless v2**
Data API는 초당 무제한의 요청을 생성할 수 있습니다.
## 기존 데이터베이스에서 Amazon RDS Data API 활성화 또는 비활성화
**Aurora Serverless v1**
+ **Amazon RDS API의 경우** – `ModifyCluster` 작업을 사용하고 `EnableHttpEndpoint` 파라미터에 대해 `True` 또는 `False`(해당하는 경우)를 지정합니다.
+ **AWS CLI의 경우** – `--enable-http-endpoint` 또는 `--no-enable-http-endpoint`(해당하는 경우) 옵션과 함께 `modify-db-cluster` 작업을 사용합니다.
**Aurora Serverless v2**
+ **Amazon RDS API 사용** - `EnableHttpEndpoint` 및 `DisableHttpEndpoint` 작업을 사용합니다.
+ **AWS CLI의 경우**: `enable-http-endpoint` 및 `disable-http-endpoint` 작업을 사용합니다.
## CloudTrail 이벤트
**Aurora Serverless v1**
데이터 API 호출의 이벤트는 관리 이벤트입니다. 이러한 이벤트는 기본적으로 추적에 자동으로 포함됩니다. 자세한 내용은 [AWS CloudTrail 추적에서 데이터 API 이벤트 제외(Aurora Serverless v1 전용)](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events) 섹션을 참조하세요.
**Aurora Serverless v2**
데이터 API 호출의 이벤트는 데이터 이벤트입니다. 이러한 이벤트는 기본적으로 추적에서 자동으로 제외됩니다. 자세한 내용은 [AWS CloudTrail 추적에서 데이터 API 이벤트 포함](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events) 섹션을 참조하세요.
## 다중 문 지원
**Aurora Serverless v1**
+ Aurora MySQL의 경우 다중 문이 지원되지 않습니다.
+ Aurora PostgreSQL의 경우 다중 문은 첫 번째 쿼리 응답만 반환합니다.
**Aurora Serverless v2**
다중 문은 지원되지 않습니다. 단일 API 직접 호출에서 다중 문을 실행하려고 하면 `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`가 발생합니다. 다중 문을 실행하려면 별도의 `ExecuteStatement` API 직접 호출을 사용하거나 배치 처리를 위해 `BatchExecuteStatement`를 사용합니다.
다음 예제에서는 다중 문 실행을 시도하는 API 직접 호출의 결과로 표시되는 오류 메시지를 보여 줍니다.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
다음 예제에서는 별도의 `ExecuteStatement` API 직접 호출을 사용하여 여러 문을 실행합니다.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## 동일한 트랜잭션 ID에 대한 동시 요청
**Aurora Serverless v1**
후속 요청은 현재 요청이 완료될 때까지 대기합니다. 대기 기간이 너무 길면 애플리케이션에서 제한 시간 초과 오류를 처리해야 합니다.
**Aurora Serverless v2**
Data API가 동일한 트랜잭션 ID로 여러 요청을 수신하면 즉시 다음 오류를 반환합니다.
`DatabaseErrorException: Transaction is still running a query`
이 오류는 다음의 두 가지 상황에서 발생합니다.
+ 애플리케이션은 동일한 트랜잭션 ID를 사용하여 비동기식 요청(예: JavaScript promise)을 수행합니다.
+ 해당 트랜잭션 ID의 이전 요청은 여전히 처리 중입니다.
다음 예제는 `promise.all()`과 병렬로 실행되는 모든 요청을 보여 줍니다.
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
이 오류를 해결하려면 동일한 트랜잭션 ID로 다른 요청을 보내기 전에 현재 요청이 완료될 때까지 기다리거나 병렬 요청을 허용하도록 트랜잭션 ID를 제거합니다.
다음 예제에서는 동일한 트랜잭션 ID로 순차적 실행을 사용하는 API 직접 호출을 보여 줍니다.
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## BatchExecuteStatement 동작
`BatchExecuteStatement`에 대한 자세한 내용은 [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)를 참조하세요.
**Aurora Serverless v1**
업데이트 결과에서 생성된 필드 객체에는 삽입된 값이 포함됩니다.
**Aurora Serverless v2**
+ Aurora MySQL의 경우 업데이트 결과에 생성된 필드 객체에는 삽입된 값이 포함됩니다.
+ Aurora PostgreSQL에서 생성된 필드 객체는 비어 있습니다.
## ExecuteSQL 동작
`ExecuteSQL`에 대한 자세한 내용은 [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html)을 참조하세요.
**Aurora Serverless v1**
`ExecuteSQL` 작업은 더 이상 사용되지 않습니다.
**Aurora Serverless v2**
`ExecuteSQL` 작업은 지원되지 않습니다.
## ExecuteStatement 동작
`ExecuteStatement`에 대한 자세한 내용은 [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)를 참조하세요.
**Aurora Serverless v1**
`ExecuteStatement` 파라미터는 다차원 배열 열 및 모든 고급 데이터 유형 검색을 지원합니다.
**Aurora Serverless v2**
`ExecuteStatement` 파라미터는 다차원 배열 열을 지원하지 않습니다. 또한 지오메트리 및 통화 유형을 포함한 특정 PostgreSQL 데이터 형식을 지원하지 않습니다. Data API가 지원되지 않는 데이터 유형을 발견하면 `UnsupportedResultException: The result contains the unsupported data type data_type` 오류를 반환합니다.
이 문제를 해결하려면 지원되지 않는 데이터 유형을 `TEXT`로 캐스팅합니다. 다음 예제에서는 지원되지 않는 데이터 형식을 `TEXT`로 캐스팅합니다.
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
각 Aurora 데이터베이스 엔진에 지원되는 데이터 유형 목록은 [Data API 작업 참조](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations)를 참조하세요.
## 스키마 파라미터 동작
**Aurora Serverless v1**
`Schema` 파라미터는 지원되지 않습니다. API 직접 호출에 `Schema` 파라미터를 포함하면 Data API는 파라미터를 무시합니다.
**Aurora Serverless v2**
`Schema` 파라미터는 이제 사용되지 않습니다. API 직접 호출에 `Schema` 파라미터를 포함하면 Data API는 `ValidationException: The schema parameter isn't supported` 오류를 반환합니다. 다음 예제에서는 `ValidationException` 오류를 반환하는 Data API 직접 호출을 보여 줍니다.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
이 문제를 해결하려면 API 직접 호출에서 `Schema` 파라미터를 제거합니다.
다음 예제에서는 `Schema` 파라미터가 제거된 Data API 직접 호출을 보여 줍니다.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# Amazon RDS Data API에 대한 액세스 권한 부여
사용자는 권한이 있는 경우에만 RDS Data API(Data API) 작업을 간접적으로 호출할 수 있습니다. 권한을 정의하는 AWS Identity and Access Management(IAM) 정책을 연결하여 데이터 API를 사용할 수 있는 권한을 사용자에게 부여할 수 있습니다. IAM 역할을 사용하는 경우 정책을 역할에 연결할 수도 있습니다. AWS 관리형 정책인 `AmazonRDSDataFullAccess`에는 데이터 API에 대한 권한이 포함되어 있습니다.
`AmazonRDSDataFullAccess` 정책에는 사용자가 AWS Secrets Manager에서 보안 암호 값을 가져올 수 있는 권한도 포함되어 있습니다. 사용자는 데이터 API 호출에 사용할 수 있는 보안 암호를 저장하는 데 Secrets Manager를 사용해야 합니다. 보안 암호를 사용하면 사용자가 데이터 API 호출의 대상이 되는 리소스에 대한 데이터베이스 보안 인증 정보를 포함할 필요가 없습니다. 데이터 API는 투명하게 Secrets Manager를 호출하여 사용자의 보안 암호에 대한 요청을 허용(또는 거부)합니다. 데이터 API와 함께 사용할 보안 암호 설정에 대한 자세한 내용은 [AWS Secrets Manager에 데이터베이스 자격 증명 저장](#data-api.secrets) 섹션을 참조하세요.
`AmazonRDSDataFullAccess` 정책은 데이터 API를 통해 리소스에 대한 완전한 액세스를 제공합니다. 리소스의 Amazon 리소스 이름(ARN)을 지정하는 사용자 고유의 정책을 정의하여 범위를 좁힐 수 있습니다.
예를 들어, 다음 정책은 사용자가 ARN으로 식별되는 DB 클러스터의 데이터 API에 액세스하는 데 필요한 최소 권한을 보여줍니다. 정책에는 Secrets Manager에 액세스하고 사용자의 DB 인스턴스에 대한 권한 부여를 얻는 데 필요한 권한이 포함되어 있습니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:ExecuteStatement",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
}
]
}
```
------
예제와 같이 정책 문에서 와일드카드(\$1) 대신 “Resources” 요소에 대한 특정 ARN을 사용하는 것이 좋습니다.
## 태그 기반 권한 부여 작업
RDS 데이터 API(데이터 API) 및 Secrets Manager 모두 태그 기반 권한 부여를 지원합니다. *태그*는 RDS 클러스터와 같은 리소스에 추가 문자열 값을 사용하여 레이블을 지정하는 키-값 쌍입니다. 예를 들면 다음과 같습니다.
+ `environment:production`
+ `environment:development`
비용 할당, 운영 지원, 액세스 제어 및 기타 여러 이유로 리소스에 태그를 적용할 수 있습니다. 리소스에 아직 태그가 없는 상태에서 태그를 적용하려는 경우 [Amazon RDS 리소스 태그 지정](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html)에서 자세한 내용을 확인할 수 있습니다. 정책 문의 태그를 사용하여 이러한 태그로 레이블이 지정된 RDS 클러스터에 대한 액세스를 제한할 수 있습니다. 예를 들어 Aurora DB 클러스터에는 환경을 프로덕션 또는 개발로 식별하는 태그가 있을 수 있습니다.
다음 예제에서는 정책 문에서 태그를 사용하는 방법을 보여줍니다. 이 문을 사용하려면 클러스터와 데이터 API 요청에 전달된 보안 암호에 `environment:production` 태그가 있어야 합니다.
정책이 적용되는 방법은 다음과 같습니다. 사용자가 데이터 API를 사용하여 호출하면 요청이 서비스로 전송됩니다. 데이터 API는 먼저 요청에서 전달된 클러스터 ARN에 `environment:production`으로 태그가 지정되어 있는지 확인합니다. 그런 다음 Secrets Manager를 호출하여 요청에서 사용자의 비밀 값을 검색합니다. Secrets Manager는 또한 `environment:production`이 사용자의 비밀에 태깅되었는지 확인됩니다. 그렇다면 데이터 API는 사용자의 DB 암호에 대해 검색된 값을 사용합니다. 마지막으로, 올바른 경우 사용자에 대해 데이터 API 요청이 성공적으로 호출됩니다.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:*"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
이 예제에서는 데이터 API 및 Secrets Manager의 `rds-data` 및 `secretsmanager`에 대한 별도의 작업을 보여줍니다. 그러나 여러 가지 방법으로 작업을 결합하고 태그 조건을 정의하여 특정 사용 사례를 지원할 수 있습니다. 자세한 내용은 [Secrets Manager에 대한 자격 증명 기반 정책(IAM 정책) 사용](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition)을 참조하십시오.
정책의 “Condition” 요소에 대해 다음 중에서 태그 키를 선택할 수 있습니다.
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
리소스 태그 및 `aws:TagKeys` 사용 방법에 대한 자세한 내용은 [리소스 태그를 사용하여 AWS 리소스에 대한 액세스 제어](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys)를 참조하십시오.
**참고**
데이터 API 및 AWS Secrets Manager 모두 사용자에게 권한을 부여합니다. 정책에 정의된 모든 작업에 대한 권한이 없는 경우 `AccessDeniedException` 오류가 발생합니다.
## AWS Secrets Manager에 데이터베이스 자격 증명 저장
Amazon RDS Data API(Data API)를 직접적으로 호출할 때 Secrets Manager에서 보안 암호를 사용하여 Aurora DB 클러스터에 대한 자격 증명을 전달합니다. 이 방식으로 자격 증명을 전달하려면 보안 암호의 이름 또는 보안 암호의 Amazon 리소스 이름(ARN)을 지정합니다.
**보안 암호에 DB 클러스터 자격 증명을 저장하려면**
1. Secrets Manager을 사용하여 Aurora DB 클러스터의 자격 증명을 포함하는 보안 암호를 생성합니다.
이에 관한 지침은 *AWS Secrets Manager 사용 설명서*의 [데이터베이스 암호 생성](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html)에서 확인하세요.
1. Secrets Manager 콘솔을 사용하여 생성한 비밀에 대한 세부 정보를 보거나 `aws secretsmanager describe-secret` AWS CLI 명령을 실행합니다.
보안 암호의 이름 및 ARN을 적어둡니다. 이러한 이름이나 ARN은 데이터 API 호출에서 사용할 수 있습니다.
Secrets Manager 사용에 대한 자세한 내용은 [AWS Secrets Manager 사용 설명서](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html)를 참조하세요.
Amazon Aurora이 자격 증명 및 액세스를 관리하는 방법을 이해하려면 [IAM에서 Amazon Aurora을 사용하는 방식](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html)을 참조하십시오.
IAM 정책 생성에 대한 자세한 내용은 *IAM 사용 설명서*의 [IAM 정책 생성](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html)을 참조하십시오. 사용자에게 IAM 정책 추가에 대한 자세한 내용은 *IAM 사용 설명서*의 [IAM 자격 증명 권한 추가 및 제거](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html)를 참조하십시오.
# Amazon RDS Data API 활성화
Amazon RDS Data API(Data API)를 사용하려면 Aurora DB 클러스터에 대해 해당 API를 활성화하세요. DB 클러스터를 생성하거나 수정할 때 데이터 API를 활성화할 수 있습니다.
**참고**
클러스터에 데이터 API를 사용할 수 있는지 여부는 Aurora 버전, 데이터베이스 엔진 및 AWS 리전에 따라 달라집니다. 이전 Aurora 버전의 경우 데이터 API는 Aurora Serverless v1 클러스터에서만 작동합니다. 최신 Aurora 버전의 경우 데이터 API는 프로비저닝된 인스턴스와 Aurora Serverless v2 인스턴스를 모두 사용하는 클러스터에서 작동합니다. 클러스터가 데이터 API를 사용할 수 있는지 확인하려면 [RDS Data API를 지원하는 리전 및 Aurora DB 엔진](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md) 섹션을 참조하세요.
**Topics**
+ [
## 데이터베이스를 생성할 때 RDS 데이터 API 활성화
](#data-api.enabling.creating)
+ [
## 기존 데이터베이스에서 RDS 데이터 API 활성화
](#data-api.enabling.modifying)
## 데이터베이스를 생성할 때 RDS 데이터 API 활성화
RDS 데이터 API(데이터 API)를 지원하는 데이터베이스를 생성하는 동안 이 기능을 활성화할 수 있습니다. 다음 절차에서는 AWS Management Console, AWS CLI 또는 RDS API를 사용할 때 해당 작업을 수행하는 방법을 설명합니다.
### 콘솔
DB 클러스터를 생성할 때 데이터 API를 활성화하려면 다음 스크린샷과 같이 **데이터베이스 생성** 페이지의 **연결** 섹션에서 **RDS 데이터 API 활성화** 확인란을 선택합니다.
![\[데이터베이스 생성 페이지의 연결 섹션에 RDS 데이터 API 활성화 확인란이 선택됨.\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
RDS 데이터 API를 사용할 수 있는 Aurora DB 클러스터를 생성하는 방법에 대한 지침은 다음을 참조하세요.
+ Aurora Serverless v2 및 프로비저닝된 클러스터의 경우 - [Amazon Aurora DB 클러스터 생성](Aurora.CreateInstance.md)
+ Aurora Serverless v1의 경우 – [Aurora Serverless v1 DB 클러스터 생성](aurora-serverless.create.md)
### AWS CLI
Aurora DB 클러스터를 생성하는 동안 데이터 API를 활성화하려면 `--enable-http-endpoint` 옵션과 함께 [create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) AWS CLI 명령을 실행합니다.
다음 예제에서는 데이터 API가 활성화된 Aurora PostgreSQL DB 클러스터를 생성합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
Windows의 경우:
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### RDS API
Aurora DB 클러스터를 생성하는 동안 데이터 API를 활성화하려면 `EnableHttpEndpoint` 파라미터 값을 `true`로 설정한 상태에서 [CreateDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) 작업을 사용하세요.
## 기존 데이터베이스에서 RDS 데이터 API 활성화
RDS 데이터 API(데이터 API)를 지원하는 DB 클러스터를 수정하여 이 기능을 활성화하거나 비활성화할 수 있습니다.
**Topics**
+ [
### 데이터 API 활성화 또는 비활성화(Aurora Serverless v2 및 프로비저닝)
](#data-api.enabling.modifying.all)
+ [
### 데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)
](#data-api.enabling.modifying.sv1)
### 데이터 API 활성화 또는 비활성화(Aurora Serverless v2 및 프로비저닝)
다음 절차를 사용하여 Aurora Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화 또는 비활성화합니다. Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 [데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)](#data-api.enabling.modifying.sv1)의 절차를 사용하세요.
#### 콘솔
이 기능을 지원하는 DB 클러스터의 RDS 콘솔을 사용하여 데이터 API를 활성화 또는 비활성화할 수 있습니다. 이렇게 하려면 데이터 API를 활성화하거나 비활성화하려는 데이터베이스의 클러스터 세부 정보 페이지를 열고 **연결 및 보안** 탭에서 **RDS 데이터 API** 섹션으로 이동합니다. 이 섹션에는 데이터 API의 상태가 표시되며 이를 활성화하거나 비활성화할 수 있습니다.
다음 스크린샷은 활성화되지 않은 **RDS 데이터 API**를 보여줍니다.
![\[DB 클러스터 세부 정보 페이지의 연결 및 보안 탭에 있는 RDS 데이터 API 섹션. 데이터 API의 상태가 비활성화된 것으로 표시되고 RDS 데이터 API 활성화 버튼이 나타납니다.\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
기존 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html) 또는 [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) AWS CLI 명령을 실행하고 DB 클러스터의 ARN을 지정합니다.
다음 예제에서는 데이터 API를 활성화합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
Windows의 경우:
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### RDS API
기존 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html) 및 [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html) 작업을 사용합니다.
### 데이터 API 활성화 또는 비활성화(Aurora Serverless v1 전용)
다음 절차를 사용하여 기존 Aurora Serverless v1 데이터베이스에서 데이터 API를 활성화 또는 비활성화합니다. Aurora Serverless v2 및 프로비저닝된 데이터베이스에서 데이터 API를 활성화하거나 비활성화하려면 [데이터 API 활성화 또는 비활성화(Aurora Serverless v2 및 프로비저닝)](#data-api.enabling.modifying.all)의 절차를 사용하세요.
#### 콘솔
Aurora Serverless v1 DB 클러스터를 수정할 때 RDS 콘솔의 **연결** 섹션에서 데이터 API를 활성화합니다.
다음 스크린샷은 Aurora DB 클러스터를 수정할 때 활성화된 **데이터 API**를 보여줍니다.
![\[DB 클러스터 수정 페이지의 연결 섹션에서 데이터 API 확인란이 선택됨.\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
Aurora Serverless v1 DB 클러스터를 수정하는 방법에 대한 지침은 [Aurora Serverless v1 DB 클러스터 수정](aurora-serverless.modifying.md) 섹션을 참조하세요.
#### AWS CLI
데이터 API를 활성화하거나 비활성화하려면 해당하는 경우 `--enable-http-endpoint` 또는 `--no-enable-http-endpoint`와 함께 [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) AWS CLI 명령을 실행합니다.
다음 예제에서는 `sample-cluster`에서 데이터 API를 활성화합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
Windows의 경우:
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### RDS API
데이터 API를 활성화하려면 [ModifyDBCluster](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) 작업을 사용하고 해당하는 경우 `EnableHttpEndpoint` 의 값을 `true` 또는 `false`로 설정합니다.
# Amazon RDS Data API에 대한 Amazon VPC 엔드포인트(AWS PrivateLink) 만들기
Amazon VPC를 사용하면 Aurora DB 클러스터 및 애플리케이션과 같은 AWS 리소스를 Virtual Private Cloud(VPC)에서 시작할 수 있습니다. AWS PrivateLink는 Amazon 네트워크에서 VPC 및 AWS 서비스 간의 프라이빗 연결을 안전하게 제공합니다. AWS PrivateLink를 사용하면 Amazon VPC 엔드포인트를 생성하여 Amazon VPC 기반의 다른 계정 및 VPC에서 서비스에 연결할 수 있습니다. AWS PrivateLink에 대한 자세한 내용은 *Amazon Virtual Private Cloud 사용 설명서*의 [VPC 엔드포인트 서비스(AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html)를 참조하세요.
Amazon VPC 엔드포인트를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 IP 주소를 사용하지 않고 Amazon VPC의 애플리케이션과 AWS 네트워크의 데이터 API 간에 트래픽을 유지합니다. Amazon VPC 엔드포인트를 사용하면 퍼블릭 인터넷 연결 제한과 관련된 규정 준수 및 규정 요구 사항을 충족할 수 있습니다. 예를 들어, Amazon VPC 엔드포인트를 사용하는 경우 Amazon EC2 인스턴스에서 실행되는 애플리케이션과 해당 애플리케이션이 포함된 VPC의 데이터 API 간 트래픽을 유지할 수 있습니다.
Amazon VPC 엔드포인트를 생성한 후에는 애플리케이션에서 코드나 구성을 변경하지 않고 엔드포인트를 사용할 수 있습니다.
**데이터 API에 대한 Amazon VPC 엔드포인트를 생성하려면**
1. AWS Management Console에 로그인하고 [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)에서 Amazon VPC 콘솔을 엽니다.
1. **엔드포인트**를 선택한 다음 **엔드포인트 생성**을 선택합니다.
1. **엔드포인트 생성** 페이지에서 **서비스 범주**에 대해 **AWS 서비스**를 선택합니다. **서비스 이름**에 대해 **rds-data**를 선택합니다.
![\[데이터 API용 Amazon VPC 엔드포인트 생성\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. **VPC**의 경우 엔드포인트를 생성할 VPC를 선택합니다.
데이터 API를 호출하는 애플리케이션이 포함된 VPC를 선택합니다.
1. **서브넷**의 경우 애플리케이션을 실행 중인 AWS 서비스에서 사용하는 각 가용 영역(AZ)의 서브넷을 선택합니다.
![\[Amazon VPC 엔드포인트에 대한 서브넷 선택\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
Amazon VPC 엔드포인트를 생성하려면 엔드포인트에 액세스할 수 있는 프라이빗 IP 주소 범위를 지정합니다. 이렇게 하려면 각 가용 영역에 대한 서브넷을 선택합니다. 이렇게 하면 VPC 엔드포인트가 각 가용 영역별 프라이빗 IP 주소 범위로 제한되고 각 가용 영역에 Amazon VPC 엔드포인트가 생성됩니다.
1. **Enable DNS name(DNS 이름 활성화)**에서 **이 엔드포인트에 대해 활성화**를 선택합니다.
![\[Amazon VPC 엔드포인트에 대해 DNS 이름 활성화\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
프라이빗 DNS는 표준 데이터 API DNS 호스트 이름(`https://rds-data.region.amazonaws.com`)을 Amazon VPC 엔드포인트에 특정한 DNS 호스트 이름과 연결된 프라이빗 IP 주소로 확인합니다. 따라서 데이터 API 엔드포인트 URL을 업데이트하기 위해 코드나 구성을 변경하지 않고도 AWS CLI 또는 AWS SDK를 사용하여 데이터 API VPC 엔드포인트에 액세스할 수 있습니다.
1. **보안 그룹**의 경우 Amazon VPC 엔드포인트와 연결할 보안 그룹을 선택합니다.
애플리케이션을 실행 중인 AWS 서비스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 예를 들어 Amazon EC2 인스턴스가 애플리케이션을 실행 중인 경우 Amazon EC2 인스턴스에 대한 액세스를 허용하는 보안 그룹을 선택합니다. 보안 그룹을 사용하면 VPC의 리소스에서 Amazon VPC 엔드포인트로 가는 트래픽을 제어할 수 있습니다.
1. **정책**의 경우 **모든 액세스**를 선택하여 Amazon VPC에 있는 모든 사용자가 이 엔드포인트를 통해 데이터 API에 액세스할 수 있도록 허용합니다. 또는 **사용자 지정**을 선택하여 액세스를 제한하는 정책을 지정합니다.
**사용자 지정**을 선택한 경우 정책 생성 도구에 정책을 입력합니다.
1. [**Create endpoint**]를 선택합니다.
엔드포인트를 생성한 후 AWS Management Console에서 링크를 선택하여 엔드포인트 세부 정보를 봅니다.
![\[Amazon VPC 엔드포인트 세부 정보에 대한 링크\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
엔드포인트 **세부 정보** 탭에는 Amazon VPC 엔드포인트를 만드는 동안 생성된 DNS 호스트 이름이 표시됩니다.
![\[Amazon VPC 엔드포인트 세부 정보에 대한 링크\]](http://docs.aws.amazon.com/ko_kr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
표준 엔드포인트(`rds-data.region.amazonaws.com`) 또는 VPC 관련 엔드포인트 중 하나를 사용하여 Amazon VPC에서 데이터 API를 호출할 수 있습니다. 표준 데이터 API 엔드포인트는 자동으로 Amazon VPC 엔드포인트로 라우팅됩니다. 이 라우팅은 Amazon VPC 엔드포인트를 생성할 때 프라이빗 DNS 호스트 이름을 활성화했기 때문에 발생합니다.
데이터 API 호출에서 Amazon VPC 엔드포인트를 사용하는 경우 애플리케이션과 데이터 API 간의 모든 트래픽은 해당 트래픽이 포함된 Amazon VPC에 남아 있습니다. 모든 유형의 데이터 API 호출에 Amazon VPC 엔드포인트를 사용할 수 있습니다. 데이터 API 호출에 대한 자세한 내용은 [Amazon RDS Data API 직접 호출](data-api.calling.md) 섹션을 참조하세요.
# Amazon RDS Data API 직접 호출
Aurora DB 클러스터에서 Amazon RDS Data API(Data API)를 활성화하면 Data API 또는 AWS CLI를 사용하여 Aurora DB 클러스터에서 SQL 문을 실행할 수 있습니다. 데이터 API는 AWS SDK에서 지원되는 프로그래밍 언어를 지원합니다. 자세한 내용은 [AWS 기반 구축 도구](https://aws.amazon.com/tools/)를 참조하세요.
**Topics**
+ [
# Amazon RDS Data API 작업 참조
](data-api-operations.md)
+ [
# AWS CLI를 사용하여 Amazon RDS Data API 직접 호출
](data-api.calling.cli.md)
+ [
# Python 애플리케이션에서 Amazon RDS Data API 직접 호출
](data-api.calling.python.md)
+ [
# Java 애플리케이션에서 Amazon RDS Data API 직접 호출
](data-api.calling.java.md)
+ [
# 데이터 API 시간 초과 동작 제어
](data-api-timeouts.md)
# Amazon RDS Data API 작업 참조
Amazon RDS Data API는 SQL 문을 수행하는 다음 작업을 제공합니다.
****
| 데이터 API 작업 | AWS CLI 명령 | 설명 |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html) | 데이터베이스에서 SQL 문을 실행합니다. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html) | 대량 업데이트 및 삽입 작업을 위해 데이터 배열을 통해 일괄 SQL 문을 실행합니다. 파라미터 집합 배열을 사용하여 데이터 조작 언어(DML) 문을 실행할 수 있습니다. 일괄 SQL 문은 개별 삽입 및 업데이트 문을 통해 중요한 성능 개선을 제공합니다. |
두 작업 중 하나를 사용하여 개별 SQL 문을 실행하거나 트랜잭션을 실행할 수 있습니다. 트랜잭션의 경우 데이터 API는 다음과 같은 작업을 제공합니다.
****
| 데이터 API 작업 | AWS CLI 명령 | 설명 |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html) | SQL 트랜잭션을 시작합니다. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html) | SQL 트랜잭션을 종료하고 변경을 수행합니다. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html) | 트랜잭션의 롤백을 수행합니다. |
SQL 문을 수행하고 트랜잭션을 지원하기 위한 작업에는 다음과 같은 일반적인 데이터 API 파라미터와 AWS CLI 옵션이 있습니다. 일부 작업은 다른 파라미터 또는 옵션을 지원합니다.
****
| 데이터 API 작업 파라미터 | AWS CLI 명령 옵션 | 필수 | 설명 |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | 예 | Aurora DB 클러스터의 Amazon 리소스 이름(ARN)입니다. 클러스터는 데이터 API를 간접적으로 호출하는 IAM 역할 또는 사용자와 동일한 AWS 계정에 있어야 합니다. 다른 계정의 클러스터에 액세스하려면 해당 계정에서 역할을 수임합니다. |
| `secretArn` | `--secret-arn` | 예 | DB 클러스터에 대한 액세스를 활성화하는 보안 암호의 이름 또는 ARN. |
RDS 데이터 API는 Aurora MySQL에 대해 다음 데이터 유형을 지원합니다.
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)`
RDS 데이터 API는 다음 Aurora PostgreSQL 스칼라 유형을 지원합니다.
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`
RDS 데이터 API는 다음 Aurora PostgreSQL 배열 유형을 지원합니다.
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
`ExecuteStatement` 및 `BatchExecuteStatement`에 대한 데이터 API 호출에서, 그리고 AWS CLI 명령 `execute-statement` 및 `batch-execute-statement` 실행 시 파라미터를 사용할 수 있습니다. 파라미터를 사용하려면 `SqlParameter` 데이터 형식에 이름-값 페어를 지정합니다. `Field` 데이터 형식으로 값을 지정하십시오. 다음 표는 JDBC(Java Database Connectivity) 데이터 형식을 Data API 호출에서 지정하는 데이터 형식에 매핑합니다.
****
| JDBC 데이터 형식 | 데이터 API 데이터 형식 |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` – , 또는 `STRING` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| 다른 형식(날짜 및 시간과 관련된 형식 포함) | `STRING` |
**참고**
데이터베이스에서 반환된 `LONG` 값에 대한 Data API 호출에서 `STRING` 또는 `LONG` 데이터 형식을 지정할 수 있습니다. JavaScript로 작업할 때 발생할 수 있는 매우 큰 수의 정밀도를 잃지 않도록 하는 것이 좋습니다.
`DECIMAL` 및 `TIME` 등 특정 유형에는 데이터 API가 `String` 값을 데이터베이스에 올바른 유형으로 전달할 수 있도록 힌트가 필요합니다. 힌트를 사용하려면 `typeHint`에 대한 값을 `SqlParameter` 데이터 형식에 포함합니다. `typeHint`에 가능한 값은 다음과 같습니다.
+ `DATE` – 해당되는 `String` 파라미터 값은 `DATE` 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 `YYYY-MM-DD`입니다.
+ `DECIMAL` – 해당되는 `String` 파라미터 값은 `DECIMAL` 유형의 객체로 데이터베이스에 전송됩니다.
+ `JSON` – 해당되는 `String` 파라미터 값은 `JSON` 유형의 객체로 데이터베이스에 전송됩니다.
+ `TIME` – 해당되는 `String` 파라미터 값은 `TIME` 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 `HH:MM:SS[.FFF]`입니다.
+ `TIMESTAMP` – 해당되는 `String` 파라미터 값은 `TIMESTAMP` 유형의 객체로 데이터베이스에 전송됩니다. 승인된 형식은 `YYYY-MM-DD HH:MM:SS[.FFF]`입니다.
+ `UUID` – 해당되는 `String` 파라미터 값은 `UUID` 유형의 객체로 데이터베이스에 전송됩니다.
**참고**
현재, 데이터 API는 범용 고유 식별자(UUID) 배열을 지원하지 않습니다.
**참고**
Amazon Aurora PostgreSQL의 경우 데이터 API는 항상 UTC 시간대로 Aurora PostgreSQL 데이터 형식 `TIMESTAMPTZ`를 반환합니다.
# AWS CLI를 사용하여 Amazon RDS Data API 직접 호출
AWS CLI를 사용하여 RDS 데이터 API(데이터 API)를 호출할 수 있습니다.
다음 예제에서는 데이터 API용 AWS CLI를 사용합니다. 자세한 내용은 [AWS CLI Data API 참조](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html)를 참조하세요.
각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.
**참고**
AWS CLI는 응답을 JSON 형식으로 지정할 수 있습니다.
**Topics**
+ [
## SQL 트랜잭션 시작
](#data-api.calling.cli.begin-transaction)
+ [
## SQL 문 실행
](#data-api.calling.cli.execute-statement)
+ [
## 데이터 배열에서 일괄 SQL 문 실행
](#data-api.calling.cli.batch-execute-statement)
+ [
## SQL 트랜잭션 커밋
](#data-api.calling.cli.commit-transaction)
+ [
## SQL 트랜잭션 롤백
](#data-api.calling.cli.rollback-transaction)
## SQL 트랜잭션 시작
`aws rds-data begin-transaction` CLI 명령을 사용하여 SQL 트랜잭션을 시작할 수 있습니다. 이 호출은 트랜잭션 식별자를 반환합니다.
**중요**
데이터 API 내에서 3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 트랜잭션이 커밋되기 전에 시간이 초과되면 데이터 API는 트랜잭션을 자동으로 롤백합니다.
트랜잭션 내의 MySQL 데이터 정의 언어(DDL) 문은 암시적 커밋을 발생시킵니다. `execute-statement` 옵션과 함께 별도의 `--continue-after-timeout` 명령으로 각 MySQL DDL 문을 실행하는 것이 좋습니다.
일반 옵션 외에도, 데이터베이스 이름을 제공하는 `--database` 옵션을 지정합니다.
예를 들어, 다음 CLI 명령은 SQL 트랜잭션을 시작합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
Windows의 경우:
```
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
```
다음은 이 응답의 예입니다.
```
{
"transactionId": "ABC1234567890xyz"
}
```
## SQL 문 실행
`aws rds-data execute-statement` CLI 명령을 사용하여 SQL 문을 실행할 수 있습니다.
`--transaction-id` 옵션으로 트랜잭션 식별자를 지정하여 트랜잭션에서 SQL 문을 실행할 수 있습니다. `aws rds-data begin-transaction` CLI 명령을 사용하여 트랜잭션을 시작할 수 있습니다. `aws rds-data commit-transaction` CLI 명령을 사용하여 트랜잭션을 끝내고 커밋할 수 있습니다.
**중요**
`--transaction-id` 옵션을 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.
일반 옵션 외에도 다음 옵션을 지정하십시오.
+ `--sql` (필수) – DB 클러스터에서 실행할 SQL 문.
+ `--transaction-id` (선택 사항) – `begin-transaction` CLI 명령을 사용하여 시작된 트랜잭션의 식별자. SQL 문을 포함할 트랜잭션의 트랜잭션 ID를 지정하십시오.
+ `--parameters` (선택 사항) – SQL 문의 파라미터.
+ `--include-result-metadata | --no-include-result-metadata` (선택 사항) – 메타데이터를 결과에 포함할지 나타내는 값. 기본값은 `--no-include-result-metadata`입니다.
+ `--database` (선택 사항) – 데이터베이스 이름.
이전 요청에서 `--sql "use database_name;"`를 실행한 후 SQL 문을 실행하면 `--database` 옵션이 작동하지 않을 수 있습니다. `--sql "use database_name;"` 문을 실행하는 대신 `--database` 옵션을 사용하는 것이 좋습니다.
+ `--continue-after-timeout | --no-continue-after-timeout`(선택 사항) - 호출이 데이터 API 시간 초과 간격인 45초를 초과한 후에도 문을 계속 실행할지 여부를 나타내는 값입니다. 기본값은 `--no-continue-after-timeout`입니다.
데이터 정의 언어(DDL) 문에 대해서는 오류 및 데이터 구조 손상 가능성을 피하기 위해 호출 시간이 초과된 후 문을 계속 실행하는 것이 좋습니다.
+ `--format-records-as "JSON"|"NONE"` - 결과 집합의 형식을 JSON 문자열로 지정할지를 결정하는 선택적 값입니다. 기본값은 `"NONE"`입니다. JSON 결과 집합 처리에 대한 사용 정보는 [JSON 형식의 Amazon RDS Data API 쿼리 결과 처리](data-api-json.md) 섹션을 참조하세요.
DB 클러스터는 각 호출에 대한 응답을 반환합니다.
**참고**
응답 크기 제한은 1MiB입니다. 호출이 1MiB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.
Aurora Serverless v1의 경우 초당 최대 요청 수는 1,000개입니다. 지원되는 다른 모든 데이터베이스의 경우 제한이 없습니다.
예를 들어, 다음 CLI 명령은 단일 SQL 문을 실행하고 결과에서 메타데이터를 생략합니다(기본값).
대상 LinuxmacOS, 또는Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"
```
Windows의 경우:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"
```
다음은 이 응답의 예입니다.
```
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}
```
다음 CLI 명령은 `--transaction-id` 옵션을 지정하여 트랜잭션에서 단일 SQL 문을 실행합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
Windows의 경우:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
```
다음은 이 응답의 예입니다.
```
{
"numberOfRecordsUpdated": 1
}
```
다음 CLI 명령은 파라미터가 있는 단일 SQL 문을 실행합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
Windows의 경우:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
```
다음은 이 응답의 예입니다.
```
{
"numberOfRecordsUpdated": 1
}
```
다음 CLI 명령은 데이터 정의 언어(DDL) SQL 문을 실행합니다. DDL 문은 `job` 열을 `role` 열로 이름을 바꿉니다.
**중요**
DDL 문에 대해서는 호출 시간이 초과된 후에도 문을 계속 실행하는 것이 좋습니다. DDL 문 실행이 끝나기 전에 종료되면 오류가 발생하고 데이터 구조가 손상될 수 있습니다. 호출이 RDS 데이터 API 시간 초과 간격인 45초를 초과한 후에도 문을 계속 실행하려면 `--continue-after-timeout` 옵션을 지정합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
Windows의 경우:
```
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
```
다음은 이 응답의 예입니다.
```
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
```
**참고**
`generatedFields` 데이터는 Aurora PostgreSQL에서 지원하지 않습니다. 생성된 필드의 값을 가져오려면 `RETURNING` 절을 사용하십시오. 자세한 내용은 PostgreSQL 설명서의 [수정된 행에서 데이터 반환](https://www.postgresql.org/docs/10/dml-returning.html) 단원을 참조하십시오.
## 데이터 배열에서 일괄 SQL 문 실행
`aws rds-data batch-execute-statement` CLI 명령을 사용하여 데이터 배열에 대해 일괄 SQL 문을 실행할 수 있습니다. 이 명령을 사용하여 일괄 가져오기 또는 업데이트 작업을 수행할 수 있습니다.
`--transaction-id` 옵션으로 트랜잭션 식별자를 지정하여 트랜잭션에서 SQL 문을 실행할 수 있습니다. `aws rds-data begin-transaction` CLI 명령을 사용하여 트랜잭션을 시작할 수 있습니다. `aws rds-data commit-transaction` CLI 명령을 사용하여 트랜잭션을 종료하고 커밋할 수 있습니다.
**중요**
`--transaction-id` 옵션을 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.
일반 옵션 외에도 다음 옵션을 지정하십시오.
+ `--sql` (필수) – DB 클러스터에서 실행할 SQL 문.
**작은 정보**
MySQL 호환 문의 경우 `--sql` 파라미터 끝에 세미콜론을 포함하지 마세요. 후행 세미콜론을 사용하면 구문 오류가 발생할 수 있습니다.
+ `--transaction-id` (선택 사항) – `begin-transaction` CLI 명령을 사용하여 시작된 트랜잭션의 식별자. SQL 문을 포함할 트랜잭션의 트랜잭션 ID를 지정하십시오.
+ `--parameter-set` (선택 사항) – 일괄 처리를 위한 파라미터 집합.
+ `--database` (선택 사항) – 데이터베이스 이름.
DB 클러스터는 호출에 대한 응답을 반환합니다.
**참고**
파라미터 세트 수는 상한이 정해져 있지 않습니다. 그러나 데이터 API를 통해 전송된 HTTP 요청의 최대 크기는 4MiB입니다. 요청이 이 제한을 초과하면 데이터 API가 오류를 반환하고 요청을 처리하지 않습니다. 이 4MiB 제한에는 요청의 HTTP 헤더와 JSON 표기법의 크기가 포함됩니다. 따라서 포함할 수 있는 파라미터 세트의 수는 SQL 문의 크기 및 각 파라미터 세트의 크기와 같은 요인의 조합에 따라 달라집니다.
응답 크기 제한은 1MiB입니다. 호출이 1MiB를 초과하는 응답 데이터를 반환하면 호출이 종료됩니다.
Aurora Serverless v1의 경우 초당 최대 요청 수는 1,000개입니다. 지원되는 다른 모든 데이터베이스의 경우 제한이 없습니다.
예를 들어, 다음 CLI 명령은 파라미터 세트를 이용해 데이터 배열에 대해 배치 SQL 문을 실행합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" \
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
Windows의 경우:
```
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "insert into mytable values (:id, :val)" ^
--parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}],
[{\"name\": \"id\", \"value\": {\"longValue\": 3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
```
**참고**
`--parameter-sets` 옵션에 줄바꿈을 포함하지 마십시오.
## SQL 트랜잭션 커밋
`aws rds-data commit-transaction` CLI 명령을 사용하여 `aws rds-data begin-transaction`으로 시작한 SQL 트랜잭션을 종료하고 변경 사항을 커밋할 수 있습니다.
일반 옵션 외에 다음 옵션을 지정하십시오.
+ `--transaction-id` (필수) – `begin-transaction` CLI 명령을 사용하여 시작된 트랜잭션의 식별자. 종료하고 커밋할 트랜잭션의 트랜잭션 ID를 지정하십시오.
예를 들어 다음 CLI 명령은 SQL 트랜잭션을 끝내고 변경 내용을 커밋합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
Windows의 경우:
```
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
다음은 이 응답의 예입니다.
```
{
"transactionStatus": "Transaction Committed"
}
```
## SQL 트랜잭션 롤백
`aws rds-data rollback-transaction` CLI 명령을 사용하여 `aws rds-data begin-transaction`으로 시작한 SQL 트랜잭션을 롤백할 수 있습니다. 트랜잭션을 롤백하면 변경 내용이 취소됩니다.
**중요**
트랜잭션 ID가 만기되었다면 트랜잭션이 자동으로 롤백된 것입니다. 이 경우 만기된 트랜잭션 ID를 지정하는 `aws rds-data rollback-transaction` 명령이 오류를 반환합니다.
일반 옵션 외에 다음 옵션을 지정하십시오.
+ `--transaction-id` (필수) – `begin-transaction` CLI 명령을 사용하여 시작된 트랜잭션의 식별자. 롤백하려는 트랜잭션의 트랜잭션 ID를 지정하십시오.
예를 들어 다음 AWS CLI 명령은 SQL 트랜잭션을 롤백합니다.
대상 LinuxmacOS, 또는Unix:
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"
```
Windows의 경우:
```
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"
```
다음은 이 응답의 예입니다.
```
{
"transactionStatus": "Rollback Complete"
}
```
# Python 애플리케이션에서 Amazon RDS Data API 직접 호출
Python 애플리케이션에서 Amazon RDS Data API(Data API)를 직접적으로 호출할 수 있습니다.
다음 예제에서는 AWS SDK for Python(Boto)을 사용합니다. Boto에 대한 자세한 내용은 [AWS SDK for Python(Boto 3) 설명서](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html)를 참조하세요.
각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.
**Topics**
+ [
## SQL 쿼리 실행
](#data-api.calling.python.run-query)
+ [
## DML SQL 문 실행
](#data-api.calling.python.run-inert)
+ [
## SQL 트랜잭션 실행
](#data-api.calling.python.run-transaction)
## SQL 쿼리 실행
`SELECT` 문을 실행하고 Python 애플리케이션으로 결과를 가져올 수 있습니다.
다음 예는 SQL 쿼리를 실행합니다.
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
response1 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'select * from employees limit 3')
print (response1['records'])
[
[
{
'longValue': 1
},
{
'stringValue': 'ROSALEZ'
},
{
'stringValue': 'ALEJANDRO'
},
{
'stringValue': '2016-02-15 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'DOE'
},
{
'stringValue': 'JANE'
},
{
'stringValue': '2014-05-09 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'STILES'
},
{
'stringValue': 'JOHN'
},
{
'stringValue': '2017-09-20 04:34:33.0'
}
]
]
```
## DML SQL 문 실행
데이터 조작 언어(DML) 문을 실행하여 데이터베이스의 데이터를 삽입, 업데이트 또는 삭제할 수 있습니다. DML 문에 파라미터를 사용할 수도 있습니다.
**중요**
호출이 `transactionID` 파라미터를 포함하지 않아서 트랜잭션의 일부가 아닌 경우 호출 결과는 자동으로 커밋됩니다.
다음 예제는 insert SQL 문을 실행하고 파라미터를 사용합니다.
```
import boto3
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
rdsData = boto3.client('rds-data')
param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]
response2 = rdsData.execute_statement(resourceArn=cluster_arn,
secretArn=secret_arn,
database='mydb',
sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
parameters = paramSet)
print (response2["numberOfRecordsUpdated"])
```
## SQL 트랜잭션 실행
SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Python 애플리케이션으로 커밋할 수 있습니다.
**중요**
3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 커밋되기 전에 트랜잭션 시간이 초과되면 자동으로 롤백됩니다.
트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.
다음 예에서는 테이블에 행을 삽입하는 SQL 트랜잭션을 실행합니다.
```
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
tr = rdsData.begin_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb')
response3 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
transactionId = tr['transactionId'])
cr = rdsData.commit_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
transactionId = tr['transactionId'])
cr['transactionStatus']
'Transaction Committed'
response3['numberOfRecordsUpdated']
1
```
**참고**
데이터 정의 언어(DDL) 문을 실행하는 경우 호출 시간이 초과된 후에도 문을 계속 실행하는 것이 좋습니다. DDL 문 실행이 끝나기 전에 종료되면 오류가 발생하고 데이터 구조가 손상될 수 있습니다. 호출이 RDS 데이터 API 시간 초과 간격인 45초를 초과한 후에도 문을 계속 실행하려면 `continueAfterTimeout` 파라미터를 `true`로 설정합니다.
# Java 애플리케이션에서 Amazon RDS Data API 직접 호출
Java 애플리케이션에서 Amazon RDS Data API(Data API)를 직접적으로 호출할 수 있습니다.
다음 예제는 AWS SDK for Java를 사용합니다. 자세한 내용은 [AWS SDK for Java 개발자 안내서](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html)를 참조하십시오.
각 예에서 DB 클러스터의 Amazon 리소스 이름(ARN)을 Aurora DB 클러스터의 ARN으로 바꿉니다. 또한 DB 클러스터에 대한 액세스를 허용하는 Secrets Manager의 보안 암호의 ARN으로 보안 암호 ARN을 바꿉니다.
**Topics**
+ [
## SQL 쿼리 실행
](#data-api.calling.java.run-query)
+ [
## SQL 트랜잭션 실행
](#data-api.calling.java.run-transaction)
+ [
## 일괄 SQL 작업 실행
](#data-api.calling.java.run-batch)
## SQL 쿼리 실행
`SELECT` 문을 실행하고 Java 애플리케이션으로 결과를 가져올 수 있습니다.
다음 예는 SQL 쿼리를 실행합니다.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;
import java.util.List;
public class FetchResultsExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb")
.withSql("select * from mytable");
ExecuteStatementResult result = rdsData.executeStatement(request);
for (List fields: result.getRecords()) {
String stringValue = fields.get(0).getStringValue();
long numberValue = fields.get(1).getLongValue();
System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
}
}
}
```
## SQL 트랜잭션 실행
SQL 트랜잭션을 시작하고 하나 이상의 SQL 문을 실행한 다음, 변경 사항을 Java 애플리케이션으로 커밋할 수 있습니다.
**중요**
3분 안에 트랜잭션 ID를 사용하는 호출이 없는 경우 트랜잭션 시간이 초과됩니다. 커밋되기 전에 트랜잭션 시간이 초과되면 자동으로 롤백됩니다.
트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.
다음 예는 SQL 트랜잭션을 실행합니다.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
public class TransactionExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb");
BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
String transactionId = beginTransactionResult.getTransactionId();
ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table VALUES ('hello world!')");
rdsData.executeStatement(executeStatementRequest);
CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN);
rdsData.commitTransaction(commitTransactionRequest);
}
}
```
**참고**
데이터 정의 언어(DDL) 문을 실행하는 경우 호출 시간이 초과된 후에도 문을 계속 실행하는 것이 좋습니다. DDL 문 실행이 끝나기 전에 종료되면 오류가 발생하고 데이터 구조가 손상될 수 있습니다. 호출이 RDS 데이터 API 시간 초과 간격인 45초를 초과한 후에도 문을 계속 실행하려면 `continueAfterTimeout` 파라미터를 `true`로 설정합니다.
## 일괄 SQL 작업 실행
Java 애플리케이션을 사용하여 데이터 배열에 대해 대량 삽입 및 업데이트 작업을 실행할 수 있습니다. 파라미터 세트의 배열을 사용하여 DML 문을 실행할 수 있습니다.
**중요**
트랜잭션 ID를 지정하지 않으면 호출 결과가 자동으로 커밋됩니다.
다음 예제에서는 대량 삽입 작업을 실행합니다.
```
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;
import java.util.Arrays;
public class BatchExecuteExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
.withDatabase("test")
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table2 VALUES (:string, :number)")
.withParameterSets(Arrays.asList(
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
),
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
)
));
rdsData.batchExecuteStatement(request);
}
}
```
# 데이터 API 시간 초과 동작 제어
데이터 API에 대한 모든 호출은 동기식입니다. `INSERT` 또는 `CREATE TABLE`과 같은 SQL 문을 실행하는 데이터 API 작업을 수행한다고 가정해 보겠습니다. 데이터 API 호출이 성공적으로 반환되면 호출이 반환되는 시점에 SQL 처리가 완료됩니다.
기본적으로 Data API는 45초 이내에 처리가 완료되지 않으면 작업을 취소하고 시간 초과 오류를 반환합니다. 이 경우 데이터가 삽입되지 않고 테이블이 생성되지 않는 등의 문제가 발생합니다.
Data API를 사용하여 45초 이내에 완료할 수 없는 장기 실행 작업을 수행할 수 있습니다. 대용량 테이블에 대한 대량 `INSERT` 또는 DDL 작업과 같은 작업이 45초보다 오래 걸릴 것으로 예상되는 경우, `ExecuteStatement` 작업에 `continueAfterTimeout` 파라미터를 지정할 수 있습니다. 애플리케이션에 여전히 시간 초과 오류가 발생합니다. 하지만 작업은 계속 실행되며 취소되지 않습니다. 문제 해결 예는 [SQL 트랜잭션 실행](data-api.calling.java.md#data-api.calling.java.run-transaction)을(를) 참조하세요.
사용 중인 프로그래밍 언어용 AWS SDK에 API 호출 또는 HTTP 소켓 연결에 대한 자체 시간 초과 기간이 있는 경우 이러한 시간 초과 기간이 모두 45초 이상인지 확인하세요. 일부 SDK의 경우 기본적으로 시간 초과 기간이 45초 미만입니다. SDK별 또는 클라이언트별 시간 초과 기간을 최소 1분으로 설정하는 것이 좋습니다. 이렇게 하면 데이터 API 작업이 성공적으로 완료되는 동안 애플리케이션에 시간 초과 오류가 발생할 가능성을 방지할 수 있습니다. 이렇게 하면 작업을 다시 시도할지 여부를 확인할 수 있습니다.
예를 들어 SDK가 애플리케이션에 시간 초과 오류를 반환하지만 데이터 API 작업이 여전히 데이터 API 시간 초과 간격 내에 완료되었다고 가정해 보겠습니다. 이 경우 작업을 다시 시도하면 중복 데이터가 삽입되거나 잘못된 결과가 발생할 수 있습니다. SDK가 자동으로 작업을 다시 시도하여 애플리케이션에서 아무런 조치를 취하지 않아도 잘못된 데이터가 발생할 수 있습니다.
시간 초과 간격은 Java 2 SDK에서 특히 중요합니다. 해당 SDK에서 API 호출 시간 초과와 HTTP 소켓 시간 초과 모두 기본적으로 30초입니다. 다음은 이러한 시간 제한을 더 높은 값으로 설정하는 예제입니다.
```
public RdsDataClient createRdsDataClient() {
return RdsDataClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.httpClientBuilder(createHttpClientBuilder())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return ApacheHttpClient.builder() // Change this to your desired HttpClient
.socketTimeout(Duration.ofSeconds(60));
}
```
다음은 비동기 데이터 클라이언트를 사용한 동일한 예제입니다.
```
public static RdsDataAsyncClient createRdsDataAsyncClient() {
return RdsDataAsyncClient.builder()
.region(Region.US_EAST_1) // Change this to your desired Region
.overrideConfiguration(createOverrideConfiguration())
.credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider
.build();
}
private static ClientOverrideConfiguration createOverrideConfiguration() {
return ClientOverrideConfiguration.builder()
.apiCallAttemptTimeout(Duration.ofSeconds(60))
.build();
}
private HttpClientBuilder createHttpClientBuilder() {
return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient
.readTimeout(Duration.ofSeconds(60));
}
```
# RDS 데이터 API용 Java 클라이언트 라이브러리 사용
RDS 데이터 API(데이터 API)용 Java 클라이언트 라이브러리를 다운로드하여 사용할 수 있습니다. 이 Java 클라이언트 라이브러리는 데이터 API를 사용할 수 있는 다른 방법을 제공합니다. 이 라이브러리를 사용하면 클라이언트 측 클래스를 데이터 API 요청 및 응답에 매핑할 수 있습니다. 이러한 매핑 지원을 통해 `Date`, `Time`, `BigDecimal` 등 일부 특정 Java 유형과 쉽게 통합할 수 있습니다.
## 데이터 API용 Java 클라이언트 라이브러리 다운로드
Data API Java 클라이언트 라이브러리는 다음 위치의 GitHub에서 오픈 소스로 제공됩니다.
[ https://github.com/awslabs/rds-data-api-client-library-java](https://github.com/awslabs/rds-data-api-client-library-java)
소스 파일에서 라이브러리를 수동으로 빌드할 수 있지만 모범 사례는 Apache Maven 종속성 관리를 사용해 라이브러리를 사용하는 것입니다. Maven POM 파일에 다음 종속성을 추가하세요.
AWS SDK 2.x와 호환되는 버전 2.x의 경우 다음을 사용하세요.
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
AWS SDK 1.x와 호환되는 버전 1.x의 경우 다음을 사용하세요.
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## Java 클라이언트 라이브러리 예시
아래에는 데이터 API Java 클라이언트 라이브러리 사용에 관한 몇 가지 일반적인 예시가 나와 있습니다. 이 예시에서는 `accounts`와 `accountId`이라는 두 개의 열이 있는 `name`라는 테이블이 있다고 가정합니다. 또한 다음과 같은 데이터 전송 객체(DTO)도 있습니다.
```
public class Account {
int accountId;
String name;
// getters and setters omitted
}
```
클라이언트 라이브러리를 통해 DTO를 입력 파라미터로 전달할 수 있습니다. 다음 예시에서는 고객 DTO가 입력 파라미터 세트로 매핑되는 방식을 보여줍니다.
```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
```
어떤 경우에는 입력 파라미터인 간단한 값으로 작업하는 것이 더 쉽습니다. 다음 구문을 사용하면 이러한 작업이 가능합니다.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
```
다음은 입력 파라미터인 간단한 값으로 작업하는 또 다른 예시입니다.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
.execute();
```
클라이언트 라이브러리에서는 결과가 반환될 때 DTO에 대한 자동 매핑을 제공합니다. 다음 예시에서는 결과가 DTO에 매핑되는 방식을 보여줍니다.
```
List result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
```
대부분의 경우 데이터베이스 결과 집합에는 단일 값만 포함됩니다. 이러한 결과 검색을 단순화하기 위해 클라이언트 라이브러리는 다음 API를 제공합니다.
```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
```
**참고**
`mapToList` 함수는 SQL 결과 집합을 사용자 정의 객체 목록으로 변환합니다. Java 클라이언트 라이브러리에 대한 `ExecuteStatement` 호출에 이 `.withFormatRecordsAs(RecordsFormatType.JSON)` 문을 사용할 수 없습니다. 동일한 용도로 사용되기 때문입니다. 자세한 내용은 [JSON 형식의 Amazon RDS Data API 쿼리 결과 처리](data-api-json.md) 섹션을 참조하세요.
# JSON 형식의 Amazon RDS Data API 쿼리 결과 처리
`ExecuteStatement` 작업을 호출할 때 쿼리 결과를 JSON 형식의 문자열로 반환하도록 선택할 수 있습니다. 이렇게 하면 프로그래밍 언어의 JSON 구문 분석 기능을 사용하여 결과 집합을 해석하고 형식을 다시 지정할 수 있습니다. 그러면 결과 집합을 반복하고 각 열 값을 해석하는 추가 코드를 작성하지 않아도 됩니다.
결과 집합을 JSON 형식으로 요청하려면 선택적으로 `formatRecordsAs` 파라미터를 `JSON` 값과 함께 전달합니다. JSON 형식의 결과 집합이 `ExecuteStatementResponse` 구조의 `formattedRecords` 필드에 반환됩니다.
`BatchExecuteStatement` 작업은 결과 집합을 반환하지 않습니다. 따라서 JSON 옵션은 해당 작업에 적용되지 않습니다.
JSON 해시 구조에서 키를 사용자 정의하려면 결과 집합에서 열 별칭을 정의합니다. SQL 쿼리의 열 목록에 있는 `AS` 절을 사용하면 됩니다.
JSON 기능을 사용하여 결과 집합을 더 쉽게 읽도록 하고 내용을 언어별 프레임워크에 매핑할 수 있습니다. ASCII로 인코딩된 결과 집합의 볼륨이 기본 표현보다 크기 때문에 많은 수의 행이나 큰 열 값을 반환하여 애플리케이션에서 사용할 수 있는 것보다 많은 메모리를 사용하는 쿼리에 기본 표현을 선택할 수 있습니다.
**Topics**
+ [
## JSON 형식의 쿼리 결과 검색
](#data-api-json-querying)
+ [
## 데이터 유형 매핑
](#data-api-json-datatypes)
+ [
## 문제 해결
](#data-api-json-troubleshooting)
+ [
## 예시
](#data-api-json-examples)
## JSON 형식의 쿼리 결과 검색
결과 집합을 JSON 문자열로 수신하려면 `ExecuteStatement` 호출에 `.withFormatRecordsAs(RecordsFormatType.JSON)`을 포함하세요. 반환 값은 `formattedRecords` 필드에 JSON 문자열로 반환됩니다. 이 경우 `columnMetadata`는 `null`입니다. 열 레이블은 각 행을 나타내는 객체의 키입니다. 이 열 이름은 결과 집합의 각 행에서 반복됩니다. 열 값은 따옴표로 묶인 문자열, 숫자 값 또는 `true`, `false` 또는 `null`을 나타내는 특수 값입니다. 길이 제약 조건 및 숫자 및 문자열의 정확한 유형과 같은 열 메타데이터는 JSON 응답에 보존되지 않습니다.
`.withFormatRecordsAs()` 호출을 생략하거나 `NONE`의 파라미터를 지정하는 경우 결과 집합은 `Records` 및 `columnMetadata` 필드를 사용하여 이진 형식으로 반환됩니다.
## 데이터 유형 매핑
결과 집합의 SQL 값은 더 작은 JSON 유형 집합에 매핑됩니다. 값은 JSON에서 문자열, 숫자 및 `true`, `false` 및 `null`과 같은 특수 상수로 표시됩니다. 프로그래밍 언어에 적합하도록 강한 타이핑 또는 약한 타이핑을 사용하여 이 값을 애플리케이션에서 변수로 변환할 수 있습니다.
****
| JDBC 데이터 유형 | JSON 데이터 유형 |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | 기본적으로 숫자입니다. `LongReturnType` 옵션이 `STRING`으로 설정되어 있으면 문자열입니다. |
| `FLOAT`, `REAL`, `DOUBLE` | 숫자 |
| `DECIMAL` | 기본적으로 문자열입니다. `DecimalReturnType` 옵션이 `DOUBLE_OR_LONG`으로 설정되어 있으면 숫자입니다. |
| `STRING` | 문자열 |
| `BOOLEAN`, `BIT` | 부울 |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | base64 인코딩의 문자열입니다. |
| `CLOB` | String |
| `ARRAY` | Array |
| `NULL` | `null` |
| 다른 형식(날짜 및 시간과 관련된 형식 포함) | String |
## 문제 해결
JSON 응답은 10MB로 제한됩니다. 응답이 이 한도보다 크면 프로그램에서 `BadRequestException` 오류를 받습니다. 이런 경우 다음 기법 중 하나를 사용하여 오류를 해결할 수 있습니다.
+ 결과 집합에서 행의 수를 줄입니다. `LIMIT` 절을 추가하면 됩니다. `LIMIT` 및 `OFFSET` 절이 있는 여러 쿼리를 제출하여 큰 결과 집합을 여러 개의 작은 결과 집합으로 나눌 수 있습니다.
결과 집합에 애플리케이션 로직별로 필터링된 행이 포함되어 있는 경우 `WHERE` 절에 조건을 더 추가하여 결과 집합에서 해당 행을 제거할 수 있습니다.
+ 결과 집합에서 열의 수를 줄입니다. 쿼리의 선택 목록에서 항목을 제거하면 됩니다.
+ 쿼리에서 열 별칭을 사용하여 열 레이블을 줄입니다. 각 열 이름은 결과 집합의 각 행에 대한 JSON 문자열에서 반복됩니다. 따라서 열 이름이 길고 행이 많은 쿼리 결과는 크기 제한을 초과할 수 있습니다. 특히 복잡한 표현식에 열 별칭을 사용하면 JSON 문자열에서 전체 표현식이 반복되는 것을 방지할 수 있습니다.
+ SQL을 사용하면 열 별칭을 사용하여 동일한 이름의 열이 두 개 이상 있는 결과 집합을 생성할 수 있지만 JSON에서는 중복 키 이름이 허용되지 않습니다. 결과 집합을 JSON 형식으로 요청하고 둘 이상의 열의 이름이 같은 경우 RDS Data API에서 오류를 반환합니다. 따라서 모든 열 레이블의 이름이 고유하도록 해야 합니다.
## 예시
다음 Java 예제는 응답이 JSON 형식의 문자열인 `ExecuteStatement`를 호출한 후 결과 집합을 해석하는 방법을 보여줍니다. *databaseName*, *secretStoreArn* 및 *clusterArn* 파라미터를 적절한 값으로 대체합니다.
다음 Java 예제에서는 결과 집합에서 소수 값을 반환하는 쿼리를 보여줍니다. `assertThat` 호출은 응답 필드에 JSON 결과 집합에 대한 규칙을 기반으로 예상되는 속성이 있는지 테스트합니다.
이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.
```
create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);
```
```
public void JSON_result_set_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request);
}
```
이전 프로그램의 `formattedRecords` 필드 값은 다음과 같습니다.
```
[{"a":10.0}]
```
JSON 결과 집합이 있기 때문에 응답의 `Records` 및 `ColumnMetadata` 필드는 모두 Null입니다.
다음 Java 예제에서는 결과 집합에서 정수 값을 반환하는 쿼리를 보여줍니다. 예제는 `getFormattedRecords`를 호출하여 JSON 형식의 문자열만 반환하고 비어 있거나 Null인 다른 응답 필드는 무시합니다. 이 예제에서는 결과를 레코드 목록을 나타내는 구조로 역직렬화합니다. 각 레코드에는 이름이 결과 집합의 열 별칭에 해당하는 필드가 있습니다. 이 기법은 결과 집합을 구문 분석하는 코드를 단순화합니다. 애플리케이션에서 결과 집합의 행과 열을 반복하여 각 값을 적절한 유형으로 변환할 필요가 없습니다.
이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.
```
create table test_simplified_json (a int);
insert into test_simplified_json values(17);
```
```
public void JSON_deserialization_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request)
.getFormattedRecords();
/* Turn the result set into a Java object, a list of records.
Each record has a field 'a' corresponding to the column
labelled 'a' in the result set. */
private static class Record { public int a; }
var recordsList = new ObjectMapper().readValue(
response, new TypeReference>() {
});
}
```
이전 프로그램의 `formattedRecords` 필드 값은 다음과 같습니다.
```
[{"a":17}]
```
결과 행 0의 `a` 열을 검색하려면 애플리케이션은 `recordsList.get(0).a`를 참조합니다.
반대로 다음 Java 예제에서는 JSON 형식을 사용하지 않을 때 결과 집합을 포함하는 데이터 구조를 구성하는 데 필요한 코드 종류를 보여줍니다. 이 경우 결과 집합의 각 행에는 단일 사용자에 대한 정보가 포함된 필드가 포함됩니다. 결과 집합을 나타내는 데이터 구조를 구축하려면 행을 반복해야 합니다. 각 행에 대해 코드는 각 필드의 값을 검색하고 적절한 형식 변환을 수행하며 행을 나타내는 객체의 해당 필드에 결과를 할당합니다. 그런 다음 코드는 각 사용자를 나타내는 객체를 전체 결과 집합을 나타내는 데이터 구조에 추가합니다. 결과 집합에서 필드를 재정렬, 추가 또는 제거하도록 쿼리가 변경된 경우 애플리케이션 코드도 변경해야 합니다.
```
/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
var user = User.builder()
.userId(row.get(0).getLongValue())
.firstName(row.get(1).getStringValue())
.lastName(row.get(2).getStringValue())
.dob(Instant.parse(row.get(3).getStringValue()))
.build();
result.add(user);
}
```
다음 샘플 값은 열, 열 별칭 및 열 데이터 유형이 서로 다른 결과 집합에 대한 `formattedRecords` 필드의 값을 보여줍니다.
결과 집합에 여러 행이 포함된 경우 각 행은 배열 요소인 객체로 표시됩니다. 결과 집합의 각 열은 객체 내에서 키가 됩니다. 키는 결과 집합의 각 행에서 반복됩니다. 따라서 여러 행과 열로 구성된 결과 집합의 경우 전체 응답의 길이 제한을 초과하지 않도록 짧은 열 별칭을 정의해야 할 수 있습니다.
이 예제는 다음 스키마 및 샘플 데이터에서 작동합니다.
```
create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
```
```
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
```
결과 집합의 열이 표현식으로 정의된 경우 표현식의 텍스트가 JSON 키가 됩니다. 따라서 일반적으로 쿼리의 선택 목록에서 각 표현식에 대한 설명 열 별칭을 정의하는 것이 편리합니다. 예를 들어, 다음 쿼리는 선택 목록에 함수 호출 및 산술 연산과 같은 표현식을 포함합니다.
```
select count(*), max(id), 4+7 from sample_names;
```
이러한 표현식은 키로 JSON 결과 집합을 통해 전달됩니다.
```
[{"count(*)":5,"max(id)":4,"4+7":11}]
```
설명 레이블이 있는 `AS` 열을 추가하면 JSON 결과 집합에서 키를 보다 간단하게 해석할 수 있습니다.
```
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
```
수정된 SQL 쿼리의 경우, `AS` 절에 의해 정의된 열 레이블이 키 이름으로 사용됩니다.
```
[{"rows":5,"largest_id":4,"addition_result":11}]
```
JSON 문자열의 각 키 값 쌍의 값은 따옴표로 묶인 문자열일 수 있습니다. 문자열에는 유니코드 문자가 포함될 수 있습니다. 문자열에 이스케이프 시퀀스가 포함되어 있거나 `"` 또는 `\`문자가 포함되어 있는 경우 이러한 문자 앞에는 백슬래시 이스케이프 문자가 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다. 예를 들어 `string_with_escape_sequences` 결과에는 특수 문자 백스페이스, 줄 바꿈, 캐리지 리턴, 탭, 양식 피드 및 `\`가 포함됩니다.
```
[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
```
JSON 문자열의 각 키 값 쌍의 값은 숫자를 나타낼 수도 있습니다. 숫자는 정수, 부동 소수점 값, 음수 값 또는 지수 표기법으로 표현되는 값일 수 있습니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.
```
[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
```
부울 값과 Null 값은 따옴표 없는 특수 키워드 `true`, `false` 및 `null`로 표현됩니다. 다음 JSON 문자열의 예제는 이러한 가능성을 보여줍니다.
```
[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]
```
BLOB 유형의 값을 선택하면 결과가 JSON 문자열에서 base64로 인코딩된 값으로 표시됩니다. 값을 원래 표현으로 다시 변환하려면 애플리케이션의 언어로 적절한 디코딩 기능을 사용할 수 있습니다. 예를 들어 Java에서는 `Base64.getDecoder().decode()` 함수를 호출합니다. 다음 샘플 출력은 `hello world`의 BLOB 값을 선택하고 결과 집합을 JSON 문자열로 반환한 것을 보여줍니다.
```
[{"blob_column":"aGVsbG8gd29ybGQ="}]
```
다음 Python 예제는 Python `execute_statement` 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 `response['formattedRecords']`의 문자열 값입니다. 이 코드는 `json.loads` 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 목록 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.
```
import json
result = json.loads(response['formattedRecords'])
print (result[0]["id"])
```
다음 JavaScript 예제는 JavaScript `executeStatement` 함수에 대한 호출의 결과에서 값에 액세스하는 방법을 보여줍니다. 결과 집합은 필드 `response.formattedRecords`의 문자열 값입니다. 이 코드는 `JSON.parse` 함수를 호출하여 JSON 문자열을 데이터 구조로 변환합니다. 그러면 결과 집합의 각 행은 데이터 구조 내의 배열 요소이며 각 행 내에서 이름으로 결과 집합의 각 필드를 참조할 수 있습니다.
```
```
# Amazon RDS Data API 문제 해결
공통 오류 메시지로 제목이 지정된 다음 섹션은 Amazon RDS Data API(Data API)를 사용하면서 발생하는 문제를 해결하는 데 유용합니다.
**Topics**
+ [
## 트랜잭션 을 찾을 수 없음
](#data-api.troubleshooting.tran-id-not-found)
+ [
## 쿼리 패킷이 너무 큽니다
](#data-api.troubleshooting.packet-too-large)
+ [
## 데이터베이스 응답이 크기 제한을 초과했습니다
](#data-api.troubleshooting.response-size-too-large)
+ [
## HttpEndpoint가 클러스터 에서 활성화되지 않음
](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [
## DatabaseErrorException: 트랜잭션이 여전히 쿼리 실행 중
](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [
## 지원되지 않는 결과 예외
](#data-api.troubleshooting.unsupported-result)
+ [
## 다중 문은 지원되지 않음
](#data-api.troubleshooting.multi-statements)
+ [
## 스키마 파라미터는 지원되지 않음
](#data-api.troubleshooting.schema-parameter)
+ [
## IPv6 연결 문제
](#data-api.troubleshooting.ipv6-connectivity)
## 트랜잭션 을 찾을 수 없음
위 오류 메시지는 데이터 API 호출 시 지정한 트랜잭션 ID를 찾을 수 없다는 것을 의미합니다. 이러한 문제가 발생하는 원인이 오류 메시지에 추가되며, 다음 중 한 가지로 표시됩니다.
+ 트랜잭션이 만료될 수 있습니다.
각 트랜잭션 호출은 지난 호출 이후 3분 이내에 실행되어야 합니다.
지정된 트랜잭션 ID가 [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) 호출에 의해 생성되지 않았을 수도 있습니다. 호출 시 유효한 트랜잭션 ID를 지정해야 합니다.
+ 하나의 이전 호출로 인해 트랜잭션이 종료되었습니다.
`CommitTransaction` 또는 `RollbackTransaction` 호출에 의해 트랜잭션이 이미 종료되었습니다.
+ 이전 호출의 오류로 인해 트랜잭션이 중단되었습니다.
이전 호출에서 예외가 발생했는지 확인합니다.
트랜잭션 실행에 대한 자세한 내용은 [Amazon RDS Data API 직접 호출](data-api.calling.md) 섹션을 참조하세요.
## 쿼리 패킷이 너무 큽니다
위 오류 메시지는 행마다 반환되는 결과 집합이 너무 크다는 것을 의미합니다. 데이터 API는 데이터베이스에서 반환되는 결과 집합에서 각 행의 크기를 64KB로 제한합니다.
이 문제를 해결하려면 결과 집합의 각 행마다 크기를 64KB 이하로 유지해야 합니다.
## 데이터베이스 응답이 크기 제한을 초과했습니다
위 오류 메시지는 데이터베이스에서 반환되는 결과 집합의 크기가 너무 크다는 것을 의미합니다. Data API는 데이터베이스에서 반환되는 결과 집합의 크기를 1MiB로 제한합니다.
이러한 문제를 해결하려면 데이터 API 호출 시 반환되는 데이터 크기를 1MiB 이하로 유지해야 합니다. 반환해야 하는 결과 집합의 크기가 1MiB보다 크면 쿼리에서 다수의 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) 호출을 `LIMIT` 절과 함께 사용할 수 있습니다.
`LIMIT` 절에 대한 자세한 내용은 MySQL 설명서에서 [SELECT 구문](https://dev.mysql.com/doc/refman/8.0/en/select.html)을 참조하세요.
## HttpEndpoint가 클러스터 에서 활성화되지 않음
이 문제의 잠재적인 원인은 다음과 같습니다.
+ Aurora DB 클러스터는 데이터 API를 지원하지 않습니다. RDS 데이터 API가 지원하는 DB 클러스터 유형에 대한 자세한 내용은 [Amazon RDS Data API의 리전 및 버전 가용성](data-api.regions.md) 섹션을 참조하세요.
+ Aurora DB 클러스터에서 데이터 API가 활성화되어 있지 않습니다. Aurora DB 클러스터에서 데이터 API를 사용하려면 DB 클러스터에서 데이터 API를 먼저 활성화해야 합니다. 데이터 API 활성화에 대한 자세한 내용은 [Amazon RDS Data API 활성화](data-api.enabling.md) 섹션을 참조하세요.
+ 데이터 API가 활성화된 후 DB 클러스터의 이름이 바뀌었습니다. 이 경우 해당 클러스터에 대한 데이터 API를 끄고 다시 활성화하세요.
+ 지정한 ARN이 클러스터의 ARN과 정확하게 일치하지 않습니다. 다른 소스에서 반환되었거나 프로그램 논리로 구성된 ARN이 클러스터의 ARN과 정확히 일치하는지 확인합니다. 예를 들어 사용하는 ARN에서 모든 영문자의 대소문자가 올바른지 확인하세요.
## DatabaseErrorException: 트랜잭션이 여전히 쿼리 실행 중
애플리케이션이 트랜잭션 ID로 요청을 보내고 해당 트랜잭션이 현재 다른 요청을 처리 중인 경우 데이터 API는 이 오류를 애플리케이션에 즉시 반환합니다. 이 조건은 애플리케이션이 Javascript의 'promises'와 같은 메커니즘을 사용하여 비동기식 요청을 하는 경우 발생할 수 있습니다.
이 문제를 해결하려면 이전 요청이 완료될 때까지 기다린 다음 요청을 다시 시도하세요. 오류가 더 이상 발생하지 않거나 애플리케이션에 몇 가지 다른 오류가 수신될 때까지 계속 재시도를 할 수 있습니다.
이 조건은 Aurora Serverless v2용 데이터 API 및 프로비저닝된 인스턴스에서 발생할 수 있습니다. Aurora Serverless v1용 데이터 API에서 동일한 트랜잭션 ID에 대한 후속 요청은 이전 요청이 완료될 때까지 자동으로 대기합니다. 그러나 이전 요청이 너무 오래 걸려서 이전 동작에 제한 시간 초과가 발생할 수 있습니다. 동시 요청을 하는 이전 데이터 API 애플리케이션을 이식하는 경우 예외 처리 로직을 수정하여 이 새로운 종류의 오류를 처리하세요.
## 지원되지 않는 결과 예외
데이터 API가 모든 데이터 유형을 지원하는 것은 아닙니다. 이 오류는 지원되지 않는 데이터 유형을 반환하는 쿼리를 실행할 때 발생합니다.
이 문제를 해결하려면 지원되지 않는 데이터 유형을 `TEXT`로 캐스팅합니다. 예제:
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## 다중 문은 지원되지 않음
Aurora Serverless v2 및 프로비저닝된 클러스터용 데이터 API에서는 다중 문이 지원되지 않습니다. 단일 API 직접 호출에서 다중 문을 실행하려고 하면 이 오류가 발생합니다.
다중 문을 실행하려면 별도의 `ExecuteStatement` API 직접 호출을 사용하거나 배치 처리를 위해 `BatchExecuteStatement` API를 사용합니다.
## 스키마 파라미터는 지원되지 않음
Aurora Serverless v1은 스키마 파라미터를 자동으로 무시합니다. 그러나 Aurora Serverless v2 및 프로비저닝된 클러스터는 스키마 파라미터를 포함하는 API 직접 호출을 명시적으로 거부합니다.
이 문제를 해결하려면 Aurora Serverless v2 또는 프로비저닝된 클러스터를 사용할 때 데이터 API에 대한 모든 직접 호출에서 스키마 파라미터를 제거합니다.
## IPv6 연결 문제
IPv6 엔드포인트를 사용하여 데이터 API에 연결할 때 문제가 발생하면 다음과 같은 잠재적 원인을 확인하세요.
+ **네트워크가 IPv6를 지원하지 않음**: 네트워크 인프라가 IPv6를 지원하고 IPv6 라우팅이 올바르게 구성되었는지 확인합니다.
+ **DNS 해결 문제**: DNS 해석기가 듀얼 스택 엔드포인트(예: `rds-data.us-east-1.api.aws`)에 대한 AAAA 레코드를 해결할 수 있는지 확인합니다.
+ **보안 그룹 구성**: 포트 443(HTTPS)에서 IPv6 트래픽을 허용하도록 보안 그룹 규칙을 업데이트합니다. IPv6 CIDR 블록에 대한 규칙을 추가합니다(예: 모든 IPv6 주소에 대해 `::/0`).
+ **네트워크 ACL 구성**: 네트워크 ACL이 필요한 포트에서 IPv6 트래픽을 허용하는지 확인합니다.
+ **클라이언트 라이브러리 호환성**: HTTP 클라이언트 라이브러리 및 AWS SDK를 지원하는지 확인합니다.
+ **VPC 엔드포인트 구성**: PrivateLink를 사용하는 경우 VPC 엔드포인트가 IPv6를 지원하도록 구성되어 있고 연결된 서브넷에 IPv6 CIDR 블록이 할당되어 있는지 확인합니다.
IPv6 연결 문제 해결:
1. IPv4 전용 엔드포인트(`.amazonaws.com`)를 사용하여 연결을 테스트하여 문제가 IPv6에만 해당하는지 확인합니다.
1. 네트워크 진단 도구를 사용하여 듀얼 스택 엔드포인트에 대한 IPv6 연결을 확인합니다.
1. IPv6 엔드포인트를 사용할 때 CloudTrail 로그에 인증 또는 권한 부여 오류가 있는지 확인합니다.
1. 애플리케이션이 새 듀얼 스택 엔드포인트 URL을 사용하도록 올바르게 구성되어 있는지 확인합니다.
# AWS CloudTrail을 사용하여 Amazon RDS Data API 직접 호출 로깅
RDS 데이터 API(데이터 API)는 사용자, 역할, AWS 서비스가 데이터 API에서 수행한 작업의 레코드를 제공하는 서비스, AWS CloudTrail과 통합됩니다. CloudTrail은 Amazon RDS 콘솔의 호출과 데이터 API 작업에 대한 코드 호출의 호출을 포함하여 데이터 API에 대한 모든 API 호출을 이벤트로 캡처합니다. 추적을 생성하면 데이터 API 이벤트를 비롯하여 CloudTrail 이벤트를 Amazon S3 버킷으로 지속적으로 배포하도록 할 수 있습니다. CloudTrail에서 수집한 데이터를 사용하여 많은 정보를 확인할 수 있습니다. 이 정보에는 Data API로 한 요청, 요청한 IP 주소, 요청 주체, 요청 시점 및 추가 세부 정보가 포함됩니다.
CloudTrail에 대한 자세한 내용은 [AWS CloudTrail 사용 설명서](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/)를 참조하세요.
## CloudTrail의 데이터 API 정보 작업
CloudTrail은 계정 생성 시 AWS 계정에서 사용되도록 설정됩니다. 데이터 API에서 지원되는 활동(관리 이벤트)이 발생하면 해당 활동은 **이벤트 기록**에 다른 AWS 서비스 이벤트와 함께 CloudTrail 이벤트에 기록됩니다. AWS 계정에서 최신 관리 이벤트를 확인, 검색 및 다운로드할 수 있습니다. 자세한 설명은 *AWS CloudTrail 사용 설명서*의 [CloudTrail 이벤트 기록 작업](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html)을 참조하세요.
데이터 API의 이벤트를 포함하여 AWS 계정에 이벤트를 지속적으로 기록하려는 경우 추적을 생성합니다. CloudTrail은 *추적*을 사용하여 Amazon S3 버킷으로 로그 파일을 전송할 수 있습니다. 콘솔에서 추적을 생성하면 기본적으로 모든 AWS Region에 추적이 적용됩니다. 추적은 AWS 파티션에 있는 모든 AWS 리전의 이벤트를 로깅하고 지정한 Amazon S3 버킷으로 로그 파일을 전송합니다. 또는 CloudTrail 로그에서 수집된 이벤트 데이터를 추가 분석 및 처리하도록 다른 AWS 서비스를 구성할 수 있습니다. 자세한 내용은 AWS CloudTrail 사용 설명서**에서 다음 주제를 참조하세요.
+ [추적 생성 개요](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail 지원 서비스 및 통합](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [CloudTrail에 대한 Amazon SNS 알림 구성](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [여러 리전에서 CloudTrail 로그 파일 수신](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) 및 [여러 계정에서 CloudTrail 로그 파일 수신](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
모든 데이터 API 작업은 CloudTrail이 기록하고 [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html)에 문서화됩니다. 예를 들어 `BatchExecuteStatement`, `BeginTransaction`, `CommitTransaction`, `ExecuteStatement` 작업에 대한 호출은 CloudTrail 로그 파일의 항목을 생성합니다.
모든 이벤트 및 로그 항목에는 요청을 생성한 사용자에 대한 정보가 들어 있습니다. 보안 인증 정보를 이용하면 다음을 쉽게 판단할 수 있습니다.
+ 요청을 루트로 했는지 아니면 사용자 자격 증명으로 했는지 여부
+ 역할 또는 페더레이션 사용자에 대한 임시 보안 인증을 사용하여 요청이 생성되었는지 여부.
+ 다른 AWS 서비스에서 요청했는지.
자세한 내용은 [CloudTrail userIdentity 요소](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html)를 참조하세요.
## AWS CloudTrail 추적에서 데이터 API 이벤트 포함 및 제외
대부분의 데이터 API 사용자는 AWS CloudTrail 추적의 이벤트에 의존하여 데이터 API 작업에 대한 기록을 제공합니다 이벤트 데이터는 데이터 API에 대한 요청의 데이터베이스 이름, 스키마 이름 또는 SQL 문을 나타내지 않습니다. 하지만 구체적인 시간에 어떤 사용자가 특정 DB 클러스터에 대해 호출을 했는지 알면 비정상적인 액세스 패턴을 감지하는 데 도움이 될 수 있습니다.
### AWS CloudTrail 추적에서 데이터 API 이벤트 포함
Aurora PostgreSQL Serverless v2 및 프로비저닝된 데이터베이스의 경우 다음과 같은 데이터 API 작업이 AWS CloudTrail에 데이터 이벤트**로 로깅됩니다. [데이터 이벤트](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events)는 CloudTrail이 기본적으로 로깅하지 않는 대용량 데이터 영역 API 작업입니다. 데이터 이벤트에는 추가 요금이 적용됩니다. CloudTrail 요금에 대한 자세한 내용은 [AWS CloudTrail 요금](https://aws.amazon.com/cloudtrail/pricing/)을 참조하세요.
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
CloudTrail 콘솔, AWS CLI 또는 CloudTrail API 작업을 사용하여 이러한 데이터 API 작업을 로깅할 수 있습니다. CloudTrail 콘솔에서 데이터 이벤트 유형으로 **RDS 데이터 API - DB 클러스터**를 선택합니다. 자세한 내용을 알아보려면 AWS CloudTrail 사용 설명서**의 [AWS Management Console을 사용한 데이터 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI)을 참조하세요.
AWS CLI를 통해 `aws cloudtrail put-event-selectors` 명령을 실행하여 추적에 대한 데이터 API 작업을 로깅합니다. DB 클러스터에 모든 Data API 이벤트를 로깅하려면 리소스 유형으로 `AWS::RDS::DBCluster`를 지정하세요. 다음 예시는 모든 데이터 API 이벤트를 DB 클러스터에 로깅합니다. 자세한 내용을 알아보려면 AWS CloudTrail 사용 설명서**의 [AWS Command Line Interface을 사용한 데이터 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html)을 참조하세요.
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
`readOnly`, `eventName,` 및 `resources.ARN` 필드를 추가로 필터링하도록 고급 이벤트 선택기를 구성할 수 있습니다. 이러한 필드에 대한 자세한 내용은 [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html)를 참조하세요.
### AWS CloudTrail 추적에서 데이터 API 이벤트 제외(Aurora Serverless v1 전용)
Aurora Serverless v1의 경우, 데이터 API 이벤트는 관리 이벤트입니다. 기본적으로 모든 데이터 API 이벤트는 AWS CloudTrail 추적에 포함됩니다. 그러나 데이터 API는 수많은 이벤트를 생성할 수 있으므로, CloudTrail 추적에서 이러한 이벤트를 제외할 수 있습니다. **Amazon RDS 데이터 API 이벤트 제외** 설정은 모든 데이터 API 이벤트를 추적에서 제외합니다. 특정 데이터 API 이벤트는 제외할 수 없습니다.
추적에서 데이터 API 이벤트를 제외하려면 다음을 수행합니다.
+ CloudTrail 콘솔에서 [추적을 생성](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html)하거나 [추적을 업데이트](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html)할 때 [**Amazon RDS 데이터 API 이벤트 제외(Exclude Amazon RDS Data API events)**] 설정을 선택합니다.
+ CloudTrail API에서 [PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html) 작업을 사용합니다. 고급 이벤트 선택기를 사용하는 경우 `eventSource` 필드를 `rdsdata.amazonaws.com`과 같지 않게 설정하여 데이터 API 이벤트를 제외할 수 있습니다. 기본 이벤트 선택기를 사용하는 경우 `ExcludeManagementEventSources` 속성 값을 `rdsdata.amazonaws.com`으로 설정하여 데이터 API 이벤트를 제외할 수 있습니다. 자세한 내용을 알아보려면 AWS CloudTrail 사용 설명서**의 [AWS Command Line Interface을 사용한 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI)을 참조하세요.
**주의**
CloudTrail 로그에서 데이터 API 이벤트를 제외하면 데이터 API 작업이 모호해질 수 있습니다. 보안 주체에게 이 작업을 수행하는 데 필요한 `cloudtrail:PutEventSelectors` 권한을 부여할 때는 주의해야 합니다.
콘솔 설정 또는 추적용 이벤트 선택기를 변경하여 언제든지 이 제외를 비활성화할 수 있습니다. 그러면 추적이 데이터 API 이벤트 기록을 시작합니다. 그러나 제외가 유효한 동안 발생한 데이터 API 이벤트는 복구할 수 없습니다.
콘솔 또는 API를 사용하여 데이터 API 이벤트를 제외하면 결과로 나타나는 CloudTrail `PutEventSelectors` API 작업도 CloudTrail Logs에 기록됩니다. 데이터 API 이벤트가 CloudTrail Logs에 나타나지 않으면 `ExcludeManagementEventSources` 속성이 `rdsdata.amazonaws.com`으로 설정된 `PutEventSelectors` 이벤트를 찾습니다.
자세한 내용은 *AWS CloudTrail 사용 설명서*의 [추적 관리 이벤트 로깅](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html)을 참조하세요.
## 데이터 API 로그 파일 항목 이해
*추적*이란 지정한 Amazon S3 버킷에 이벤트를 로그 파일로 입력할 수 있게 하는 구성입니다. CloudTrail 로그 파일에는 하나 이상의 로그 항목이 포함될 수 있습니다. 이벤트**는 모든 소스로부터의 단일 요청을 나타내며 요청 작업, 작업 날짜와 시간, 요청 파라미터 등에 대한 정보가 들어 있습니다. CloudTrail 로그 파일은 퍼블릭 API 직접 호출의 주문 스택 트레이스가 아니므로 특정 순서로 표시되지 않습니다.
**Aurora PostgreSQL Serverless v2 및 프로비저닝**
다음은 Aurora PostgreSQL Serverless v2와 프로비저닝된 데이터베이스의 `ExecuteStatement` 작업을 보여주는 CloudTrail 로그 항목을 나타낸 예제입니다. 이러한 데이터베이스의 경우, 모든 데이터 API 이벤트는 이벤트 소스가 **rdsdataapi.amazonaws.com**이고 이벤트 유형이 **Rds 데이터 서비스**인 데이터 이벤트입니다.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
다음 예는 위의 예제 CloudTrail 로그 항목이 Aurora Serverless v1에 대해 어떻게 나타나는지 보여줍니다. Aurora Serverless v1의 경우, 모든 이벤트는 이벤트 소스가 **rdsdata.amazonaws.com**이고 이벤트 유형이 **AwsApiCall**인 관리 이벤트입니다.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# 성능 개선 도우미를 사용한 RDS 데이터 API 쿼리 모니터링
Aurora 클러스터가 Aurora Serverless v2 또는 프로비저닝된 인스턴스를 실행 중인 경우 RDS 데이터 API와 함께 성능 개선 도우미를 사용할 수 있습니다.
Aurora와 함께 성능 개선 도우미를 사용하는 방법에 대한 자세한 내용은 [성능 개선 도우미를 통한 Amazon Aurora 모니터링](USER_PerfInsights.md) 섹션을 참조하세요.
## 성능 개선 도우미에서 RDS 데이터 API 쿼리를 나타내는 방법
데이터 API를 사용하면 Aurora 클러스터는 애플리케이션에서 제출한 데이터 API 호출을 기반으로 쿼리를 처리합니다. 또한 데이터 API는 제한 시간 임계값을 초과하는 쿼리 취소와 같은 내부 작업의 일부로 일부 SQL 문을 수행합니다. 두 종류의 SQL 작업은모두 성능 개선 도우미 통계 및 차트에 표시됩니다.
+ Aurora 클러스터에 제출하는 데이터 API 쿼리의 경우 PI 대시보드의 **호스트** 필드가 **RDS 데이터 API **로 표시됩니다. Aurora PostgreSQL의 경우 **application\$1name** 필드에 `rds-data-api` 값이 있습니다. **상위 호스트** 또는 **상위 애플리케이션**을 차원으로 사용하여 데이터베이스 로드를 분석할 때 이러한 레이블을 찾습니다.
+ 연결 풀 및 쿼리 제한 시간과 같은 데이터베이스 측면을 관리하기 위해 데이터 API가 실행하는 모든 내부 쿼리는 접두사 **RDS 데이터 API**로 주석이 지정됩니다. 예: `/* RDS Data API */ select * from my_table;`은 **상위 SQL**을 차원으로 데이터베이스 로드를 분석할 때 이러한 접두사를 찾습니다. 문에는 `/* RDS Data API */`의 SQL 주석이 달립니다.