Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra.
# Appel de l’API de données Amazon RDS
Quand l’API de données Amazon RDS (API de données) est activée sur votre cluster de bases de données Aurora, vous pouvez exécuter des instructions SQL sur le cluster de bases de données Aurora à l’aide de l’API de données ou de l’AWS CLI. L’API de données est compatible avec les langages de programmation pris en charge par les kits AWS SDK. Pour plus d’informations, consultez [Outils pour créer sur AWS](https://aws.amazon.com/tools/).
**Topics**
+ [Référence des opérations de l’API de données Amazon RDS](data-api-operations.md)
+ [Appel de l’API de données Amazon RDS à l’aide de l’AWS CLI](data-api.calling.cli.md)
+ [Appel à l’API de données Amazon RDS depuis une application Python](data-api.calling.python.md)
+ [Appel à l’API de données Amazon RDS depuis une application Java](data-api.calling.java.md)
+ [Contrôle du comportement en cas d’expiration de l’API de données](data-api-timeouts.md)
# Référence des opérations de l’API de données Amazon RDS
L’API de données Amazon RDS fournit les opérations suivantes pour exécuter les instructions SQL.
****
| Opération d’API de données | AWS CLI commande | Description |
| --- | --- | --- |
| [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) | Exécute une instruction SQL sur une base de données. |
| [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) | Exécute une instruction SQL par lots sur un tableau de données pour les opérations d’insertion et de mise à jour en bloc. Vous pouvez exécuter une instruction en langage de manipulation de données (DML) avec un tableau de jeux de paramètres. Une instruction SQL par lots peut nettement améliorer les performances sur des instructions d’insertion et de mise à jour. |
Vous pouvez utiliser l’une ou l’autre des opérations pour exécuter des instructions SQL individuelles ou des transactions. Pour les transactions, l’API de données fournit les opérations suivantes.
****
| Opération d’API de données | AWS CLI commande | Description |
| --- | --- | --- |
| [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) | Démarre une transaction 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) | Termine une transaction SQL et valide les modifications. |
| [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) | Restaure une transaction. |
Les opérations permettant d'exécuter des instructions SQL et de prendre en charge les transactions ont les paramètres et AWS CLI options communs suivants de l'API de données. Certaines opérations prennent en charge d’autres paramètres et options.
****
| Paramètre d’opération d’API de données | AWS CLI option de commande | Obligatoire | Description |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | Oui | Amazon Resource Name (ARN) du cluster de bases de données Aurora. Le cluster doit être identique Compte AWS au rôle ou à l'utilisateur IAM qui appelle l'API de données. Pour accéder à un cluster dans un autre compte, vous devez endosser un rôle dans ce compte. |
| `secretArn` | `--secret-arn` | Oui | Nom ou ARN du secret qui active l’accès au cluster de bases de données. |
L’API de données RDS prend en charge les types de données suivants pour 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)`
L’API de données RDS prend en charge les types scalaires Aurora PostgreSQL suivants :
+ `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`
L’API de données RDS prend en charge les types de tableaux Aurora PostgreSQL suivants :
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
Vous pouvez utiliser des paramètres dans les appels de l'API de données vers `ExecuteStatement` et`BatchExecuteStatement`, et lorsque vous exécutez les AWS CLI commandes `execute-statement` et`batch-execute-statement`. Pour utiliser un paramètre, spécifiez une paire nom-valeur dans le type de données `SqlParameter`. Vous devez spécifier la valeur avec le type de données `Field`. Le tableau suivant associe les types de données Java Database Connectivity (JDBC) aux types de données que vous spécifiez dans les appels d’API de données.
****
| Type de données JDBC | Type de données API de données |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` (ou `STRING`) |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| Autres types (y compris les types liés à la date et à l’heure) | `STRING` |
**Note**
Vous pouvez spécifier le type de données `LONG` ou `STRING` dans votre appel d’API de données pour les valeurs `LONG` renvoyées par la base de données. Nous vous recommandons de le faire afin d'éviter de perdre en précision pour des nombres extrêmement élevés, ce qui peut se produire lorsque vous travaillez avec JavaScript.
Certains types, tels que `DECIMAL` et `TIME`, nécessitent un indice pour que l’API de données transmette les valeurs `String` à la base de données en tant que type correct. Pour utiliser un indice, incluez des valeurs pour `typeHint` dans le type de données `SqlParameter`. Les valeurs possibles pour `typeHint` sont les suivantes :
+ `DATE` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `DATE` à la base de données. Le format accepté est `YYYY-MM-DD`.
+ `DECIMAL` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `DECIMAL` à la base de données.
+ `JSON` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `JSON` à la base de données.
+ `TIME` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `TIME` à la base de données. Le format accepté est `HH:MM:SS[.FFF]`.
+ `TIMESTAMP` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `TIMESTAMP` à la base de données. Le format accepté est `YYYY-MM-DD HH:MM:SS[.FFF]`.
+ `UUID` : la valeur de paramètre `String` correspondante est envoyée en tant qu’objet de type `UUID` à la base de données.
**Note**
Actuellement, l'API de données ne prend pas en charge les tableaux d'identifiants uniques universels ()UUIDs.
**Note**
Pour Amazon Aurora PostgreSQL, l’API de données renvoie toujours le type de données Aurora PostgreSQL `TIMESTAMPTZ` dans le fuseau horaire UTC.
# Appel de l’API de données Amazon RDS à l’aide de l’AWS CLI
Vous pouvez appeler l’API de données RDS (API de donnée) à l’aide d’AWS CLI.
Les exemples suivants utilisent AWS CLI pour l’API de données. Pour plus d’informations, consultez le [document de référence AWS CLI pour l’API de données](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html).
Dans chaque exemple, remplacez l’Amazon Resource Name (ARN) du cluster de bases de données par l’ARN de votre cluster de bases de données Aurora. De même, remplacez l’ARN du secret par l’ARN du secret dans Secrets Manager qui autorise l’accès au cluster de bases de données.
**Note**
AWS CLI peut formater les réponses en JSON.
**Topics**
+ [Démarrage d’une transaction SQL](#data-api.calling.cli.begin-transaction)
+ [Exécution d’une instruction SQL](#data-api.calling.cli.execute-statement)
+ [Exécution d’une instruction SQL par lots sur un tableau de données](#data-api.calling.cli.batch-execute-statement)
+ [Validation d’une transaction SQL](#data-api.calling.cli.commit-transaction)
+ [Restauration d’une transaction](#data-api.calling.cli.rollback-transaction)
## Démarrage d’une transaction SQL
Vous pouvez démarrer une transaction SQL à l’aide de la commande CLI `aws rds-data begin-transaction`. L’appel renvoie un identifiant de transaction.
**Important**
Dans l’API de données, une transaction expire si aucun appel n’utilise son identifiant de transaction dans un délai de trois minutes. Si une transaction expire avant d’être validée, l’API de données la restaure automatiquement.
Les instructions DDL (Data Definition Language) MySQL d’une transaction provoquent une validation implicite. Nous vous recommandons d’exécuter chaque instruction DDL MySQL dans une commande `execute-statement` séparée avec l’option `--continue-after-timeout`.
En plus des options communes, spécifiez l’option `--database` qui indique le nom de la base de données.
Par exemple, la commande CLI suivante démarre une transaction SQL.
Pour Linux, macOS ou 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"
```
Pour 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"
```
Voici un exemple de réponse.
```
{
"transactionId": "ABC1234567890xyz"
}
```
## Exécution d’une instruction SQL
Vous pouvez exécuter une instruction SQL à l’aide de la commande CLI `aws rds-data execute-statement`.
Vous pouvez exécuter une instruction SQL à l’intérieur d’une transaction en spécifiant l’identifiant de la transaction avec l’option `--transaction-id`. Vous pouvez démarrer une transaction à l’aide de la commande CLI `aws rds-data begin-transaction`. Vous pouvez terminer et valider une transaction à l’aide de la commande CLI `aws rds-data commit-transaction`.
**Important**
Si vous ne spécifiez pas l’option `--transaction-id`, les modifications renvoyées par l’appel sont automatiquement validées.
En plus des options courantes, spécifiez les options suivantes :
+ `--sql` (obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données.
+ `--transaction-id` (facultatif) – Identifiant d’une transaction démarrée à l’aide de la commande CLI `begin-transaction`. Spécifiez l’identifiant de la transaction dans laquelle vous souhaitez intégrer l’instruction SQL.
+ `--parameters` (facultatif) – Paramètres pour l’instruction SQL.
+ `--include-result-metadata | --no-include-result-metadata` (facultatif) – Valeur indiquant si les métadonnées doivent apparaître dans les résultats. La valeur par défaut est `--no-include-result-metadata`.
+ `--database` (facultatif) – Nom de la base de données.
L’option `--database` peut ne pas fonctionner lorsque vous exécutez une instruction SQL après avoir exécuté `--sql "use database_name;"` dans la demande précédente. Nous vous recommandons d’utiliser l’option `--database` plutôt que d’exécuter des instructions `--sql "use database_name;"`.
+ `--continue-after-timeout | --no-continue-after-timeout` (facultatif) – Valeur indiquant si l’exécution de l’instruction doit se poursuivre lorsque l’appel dépasse le délai d’expiration de 45 secondes de l’API de données. La valeur par défaut est `--no-continue-after-timeout`.
Pour les instructions en langage de définition de données (DDL), nous vous recommandons de continuer à exécuter l’instruction après l’expiration de l’appel afin d’éviter les erreurs et la corruption de structures de données.
+ `--format-records-as "JSON"|"NONE"` : une valeur facultative qui spécifie si l’ensemble de résultats doit être formaté en tant que chaîne JSON. La valeur par défaut est `"NONE"`. Pour obtenir des informations sur l’utilisation du traitement des ensembles de résultats JSON, consultez [Traitement des requêtes d’API Amazon RDS Data au format JSON](data-api-json.md).
Le cluster de bases de données renvoie une réponse pour l’appel.
**Note**
La taille de réponse est limitée à 1 Mio. Si l’appel renvoie plus de 1 Mio de données de réponse, l’appel est arrêté.
Le nombre maximal de demandes par seconde est 1 000 pour Aurora Serverless v1. Aucune limite n’est imposée pour les autres bases de données prises en charge.
Par exemple, la commande CLI suivante exécute une instruction SQL unique et omet les métadonnées dans les résultats (par défaut).
Pour Linux, macOS ou 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"
```
Pour 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"
```
Voici un exemple de réponse.
```
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}
```
La commande CLI suivante exécute une instruction SQL unique dans une transaction en spécifiant l’option `--transaction-id`.
Pour Linux, macOS ou 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"
```
Pour 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"
```
Voici un exemple de réponse.
```
{
"numberOfRecordsUpdated": 1
}
```
La commande CLI suivante exécute une seule instruction SQL avec des paramètres.
Pour Linux, macOS ou 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\"}}]"
```
Pour 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\"}}]"
```
Voici un exemple de réponse.
```
{
"numberOfRecordsUpdated": 1
}
```
La commande CLI suivante exécute une instruction SQL en langage de définition de données (DDL). L’instruction DDL renomme la colonne `job` en colonne `role`.
**Important**
Pour les instructions DDL, nous vous recommandons de continuer à exécuter l’instruction une fois l’appel expiré. Lorsqu’une instruction DDL se termine avant la fin de son exécution, cela peut entraîner des erreurs et corrompre les structures de données. Pour maintenir l’exécution d’une instruction lorsqu’un appel dépasse le délai d’expiration de 45 secondes de l’API de données RDS, sélectionnez l’option `--continue-after-timeout`.
Pour Linux, macOS ou 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
```
Pour 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
```
Voici un exemple de réponse.
```
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}
```
**Note**
Les données `generatedFields` ne sont pas prises en charge par Aurora PostgreSQL. Pour obtenir les valeurs des champs générés, utilisez la clause `RETURNING`. Pour plus d’informations, consultez [ Renvoi de données de lignes modifiées](https://www.postgresql.org/docs/10/dml-returning.html) dans la documentation PostgreSQL.
## Exécution d’une instruction SQL par lots sur un tableau de données
Vous pouvez exécuter une instruction SQL par lots sur un tableau de données à l’aide de la commande CLI `aws rds-data batch-execute-statement`. Vous pouvez utiliser cette commande pour réaliser une opération d’importation ou de mise à jour en bloc.
Vous pouvez exécuter une instruction SQL à l’intérieur d’une transaction en spécifiant l’identifiant de la transaction avec l’option `--transaction-id`. Vous pouvez démarrer une transaction à l’aide de la commande CLI `aws rds-data begin-transaction`. Vous pouvez terminer et valider une transaction à l’aide de la commande CLI `aws rds-data commit-transaction`.
**Important**
Si vous ne spécifiez pas l’option `--transaction-id`, les modifications renvoyées par l’appel sont automatiquement validées.
En plus des options courantes, spécifiez les options suivantes :
+ `--sql` (obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données.
**Astuce**
Pour les instructions compatibles avec MySQL, n’incluez pas de point-virgule à la fin du paramètre `--sql`. Un point-virgule final peut entraîner une erreur de syntaxe.
+ `--transaction-id` (facultatif) – Identifiant d’une transaction démarrée à l’aide de la commande CLI `begin-transaction`. Spécifiez l’identifiant de la transaction dans laquelle vous souhaitez intégrer l’instruction SQL.
+ `--parameter-set` (facultatif) – Ensembles de paramètres pour l’opération par lots.
+ `--database` (facultatif) – Nom de la base de données.
Le cluster de bases de données renvoie une réponse à l’appel.
**Note**
Il n’existe pas de limite supérieure fixe pour le nombre d’ensembles de paramètres. Toutefois, la taille maximale de la demande HTTP envoyée via l’API de données est de 4 MiB. Si la demande dépasse cette limite, l’API de données renvoie une erreur et ne traite pas la demande. Cette limite de 4 MiB inclut la taille des en-têtes HTTP et la notation JSON dans la demande. Ainsi, le nombre d’ensembles de paramètres que vous pouvez inclure dépend d’une combinaison de facteurs, tels que la taille de l’instruction SQL et la taille de chaque ensemble de paramètres.
La taille de réponse est limitée à 1 Mio. Si l’appel renvoie plus de 1 Mio de données de réponse, l’appel est arrêté.
Le nombre maximal de demandes par seconde est 1 000 pour Aurora Serverless v1. Aucune limite n’est imposée pour les autres bases de données prises en charge.
Par exemple, la commande CLI suivante exécute une instruction SQL par lots sur un tableau de données avec un ensemble de paramètres.
Pour Linux, macOS ou 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\"}}]]"
```
Pour 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\"}}]]"
```
**Note**
N’incluez pas les sauts de ligne présents dans l’option `--parameter-sets`.
## Validation d’une transaction SQL
À l’aide de la commande CLI `aws rds-data commit-transaction`, vous pouvez terminer une transaction SQL que vous avez démarrée avec `aws rds-data begin-transaction` et valider les modifications.
En plus des options courantes, spécifiez l’option suivante :
+ `--transaction-id` (obligatoire) – Identifiant d’une transaction démarrée à l’aide de la commande CLI `begin-transaction`. Spécifiez l’identifiant de la transaction que vous souhaitez terminer et valider.
Par exemple, la commande CLI suivante termine une transaction SQL et valide les changements.
Pour Linux, macOS ou 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"
```
Pour 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"
```
Voici un exemple de réponse.
```
{
"transactionStatus": "Transaction Committed"
}
```
## Restauration d’une transaction
À l’aide de la commande CLI `aws rds-data rollback-transaction`, vous pouvez restaurer une transaction SQL que vous avez démarrée avec `aws rds-data begin-transaction`. La restauration d’une transaction annule les changements apportés.
**Important**
L’expiration de l’identifiant de la transaction entraîne automatiquement sa restauration. Dans ce cas, une commande `aws rds-data rollback-transaction` qui spécifie l’identifiant de transaction expiré renvoie une erreur.
En plus des options courantes, spécifiez l’option suivante :
+ `--transaction-id` (obligatoire) – Identifiant d’une transaction démarrée à l’aide de la commande CLI `begin-transaction`. Spécifiez l’identifiant de la transaction que vous souhaitez restaurer.
Par exemple, la commande AWS CLI suivante restaure une transaction SQL.
Pour Linux, macOS ou 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"
```
Pour 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"
```
Voici un exemple de réponse.
```
{
"transactionStatus": "Rollback Complete"
}
```
# Appel à l’API de données Amazon RDS depuis une application Python
Vous pouvez appeler l’API de données Amazon RDS (API de données) depuis une application Python.
Les exemples suivants utilisent le kit AWS SDK pour Python (Boto). Pour plus d’informations sur Boto, consultez la [documentation AWS SDK pour Python (Boto 3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html).
Dans chaque exemple, remplacez l’Amazon Resource Name (ARN) du cluster de bases de données par l’ARN de votre cluster de bases de données Aurora. De même, remplacez l’ARN du secret par l’ARN du secret dans Secrets Manager qui autorise l’accès au cluster de bases de données.
**Topics**
+ [Exécution d’une requête SQL](#data-api.calling.python.run-query)
+ [Exécution d’une instruction SQL DML](#data-api.calling.python.run-inert)
+ [Exécution d’une transaction SQL](#data-api.calling.python.run-transaction)
## Exécution d’une requête SQL
Vous pouvez exécuter une instruction `SELECT` puis extraire les résultats avec une application Python.
L’exemple suivant exécute une requête 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'
}
]
]
```
## Exécution d’une instruction SQL DML
Vous pouvez exécuter une instruction en langage de manipulation de données (DML) pour intégrer, mettre à jour ou supprimer des données dans votre base de données. Vous pouvez également utiliser des paramètres dans les instructions DML.
**Important**
Si un appel ne fait pas partie d’une transaction, car il ne comprend pas le paramètre `transactionID`, les modifications résultant de l’appel sont validées automatiquement.
L’exemple suivant exécute une instruction SQL INSERT et utilise des paramètres.
```
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"])
```
## Exécution d’une transaction SQL
Vous pouvez démarrer une transaction SQL, exécuter une ou plusieurs instructions SQL, puis valider les modifications avec une application Python.
**Important**
Une transaction expire si aucun appel n’utilise son identifiant de transaction dans un délai de trois minutes. Si une transaction expire avant d’être validée, elle est automatiquement restaurée.
Si vous ne spécifiez pas d’identifiant de transaction, les modifications résultant de l’appel sont validées automatiquement.
L’exemple suivant exécute une transaction SQL qui insère une ligne dans un tableau.
```
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
```
**Note**
Si vous exécutez une instruction en langage de définition de données (DDL), nous vous recommandons de continuer à exécuter l’instruction une fois l’appel expiré. Lorsqu’une instruction DDL se termine avant la fin de son exécution, cela peut entraîner des erreurs et corrompre les structures de données. Pour maintenir l’exécution d’une instruction lorsqu’un appel dépasse le délai d’expiration de 45 secondes de l’API de données RDS, définissez le paramètre `continueAfterTimeout` sur `true`.
# Appel à l’API de données Amazon RDS depuis une application Java
Vous pouvez appeler l’API de données Amazon RDS (API de données) depuis une application Java.
Les exemples suivants utilisent le kit AWS SDK pour Java. Pour plus d’informations, consultez le [Manuel du développeur AWS SDK pour Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html).
Dans chaque exemple, remplacez l’Amazon Resource Name (ARN) du cluster de bases de données par l’ARN de votre cluster de bases de données Aurora. De même, remplacez l’ARN du secret par l’ARN du secret dans Secrets Manager qui autorise l’accès au cluster de bases de données.
**Topics**
+ [Exécution d’une requête SQL](#data-api.calling.java.run-query)
+ [Exécution d’une transaction SQL](#data-api.calling.java.run-transaction)
+ [Exécution d’une opération SQL par lots](#data-api.calling.java.run-batch)
## Exécution d’une requête SQL
Vous pouvez exécuter une instruction `SELECT`? puis extraire les résultats avec une application Java.
L’exemple suivant exécute une requête 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));
}
}
}
```
## Exécution d’une transaction SQL
Vous pouvez démarrer une transaction SQL, exécuter une ou plusieurs instructions SQL, puis valider les modifications avec une application Java.
**Important**
Une transaction expire si aucun appel n’utilise son identifiant de transaction dans un délai de trois minutes. Si une transaction expire avant d’être validée, elle est automatiquement restaurée.
Si vous ne spécifiez pas d’identifiant de transaction, les modifications résultant de l’appel sont validées automatiquement.
L’exemple suivant exécute une transaction 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);
}
}
```
**Note**
Si vous exécutez une instruction en langage de définition de données (DDL), nous vous recommandons de continuer à exécuter l’instruction une fois l’appel expiré. Lorsqu’une instruction DDL se termine avant la fin de son exécution, cela peut entraîner des erreurs et corrompre les structures de données. Pour maintenir l’exécution d’une instruction lorsqu’un appel dépasse le délai d’expiration de 45 secondes de l’API de données RDS, définissez le paramètre `continueAfterTimeout` sur `true`.
## Exécution d’une opération SQL par lots
Vous pouvez exécuter des opérations d’insertion et de mise à jour en bloc sur un tableau de données avec une application Java. Vous pouvez exécuter une instruction DML avec des groupes de valeurs de paramètres.
**Important**
Si vous ne spécifiez pas d’identifiant de transaction, les modifications résultant de l’appel sont validées automatiquement.
L’exemple suivant exécute une opération d’insertion par lots.
```
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);
}
}
```
# Contrôle du comportement en cas d’expiration de l’API de données
Tous les appels à l’API de données sont synchrones. Supposons que vous exécutiez une opération d’API de données qui exécute une instruction SQL comme `INSERT` ou `CREATE TABLE`. Si l’appel de l’API de données aboutit, le traitement SQL se termine lorsque l’appel est renvoyé.
Par défaut, l’API de données annule une opération et renvoie une erreur d’expiration du délai si le traitement de l’opération ne s’est pas terminé dans les 45 secondes. Dans ce cas, les données ne sont pas insérées, la table n’est pas créée, etc.
Vous pouvez utiliser l’API de données pour effectuer des opérations de longue durée qui ne peuvent pas être effectuées en 45 secondes. Si vous estimez qu’une opération, telle qu’une opération DDL ou `INSERT` en bloc sur une table de grande taille, durera plus de 45 secondes, vous pouvez spécifier le paramètre `continueAfterTimeout` de l’opération `ExecuteStatement`. Votre application recevra tout de même le message d’erreur d’expiration du délai. Toutefois, l’opération continuera et ne sera pas annulée. Pour obtenir un exemple, consultez [Exécution d’une transaction SQL](data-api.calling.java.md#data-api.calling.java.run-transaction).
Si le kit AWS SDK correspondant à votre langage de programmation utilise son propre délai d’expiration pour les appels d’API ou les connexions au socket HTTP, assurez-vous que tous ces délais soient supérieurs à 45 secondes. Pour certains kits SDK, le délai d’expiration par défaut est inférieur à 45 secondes. Nous vous recommandons de spécifier des délais d’expiration spécifiques aux kits SDK ou aux clients d’au moins une minute. Cela permet d’éviter que votre application reçoive une erreur d’expiration du délai alors que l’opération de l’API de données aboutit. Et vous savez ainsi quand vous devez retenter l’opération ou non.
Supposons, par exemple, que le kit SDK renvoie une erreur d’expiration du délai à votre application, mais que l’opération de l’API de données se termine tout de même dans l’intervalle d’expiration de l’API. Dans ce cas, une nouvelle tentative d’exécution de cette opération risquerait d’insérer des données dupliquées ou de générer des résultats incorrects. Le kit SDK pourrait réessayer d’exécuter l’opération automatiquement, ce qui entraînerait des données incorrectes sans aucune action de la part de votre application.
L’intervalle d’expiration est particulièrement important pour le SDK Java 2. Dans ce kit SDK, le délai d’expiration des appels d’API et celui du socket HTTP sont tous deux de 30 secondes par défaut. Voici un exemple de procédure à suivre pour définir une valeur supérieure pour ces délais d’expiration :
```
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));
}
```
Voici un exemple équivalent utilisant le client de données asynchrone :
```
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));
}
```