# 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"
}
```