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 avec le AWS CLI
Vous pouvez appeler l'API de données RDS (API de données) à l'aide du AWS CLI.
Les exemples suivants utilisent l'API AWS CLI for Data. Pour plus d'informations, consultez le document de référence AWS CLI pour l'API de données.
Dans chaque exemple, remplacez l'Amazon Resource Name (ARN) du cluster de base de données par l'ARN de votre cluster de base 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 base de données.
Note
Ils AWS CLI peuvent formater les réponses en JSON.
Rubriques
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 Data, une transaction expire si aucun appel n'utilise son identifiant de transaction dans les trois minutes. Si une transaction expire avant d'être validée, l'API Data l'annule automatiquement.
Les instructions du langage de définition de données (DDL) MySQL à l'intérieur d'une transaction entraînent une validation implicite. Nous vous recommandons d'exécuter chaque instruction DDL MySQL dans une execute-statement
commande séparée avec l'--continue-after-timeout
option.
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 LinuxmacOS, 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
"
Dans 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 CLIbegin-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
dans la requête précédente. Nous vous recommandons d'utiliser l'optiondatabase_name
;"--database
plutôt que d'exécuter des instructions--sql "use
.database_name
;" -
--continue-after-timeout | --no-continue-after-timeout
(facultatif) — Valeur qui indique s'il faut continuer à exécuter l'instruction après que l'appel ait dépassé 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. L’argument par défaut est"NONE"
. Pour obtenir des informations sur l'utilisation du traitement des ensembles de résultats JSON, consultez Traitement des résultats des requêtes de l'API Amazon RDS Data au format JSON.
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é.
Car Aurora Serverless v1 le nombre maximum de demandes par seconde est de 1 000. Pour toutes les autres bases de données prises en charge, il n'y a aucune limite.
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 LinuxmacOS, 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
"
Dans 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 LinuxmacOS, 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
"
Dans 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 LinuxmacOS, 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 intomytable
values (:id
,:val
)" --parameters "[{\"name\": \"id
\", \"value\": {\"longValue\":1
}},{\"name\": \"val
\", \"value\": {\"stringValue\": \"value1
\"}}]"
Dans 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 intomytable
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 continuer à exécuter une instruction après qu'un appel dépasse le délai d'expiration de 45 secondes de l'API de données RDS, spécifiez l'--continue-after-timeout
option.
Pour LinuxmacOS, 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
Dans 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 de plus amples informations, veuillez consulter Renvoi de données de lignes modifiées
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 CLIbegin-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. Cependant, la taille maximale de la requête HTTP soumise via l'API Data est de 4 MiB. Si la demande dépasse cette limite, l'API Data 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é.
Car Aurora Serverless v1 le nombre maximum de demandes par seconde est de 1 000. Pour toutes les autres bases de données prises en charge, il n'y a aucune limite.
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 LinuxmacOS, 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 intomytable
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
\"}}]]"
Dans 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 intomytable
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 CLIbegin-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 LinuxmacOS, 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
"
Dans 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 CLIbegin-transaction
. Spécifiez l'identifiant de la transaction que vous souhaitez restaurer.
Par exemple, la AWS CLI commande suivante annule une transaction SQL.
Pour LinuxmacOS, 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
"
Dans 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"
}