# 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));
}
```