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