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.
# Utilisation de l’API de données Amazon RDS
L’API de données RDS (API de données), vous permet d’accéder à votre cluster de bases de données Aurora via une interface de services Web. L’API de données ne nécessite pas de connexion persistante au cluster de bases de données. Au lieu de cela, il fournit un point de terminaison HTTP sécurisé et une intégration avec AWS SDKs. Vous pouvez utiliser le point de terminaison pour exécuter des instructions SQL sans avoir à gérer de connexions.
Les utilisateurs n'ont pas besoin de transmettre des informations d'identification lors des appels à l'API de données, car l'API de données utilise les informations d'identification de base de données stockées dans AWS Secrets Manager. Pour stocker des informations d’identification dans Secrets Manager, les utilisateurs doivent disposer des autorisations appropriées pour utiliser Secrets Manager et l’API de données. Pour plus d’informations sur les autorisations accordées aux utilisateurs, consultez [Autorisation de l’accès à l’API de données Amazon RDS](data-api.access.md).
Vous pouvez également utiliser l'API de données pour intégrer Amazon Aurora à d'autres AWS applications telles que AWS Lambda AWS AppSync, et AWS Cloud9. L’API de données permet d’utiliser AWS Lambda de façon plus sécurisée. Il vous permet d’avoir accès au cluster de bases de données sans avoir à configurer une fonction Lambda pour accéder aux ressources au sein d’un cloud privé virtuel (VPC). Pour plus d’informations, consultez [AWS Lambda](https://aws.amazon.com/lambda/), [AWS AppSync](https://aws.amazon.com/appsync/) et [AWS Cloud9](https://aws.amazon.com/cloud9/).
Vous pouvez activer l’API de données lorsque vous créez le cluster de bases de données Aurora. Vous pouvez également modifier la configuration ultérieurement. Pour plus d’informations, consultez [Activation de l’API de données Amazon RDS](data-api.enabling.md).
Après avoir activé l’API de données, vous pouvez également utiliser l’éditeur de requête pour exécuter des requête ad hoc sans configurer d’outil de requête pour accéder à Aurora dans un VPC. Pour plus d’informations, consultez [Utilisation de l’éditeur de requêtes Aurora](query-editor.md).
**Topics**
+ [
# Disponibilité des régions et des versions de pour l’API de données Amazon RDS
](data-api.regions.md)
+ [
# Utilisation IPv6 avec l'API de données Amazon RDS
](data-api.ipv6.md)
+ [
# Limites de l’API de données Amazon RDS
](data-api.limitations.md)
+ [
# Comparaison des comportements de l’API de données Amazon RDS entre Aurora Serverless v2 et les clusters provisionnés avec les clusters Aurora Serverless v1
](data-api.differences.md)
+ [
# Autorisation de l’accès à l’API de données Amazon RDS
](data-api.access.md)
+ [
# Activation de l’API de données Amazon RDS
](data-api.enabling.md)
+ [
# Création d’un point de terminaison de VPC Amazon pour l’API de données Amazon RDS (AWS PrivateLink)
](data-api.vpc-endpoint.md)
+ [
# Appel de l’API de données Amazon RDS
](data-api.calling.md)
+ [
# Utilisation de la bibliothèque cliente Java pour l’API de données RDS
](data-api.java-client-library.md)
+ [
# Traitement des requêtes d’API Amazon RDS Data au format JSON
](data-api-json.md)
+ [
# Dépannage de l’API de données Amazon RDS
](data-api.troubleshooting.md)
+ [
# Journalisation des appels d'API Amazon RDS Data avec AWS CloudTrail
](logging-using-cloudtrail-data-api.md)
+ [
# Surveillance des requêtes de l’API de données RDS avec Performance Insights
](monitoring-using-performance-insights-data-api.md)
# Disponibilité des régions et des versions de pour l’API de données Amazon RDS
Pour connaître les régions et les versions de moteurs prises en charge par l’API de données, consultez les sections suivantes.
| Type de cluster | Disponibilité des régions et des versions |
| --- | --- |
| Aurora PostgreSQL provisionné et sans serveur v2 | [API de données avec Aurora PostgreSQL sans serveur v2 et provisionné](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL provisionné et sans serveur v2 | [API de données avec Aurora MySQL sans serveur v2 et provisionné](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL sans serveur v1 | [API de données avec Aurora PostgreSQL sans serveur v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL sans serveur v1 | [API de données avec Aurora MySQL sans serveur v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
Si vous avez besoin de modules cryptographiques validés FIPS 140-2 lorsque vous accédez à l’API de données via une CLI ou une API, utilisez un point de terminaison FIPS. Pour plus d’informations sur les points de terminaison FIPS (Federal Information Processing Standard) disponibles, consultez [Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com/compliance/fips/) (Normes de traitement de l’information fédérale).
# Utilisation IPv6 avec l'API de données Amazon RDS
L'API Amazon RDS Data prend en charge la IPv6 connectivité via des points de terminaison à double pile. Cela vous permet de vous connecter à l'API de données à l'aide d' IPv6 adresses tout en maintenant la rétrocompatibilité avec IPv4.
## IPv6 assistance aux terminaux
L'API de données fournit des points de terminaison à double pile qui prennent en charge à la fois les connexions IPv4 et les connexions IPv6 . Ces points de terminaison utilisent le domaine `.aws` au lieu du domaine `.amazonaws.com` traditionnel.
### Types de point de terminaison disponibles
Points de terminaison Dual-Stack publics
Format : `rds-data.region.api.aws`
Exemple : `rds-data.us-east-1.api.aws`
Points de terminaison FIPS Dual-Stack
Format : `rds-data-fips.region.api.aws`
Exemple : `rds-data-fips.us-east-1.api.aws`
PrivateLink IPv6 points de terminaison
Disponible via les points de terminaison VPC avec support IPv6
Permet une IPv6 connectivité privée au sein de votre VPC
### IPv4Terminaux traditionnels uniquement
Les `.amazonaws.com` points de terminaison existants continuent de prendre en charge les IPv4 connexions uniquement :
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**Note**
Les points de terminaison existants restent inchangés afin de garantir la rétrocompatibilité avec les applications existantes.
## Utilisation des points de IPv6 terminaison
Pour l'utiliser IPv6 avec l'API Data, mettez à jour votre application pour utiliser les nouveaux points de terminaison à double pile. Votre application sera automatiquement utilisée IPv6 si elle est disponible, ou reviendra à IPv4.
Pour obtenir des conseils généraux sur la configuration IPv6 dans votre VPC, consultez la section [Migration vers IPv6 le guide de](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html) l'utilisateur Amazon *VPC*.
Vous pouvez configurer les IPv6 points de terminaison de deux manières :
+ **Utilisation d'une variable d'environnement** : définissez `AWS_USE_DUALSTACK_ENDPOINT=true` dans votre IPv6 environnement. Le AWS CLI et AWS SDKs construira automatiquement les `api.aws` points de terminaison appropriés sans que vous ayez à spécifier le point de terminaison URLs manuellement.
+ **Utilisation d'un point de terminaison explicite URLs** : spécifiez l'URL du point de terminaison à double pile directement dans vos AWS CLI commandes ou dans la configuration du SDK, comme indiqué dans les exemples ci-dessous.
### AWS CLI configuration
Configurez les IPv6 points AWS CLI de terminaison pour les utiliser en spécifiant l'URL du point de terminaison :
Pour Linux, macOS ou Unix :
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
Pour Windows :
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### AWS Configuration du SDK
Configurez AWS SDKs pour utiliser des points de terminaison à double pile :
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## Utilisation AWS PrivateLink avec IPv6
Vous pouvez créer des points de terminaison VPC pour l'API de données qui prennent en charge la IPv6 connectivité au sein de votre VPC. Pour obtenir des instructions détaillées sur la création de points de terminaison de VPC pour l’API de données, consultez [Création d’un point de terminaison de VPC Amazon pour l’API de données Amazon RDS (AWS PrivateLink)](data-api.vpc-endpoint.md).
Lorsque vous créez un point de terminaison VPC pour le IPv6 support, assurez-vous que :
+ Votre VPC et vos sous-réseaux sont configurés pour prendre en charge IPv6
+ Les groupes de sécurité autorisent le IPv6 trafic sur les ports requis (généralement 443 pour HTTPS)
+ Le réseau ACLs est configuré pour autoriser IPv6 le trafic
## Considérations concernant la migration
Lors de la migration vers des IPv6 terminaux, tenez compte des points suivants :
+ **Migration progressive** : vous pouvez migrer les applications progressivement en mettant à jour le terminal URLs une application à la fois.
+ **Compatibilité réseau** : assurez-vous que votre infrastructure réseau est compatible IPv6 avant de procéder à la migration.
+ **Politiques de sécurité** : mettez à jour les règles du groupe de sécurité et ACLs le réseau pour autoriser IPv6 le trafic si nécessaire.
+ **Surveillance** : mettez à jour les configurations de surveillance et de journalisation pour gérer IPv6 les adresses.
**Note**
**Adresses de connexion à la base** de données : lorsque vous utilisez des IPv6 points de terminaison pour l'API de données, les connexions à la base de données sous-jacentes et les journaux de base de données affichent toujours IPv4 les adresses. Ce comportement est attendu et n'affecte pas les fonctionnalités de vos applications IPv6 activées.
## Résolution des problèmes IPv6 de connectivité
Si vous rencontrez des problèmes de IPv6 connectivité, vérifiez les points suivants :
Configuration réseau
Vérifiez que votre réseau est compatible IPv6 et que IPv6 le routage est correctement configuré.
Résolution DNS
Assurez-vous que votre résolveur DNS peut résoudre les enregistrements AAAA pour les points de terminaison Dual-Stack.
Groupes de sécurité
Mettez à jour les règles du groupe de sécurité pour autoriser le IPv6 trafic sur les ports requis (généralement 443 pour HTTPS).
Bibliothèques clientes
Vérifiez que vos bibliothèques clientes HTTP prennent en charge IPv6 la connectivité à double pile.
# Limites de l’API de données Amazon RDS
L’API de données RDS présente les limitations suivantes :
+ Vous ne pouvez exécuter des requêtes d’API de données que sur des instances en écriture dans un cluster de bases de données. Toutefois, les instances en écriture peuvent accepter à la fois des requêtes d’écriture et de lecture.
+ Les bases de données globales Aurora permettent d’activer l’API de données aussi bien sur le cluster de bases de données principal que sur le cluster secondaire. Toutefois, un cluster secondaire ne possède aucune instance en écriture tant qu’il n’est pas devenu le cluster principal. L’API de données requiert un accès à l’instance en écriture pour traiter les requêtes, y compris les requêtes en lecture. Ainsi, les requêtes de lecture et d’écriture envoyées à un cluster secondaire échouent tant qu’il ne dispose pas d’une instance en écriture. Dès qu’un cluster secondaire est promu et qu’une instance en écriture devient disponible, les requêtes de l’API de données sur cette base de données aboutissent.
+ L’API de données n’est pas prise en charge sur les classes d’instance de base de données T.
+ L’API de données RDS ne prend pas en charge certains types de données lorsqu’elle est utilisée avec Aurora Serverless v2 ou des clusters de bases de données provisionnés. Pour obtenir la liste des types pris en charge, consultez [Comparaison des comportements de l’API de données Amazon RDS entre Aurora Serverless v2 et les clusters provisionnés avec les clusters Aurora Serverless v1](data-api.differences.md).
+ Pour les bases de données Aurora PostgreSQL version 14 et ultérieures, l’API de données prend uniquement en charge `scram-sha-256` pour le chiffrement des mots de passe.
+ 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.
+ La taille de l’API de données ne doit pas dépasser 64 Ko par ligne dans le jeu de résultat renvoyé par la base de données. Assurez-vous que la taille de chaque ligne d’un jeu de résultat est inférieure ou égale à 64 Ko.
# Comparaison des comportements de l’API de données Amazon RDS entre Aurora Serverless v2 et les clusters provisionnés avec les clusters Aurora Serverless v1
Les dernières améliorations apportées aux API de données Amazon RDS les rendent compatibles avec les clusters fonctionnant sur les versions récentes des moteurs PostgreSQL ou MySQL. Ces clusters peuvent être configurés pour utiliser Aurora Serverless v2 ou provisionner des classes d’instance telles que `db.r6g` ou `db.r6i`.
Les sections suivantes décrivent les différences de l’API de données Amazon RDS entre Aurora Serverless v2 et les clusters de bases de données provisionnés, ainsi que les clusters de bases de données Aurora Serverless v1. Les clusters de bases de données Aurora Serverless v1 utilisent le mode moteur `serverless`. Les clusters de bases de données provisionnés utilisent le mode moteur `provisioned`. Un cluster de bases de données Aurora Serverless v2 utilise le mode moteur `provisioned` et contient une ou plusieurs instances de base de données Aurora Serverless v2 avec la classe d’instance `db.serverless`.
## Nombre maximal de demandes par seconde
**Aurora Serverless v1**
Les API de données peuvent traiter jusqu’à 1 000 demandes par seconde.
**Aurora Serverless v2**
Les API de données peuvent traiter un nombre illimité de demandes par seconde.
## Activation ou désactivation de l’API de données Amazon RDS sur une base de données existante
**Aurora Serverless v1**
+ **Avec l’API Amazon RDS** : utilisez l’opération `ModifyCluster` et indiquez `True` ou `False`, selon le cas, pour le paramètre `EnableHttpEndpoint`.
+ **Avec AWS CLI** : utilisez l’opération `modify-db-cluster` avec l’option `--enable-http-endpoint` ou `--no-enable-http-endpoint`, selon le cas.
**Aurora Serverless v2**
+ **Avec l’API Amazon RDS** : utilisez les opérations `EnableHttpEndpoint` et `DisableHttpEndpoint`.
+ **Avec AWS CLI** : utilisez les opérations `enable-http-endpoint` et `disable-http-endpoint`.
## Événements CloudTrail
**Aurora Serverless v1**
Les événements provenant des appels de l’API de données sont des événements de gestion. Par défaut, ces événements sont consignés automatiquement dans un journal d’activité. Pour plus d’informations, consultez [Exclure les événements de l'API de données AWS CloudTrail d'un historique (Aurora Serverless v1uniquement)](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events).
**Aurora Serverless v2**
Les événements provenant des appels de l’API de données sont des événements de données. Par défaut, ces événements sont automatiquement exclus du journal d’activité. Pour plus d’informations, consultez [Inclure les événements de l'API de données dans un AWS CloudTrail historique](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events).
## Prise en charge d’instructions multiples
**Aurora Serverless v1**
+ Les instructions multiples ne sont pas prises en charge avec Aurora MySQL.
+ Les instructions multiples renvoient uniquement la première réponse à la requête dans Aurora PostgreSQL.
**Aurora Serverless v2**
Les instructions multiples ne sont pas prises en charge. Toute tentative d’exécution d’instructions multiples dans un seul appel d’API renvoie `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`. Pour exécuter des instructions multiples, effectuez des appels d’API `ExecuteStatement` distincts ou utilisez `BatchExecuteStatement` pour le traitement par lots.
L’exemple suivant illustre le message d’erreur renvoyé par un appel d’API qui tente d’exécuter une instruction multiple.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
L’exemple suivant exécute des instructions multiples avec des appels d’API `ExecuteStatement` distincts.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## Demandes simultanées pour le même ID de transaction
**Aurora Serverless v1**
Les demandes suivantes sont mises en attente jusqu’à ce que la demande en cours soit achevée. Votre application doit traiter les erreurs de délai d’expiration en cas d’attente prolongée.
**Aurora Serverless v2**
Lorsque l’API de données reçoit plusieurs demandes avec le même ID de transaction, elle renvoie immédiatement cette erreur :
`DatabaseErrorException: Transaction is still running a query`
Cette erreur se produit dans deux situations :
+ Votre application effectue des demandes asynchrones (comme des promesses JavaScript) en utilisant le même ID de transaction.
+ Une demande précédente avec cet ID de transaction est toujours en cours de traitement.
L’exemple suivant illustre toutes les demandes exécutées en parallèle avec `promise.all()`.
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
Pour résoudre cette erreur, attendez que la demande en cours se termine avant d’envoyer une autre demande avec le même ID de transaction, ou supprimez l’ID de transaction afin d’autoriser les demandes parallèles.
L’exemple suivant illustre un appel d’API qui utilise une exécution séquentielle avec le même ID de transaction.
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## Comportement de l’instruction BatchExecuteStatement
Pour plus d’informations sur l’instruction `BatchExecuteStatement`, consultez [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html).
**Aurora Serverless v1**
L’objet des champs générés dans le résultat de la mise à jour inclut les valeurs insérées.
**Aurora Serverless v2**
+ L’objet des champs générés dans le résultat de la mise à jour inclut les valeurs insérées dans Aurora MySQL.
+ L’objet des champs générés est vide dans Aurora PostgreSQL.
## Comportement de l’instruction ExecuteSQL
Pour plus d’informations sur l’instruction `ExecuteSQL`, consultez [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html).
**Aurora Serverless v1**
L’opération `ExecuteSQL` est obsolète.
**Aurora Serverless v2**
L’opération `ExecuteSQL` n’est pas prise en charge.
## Comportement de l’instruction ExecuteStatement
Pour plus d’informations sur l’instruction `ExecuteStatement`, consultez [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html).
**Aurora Serverless v1**
Le paramètre `ExecuteStatement` prend en charge la récupération de colonnes de tableaux multidimensionnels ainsi que de tous les types de données avancés.
**Aurora Serverless v2**
Le paramètre `ExecuteStatement` ne prend pas en charge les colonnes de tableaux multidimensionnels. Certains types de données PostgreSQL ne sont également pas pris en charge, en particulier les types géométriques et les types monétaires. Lorsqu’une API de données rencontre un type de données non pris en charge, elle renvoie cette erreur : `UnsupportedResultException: The result contains the unsupported data type data_type`.
Pour contourner ce problème, convertissez le type de données non pris en charge en `TEXT`. L’exemple suivant convertit un type de données non pris en charge en `TEXT`.
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
Pour obtenir la liste des types de données pris en charge pour chaque moteur de base de données Aurora, consultez [Référence des opérations de l’API de données](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations).
## Comportement des paramètres de schéma
**Aurora Serverless v1**
Le paramètre `Schema` n’est pas pris en charge. Si le paramètre `Schema` est inclus dans un appel d’API, il est ignoré par l’API de données.
**Aurora Serverless v2**
Le paramètre `Schema` est obsolète. Si le paramètre `Schema` est inclus dans un appel d’API, l’API de données renvoie l’erreur suivante : `ValidationException: The schema parameter isn't supported`. L’exemple suivant illustre un appel de l’API de données qui renvoie l’erreur `ValidationException`.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
Pour résoudre ce problème, supprimez le paramètre `Schema` de votre appel d’API.
L’exemple suivant illustre un appel de l’API de données où le paramètre `Schema` a été supprimé.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# Autorisation de l’accès à l’API de données Amazon RDS
Les utilisateurs peuvent invoquer les opérations de l’API de données Amazon RDS (API de données) seulement s’ils sont autorisés à le faire. Vous pouvez autoriser un utilisateur à utiliser l'API de données en joignant une politique Gestion des identités et des accès AWS (IAM) qui définit ses privilèges. Vous pouvez également attacher la politique à un rôle si vous utilisez les rôles IAM. Une politique AWS gérée inclut `AmazonRDSDataFullAccess` des autorisations pour l'API de données.
La `AmazonRDSDataFullAccess` politique inclut également des autorisations permettant à l'utilisateur d'obtenir la valeur d'un secret AWS Secrets Manager. Les utilisateurs doivent utiliser Secrets Manager pour stocker les secrets qu’ils peuvent utiliser dans leurs appels à l’API de données. L’utilisation de secrets signifie que les utilisateurs n’ont pas besoin d’inclure des informations d’identification de base de données pour les ressources qu’ils ciblent dans leurs appels à l’API de données. L’API de données appelle Secrets Manager de manière transparente, qui autorise (ou refuse) la demande de secret de l’utilisateur. Pour plus d’informations sur la configuration des secrets à utiliser avec l’API de données, consultez [Stockage des identifiants de base de données dans AWS Secrets Manager](#data-api.secrets).
La politique `AmazonRDSDataFullAccess` fournit un accès complet (via l’API de données) aux ressources. Vous pouvez limiter la portée en définissant vos propres politiques qui spécifient l’ARN (Amazon Resource Name) d’une ressource.
Par exemple, la politique suivante présente un exemple des autorisations minimales requises pour qu’un utilisateur puisse accéder à l’API de données pour le cluster de bases de données identifié par son ARN. La politique comprend les autorisations nécessaires pour accéder à Secrets Manager et obtenir l’autorisation sur l’instance de base de données pour l’utilisateur.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:BatchExecuteStatement",
"rds-data:BeginTransaction",
"rds-data:CommitTransaction",
"rds-data:ExecuteStatement",
"rds-data:RollbackTransaction"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
}
]
}
```
------
Nous vous recommandons d’utiliser un ARN spécifique pour l’élément « Resources » dans les instructions de votre politique (comme indiqué dans l’exemple) plutôt qu’un caractère générique (\$1).
## Utilisation de l’autorisation basée sur les balises
L’API de données RDS (API de données) et Secrets Manager prennent en charge l’autorisation basée sur les balises. Les *balises* sont des paires clé-valeur qui étiquettent une ressource, telle qu’un cluster RDS, avec une valeur de chaîne supplémentaire, par exemple :
+ `environment:production`
+ `environment:development`
Vous pouvez appliquer des balises à vos ressources pour la répartition des coûts, la prise en charge des opérations, le contrôle d’accès et bien d’autres raisons. (Si vous n’avez pas appliqué de balises à vos ressources et que vous souhaitez le faire, vous pouvez en savoir plus en consultant [Balisage de ressources Amazon RDS](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html).) Vous pouvez utiliser les balises de vos instructions de politique pour limiter l’accès aux clusters RDS étiquetés avec ces balises. Par exemple, un cluster de bases de données Aurora peut avoir des balises qui identifient son environnement en tant que production ou développement.
L’exemple suivant montre comment utiliser les balises dans vos instructions de politique. Cette instruction exige que le cluster et le secret transmis dans la demande d’API de données aient une balise `environment:production`.
Voici comment la politique est appliquée : lorsqu’un utilisateur effectue un appel via l’API de données, la demande est envoyée au service. L’API de données vérifie d’abord que l’ARN du cluster transmis dans la demande contient la balise `environment:production`. Elle appelle ensuite Secrets Manager pour récupérer la valeur du secret de l’utilisateur dans la requête. Secrets Manager vérifie également que le secret de l’utilisateur est étiqueté avec `environment:production`. Si tel est le cas, l’API de données utilise ensuite la valeur extraite en tant que mot de passe de base de données de l’utilisateur. Enfin, si cette valeur est également correcte, la demande d’API de données est appelée avec succès pour l’utilisateur.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "SecretsManagerDbCredentialsAccess",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
},
{
"Sid": "RDSDataServiceAccess",
"Effect": "Allow",
"Action": [
"rds-data:*"
],
"Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
"Condition": {
"StringEquals": {
"aws:ResourceTag/environment": [
"production"
]
}
}
}
]
}
```
------
L’exemple montre des actions distinctes pour `rds-data` et `secretsmanager` pour l’API de données et Secrets Manager. Cependant, vous pouvez combiner des actions et définir des conditions de balise de différentes manières afin de prendre en charge vos cas d’utilisation spécifiques. Pour plus d’informations, consultez [Utilisation des stratégies basées sur l’identité (stratégies IAM) pour Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition).
Dans l’élément « Condition » de la politique, vous pouvez choisir les clés de balise parmi les suivantes :
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
Pour en savoir plus sur les balises de ressources et sur leur utilisation`aws:TagKeys`, consultez la section [Contrôle de l'accès aux AWS ressources à l'aide de balises de ressources](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys).
**Note**
À la fois l'API de données et AWS Secrets Manager les utilisateurs autorisés. Si vous ne disposez pas des autorisations requises pour toutes les actions définies dans une stratégie, une erreur `AccessDeniedException` s’affiche.
## Stockage des identifiants de base de données dans AWS Secrets Manager
Lorsque vous appelez l’API de données Amazon RDS (API de données), vous pouvez transmettre des informations d’identification pour le cluster de bases de données en utilisant un secret dans Secrets Manager. Pour ce faire, vous devez spécifier le nom du secret ou son ARN (Amazon Resource Name).
**Pour stocker les informations d’identification de cluster de bases de données dans un secret**
1. Utilisez Secrets Manager pour créer un secret qui contient les informations d’identification du cluster de bases de données Aurora.
Pour obtenir des instructions, consultez [Création d’un secret de base de données](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html) dans le *Guide de l’utilisateur AWS Secrets Manager *.
1. Utilisez la console Secrets Manager pour afficher les détails du secret que vous avez créé ou exécutez la `aws secretsmanager describe-secret` AWS CLI commande.
Notez le nom et l’ARN du secret. Vous pouvez les utiliser dans les appels à l’API de données.
Pour plus d’informations sur l’utilisation de Secrets Manager, consultez le [Guide de l’utilisateur AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html).
Pour comprendre comment Amazon Aurora assure la gestion des identités et des accès, consultez [Comment Amazon Aurora fonctionne avec IAM](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html).
Pour en savoir plus sur la création d’une stratégie IAM, consultez [Création de stratégies IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) dans le *Guide de l’utilisateur IAM*. Pour en savoir plus sur l’ajout d’une stratégie IAM, consultez [Ajout et suppression de stratégies IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) dans le *Guide de l’utilisateur IAM*.
# Activation de l’API de données Amazon RDS
L’API de données Amazon RDS (API de données) doit être activée sur le cluster de bases de données Aurora avant de pouvoir être utilisée. Vous pouvez activer l’API de données lorsque vous créez ou modifiez le cluster de bases de données.
**Note**
La disponibilité de l'API de données pour votre cluster dépend de votre version d'Aurora, de votre moteur de base de données et de votre AWS région. Sur les anciennes versions d’Aurora, l’API de données ne peut être utilisée qu’avec des clusters Aurora Serverless v1. Sur les nouvelles versions d’Aurora, l’API de données fonctionne avec des clusters qui utilisent à la fois des instances provisionnées et des instances Aurora Serverless v2. Pour vérifier si votre cluster peut utiliser l’API de données, consultez [Régions et moteurs de base de données Aurora pris en charge pour l’API de données RDS](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md).
**Topics**
+ [
## Activation de l’API de données RDS lors de la création d’une base de données
](#data-api.enabling.creating)
+ [
## Activation de l’API de données RDS sur une base de données existante
](#data-api.enabling.modifying)
## Activation de l’API de données RDS lors de la création d’une base de données
Lorsque vous créez une base de données compatible avec l’API de données RDS (API de données), vous pouvez activer cette fonctionnalité. Les procédures suivantes décrivent comment procéder lorsque vous utilisez l'API AWS Management Console AWS CLI, la ou l'API RDS.
### Console
Pour activer l’API de données lors de la création d’un cluster de bases de données, cochez la case **Activer l’API de données RDS** dans la section **Connectivité** de la page **Créer une base de données**, comme illustré dans la capture d’écran suivante.
![\[Section Connectivité de la page Créer une base de données, où la case Activer l’API de données RDS est cochée.\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
Pour obtenir des instructions sur la création d’un cluster de bases de données Aurora compatible avec l’API de données RDS, consultez les informations suivantes :
+ Pour Aurora Serverless v2 et les clusters provisionnés : [Création d’un cluster de bases de données Amazon Aurora](Aurora.CreateInstance.md)
+ Pour Aurora Serverless v1 : [Création d’un cluster de bases de données Aurora Serverless v1](aurora-serverless.create.md)
### AWS CLI
Pour activer l'API de données lors de la création d'un cluster de base de données Aurora, exécutez la [create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) AWS CLI commande avec l'`--enable-http-endpoint`option.
Voici un exemple de création d’un cluster de bases de données Aurora PostgreSQL où l’API de données est activée.
Pour Linux, macOS ou Unix :
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
Pour Windows :
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### API RDS
Pour activer l'API de données pendant que vous créez un cluster de base de données Aurora, utilisez l'DBClusteropération [Create](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) avec la valeur du `EnableHttpEndpoint` paramètre définie sur`true`.
## Activation de l’API de données RDS sur une base de données existante
Vous pouvez modifier un cluster de bases de données compatible avec l’API de données RDS (API de données) pour activer ou désactiver cette fonctionnalité.
**Topics**
+ [
### Activation ou désactivation de l’API de données (Aurora Serverless v2 et base de données provisionnée)
](#data-api.enabling.modifying.all)
+ [
### Activation ou désactivation de l’API de données (Aurora Serverless v1 uniquement)
](#data-api.enabling.modifying.sv1)
### Activation ou désactivation de l’API de données (Aurora Serverless v2 et base de données provisionnée)
Utilisez les procédures suivantes pour activer ou désactiver l’API de données sur Aurora Serverless v2 et les bases de données provisionnées. Pour activer ou désactiver l’API de données sur les bases de données Aurora Serverless v1, utilisez les procédures indiquées dans [Activation ou désactivation de l’API de données (Aurora Serverless v1 uniquement)](#data-api.enabling.modifying.sv1).
#### Console
Si votre cluster de bases de données prend en charge cette fonctionnalité, vous pouvez activer ou désactiver l’API de données directement depuis la console RDS. Pour ce faire, ouvrez la page des détails du cluster de la base de données sur laquelle vous souhaitez activer ou désactiver l’API de données, puis dans l’onglet **Connectivité et sécurité**, accédez à la section **API de données RDS**. Cette section affiche l’état de l’API de données et vous permet de l’activer ou de la désactiver.
Dans la capture d’écran suivante, l’**API de données RDS** est désactivée.
![\[Section API de données RDS sur l’onglet Connectivité et sécurité de la page des détails d’un cluster de bases de données. L’API de données apparaît comme désactivée et le bouton Activer l’API de données RDS est visible.\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
Pour activer ou désactiver l'API de données sur une base de données existante, exécutez la [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) AWS CLI commande [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html)or et spécifiez l'ARN de votre cluster de bases de données.
Dans l’exemple suivant, l’API de données est activée.
Pour Linux, macOS ou Unix :
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
Pour Windows :
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### API RDS
Pour activer ou désactiver l'API de données sur une base de données existante, utilisez les [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html)opérations [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html)et.
### Activation ou désactivation de l’API de données (Aurora Serverless v1 uniquement)
Utilisez les procédures suivantes pour activer ou désactiver l’API de données sur les bases de données Aurora Serverless v1 existantes. Utilisez les procédures indiquées dans [Activation ou désactivation de l’API de données (Aurora Serverless v2 et base de données provisionnée)](#data-api.enabling.modifying.all) pour activer ou désactiver l’API de données sur Aurora Serverless v2 et les bases de données provisionnées.
#### Console
Lorsque vous créez ou modifiez un cluster de bases de données Aurora Serverless v1, vous pouvez activez l’API de données dans la section **Connectivité** de la console RDS.
Dans la capture d’écran ci-dessous, l’**API de données** est activée lors de la modification d’un cluster de bases de données Aurora.
![\[Dans la section Connectivité de la page Modifier le cluster de bases de données, la case API de données est cochée.\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
Pour obtenir des instructions sur la modification d’un cluster de bases de données Aurora Serverless v1, consultez [Modification d’un cluster de bases de données Aurora Serverless v1](aurora-serverless.modifying.md).
#### AWS CLI
Pour activer ou désactiver l'API de données, exécutez la [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) AWS CLI commande, avec le `--enable-http-endpoint` ou`--no-enable-http-endpoint`, selon le cas.
Dans l’exemple suivant, l’API de données est activée sur `sample-cluster`.
Pour Linux, macOS ou Unix :
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
Pour Windows :
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### API RDS
Pour activer l'API de données, utilisez l'DBClusteropération [Modifier](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) et définissez la valeur de `EnableHttpEndpoint` to `true` ou`false`, le cas échéant.
# Création d’un point de terminaison de VPC Amazon pour l’API de données Amazon RDS (AWS PrivateLink)
Amazon VPC vous permet de lancer AWS des ressources, telles que des clusters de base de données Aurora et des applications, dans un cloud privé virtuel (VPC). AWS PrivateLink fournit une connectivité privée VPCs et AWS des services hautement sécurisés sur le réseau Amazon. À l'aide de AWS PrivateLink, vous pouvez créer des points de terminaison Amazon VPC, qui vous permettent de vous connecter à des services via différents comptes et VPCs sur la base d'Amazon VPC. Pour plus d’informations sur AWS PrivateLink, consultez [Services de points de terminaison de VPC (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) dans le *Guide de l’utilisateur Amazon Virtual Private Cloud*.
Vous pouvez appeler l’API de données RDS (API de données) avec des points de terminaison Amazon VPC. L'utilisation d'un point de terminaison Amazon VPC permet de maintenir le trafic entre les applications de votre Amazon VPC et l'API de données sur le AWS réseau, sans utiliser d'adresses IP publiques. Les points de terminaison Amazon VPC peuvent vous aider à respecter les exigences réglementaires et de conformité liées à la limitation de la connectivité Internet publique. Par exemple, si vous utilisez un point de terminaison Amazon VPC, vous pouvez conserver le trafic entre une application exécutée sur une instance Amazon EC2 et l'API de données qui VPCs les contient.
Une fois que vous avez créé le point de terminaison Amazon VPC, vous pouvez commencer à l’utiliser sans modifier le code ou la configuration de votre application.
**Pour créer un point de terminaison Amazon VPC pour l’API de données**
1. Connectez-vous à la console Amazon VPC AWS Management Console et ouvrez-la à l'adresse. [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)
1. Choisissez **Points de terminaison**, puis **Créer un point de terminaison**.
1. Sur la page **Créer un point de terminaison**, pour **Catégorie de services**, choisissez **Services AWS **. Pour **Nom du service**, choisissez **rds-data**.
![\[Créez un point de terminaison Amazon VPC pour l’API de données\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. Pour **VPC**, choisissez le VPC dans lequel créer le point de terminaison.
Choisissez le VPC contenant l’application qui effectue des appels de l’API de données.
1. Pour les **sous-réseaux**, choisissez le sous-réseau pour chaque zone de disponibilité (AZ) utilisée par le AWS service qui exécute votre application.
![\[Choisissez des sous-réseaux pour le point de terminaison Amazon VPC\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
Pour créer un point de terminaison Amazon VPC, spécifiez la plage d’adresses IP privées dans laquelle le point de terminaison sera accessible. Pour ce faire, choisissez le sous-réseau de chaque zone de disponibilité. Cela limite le point de terminaison de VPC à la plage d’adresses IP privées spécifique à chaque zone de disponibilité et crée également un point de terminaison Amazon VPC dans chaque zone de disponibilité.
1. Pour **Enable DNS Name (Activer le nom DNS)**, sélectionnez **Activer pour ce point de terminaison**.
![\[Activez le nom DNS pour le point de terminaison Amazon VPC\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
Private DNS résout le nom d’hôte DNS standard de l’API de données (`https://rds-data.region.amazonaws.com`) par les adresses IP privées associées au nom d’hôte DNS spécifique à votre point de terminaison Amazon VPC. Par conséquent, vous pouvez accéder au point de terminaison VPC de l'API de données en utilisant AWS CLI ou AWS SDKs sans apporter de modifications de code ou de configuration pour mettre à jour l'URL du point de terminaison de l'API de données.
1. Pour **Groupe de sécurité**, choisissez un groupe de sécurité à associer au point de terminaison Amazon VPC.
Choisissez le groupe de sécurité qui autorise l'accès au AWS service qui exécute votre application. Par exemple, si une instance Amazon EC2 exécute votre application, choisissez le groupe de sécurité qui autorise l’accès à cette instance Amazon EC2. Le groupe de sécurité vous permet de contrôler le trafic vers le point de terminaison Amazon VPC à partir des ressources de votre VPC.
1. Pour **Stratégie**, choisissez **Accès complet** pour permettre à toute personne à l’intérieur de l’Amazon VPC d’accéder à l’API de données via ce point de terminaison. Ou choisissez **Personnalisé** pour spécifier une stratégie qui limite l’accès.
Si vous choisissez **Personnalisé**, entrez la stratégie dans l’outil de création de stratégie.
1. Choisissez **Créer un point de terminaison**.
Une fois le point de terminaison créé, choisissez le lien dans le AWS Management Console pour afficher les détails du point de terminaison.
![\[Lien vers les détails du point de terminaison Amazon VPC\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
L’onglet **Détails** du point de terminaison affiche les noms d’hôte DNS générés lors de la création du point de terminaison Amazon VPC.
![\[Lien vers les détails du point de terminaison Amazon VPC\]](http://docs.aws.amazon.com/fr_fr/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
Vous pouvez utiliser le point de terminaison standard (`rds-data.region.amazonaws.com`) ou l’un des points de terminaison spécifiques au VPC pour appeler l’API de données dans l’Amazon VPC. Le point de terminaison standard de l’API de données effectue automatiquement un routage vers le point de terminaison Amazon VPC. Ce routage se produit car le nom d’hôte DNS privé a été activé lors de la création du point de terminaison Amazon VPC.
Lorsque vous utilisez un point de terminaison Amazon VPC dans un appel d'API de données, tout le trafic entre votre application et l'API de données reste dans l'Amazon VPCs qui les contient. Vous pouvez utiliser un point de terminaison Amazon VPC pour n’importe quel type d’appel à l’API de données. Pour plus d’informations sur l’appel de l’API de données, consultez [Appel de l’API de données Amazon RDS](data-api.calling.md).
# 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));
}
```
# Utilisation de la bibliothèque cliente Java pour l’API de données RDS
Vous pouvez télécharger et utiliser une bibliothèque cliente Java pour l’API de données RDS (API de données). Cette bibliothèque cliente Java propose une autre manière d’utiliser l’API de données. En utilisant cette bibliothèque, vous pouvez mapper vos classes côté client aux demandes et aux réponses de l’API de données. La prise en charge de ce mappage peut faciliter l’intégration à certains types Java précis, comme `Date`, `Time` et `BigDecimal`.
## Téléchargement de la bibliothèque cliente Java pour l’API de données
La bibliothèque cliente Java de l'API de données est open source GitHub à l'emplacement suivant :
[ https://github.com/awslabs/rds-data-api-client-bibliothèque-java](https://github.com/awslabs/rds-data-api-client-library-java)
Vous pouvez créer la bibliothèque manuellement à partir des fichiers sources, mais la bonne pratique consiste à la consommer en utilisant la gestion des dépendances Apache Maven. Ajoutez la dépendance suivante à votre fichier POM Maven.
Pour la version 2.x, qui est compatible avec le AWS SDK 2.x, utilisez ce qui suit :
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
Pour la version 1.x, qui est compatible avec le AWS SDK 1.x, utilisez ce qui suit :
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## Exemples relatifs à la bibliothèque cliente Java
Vous trouverez, ci-dessous, quelques exemples d’utilisation de la bibliothèque cliente Java de l’API de données. Ces exemples supposent que vous disposez d’un tableau `accounts` à deux colonnes : `accountId` et `name`. Vous disposez également de l’objet de transfert de données (DTO) suivant.
```
public class Account {
int accountId;
String name;
// getters and setters omitted
}
```
La bibliothèque cliente vous permet de passer en DTOs tant que paramètres d'entrée. L'exemple suivant montre comment le client DTOs est mappé aux ensembles de paramètres d'entrée.
```
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();
```
Dans certains cas, il est plus facile de travailler avec des valeurs simples en tant que paramètres d’entrée. Pour cela, utilisez la syntaxe suivante.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();
```
Voici un autre exemple qui fonctionne avec des valeurs simples en tant que paramètres d’entrée.
```
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
.execute();
```
La bibliothèque cliente fournit un mappage automatique vers le DTOs moment où un résultat est renvoyé. Les exemples suivants montrent comment le résultat est mappé à votre DTOs.
```
List result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);
```
Dans de nombreux cas, l’ensemble de résultats de la base de données ne contient qu’une seule valeur. Afin de simplifier la récupération de ces résultats, la bibliothèque cliente propose l’API suivante :
```
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
```
**Note**
La fonction `mapToList` convertit un ensemble de résultats SQL en liste d’objets définie par l’utilisateur. Nous ne prenons pas en charge l’utilisation de l’instruction `.withFormatRecordsAs(RecordsFormatType.JSON)` dans un appel `ExecuteStatement` pour la bibliothèque cliente Java, car elle a la même finalité. Pour plus d’informations, consultez [Traitement des requêtes d’API Amazon RDS Data au format JSON](data-api-json.md).
# Traitement des requêtes d’API Amazon RDS Data au format JSON
Lorsque vous appelez l’opération `ExecuteStatement`, vous pouvez choisir que les résultats de la requête soient retournés sous forme de chaîne au format JSON. Ainsi, vous pouvez utiliser les capacités d’analyse JSON de votre langage de programmation pour interpréter et reformater l’ensemble de résultats. Cela permet d’éviter d’écrire du code supplémentaire pour boucler sur l’ensemble de résultats et interpréter chaque valeur de colonne.
Pour demander l’ensemble de résultats au format JSON, vous transmettez le paramètre `formatRecordsAs` facultatif avec une valeur `JSON`. L’ensemble de résultats au format JSON est renvoyé dans le champ `formattedRecords` de la structure `ExecuteStatementResponse`.
L’action `BatchExecuteStatement` ne renvoie pas d’ensemble de résultats. Ainsi, l’option JSON ne s’applique pas à cette action.
Pour personnaliser les clés dans la structure de hachage JSON, définissez des alias de colonne dans l’ensemble de résultats. Vous pouvez le faire en utilisant la clause `AS` dans la liste des colonnes de votre requête SQL.
Vous pouvez utiliser la fonctionnalité JSON pour faciliter la lecture de l’ensemble des résultats et faire correspondre son contenu à des cadres spécifiques à la langue. Étant donné que le volume de l’ensemble des résultats codés en ASCII est plus important que celui de la représentation par défaut, vous pouvez choisir cette dernière pour les requêtes qui renvoient un grand nombre de lignes ou des valeurs de colonnes importantes qui consomment plus de mémoire que celle dont dispose votre application.
**Topics**
+ [
## Récupération des résultats des requêtes au format JSON
](#data-api-json-querying)
+ [
## Mappage des types de données
](#data-api-json-datatypes)
+ [
## Résolution des problèmes
](#data-api-json-troubleshooting)
+ [
## Exemples
](#data-api-json-examples)
## Récupération des résultats des requêtes au format JSON
Pour recevoir l’ensemble de résultats sous forme de chaîne JSON, incluez `.withFormatRecordsAs(RecordsFormatType.JSON)` dans l’appel `ExecuteStatement`. La valeur de retour revient sous la forme d’une chaîne JSON dans le champ `formattedRecords`. Dans ce cas, le champ `columnMetadata` est `null`. Les étiquettes des colonnes sont les clés de l’objet qui représente chaque ligne. Ces noms de colonnes sont répétés pour chaque ligne de l’ensemble de résultats. Les valeurs des colonnes sont des chaînes de caractères entre guillemets, des valeurs numériques ou des valeurs spéciales représentant `true`, `false`, ou `null`. Les métadonnées des colonnes, telles que les contraintes de longueur et le type précis des nombres et des chaînes de caractères, ne sont pas conservées dans la réponse JSON.
Si vous omettez l’appel `.withFormatRecordsAs()` ou spécifiez un paramètre de `NONE`, l’ensemble de résultats est renvoyé au format binaire en utilisant les champs `Records` et `columnMetadata`.
## Mappage des types de données
Les valeurs SQL de l’ensemble de résultats sont mises en correspondance avec un ensemble plus petit de types JSON. Les valeurs sont représentées dans JSON sous forme de chaînes de caractères, de nombres et de certaines constantes spéciales telles que `true`, `false` et `null`. Vous pouvez convertir ces valeurs en variables dans votre application, en utilisant un typage fort ou faible, selon le langage de programmation utilisé.
****
| Type de données JDBC | Type de données JSON |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | Numéro par défaut. Chaîne si l’option `LongReturnType` est définie sur `STRING`. |
| `FLOAT`, `REAL`, `DOUBLE` | Nombre |
| `DECIMAL` | Chaîne par défaut. Nombre si l’option `DecimalReturnType` est définie sur `DOUBLE_OR_LONG`. |
| `STRING` | Chaîne |
| `BOOLEAN`, `BIT` | Booléen |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | Chaîne avec encodage base64. |
| `CLOB` | Chaîne |
| `ARRAY` | Tableau |
| `NULL` | `null` |
| Autres types (y compris les types liés à la date et à l’heure) | Chaîne |
## Résolution des problèmes
La réponse JSON est limitée à 10 mégaoctets. Si la réponse est supérieure à cette limite, votre programme reçoit une erreur `BadRequestException`. Dans ce cas, vous pouvez résoudre l’erreur en utilisant l’une des techniques suivantes :
+ Réduisez le nombre de lignes dans l’ensemble de résultats. Pour ce faire, ajoutez une clause `LIMIT`. Vous pouvez diviser un grand ensemble de résultats en plusieurs petits ensembles en envoyant plusieurs requêtes avec des clauses `LIMIT` et `OFFSET`.
Si l’ensemble de résultats comprend des lignes qui sont filtrées par la logique d’application, vous pouvez supprimer ces lignes de l’ensemble de résultats en ajoutant d’autres conditions à la clause `WHERE`.
+ Réduisez le nombre de colonnes dans l’ensemble de résultats. Pour ce faire, supprimez les éléments de la liste Select de la requête.
+ Raccourcissez les étiquettes des colonnes en utilisant des alias de colonnes dans la requête. Chaque nom de colonne est répété dans la chaîne JSON pour chaque ligne de l’ensemble de résultats. Ainsi, un résultat de requête comportant de longs noms de colonnes et de nombreuses lignes pourrait dépasser la limite de taille. En particulier, utilisez des alias de colonne pour les expressions complexes afin d’éviter que l’expression entière ne soit répétée dans la chaîne JSON.
+ Bien qu’en SQL, vous puissiez utiliser des alias de colonne pour produire un ensemble de résultats comportant plusieurs colonnes portant le même nom, les doublons de noms de clés ne sont pas autorisés en JSON. L’API de données RDS renvoie une erreur si vous demandez l’ensemble de résultats au format JSON et que plusieurs colonnes portent le même nom. Ainsi, assurez-vous que toutes les étiquettes de colonne portent des noms uniques.
## Exemples
Les exemples Java suivants montrent comment appeler `ExecuteStatement` avec la réponse sous forme de chaîne formatée en JSON, puis interpréter l’ensemble de résultats. Remplacez les valeurs appropriées pour les paramètres *databaseName*, *secretStoreArn* et *clusterArn*.
L’exemple Java suivant illustre une requête qui renvoie une valeur numérique décimale dans l’ensemble de résultats. Les appels `assertThat` vérifient que les champs de la réponse présentent les propriétés attendues, conformément aux règles applicables aux ensembles de résultats JSON.
Cet exemple fonctionne avec le schéma et les exemples de données suivants :
```
create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);
```
```
public void JSON_result_set_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request);
}
```
La valeur du champ `formattedRecords` du programme précédent est :
```
[{"a":10.0}]
```
Les champs `Records` et `ColumnMetadata` dans la réponse sont tous deux nuls, en raison de la présence de l’ensemble de résultats JSON.
L’exemple Java suivant illustre une requête qui renvoie une valeur numérique entière dans l’ensemble de résultats. L’exemple appelle `getFormattedRecords` à ne retourner que la chaîne formatée en JSON et à ignorer les autres champs de réponse qui sont vides ou nuls. L’exemple désérialise le résultat dans une structure représentant une liste de registres. Chaque registre possède des champs dont les noms correspondent aux alias des colonnes de l’ensemble de résultats. Cette technique simplifie le code qui analyse l’ensemble des résultats. Votre application n’a pas besoin de boucler sur les lignes et les colonnes de l’ensemble de résultats et de convertir chaque valeur dans le type approprié.
Cet exemple fonctionne avec le schéma et les exemples de données suivants :
```
create table test_simplified_json (a int);
insert into test_simplified_json values(17);
```
```
public void JSON_deserialization_demo() {
var sql = "select * from test_simplified_json";
var request = new ExecuteStatementRequest()
.withDatabase(databaseName)
.withSecretArn(secretStoreArn)
.withResourceArn(clusterArn)
.withSql(sql)
.withFormatRecordsAs(RecordsFormatType.JSON);
var result = rdsdataClient.executeStatement(request)
.getFormattedRecords();
/* Turn the result set into a Java object, a list of records.
Each record has a field 'a' corresponding to the column
labelled 'a' in the result set. */
private static class Record { public int a; }
var recordsList = new ObjectMapper().readValue(
response, new TypeReference>() {
});
}
```
La valeur du champ `formattedRecords` du programme précédent est :
```
[{"a":17}]
```
Pour récupérer la colonne `a` de la ligne de résultats 0, l’application doit se référer à `recordsList.get(0).a`.
En revanche, l’exemple Java suivant montre le type de code nécessaire pour créer une structure de données contenant l’ensemble de résultats lorsque vous n’utilisez pas le format JSON. Dans ce cas, chaque ligne de l’ensemble de résultats contient des champs comportant des informations sur un seul utilisateur. La création d’une structure de données pour représenter l’ensemble des résultats nécessite l’exécution en boucle des lignes. Pour chaque ligne, le code récupère la valeur de chaque champ, effectue une conversion de type appropriée et affecte le résultat au champ correspondant dans l’objet représentant la ligne. Ensuite, le code ajoute l’objet représentant chaque utilisateur à la structure de données représentant l’ensemble des résultats. Si la requête était modifiée pour réorganiser, ajouter ou supprimer des champs dans l’ensemble de résultats, le code de l’application devrait également être modifié.
```
/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
var user = User.builder()
.userId(row.get(0).getLongValue())
.firstName(row.get(1).getStringValue())
.lastName(row.get(2).getStringValue())
.dob(Instant.parse(row.get(3).getStringValue()))
.build();
result.add(user);
}
```
Les exemples suivants montrent les valeurs du champ `formattedRecords` pour des ensembles de résultats comportant différents nombres de colonnes, alias de colonnes et types de données de colonnes.
Si l’ensemble de résultats comprend plusieurs lignes, chaque ligne est représentée par un objet qui constitue un élément de tableau. Chaque colonne de l’ensemble de résultats devient une clé dans l’objet. Les clés sont répétées pour chaque ligne de l’ensemble de résultats. Ainsi, pour les ensembles de résultats composés de nombreuses lignes et colonnes, vous devrez peut-être définir des alias de colonne courts pour éviter de dépasser la limite de longueur pour l’ensemble de la réponse.
Cet exemple fonctionne avec le schéma et les exemples de données suivants :
```
create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
```
```
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
```
Si une colonne de l’ensemble de résultats est définie comme une expression, le texte de l’expression devient la clé JSON. Ainsi, il est généralement pratique de définir un alias de colonne descriptif pour chaque expression de la liste Select de la requête. Par exemple, la requête suivante inclut des expressions telles que des appels de fonction et des opérations arithmétiques dans sa liste Select.
```
select count(*), max(id), 4+7 from sample_names;
```
Ces expressions sont transmises à l’ensemble de résultats JSON en tant que clés.
```
[{"count(*)":5,"max(id)":4,"4+7":11}]
```
L’ajout de colonnes `AS` avec des étiquettes descriptives rend les clés plus simples à interpréter dans l’ensemble de résultats JSON.
```
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
```
Avec la requête SQL révisée, les étiquettes des colonnes définies par les clauses `AS` sont utilisées comme noms de clés.
```
[{"rows":5,"largest_id":4,"addition_result":11}]
```
La valeur de chaque paire clé-valeur dans la chaîne JSON peut être une chaîne entre guillemets. La chaîne peut contenir des caractères unicode. Si la chaîne contient des séquences d’échappement ou les caractères `"` ou `\`, ces caractères sont précédés de caractères d’échappement barre oblique inverse. Les exemples suivants de chaînes JSON illustrent ces possibilités. Par exemple, le résultat `string_with_escape_sequences` contient les caractères spéciaux retour arrière, saut de ligne, retour chariot, tabulation, saut de page et `\`.
```
[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
```
La valeur de chaque paire clé-valeur dans la chaîne JSON peut également représenter un nombre. Le nombre peut être un entier, une valeur en virgule flottante, une valeur négative ou une valeur représentée en notation exponentielle. Les exemples suivants de chaînes JSON illustrent ces possibilités.
```
[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
```
Les valeurs booléennes et nulles sont représentées par les mots-clés spéciaux non entourés de guillemets `true`, `false` et `null`. Les exemples suivants de chaînes JSON illustrent ces possibilités.
```
[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}]
```
Si vous sélectionnez une valeur de type BLOB, le résultat est représenté dans la chaîne JSON sous la forme d’une valeur avec encodage base64. Pour reconvertir la valeur dans sa représentation originale, vous pouvez utiliser la fonction de décodage appropriée dans le langage de votre application. Par exemple, en Java, vous appelez la fonction `Base64.getDecoder().decode()`. L’exemple de sortie suivant montre le résultat de la sélection d’une valeur BLOB de `hello world` et du renvoi de l’ensemble de résultats sous forme de chaîne JSON.
```
[{"blob_column":"aGVsbG8gd29ybGQ="}]
```
L’exemple Python suivant montre comment accéder aux valeurs du résultat d’un appel à la fonction Python `execute_statement`. L’ensemble de résultats est une valeur de chaîne de caractères dans le champ `response['formattedRecords']`. Le code transforme la chaîne JSON en une structure de données en appelant la fonction `json.loads`. Ensuite, chaque ligne de l’ensemble de résultats est un élément de liste dans la structure de données ; dans chaque ligne, vous pouvez faire référence à chaque champ de l’ensemble de résultats par son nom.
```
import json
result = json.loads(response['formattedRecords'])
print (result[0]["id"])
```
L’exemple JavaScript suivant montre comment accéder aux valeurs du résultat d’un appel à la fonction JavaScript `executeStatement`. L’ensemble de résultats est une valeur de chaîne de caractères dans le champ `response.formattedRecords`. Le code transforme la chaîne JSON en une structure de données en appelant la fonction `JSON.parse`. Ensuite, chaque ligne de l’ensemble de résultats représente un élément de tableau dans la structure de données ; dans chaque ligne, vous pouvez faire référence à chaque champ de l’ensemble de résultats par son nom.
```
```
# Dépannage de l’API de données Amazon RDS
Utilisez les sections suivantes, dont le titre correspond aux messages d’erreur courants, pour vous aider à résoudre les problèmes que vous rencontrez avec l’API de données Amazon RDS (API de données).
**Topics**
+ [
## Transaction isn’t found
](#data-api.troubleshooting.tran-id-not-found)
+ [
## Packet for query is too large
](#data-api.troubleshooting.packet-too-large)
+ [
## Database Response Exceeded Size Limit
](#data-api.troubleshooting.response-size-too-large)
+ [
## HttpEndpoint n'est pas activé pour le cluster
](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [
## DatabaseErrorException: La transaction exécute toujours une requête
](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [
## Exception de résultat non pris en charge
](#data-api.troubleshooting.unsupported-result)
+ [
## Les instructions multiples ne sont pas prises en charge
](#data-api.troubleshooting.multi-statements)
+ [
## Le paramètre de schéma n’est pas pris en charge
](#data-api.troubleshooting.schema-parameter)
+ [
## IPv6 problèmes de connectivité
](#data-api.troubleshooting.ipv6-connectivity)
## Transaction isn’t found
Dans ce cas, l’ID de transaction spécifié dans un appel de l’API de données est introuvable. La cause de ce problème, parmi les suivantes, est ajoutée au message d’erreur :
+ La transaction peut avoir expiré.
Assurez-vous que chaque appel transactionnel s’exécute dans un délai de trois minutes à la suite du précédent.
Il est également possible que l'identifiant de transaction spécifié n'ait pas été créé par un [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)appel. Assurez-vous que l’ID de transaction de votre appel est valide.
+ Un appel précédent a entraîné l’arrêt de votre transaction.
La transaction a déjà été arrêtée par votre appel `CommitTransaction` ou `RollbackTransaction`.
+ La transaction a été abandonnée en raison d’une erreur issue d’un appel précédent.
Vérifiez si vos appels précédents ont généré des exceptions.
Pour plus d’informations sur l’exécution des transactions, consultez [Appel de l’API de données Amazon RDS](data-api.calling.md).
## Packet for query is too large
Dans ce cas, le jeu de résultats renvoyé pour une ligne était trop volumineux. La taille de l’API de données ne doit pas dépasser 64 Ko par ligne dans le jeu de résultat renvoyé par la base de données.
Pour résoudre ce problème, assurez-vous que la taille de chaque ligne d’un jeu de résultat est inférieure ou égale à 64 Ko.
## Database Response Exceeded Size Limit
Dans ce cas, la taille du jeu de résultat renvoyé par la base de données était trop grande. La limite de l’API de données est de 1 Mio dans le jeu de résultats renvoyé par la base de données.
Pour résoudre ce problème, assurez-vous que les appels à l’API de données renvoient au maximum 1 Mio. Si vous avez besoin de renvoyer plus de 1 Mio, vous pouvez utiliser plusieurs appels [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) avec la clause `LIMIT` dans votre requête.
Pour plus d’informations sur la clause `LIMIT`, consultez [Syntaxe SELECT](https://dev.mysql.com/doc/refman/8.0/en/select.html) dans la documentation de MySQL.
## HttpEndpoint n'est pas activé pour le cluster
Vérifiez les causes potentielles suivantes de ce problème :
+ Le cluster de bases de données Aurora ne prend pas en charge l’API de données. Pour plus d’informations sur les types de clusters de bases de données pris en charge par l’API de données RDS, consultez [Disponibilité des régions et des versions de pour l’API de données Amazon RDS](data-api.regions.md).
+ L’API de données n’est pas activée pour le cluster de bases de données Aurora. Pour utiliser l’API de données avec un cluster de bases de données Aurora, l’API de données doit être activée pour le cluster de bases de données. Pour plus d’informations sur l’activation de l’API de données, consultez [Activation de l’API de données Amazon RDS](data-api.enabling.md).
+ Le cluster de bases de données a été renommé après l’activation de l’API de données. Dans ce cas, désactivez l’API de données pour ce cluster, puis réactivez-la.
+ L’ARN que vous avez spécifié ne correspond pas précisément à l’ARN du cluster. Vérifiez que l’ARN renvoyé par une autre source ou créé par la logique du programme correspond exactement à l’ARN du cluster. Par exemple, assurez-vous que l’ARN que vous utilisez respecte la casse adéquate pour tous les caractères alphabétiques.
## DatabaseErrorException: La transaction exécute toujours une requête
Lorsque votre application envoie une demande avec un ID de transaction qui exécute déjà une autre requête, l’API de données renvoie immédiatement cette erreur à votre application. Cette situation peut se produire si votre application envoie des demandes de façon asynchrone, par exemple à l’aide d’un mécanisme comme les « promesses » en Javascript.
Pour résoudre ce problème, attendez que la demande précédente soit terminée, puis réessayez. Vous pouvez répéter la tentative jusqu’à ce que l’erreur disparaisse ou qu’un autre type d’erreur soit renvoyé à l’application.
Cette condition peut se produire avec l’API de données pour Aurora Serverless v2 et les instances provisionnées. Dans l’API de données pour Aurora Serverless v1, les demandes envoyées avec le même ID de transaction sont mises en attente jusqu’à ce que la précédente soit terminée. Cependant, cet ancien comportement peut entraîner des délais d’expiration si la demande précédente met trop de temps à s’exécuter. Si vous migrez une ancienne application d’API de données qui envoie des demandes simultanées, adaptez votre logique de gestion des exceptions afin de prendre en compte ce nouveau type d’erreur.
## Exception de résultat non pris en charge
L’API de données ne prend pas en charge tous les types de données. Cette erreur se produit lorsque vous exécutez une requête qui renvoie un type de données non pris en charge.
Pour contourner ce problème, convertissez le type de données non pris en charge en `TEXT`. Par exemple :
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## Les instructions multiples ne sont pas prises en charge
Les instructions multiples ne sont pas prises en charge dans l’API de données pour Aurora sans serveur v2 et les clusters provisionnés. Toute tentative d’exécuter plusieurs instructions dans un seul appel d’API entraîne cette erreur.
Pour exécuter des instructions multiples, utilisez des appels d’API `ExecuteStatement` distincts ou utilisez l’API `BatchExecuteStatement` pour le traitement par lots.
## Le paramètre de schéma n’est pas pris en charge
Aurora sans serveur v1 ignore silencieusement le paramètre de schéma. Cependant, Aurora sans serveur v2 et les clusters provisionnés rejettent explicitement les appels d’API contenant le paramètre de schéma.
Pour résoudre ce problème, supprimez le paramètre de schéma de tous les appels à l’API de données lorsque vous utilisez Aurora sans serveur v2 ou des clusters provisionnés.
## IPv6 problèmes de connectivité
Si vous rencontrez des problèmes lors de la connexion à l'API de données à l'aide de IPv6 points de terminaison, vérifiez les causes potentielles suivantes :
+ Le **réseau n'est pas compatible IPv6** : vérifiez que votre infrastructure réseau est compatible IPv6 et que IPv6 le routage est correctement configuré.
+ **Problèmes de résolution DNS** : assurez-vous que votre résolveur DNS peut résoudre les enregistrements AAAA pour les points de terminaison Dual-Stack (par ex., `rds-data.us-east-1.api.aws`).
+ **Configuration du groupe de sécurité** : mettez à jour les règles du groupe de sécurité pour autoriser le IPv6 trafic sur le port 443 (HTTPS). Ajoutez des règles pour les blocs IPv6 CIDR (par exemple, `::/0` pour toutes les IPv6 adresses).
+ **Configuration de l'ACL réseau** : assurez-vous que le réseau ACLs autorise le IPv6 trafic sur les ports requis.
+ **Compatibilité avec les bibliothèques clientes** : vérifiez que vos bibliothèques clientes HTTP AWS SDKs prennent en charge IPv6 la connectivité à double pile.
+ **Configuration du point de terminaison VPC** : si vous l'utilisez PrivateLink, assurez-vous que votre point de terminaison VPC est configuré pour prendre en charge IPv6 et que des blocs d'adresse CIDR sont attribués aux sous-réseaux associés. IPv6
Pour résoudre les problèmes de IPv6 connectivité, procédez comme suit :
1. Testez la connectivité à l'aide des points de terminaison IPv4 -only (`.amazonaws.com`) pour vérifier que le problème est spécifique à. IPv6
1. Utilisez les outils de diagnostic réseau pour vérifier la IPv6 connectivité aux points de terminaison à double pile.
1. Vérifiez les CloudTrail journaux pour détecter toute erreur d'authentification ou d'autorisation lors de l'utilisation de IPv6 points de terminaison.
1. Vérifiez que votre application est correctement configurée pour utiliser le nouveau point de terminaison URLs à double pile.
# Journalisation des appels d'API Amazon RDS Data avec AWS CloudTrail
L'API de données RDS (API de données) est intégrée à AWS CloudTrail un service qui fournit un enregistrement des actions entreprises par un utilisateur, un rôle ou un AWS service dans l'API de données. CloudTrail capture tous les appels d'API pour l'API de données sous forme d'événements, y compris les appels depuis la console Amazon RDS et les appels de code vers les opérations de l'API de données. Si vous créez un suivi, vous pouvez activer la diffusion continue d' CloudTrail événements vers un compartiment Amazon S3, y compris des événements pour l'API de données. À l'aide des données collectées par CloudTrail, vous pouvez déterminer de nombreuses informations. Ces informations comprennent la demande qui a été faite à l’API de données, l’adresse IP à partir de laquelle la demande a été faite, qui a effectué la demande, quand elle a eu lieu, ainsi que des détails supplémentaires.
Pour en savoir plus CloudTrail, consultez le [guide de AWS CloudTrail l'utilisateur](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
## Utilisation des informations de l'API de données dans CloudTrail
CloudTrail est activé sur votre AWS compte lorsque vous le créez. Lorsqu'une activité prise en charge (événements de gestion) se produit dans l'API de données, cette activité est enregistrée dans un CloudTrail événement avec d'autres événements de AWS service dans **l'historique** des événements. Vous pouvez consulter, rechercher et télécharger les derniers événements de gestion dans votre AWS compte. Pour plus d'informations, consultez la section [Utilisation de l'historique des CloudTrail événements](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) dans le *guide de AWS CloudTrail l'utilisateur.*
Pour un enregistrement continu des événements de votre AWS compte, y compris des événements relatifs à l'API Data, créez une trace. Un *suivi* permet CloudTrail de fournir des fichiers journaux à un compartiment Amazon S3. Par défaut, lorsque vous créez un parcours dans la console, celui-ci s'applique à toutes les AWS régions. Le journal enregistre les événements de toutes les AWS régions de la AWS partition et transmet les fichiers journaux au compartiment Amazon S3 que vous spécifiez. En outre, vous pouvez configurer d'autres AWS services pour analyser plus en détail les données d'événements collectées dans les CloudTrail journaux et agir en conséquence. Pour plus d’informations, consultez les rubriques suivantes dans le *AWS CloudTrail Guide de l’utilisateur* :
+ [Présentation de la création d’un journal d’activité](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail services et intégrations pris en charge](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [Configuration des notifications Amazon SNS pour CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [Réception de fichiers CloudTrail journaux de plusieurs régions](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) et [réception de fichiers CloudTrail journaux de plusieurs comptes](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html)
Toutes les opérations de l'API de données sont enregistrées CloudTrail et documentées dans la [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html). Par exemple, les appels aux `ExecuteStatement` opérations `BatchExecuteStatement``BeginTransaction`,`CommitTransaction`, et génèrent des entrées dans les fichiers CloudTrail journaux.
Chaque événement ou entrée de journal contient des informations sur la personne ayant initié la demande. Les informations relatives à l’identité permettent de déterminer les éléments suivants :
+ Si la demande a été effectuée avec les informations d’identification utilisateur racine ou .
+ Si la demande a été effectuée avec les informations d’identification de sécurité temporaires d’un rôle ou d’un utilisateur fédéré.
+ Si la demande a été faite par un autre AWS service.
Pour de plus amples informations, veuillez consulter l'[élément userIdentity CloudTrail ](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
## Inclure et exclure les événements de l'API de données d'un AWS CloudTrail historique
La plupart des utilisateurs de l'API de données s'appuient sur les événements d' AWS CloudTrail un suivi pour fournir un enregistrement des opérations de l'API de données. Les données d’événements ne révèlent pas le nom de la base de données, le nom du schéma ni les instructions SQL dans les demandes adressées à l’API de données. Toutefois, identifier quel utilisateur a exécuté un type d’appel sur un cluster de bases de données spécifique à un instant donné peut contribuer à repérer les modèles d’accès anormaux.
### Inclure les événements de l'API de données dans un AWS CloudTrail historique
*Pour Aurora PostgreSQL Serverless v2 et les bases de données provisionnées, les opérations de l'API de données suivantes sont enregistrées en tant qu'événements de données. AWS CloudTrail * Les [événements de données](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) sont des opérations d'API de plan de données à volume élevé qui CloudTrail ne sont pas enregistrées par défaut. Des frais supplémentaires s’appliquent pour les événements de données. Pour plus d'informations sur la CloudTrail tarification, consultez la section [AWS CloudTrail Tarification](https://aws.amazon.com/cloudtrail/pricing/).
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
Vous pouvez utiliser la CloudTrail console ou AWS CLI les opérations d' CloudTrail API pour enregistrer ces opérations d'API de données. Dans la CloudTrail console, choisissez **RDS Data API - DB Cluster** pour le type d'événement Data. Pour plus d’informations, consultez [Journalisation des événements de données avec l’ AWS Management Console](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI) dans le *Guide de l’utilisateur AWS CloudTrail *.
À l'aide de AWS CLI, exécutez la `aws cloudtrail put-event-selectors` commande pour enregistrer ces opérations de l'API de données pour votre parcours. Pour enregistrer tous les événements de l’API de données sur les clusters de bases de données, indiquez `AWS::RDS::DBCluster` pour le type de ressource. L’exemple suivant illustre la journalisation de tous les événements de l’API de données sur les clusters de bases de données. Pour plus d’informations, consultez [Journalisation des événements de données avec la AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html) dans le *Guide de l’utilisateur AWS CloudTrail *.
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
Vous pouvez configurer des sélecteurs d’événements avancés pour appliquer un filtre supplémentaire sur les champs `readOnly`, `eventName,` et `resources.ARN`. Pour plus d'informations sur ces champs, consultez [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html).
### Exclure les événements de l'API de données AWS CloudTrail d'un historique (Aurora Serverless v1uniquement)
Les événements de l’API de données sont des événements de gestion dans Aurora Serverless v1. Par défaut, tous les événements de l'API de données sont inclus dans un AWS CloudTrail journal. Toutefois, étant donné que l'API de données peut générer un grand nombre d'événements, vous souhaiterez peut-être exclure ces événements de votre CloudTrail suivi. Le paramètre **Exclure les événements de l’API de données Amazon RDS** exclut tous les événements de l’API de données du journal d’activité. Vous ne pouvez pas exclure des événements d’API de données spécifiques.
Pour exclure des événements d’API de données d’un journal d’activité, procédez comme suit :
+ Dans la CloudTrail console, choisissez le paramètre **Exclure les événements de l'API Amazon RDS Data** lorsque vous [créez un suivi ou que](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html) vous le [mettez à jour.](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html)
+ Dans l' CloudTrail API, utilisez l'[PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html)opération. Si vous utilisez des sélecteurs d’événements avancés, vous pouvez exclure les événements de l’API de données en configurant le champ `eventSource` avec une valeur différente de `rdsdata.amazonaws.com`. Si vous utilisez des sélecteurs d’événements basiques, vous pouvez exclure les événements de l’API de données en définissant la valeur de l’attribut `ExcludeManagementEventSources` sur `rdsdata.amazonaws.com`. Pour plus d’informations, consultez [Journalisation des événements avec l’ AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI) dans le *Guide de l’utilisateur AWS CloudTrail *.
**Avertissement**
L'exclusion des événements de l'API de données d'un CloudTrail journal peut masquer les actions de l'API de données. Soyez prudent lorsque vous accordez aux principaux l’autorisation `cloudtrail:PutEventSelectors` nécessaire pour effectuer cette opération.
Vous pouvez désactiver cette exclusion à tout moment en modifiant le paramétrage de la console ou les sélecteurs d’événements pour un journal d’activité. Le journal d’activité commencera alors à enregistrer les événements d’API de données. Toutefois, il ne pourra pas récupérer les événements d’API de données survenus pendant que l’exclusion était effective.
Lorsque vous excluez des événements de l'API Data à l'aide de la console ou de l'API, l'opération d' CloudTrail`PutEventSelectors`API qui en résulte est également enregistrée dans vos CloudTrail journaux. Si les événements de l'API de données n'apparaissent pas dans vos CloudTrail journaux, recherchez un `PutEventSelectors` événement dont l'`ExcludeManagementEventSources`attribut est défini sur`rdsdata.amazonaws.com`.
Pour plus d’informations, consultez [Journalisation des événements de gestion pour les journaux d’activité](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html) dans le *Guide de l’utilisateur AWS CloudTrail *.
## Présentation des entrées des fichiers journaux de l’API de données
Un *suivi* est une configuration qui permet de transmettre des événements sous forme de fichiers journaux à un compartiment Amazon S3 que vous spécifiez. CloudTrail les fichiers journaux contiennent une ou plusieurs entrées de journal. Un *événement* représente une demande unique provenant de n'importe quelle source et inclut des informations sur l'action demandée, la date et l'heure de l'action, les paramètres de la demande, etc. CloudTrail les fichiers journaux ne constituent pas une trace ordonnée des appels d'API publics, ils n'apparaissent donc pas dans un ordre spécifique.
**Aurora PostgreSQL sans serveur v2 et les bases de données provisionnées**
L'exemple suivant montre une entrée de CloudTrail journal qui illustre le `ExecuteStatement` fonctionnement d'Aurora PostgreSQL Serverless v2 et des bases de données provisionnées. Pour ces bases de données, tous les événements de l’API de données sont des événements de données dont la source est **rdsdataapi.amazonaws.com** et le type d’événement est **Rds Data Service**.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
L'exemple suivant montre comment l'exemple d'entrée de CloudTrail journal précédent apparaît pourAurora Serverless v1. En effetAurora Serverless v1, tous les événements sont des événements de gestion dont la source est **rdsdata.amazonaws.com** et le type d'événement est. **AwsApiCall**
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# Surveillance des requêtes de l’API de données RDS avec Performance Insights
Si votre cluster Aurora exécute Aurora Serverless v2 ou des instances provisionnées, vous pouvez utiliser Performance Insights avec l’API de données RDS.
Pour plus d’informations sur l’utilisation de Performance Insights avec Aurora, consultez [Surveillance de la charge de la base de données avec Performance Insights sur ](USER_PerfInsights.md).
## Représentation des requêtes de l’API de données RDS dans Performance Insights
Avec l’API de données, votre cluster Aurora traite les requêtes en fonction des appels d’API de données que vous soumettez depuis votre application. L’API de données exécute également certaines instructions SQL dans le cadre de son propre fonctionnement interne, telles que l’annulation de requêtes dépassant le seuil du délai d’exécution. Les deux types d’opérations SQL sont présentés dans les statistiques et les graphiques de Performance Insights.
+ Lorsqu’une requête de l’API de données est envoyée à un cluster Aurora, le champ **Hôte** dans le tableau de bord PI apparaît comme **API de données RDS**. Pour Aurora PostgreSQL, le champ **application\$1name** présente la valeur `rds-data-api`. Recherchez ces étiquettes lorsque vous analysez la charge de la base de données en utilisant la dimension **Principaux hôtes** ou **Principales applications**.
+ Toutes les requêtes internes exécutées par l’API de données pour gérer les aspects de la base de données tels que le pool de connexions et les délais d’expiration des requêtes sont annotées avec un préfixe **API de données RDS**. Exemple : `/* RDS Data API */ select * from my_table;` recherche ces préfixes lorsque vous analysez la charge de la base de données en fonction des **Principaux éléments SQL** en tant que dimension. utilisés comme dimension. Les instructions sont annotées à l’aide d’un commentaire SQL de `/* RDS Data API */`.