# Amazon RDS Data API の呼び出し
Aurora DB クラスターで Amazon RDS Data API (Data API) を有効にした状態で、Data API または AWS CLI により、Aurora DB クラスターで SQL ステートメントを実行できます。Data 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)
+ [Data API タイムアウト動作の制御](data-api-timeouts.md)
# Amazon RDS Data API オペレーションリファレンス
Amazon RDS Data API では、以下のオペレーションを使用して、SQL ステートメントを実行することができます。
****
| Data 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 ステートメントを実行したり、トランザクションを実行したりできます。トランザクションの場合、Data API は次のオペレーションを提供します。
****
| Data 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 ステートメントを実行し、トランザクションをサポートするためのオペレーションには、以下の共通の Data API パラメータおよび AWS CLI オプションがあります。他のパラメータやオプションをサポートするオペレーションもあります。
****
| Data API オペレーションのパラメータ | AWS CLI コマンドオプション | 必須 | 説明 |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | はい | Aurora DB クラスターの Amazon リソースネーム (ARN)。クラスターは、Data API を呼び出す IAM ロールまたはユーザーと同じ AWS アカウントにある必要があります。別のアカウントのクラスターにアクセスするには、そのアカウントのロールを引き受けます。 |
| `secretArn` | `--secret-arn` | はい | DB クラスターへのアクセスを有効にするシークレットの ARN の名前。 |
RDS Data 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 Data 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 Data 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[]`
パラメータは、Data API の `ExecuteStatement` および `BatchExecuteStatement` への呼び出しと、AWS CLI の `execute-statement` コマンドおよび `batch-execute-statement` コマンドの実行時に使用できます。パラメータを使用するには、名前と値のペアを `SqlParameter` データ型で指定します。値は、`Field` データ型で指定します。次の表は、Data API 呼び出しで指定したデータ型に Java Database Connectivity (JDBC) データ型をマッピングしたものです。
****
| JDBC データ型 | Data API のデータ型 |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG`\$1 または `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` などの特定のタイプでは、Data 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` タイプのオブジェクトとしてデータベースに送信されます。
**注記**
現在、Data API はユニバーサル固有識別子 (UUID) の配列をサポートしていません。
**注記**
Amazon Aurora PostgreSQL の場合、Data API は常に UTC タイムゾーンの Aurora PostgreSQL データ型 `TIMESTAMPTZ` を返します。
# AWS CLI を使用した Amazon RDS Data API の呼び出し
RDS Data API (Data API) は、AWS CLI を使用して呼び出すことができます。
以下の例では、Data API で AWS CLI を使用しています。詳細については、[AWS CLI reference for the Data API](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html) を参照してください。
それぞれの例で、DB クラスターの Amazon リソースネーム (ARN) を Aurora DB クラスターの ARN に置き換えます。また、シークレット ARN を Secrets Manager のシークレットの ARN に置き換え、DB クラスターへのアクセスを許可します。
**注記**
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 トランザクションのスタート
SQL トランザクションをスタートするには、CLI の `aws rds-data begin-transaction` コマンドを使用します。コールによって、トランザクション識別子が返ります。
**重要**
Data API では、3 分以内にトランザクション ID を使用する呼び出しがないと、トランザクションはタイムアウトします。トランザクションがコミットされる前にタイムアウトした場合、Data API は自動的にロールバックします。
トランザクション内の MySQL データ定義言語 (DDL) ステートメントは、暗黙的なコミットを引き起こします。各 MySQL DDL ステートメントは、`execute-statement` コマンドに `--continue-after-timeout` オプションを指定して、個別に実行することをお勧めします。
共通オプションに加えて、`--database` オプションを指定します。オプションには、データベースの名前を指定します。
例えば、次の CLI コマンドでは、SQL トランザクションを起動します。
Linux、macOS、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 ステートメントの実行
SQL ステートメントを実行するには、CLI の `aws rds-data execute-statement` を使用します。
SQL ステートメントをトランザクションで実行するには、`--transaction-id` オプションとあわせてトランザクション識別子を指定します。トランザクションをスタートするには、CLI の `aws rds-data begin-transaction` コマンドを使用します。トランザクションを終了し、コミットするには、CLI の `aws rds-data commit-transaction` コマンドを使用します。
**重要**
`--transaction-id` オプションを指定しない場合、呼び出しによる変更は自動的にコミットされます。
共通オプションに加えて、次のオプションを指定します。
+ `--sql` (必須) - DB クラスターで実行する SQL ステートメント。
+ `--transaction-id` (オプション) - CLI の `begin-transaction` コマンドを使用してスタートされたトランザクションの識別子。SQL ステートメントを含めるトランザクションのトランザクション ID を指定します。
+ `--parameters` (オプション) - SQL ステートメントのパラメータ。
+ `--include-result-metadata | --no-include-result-metadata` (オプション) - 結果にメタデータを含むかどうかを示す値。デフォルトは `--no-include-result-metadata` です。
+ `--database` (オプション) - データベースの名前。
`--database` オプションは、前のリクエストで `--sql "use database_name;"` を実行した後に SQL ステートメントを実行すると、機能しない場合があります。`--sql "use database_name;"` ステートメントを実行する代わりに `--database` オプションを使用することをお勧めします。
+ `--continue-after-timeout | --no-continue-after-timeout` (オプション) — 呼び出しが Data API タイムアウト間隔の 45 秒を超えた後もステートメントの実行を継続するかどうかを示す値。デフォルトは `--no-continue-after-timeout` です。
データ定義言語 (DDL) ステートメントでは、エラーやデータ構造の破損の可能性を回避するために、呼び出しがタイムアウトした後もステートメントを実行し続けることをお勧めします。
+ `--format-records-as "JSON"|"NONE"` - 結果セットを JSON 文字列としてフォーマットするかどうかを指定するオプションの値です。デフォルトは `"NONE"` です。JSON 結果セットの処理の詳細については、「[JSON 形式で RDS Data API クエリ結果を処理する](data-api-json.md)」を参照してください。
DB クラスターは呼び出しに対してレスポンスを返します。
**注記**
レスポンスサイズの上限は 1 MiB です。1 MiB を超えるレスポンスデータが返されると、その呼び出しは終了します。
Aurora Serverless v1 では、1 秒あたりの最大リクエスト数は 1,000 です。サポートされている他のすべてのデータベースには、制限はありません。
例えば、次の CLI コマンドでは単一の SQL ステートメントを実行して、結果からメタデータを除外します (デフォルト)。
Linux、macOS、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 ステートメントを実行します。
Linux、macOS、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 ステートメントを実行します。
Linux、macOS、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 Data API のタイムアウト間隔である 45 秒を超えた後もステートメントの実行を続けるには、`--continue-after-timeout` オプションを指定します。
Linux、macOS、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 ステートメントの実行
データの配列に対してバッチ SQL ステートメントを実行するには、CLI の `aws rds-data batch-execute-statement` コマンドを使用します。このコマンドを使用して、一括インポートまたは一括更新オペレーションを実行できます。
SQL ステートメントをトランザクションで実行するには、`--transaction-id` オプションとあわせてトランザクション識別子を指定します。トランザクションをスタートするには、CLI の `aws rds-data begin-transaction` コマンドを使用します。トランザクションを終了し、コミットするには、CLI の `aws rds-data commit-transaction` コマンドを使用します。
**重要**
`--transaction-id` オプションを指定しない場合、呼び出しによる変更は自動的にコミットされます。
共通オプションに加えて、次のオプションを指定します。
+ `--sql` (必須) - DB クラスターで実行する SQL ステートメント。
**ヒント**
MySQL 互換のステートメントでは、`--sql` パラメータの末尾にセミコロンを含めないでください。末尾のセミコロンは、構文エラーを引き起こす可能性があります。
+ `--transaction-id` (オプション) - CLI の `begin-transaction` コマンドを使用してスタートされたトランザクションの識別子。SQL ステートメントを含めるトランザクションのトランザクション ID を指定します。
+ `--parameter-set` (オプション) - バッチオペレーション用のパラメータセット。
+ `--database` (オプション) - データベースの名前。
DB クラスターは、呼び出しに対してレスポンスを返します。
**注記**
パラメータセットの数に固定された上限はありません。ただし、データ API を介して送信される HTTP リクエストの最大サイズは 4 MiB です。リクエストがこの制限を超えると、データ API はエラーを返し、リクエストを処理しません。この 4 MiB の制限には、リクエスト内の HTTP ヘッダーのサイズと JSON 表記が含まれます。したがって、含めることができるパラメータセットの数は、SQL ステートメントのサイズや各パラメータセットのサイズなどの要素の組み合わせによって異なります。
レスポンスサイズの上限は 1 MiB です。1 MiB を超えるレスポンスデータが返されると、その呼び出しは終了します。
Aurora Serverless v1 では、1 秒あたりの最大リクエスト数は 1,000 です。サポートされている他のすべてのデータベースには、制限はありません。
例えば、次の CLI コマンドは、パラメータセットを使用してデータの配列に対してバッチ SQL ステートメントを実行します。
Linux、macOS、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 トランザクションのコミット
CLI の `aws rds-data commit-transaction` コマンドを使用すると、`aws rds-data begin-transaction` でスタートした SQL トランザクションを終了し、変更をコミットすることができます。
共通オプションに加えて、次のオプションを指定します。
+ `--transaction-id` (必須) - CLI の `begin-transaction` コマンドを使用してスタートされたトランザクションの識別子。終了し、コミットするトランザクションのトランザクション ID を指定します。
例えば、次の CLI コマンドでは、SQL トランザクションを終了し、変更をコミットします。
Linux、macOS、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 トランザクションのロールバック
CLI の `aws rds-data rollback-transaction` コマンドを使用すると、`aws rds-data begin-transaction` でスタートした SQL トランザクションをロールバックすることができます。トランザクションをロールバックすると、変更はキャンセルされます。
**重要**
トランザクション ID の有効期限が切れている場合、トランザクションは自動的にロールバックされます。この場合、有効期限切れのトランザクション ID を指定する `aws rds-data rollback-transaction` コマンドによって、エラーが返ります。
共通オプションに加えて、次のオプションを指定します。
+ `--transaction-id` (必須) - CLI の `begin-transaction` コマンドを使用してスタートされたトランザクションの識別子。ロールバックするトランザクションのトランザクション ID を指定します。
例えば、次の AWS CLI コマンドでは、SQL トランザクションをロールバックします。
Linux、macOS、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 に置き換えます。また、シークレット ARN を Secrets Manager のシークレットの ARN に置き換え、DB クラスターへのアクセスを許可します。
**Topics**
+ [SQL クエリの実行](#data-api.calling.python.run-query)
+ [DML SQL ステートメントの実行](#data-api.calling.python.run-inert)
+ [SQL トランザクションの実行](#data-api.calling.python.run-transaction)
## SQL クエリの実行
Python アプリケーションを使用して、`SELECT` ステートメントを実行し、結果を取得することができます。
以下の例では、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` パラメータが含まれていないため、呼び出しがトランザクションの一部ではない場合、呼び出しによる変更は自動的にコミットされます。
以下の例では、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 トランザクションのスタートから、1 つ以上の 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 Data 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 に置き換えます。また、シークレット ARN を Secrets Manager のシークレットの ARN に置き換え、DB クラスターへのアクセスを許可します。
**Topics**
+ [SQL クエリの実行](#data-api.calling.java.run-query)
+ [SQL トランザクションの実行](#data-api.calling.java.run-transaction)
+ [SQL のバッチオペレーションを実行する](#data-api.calling.java.run-batch)
## SQL クエリの実行
Java アプリケーションを使用して、`SELECT` ステートメントを実行し、結果を取得することができます。
以下の例では、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 トランザクションのスタートから、1 つ以上の 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 Data 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);
}
}
```
# Data API タイムアウト動作の制御
Data API へのすべての呼び出しは同期的です。`INSERT` または `CREATE TABLE` などの SQL ステートメントを実行する Data API 操作を実行するとします。Data 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 分に設定することをお勧めします。これにより、アプリケーションがタイムアウトエラーを受け取る可能性を回避しつつ、Data API 操作を正常に完了できます。これにより、操作を再試行するかどうかを確認できます。
例えば、SDK がタイムアウトエラーをアプリケーションに返したが、Data API 操作は Data 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));
}
```