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 RDS
En utilisant l'API de données RDS (API de données), vous pouvez utiliser une interface de services Web pour votre cluster de base de données Aurora. L'API de données ne nécessite pas de connexion permanente au cluster de base de données. Au lieu de cela, il fournit un point de terminaison HTTP sécurisé et une intégration avec AWS les SDK. 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 les informations d'identification dans Secrets Manager, les utilisateurs doivent disposer des autorisations appropriées pour utiliser Secrets Manager, ainsi que l'API de données. Pour plus d'informations sur les autorisations accordées aux utilisateurs, consultez Autoriser l'accès à l'API de données RDS.
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 fournit un moyen d'utilisation plus sécurisé AWS Lambda. 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 Virtual Private Cloud (VPC). Pour plus d’informations, consultez AWS Lambda
Vous pouvez activer l'API de données lorsque vous créez le cluster de base de données Aurora. Vous pouvez également modifier la configuration ultérieurement. Pour plus d’informations, consultez Activation de l'API de données RDS.
Après avoir activé l'API de données, vous pouvez également utiliser l'éditeur de requêtes pour exécuter des requêtes 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.
Rubriques
- Disponibilité des régions et des versions
- Limites de l'API de données RDS
- Comparaison de l'API de données RDS avec Serverless v2 et provisionnée, et Aurora Serverless v1
- Autoriser l'accès à l'API de données RDS
- Activation de l'API de données RDS
- Création d'un point de terminaison Amazon VPC pour l'API de données RDS ()AWS PrivateLink
- Appel de l'API de données RDS
- Utilisation de la bibliothèque cliente Java pour l'API de données RDS
- Traitement des résultats des requêtes de l'API RDS Data au format JSON
- Résolution des problèmes liés à l'API RDS Data
- Journalisation des appels d'API RDS Data avec AWS CloudTrail
Disponibilité des régions et des versions
Pour plus d'informations sur les régions et les versions du moteur disponibles pour l'API de données, consultez les sections suivantes.
| Type de cluster | Disponibilité des régions et des versions |
|---|---|
Aurora PostgreSQL v2 provisionné et sans serveur |
API de données avec Aurora PostgreSQL Serverless v2 et provisionnée |
Aurora PostgreSQL sans serveur v1 |
|
Aurora MySQL version 1 sans serveur |
Note
Actuellement, l'API de données n'est pas disponible pour les clusters de base de données Aurora MySQL provisionnés ou sans serveur v2.
Si vous avez besoin de modules cryptographiques validés par la norme FIPS 140-2 lorsque vous accédez à l'API de données via une interface de ligne de commande 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
Limites de l'API de données RDS
L'API de données RDS (API de données) présente les limites suivantes :
Vous ne pouvez exécuter des requêtes d'API de données que sur des instances d'écriture dans un cluster de base de données. Toutefois, les instances Writer peuvent accepter à la fois des requêtes d'écriture et de lecture.
Avec les bases de données globales Aurora, vous pouvez activer l'API de données sur les clusters de base de données principaux et secondaires. Cependant, tant qu'un cluster secondaire n'est pas promu principal, il ne possède aucune instance d'écriture. Ainsi, les requêtes de l'API de données que vous envoyez au secondaire échouent. Une fois qu'une instance de rédacteur secondaire promue est disponible, les requêtes de l'API de données sur cette instance de base de données devraient aboutir.
Performance Insights ne prend pas en charge la surveillance des requêtes de base de données que vous effectuez à l'aide de l'API Data.
L'API de données n'est pas prise en charge sur les classes d'instance de base de données T.
Pour Aurora PostgreSQL Serverless v2 et les clusters de bases de données provisionnés, l'API de données RDS ne prend pas en charge certains types de données. Pour obtenir la liste des types pris en charge, consultezComparaison de l'API de données RDS avec Serverless v2 et provisionnée, et Aurora Serverless v1.
Pour les bases de données Aurora PostgreSQL version 14 et supérieures, l'API Data prend uniquement en charge scram-sha-256 pour le chiffrement des mots de passe.
Comparaison de l'API de données RDS avec Serverless v2 et provisionnée, et Aurora Serverless v1
Le tableau suivant décrit les différences entre l'API de données RDS (API de données) avec Aurora PostgreSQL Serverless v2 et les clusters de base de données provisionnés, et les clusters de base de données. Aurora Serverless v1
| Différence | Aurora PostgreSQL Serverless v2 et provisionné | Aurora Serverless v1 |
|---|---|---|
| Nombre maximum de demandes par seconde | Illimité | 1 000 |
| Activation ou désactivation de l'API de données sur une base de données existante à l'aide de l'API RDS ou AWS CLI |
|
|
| CloudTrail événements | Les événements issus des appels d'API de données sont des événements de données. Ces événements sont automatiquement exclus d'un parcours par défaut. Pour plus d’informations, consultez Inclure les événements de l'API de données dans un AWS CloudTrail historique. | Les événements issus des appels d'API de données sont des événements de gestion. Ces événements sont automatiquement inclus dans un parcours par défaut. Pour plus d’informations, consultez Exclure les événements de l'API de données AWS CloudTrail d'un historique (Aurora Serverless v1uniquement). |
| Prise en charge de plusieurs déclarations | Les multiinstructions ne sont pas prises en charge. Dans ce cas, l'API Data lanceValidationException: Multistatements aren't
supported. |
Pour Aurora PostgreSQL, les instructions multiples renvoient uniquement la première réponse à la requête. Pour Aurora MySQL, les instructions multiples ne sont pas prises en charge. |
| BatchExecuteDéclaration | L'objet des champs générés dans le résultat de la mise à jour est vide. | L'objet des champs générés dans le résultat de la mise à jour inclut les valeurs insérées. |
| Exécuter SQL | Non pris en charge | Obsolète |
| ExecuteStatement |
L'API de données ne prend pas en charge certains types de données, tels que les types géométriques et monétaires. Dans ce cas, l'API Data lance Seuls les types suivants sont pris en charge :
Seuls les types de tableaux suivants sont pris en charge :
|
ExecuteStatementprend en charge la récupération de colonnes de tableaux multidimensionnels et de tous les types de données avancés. |
Autoriser l'accès à l'API de données RDS
Les utilisateurs peuvent invoquer les opérations de l'API de données RDS (API de données) uniquement s'ils sont autorisés à le faire. Vous pouvez autoriser un utilisateur à utiliser l'API de données en joignant une politique AWS Identity and Access Management (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 des 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 les 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 de manière transparente Secrets Manager, 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, consultezStockage des identifiants de base de données dans AWS Secrets Manager.
La AmazonRDSDataFullAccess politique 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 montre un exemple des autorisations minimales requises pour qu'un utilisateur accède à l'API de données pour le cluster de base 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.
{ "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 (*).
Utilisation de l'autorisation basée sur les balises
L'API de données RDS (API de données) et Secrets Manager prennent tous deux en charge l'autorisation basée sur des 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:productionenvironment: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.) 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 base 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 passe un appel à l'aide de l'API Data, 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 est étiqueté avecenvironment: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.
{ "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 pour 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 de plus amples informations, veuillez consulter Utilisation des stratégies basées sur l'identité (stratégies IAM) pour Secrets Manager.
Dans l'élément « Condition » de la politique, vous pouvez choisir les clés de balise parmi les suivantes :
aws:TagKeysaws:ResourceTag/${TagKey}
Pour en savoir plus sur les balises de ressources et sur leur utilisationaws:TagKeys, consultez la section Contrôle de l'accès aux AWS ressources à l'aide de balises de ressources.
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 RDS (API de données), vous transmettez les informations d'identification du cluster de base de données Aurora 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 base de données dans un secret
-
Utilisez Secrets Manager pour créer un secret qui contient les informations d'identification du cluster de base de données Aurora.
Pour obtenir des instructions, consultez la section Création d'un secret de base de données dans le Guide de l'utilisateur AWS Secrets Manager .
-
Utilisez la console Secrets Manager pour afficher les détails du secret que vous avez créé ou exécutez la
aws secretsmanager describe-secretAWS CLI commande.Notez le nom et l'ARN du secret. Vous pouvez les utiliser dans les appels à l'API Data.
Pour plus d'informations sur l'utilisation de Secrets Manager, consultez le Guide de l'utilisateur AWS Secrets Manager.
Pour comprendre comment Amazon Aurora assure la gestion des identités et des accès, veuillez consulter Comment Amazon Aurora fonctionne avec IAM.
Pour en savoir plus sur la création d'une stratégie IAM, consultez Création de stratégies IAM dans le IAM Guide de l'utilisateur. Pour en savoir plus sur l'ajout d'une stratégie IAM, consultez Ajout et suppression de stratégies IAM dans le IAM Guide de l'utilisateur.
Activation de l'API de données RDS
Pour utiliser l'API de données RDS (API de données), activez-la pour votre cluster de base de données Aurora. Vous pouvez activer l'API de données lorsque vous créez ou modifiez le cluster de base de données.
Note
Pour Aurora PostgreSQL, l'API de données est prise en charge et provisionnée Aurora Serverless v2 avec des Aurora Serverless v1 bases de données. Pour Aurora MySQL, l'API de données n'est prise en charge qu'avec les Aurora Serverless v1 bases de données.
Rubriques
Activation de l'API RDS Data lors de la création d'une base de données
Lorsque vous créez une base de données qui prend en charge 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.
Pour activer l'API de données lorsque vous créez un cluster de base 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 dans la capture d'écran suivante.
Pour obtenir des instructions sur la création d'une base de données, consultez les rubriques suivantes :
Pour Aurora PostgreSQL Serverless v2 et les bases de données provisionnées : Création d'un cluster de base de données Amazon Aurora
Pour Aurora Serverless v1 — Création d'un cluster de bases de données Aurora Serverless v1
Pour activer l'API de données lors de la création d'un cluster de base de données Aurora, exécutez la AWS CLI commande create-db-cluster avec l'option. --enable-http-endpoint
L'exemple suivant crée un cluster de base de données Aurora PostgreSQL avec l'API de données activée.
Pour LinuxmacOS, ou Unix :
aws rds create-db-cluster \ --db-cluster-identifiermy_pg_cluster\ --engine aurora-postgresql \ --enable-http-endpoint
Dans Windows :
aws rds create-db-cluster ^ --db-cluster-identifiermy_pg_cluster^ --engine aurora-postgresql ^ --enable-http-endpoint
Pour activer l'API de données pendant que vous créez un cluster de base de données Aurora, utilisez l'opération CreateDBCluster avec la valeur EnableHttpEndpoint du 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 base de données qui prend en charge l'API de données RDS (API de données) pour activer ou désactiver cette fonctionnalité.
Rubriques
Activation ou désactivation de l'API de données (Aurora PostgreSQL Serverless v2 et provisionnée)
Utilisez les procédures suivantes pour activer ou désactiver l'API de données sur Aurora PostgreSQL Serverless v2 et les bases de données provisionnées. Pour activer ou désactiver l'API de données sur les Aurora Serverless v1 bases de données, utilisez les procédures décrites dansActivation ou désactivation de l'API de données (Aurora Serverless v1uniquement).
Vous pouvez activer ou désactiver l'API de données à l'aide de la console RDS d'un cluster de base de données prenant en charge cette fonctionnalité. 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.
La capture d'écran suivante montre que l'API de données RDS n'est pas activée.
Pour activer ou désactiver l'API de données sur une base de données existante, exécutez la AWS CLI commande enable-http-endpoint ou disable-http-endpoint et spécifiez l'ARN de votre cluster de base de données.
L'exemple suivant active l'API Data.
Pour LinuxmacOS, ou Unix :
aws rds enable-http-endpoint \ --resource-arncluster_arn
Dans Windows :
aws rds enable-http-endpoint ^ --resource-arncluster_arn
Pour activer ou désactiver l'API de données sur une base de données existante, utilisez les opérations EnableHttpEndpoint et DisableHttpEndpoint.
Activation ou désactivation de l'API de données (Aurora Serverless v1uniquement)
Utilisez les procédures suivantes pour activer ou désactiver l'API de données sur les Aurora Serverless v1 bases de données existantes. Pour activer ou désactiver l'API de données sur Aurora PostgreSQL Serverless v2 et les bases de données provisionnées, utilisez les procédures décrites dans. Activation ou désactivation de l'API de données (Aurora PostgreSQL Serverless v2 et provisionnée)
Lorsque vous modifiez un Aurora Serverless v1 cluster de base de données, vous activez l'API de données dans la section Connectivité de la console RDS.
La capture d'écran suivante montre l'API de données activée lors de la modification d'un cluster de base de données Aurora.
Pour obtenir des instructions sur la façon de modifier un Aurora Serverless v1 cluster de base de données, consultezModification d'un cluster de bases de données Aurora Serverless v1.
Pour activer ou désactiver l'API de données, exécutez la AWS CLI commande modify-db-cluster, avec le ou, le --enable-http-endpoint cas échéant. --no-enable-http-endpoint
L'exemple suivant active l'API Data sursample-cluster.
Pour LinuxmacOS, ou Unix :
aws rds modify-db-cluster \ --db-cluster-identifier sample-cluster \ --enable-http-endpoint
Dans Windows :
aws rds modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --enable-http-endpoint
Pour activer l'API de données, utilisez l'opération ModifyDbCluster et définissez la valeur EnableHttpEndpoint de true ou, le cas échéant. false
Création d'un point de terminaison Amazon VPC pour l'API de données 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 entre les VPC et les AWS services avec un haut niveau de sécurité 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 VPC basés sur Amazon VPC. Pour plus d’informations sur AWS PrivateLink, consultez Services de points de terminaison de VPC (AWS PrivateLink) dans le Guide de l’utilisateur Amazon Virtual Private Cloud.
Vous pouvez appeler l'API de données RDS (API de données) avec les 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 dans les VPC qui les contiennent.
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 Data
-
Choisissez Points de terminaison, puis Créer un point de terminaison.
-
Sur la page Créer un point de terminaison, pour Catégorie de services, choisissez Services AWS . Pour Nom du service, choisissez rds-data.
-
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.
-
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.
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é.
-
Pour Enable DNS Name (Activer le nom DNS), sélectionnez Activer pour ce point de terminaison.
Private DNS résout le nom d'hôte DNS standard de l'API de données (
https://rds-data.) 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 à l'aide des AWS SDK AWS CLI ou SDK sans apporter de modifications au code ou à la configuration pour mettre à jour l'URL du point de terminaison de l'API de données.region.amazonaws.com -
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.
-
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.
-
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.
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.
Vous pouvez utiliser le point de terminaison standard (rds-data.) 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.region.amazonaws.com
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 les Amazon VPC qui les contiennent. 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 Data, consultezAppel de l'API de données RDS.
Appel de l'API de données RDS
Lorsque l'API de données RDS (API de données) est activée sur votre cluster de base de données Aurora, vous pouvez exécuter des instructions SQL sur le cluster de base de données Aurora à l'aide de l'API de données ou du AWS CLI. L'API de données prend en charge les langages de programmation pris en charge par les AWS SDK. Pour plus d'informations, consultez la section Outils sur lesquels vous pouvez vous appuyer AWS
Rubriques
Référence des opérations de l'API de données
L'API de données fournit les opérations suivantes pour exécuter des instructions SQL.
|
Opération d'API de données |
AWS CLI commande |
Description |
|---|---|---|
|
Exécute une instruction SQL sur une base de données. |
||
|
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 |
|---|---|---|
|
Démarre une transaction SQL. |
||
|
Termine une transaction SQL et valide les modifications. |
||
|
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 |
|---|---|---|---|
|
|
|
Oui |
Le nom de ressource Amazon (ARN) du cluster de base de données Aurora. |
|
|
|
Oui |
Nom ou ARN du secret qui active l'accès au cluster de bases de données. |
Vous pouvez utiliser des paramètres dans les appels de l'API de données vers ExecuteStatement etBatchExecuteStatement, et lorsque vous exécutez les AWS CLI commandes execute-statement etbatch-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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Autres types (y compris les types liés à la date et à l'heure) |
|
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 etTIME, nécessitent un indice pour que l'API de données transmette String les valeurs à la base de données sous le 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ètreStringcorrespondante est envoyée en tant qu'objet de typeDATEà la base de données. Le format accepté estYYYY-MM-DD. -
DECIMAL– La valeur de paramètreStringcorrespondante est envoyée en tant qu'objet de typeDECIMALà la base de données. -
JSON– La valeur de paramètreStringcorrespondante est envoyée en tant qu'objet de typeJSONà la base de données. -
TIME– La valeur de paramètreStringcorrespondante est envoyée en tant qu'objet de typeTIMEà la base de données. Le format accepté estHH:MM:SS[.FFF]. -
TIMESTAMP– La valeur de paramètreStringcorrespondante est envoyée en tant qu'objet de typeTIMESTAMPà la base de données. Le format accepté estYYYY-MM-DD HH:MM:SS[.FFF]. -
UUID– La valeur de paramètreStringcorrespondante est envoyée en tant qu'objet de typeUUIDà la base de données.Note
À l'heure actuelle, l'API de données ne prend pas en charge les tableaux d'identifiants uniques universels (UUID).
Note
Pour Amazon Aurora PostgreSQL, l'API de données renvoie toujours le type de données Aurora PostgreSQL dans le fuseau horaire UTC. TIMESTAMPTZ
Appel de l'API de données RDS à l'aide du AWS CLI
Vous pouvez appeler l'API de données RDS (API de données) à l'aide du AWS CLI.
Les exemples suivants utilisent l'API AWS CLI for Data. Pour plus d'informations, consultez le document de référence AWS CLI pour l'API de données.
Dans chaque exemple, remplacez l'Amazon Resource Name (ARN) du cluster de base de données par l'ARN de votre cluster de base de données Aurora. De même, remplacez l'ARN du secret par l'ARN du secret dans Secrets Manager qui autorise l'accès au cluster de base de données.
Note
Ils AWS CLI peuvent formater les réponses en JSON.
Rubriques
Démarrage d'une transaction SQL
Vous pouvez démarrer une transaction SQL à l'aide de la commande CLI aws rds-data
begin-transaction. L'appel renvoie un identifiant de transaction.
Important
Dans l'API Data, une transaction expire si aucun appel n'utilise son identifiant de transaction dans les trois minutes. Si une transaction expire avant d'être validée, l'API Data l'annule automatiquement.
Les instructions du langage de définition de données (DDL) MySQL à l'intérieur d'une transaction entraînent une validation implicite. Nous vous recommandons d'exécuter chaque instruction DDL MySQL dans une execute-statement commande séparée avec l'--continue-after-timeoutoption.
En plus des options communes, spécifiez l'option --database qui indique le nom de la base de données.
Par exemple, la commande CLI suivante démarre une transaction SQL.
Pour LinuxmacOS, ou Unix :
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
Dans Windows :
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
Voici un exemple de réponse.
{
"transactionId": "ABC1234567890xyz"
}Exécution d'une instruction SQL
Vous pouvez exécuter une instruction SQL à l'aide de la commande CLI aws rds-data execute-statement.
Vous pouvez exécuter une instruction SQL à l'intérieur d'une transaction en spécifiant l'identifiant de la transaction avec l'option --transaction-id. Vous pouvez démarrer une transaction à l'aide de la commande CLI aws rds-data begin-transaction. Vous pouvez terminer et valider une transaction à l'aide de la commande CLI aws rds-data
commit-transaction.
Important
Si vous ne spécifiez pas l'option --transaction-id, les modifications renvoyées par l'appel sont automatiquement validées.
En plus des options courantes, spécifiez les options suivantes :
-
--sql(obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données. -
--transaction-id(facultatif) – Identifiant d'une transaction démarrée à l'aide de la commande CLIbegin-transaction. Spécifiez l'identifiant de la transaction dans laquelle vous souhaitez intégrer l'instruction SQL. -
--parameters(facultatif) – Paramètres pour l'instruction SQL. -
--include-result-metadata | --no-include-result-metadata(facultatif) – Valeur indiquant si les métadonnées doivent apparaître dans les résultats. La valeur par défaut est--no-include-result-metadata. -
--database(facultatif) – Nom de la base de données.L'option
--databasepeut ne pas fonctionner lorsque vous exécutez une instruction SQL après avoir exécuté--sql "usedans la requête précédente. Nous vous recommandons d'utiliser l'optiondatabase_name;"--databaseplutôt que d'exécuter des instructions--sql "use.database_name;" -
--continue-after-timeout | --no-continue-after-timeout(facultatif) — Valeur qui indique s'il faut continuer à exécuter l'instruction après que l'appel ait dépassé le délai d'expiration de 45 secondes de l'API de données. La valeur par défaut est--no-continue-after-timeout.Pour les instructions en langage de définition de données (DDL), nous vous recommandons de continuer à exécuter l'instruction après l'expiration de l'appel afin d'éviter les erreurs et la corruption de structures de données.
-
--format-records-as "JSON"|"NONE": une valeur facultative qui spécifie si l'ensemble de résultats doit être formaté en tant que chaîne JSON. L’argument par défaut est"NONE". Pour obtenir des informations sur l'utilisation du traitement des ensembles de résultats JSON, consultez Traitement des résultats des requêtes de l'API RDS Data au format JSON.
Le cluster de bases de données renvoie une réponse pour l'appel.
Note
La taille de réponse est limitée à 1 Mio. Si l'appel renvoie plus de 1 Mio de données de réponse, l'appel est arrêté.
Car Aurora Serverless v1 le nombre maximum de demandes par seconde est de 1 000. Pour toutes les autres bases de données prises en charge, il n'y a aucune limite.
Par exemple, la commande CLI suivante exécute une instruction SQL unique et omet les métadonnées dans les résultats (par défaut).
Pour LinuxmacOS, ou Unix :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "select * from mytable"
Dans Windows :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "select * from mytable"
Voici un exemple de réponse.
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}La commande CLI suivante exécute une instruction SQL unique dans une transaction en spécifiant l'option --transaction-id.
Pour LinuxmacOS, ou Unix :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
Dans Windows :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
Voici un exemple de réponse.
{
"numberOfRecordsUpdated": 1
}La commande CLI suivante exécute une seule instruction SQL avec des paramètres.
Pour LinuxmacOS, ou Unix :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "insert intomytablevalues (:id,:val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
Dans Windows :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "insert intomytablevalues (:id,:val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
Voici un exemple de réponse.
{
"numberOfRecordsUpdated": 1
}La commande CLI suivante exécute une instruction SQL en langage de définition de données (DDL). L'instruction DDL renomme la colonne job en colonne role.
Important
Pour les instructions DDL, nous vous recommandons de continuer à exécuter l'instruction une fois l'appel expiré. Lorsqu'une instruction DDL se termine avant la fin de son exécution, cela peut entraîner des erreurs et corrompre les structures de données. Pour continuer à exécuter une instruction après qu'un appel dépasse le délai d'expiration de 45 secondes de l'API de données RDS, spécifiez l'--continue-after-timeoutoption.
Pour LinuxmacOS, ou Unix :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
Dans Windows :
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
Voici un exemple de réponse.
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}Note
Les données generatedFields ne sont pas prises en charge par Aurora PostgreSQL. Pour obtenir les valeurs des champs générés, utilisez la clause RETURNING. Pour de plus amples informations, veuillez consulter Renvoi de données de lignes modifiées
Exécution d'une instruction SQL par lots sur un tableau de données
Vous pouvez exécuter une instruction SQL par lots sur un tableau de données à l'aide de la commande CLI aws rds-data batch-execute-statement. Vous pouvez utiliser cette commande pour réaliser une opération d'importation ou de mise à jour en bloc.
Vous pouvez exécuter une instruction SQL à l'intérieur d'une transaction en spécifiant l'identifiant de la transaction avec l'option --transaction-id. Vous pouvez démarrer une transaction à l'aide de la commande CLI aws rds-data
begin-transaction. Vous pouvez terminer et valider une transaction à l'aide de la commande CLI aws rds-data commit-transaction.
Important
Si vous ne spécifiez pas l'option --transaction-id, les modifications renvoyées par l'appel sont automatiquement validées.
En plus des options courantes, spécifiez les options suivantes :
-
--sql(obligatoire) – Instruction SQL à exécuter sur le cluster de bases de données.Astuce
Pour les instructions compatibles avec MySQL, n'incluez pas de point-virgule à la fin du paramètre
--sql. Un point-virgule final peut entraîner une erreur de syntaxe. -
--transaction-id(facultatif) – Identifiant d'une transaction démarrée à l'aide de la commande CLIbegin-transaction. Spécifiez l'identifiant de la transaction dans laquelle vous souhaitez intégrer l'instruction SQL. -
--parameter-set(facultatif) – Ensembles de paramètres pour l'opération par lots. -
--database(facultatif) – Nom de la base de données.
Le cluster de bases de données renvoie une réponse à l'appel.
Note
Il n'existe pas de limite supérieure fixe pour le nombre d'ensembles de paramètres. Cependant, la taille maximale de la requête HTTP soumise via l'API Data est de 4 MiB. Si la demande dépasse cette limite, l'API Data renvoie une erreur et ne traite pas la demande. Cette limite de 4 MiB inclut la taille des en-têtes HTTP et la notation JSON dans la demande. Ainsi, le nombre d'ensembles de paramètres que vous pouvez inclure dépend d'une combinaison de facteurs, tels que la taille de l'instruction SQL et la taille de chaque ensemble de paramètres.
La taille de réponse est limitée à 1 Mio. Si l'appel renvoie plus de 1 Mio de données de réponse, l'appel est arrêté.
Car Aurora Serverless v1 le nombre maximum de demandes par seconde est de 1 000. Pour toutes les autres bases de données prises en charge, il n'y a aucune limite.
Par exemple, la commande CLI suivante exécute une instruction SQL par lots sur un tableau de données avec un ensemble de paramètres.
Pour LinuxmacOS, ou Unix :
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "insert intomytablevalues (:id,:val)" \ --parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
Dans Windows :
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "insert intomytablevalues (:id,:val)" ^ --parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
Note
N'incluez pas les sauts de ligne présents dans l'option --parameter-sets.
Validation d'une transaction SQL
À l'aide de la commande CLI aws rds-data commit-transaction, vous pouvez terminer une transaction SQL que vous avez démarrée avec aws rds-data
begin-transaction et valider les modifications.
En plus des options courantes, spécifiez l'option suivante :
-
--transaction-id(obligatoire) – Identifiant d'une transaction démarrée à l'aide de la commande CLIbegin-transaction. Spécifiez l'identifiant de la transaction que vous souhaitez terminer et valider.
Par exemple, la commande CLI suivante termine une transaction SQL et valide les changements.
Pour LinuxmacOS, ou Unix :
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --transaction-id "ABC1234567890xyz"
Dans Windows :
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --transaction-id "ABC1234567890xyz"
Voici un exemple de réponse.
{
"transactionStatus": "Transaction Committed"
}Restauration d'une transaction
À l'aide de la commande CLI aws rds-data rollback-transaction, vous pouvez restaurer une transaction SQL que vous avez démarrée avec aws rds-data
begin-transaction. La restauration d'une transaction annule les changements apportés.
Important
L'expiration de l'identifiant de la transaction entraîne automatiquement sa restauration. Dans ce cas, une commande aws rds-data rollback-transaction qui spécifie l'identifiant de transaction expiré renvoie une erreur.
En plus des options courantes, spécifiez l'option suivante :
-
--transaction-id(obligatoire) – Identifiant d'une transaction démarrée à l'aide de la commande CLIbegin-transaction. Spécifiez l'identifiant de la transaction que vous souhaitez restaurer.
Par exemple, la AWS CLI commande suivante annule une transaction SQL.
Pour LinuxmacOS, ou Unix :
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --transaction-id "ABC1234567890xyz"
Dans Windows :
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --transaction-id "ABC1234567890xyz"
Voici un exemple de réponse.
{
"transactionStatus": "Rollback Complete"
}Appel de l'API RDS Data à partir d'une application Python
Vous pouvez appeler l'API de données RDS (API de données) à partir d'une application Python.
Les exemples suivants utilisent le AWS SDK pour Python (Boto). Pour plus d'informations sur Boto, consultez la documentation AWS SDK pour Python (Boto 3)
Dans chaque exemple, remplacez le nom de ressource Amazon (ARN) du cluster de base de données par l'ARN de votre cluster de base de données Aurora. De même, remplacez l'ARN du secret par l'ARN du secret dans Secrets Manager qui autorise l'accès au cluster de base de données.
Rubriques
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']
1Note
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 continuer à exécuter une instruction après qu'un appel dépasse le délai d'expiration de 45 secondes de l'API de données RDS, définissez le continueAfterTimeout paramètre sur. true
Appel de l'API RDS Data à partir d'une application Java
Vous pouvez appeler l'API de données RDS (API de données) à partir d'une application Java.
Les exemples suivants utilisent le AWS SDK for Java. Pour plus d’informations, consultez le Guide du développeur AWS SDK for Java.
Dans chaque exemple, remplacez le nom de ressource Amazon (ARN) du cluster de base de données par l'ARN de votre cluster de base de données Aurora. De même, remplacez l'ARN du secret par l'ARN du secret dans Secrets Manager qui autorise l'accès au cluster de base de données.
Rubriques
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<Field> 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 continuer à exécuter une instruction après qu'un appel dépasse le délai d'expiration de 45 secondes de l'API de données RDS, définissez le continueAfterTimeout paramètre 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 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 telle que INSERT ouCREATE TABLE. Si l'appel Data API est renvoyé avec succès, le traitement SQL est terminé lorsque l'appel est renvoyé.
Par défaut, l'API Data annule une opération et renvoie une erreur de temporisation si le traitement de l'opération n'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 pensez qu'une opération, telle qu'une opération en bloc INSERT ou une opération DDL sur une grande table, dure plus de 45 secondes, vous pouvez spécifier le continueAfterTimeout paramètre de l'ExecuteStatementopération. Votre application reçoit toujours le message d'erreur de temporisation. Cependant, l'opération continue et n'est pas annulée. Pour obtenir un exemple, consultez Exécution d'une transaction SQL.
Si le AWS SDK de votre langage de programmation dispose de son propre délai d'expiration pour les appels d'API ou les connexions au socket HTTP, assurez-vous que tous ces délais sont supérieurs à 45 secondes. Pour certains SDK, le délai d'expiration est inférieur à 45 secondes par défaut. Nous vous recommandons de définir les délais d'expiration spécifiques au SDK ou au client à au moins une minute. Cela permet d'éviter que votre application reçoive une erreur de temporisation alors que l'opération Data API se termine toujours avec succès. Ainsi, vous pouvez être sûr de recommencer l'opération ou non.
Supposons, par exemple, que le SDK renvoie une erreur de temporisation à votre application, mais que l'opération de l'API de données se termine toujours dans l'intervalle de temporisation de l'API de données. Dans ce cas, une nouvelle tentative d'opération risque d'insérer des données dupliquées ou de produire des résultats incorrects. Le SDK peut réessayer l'opération automatiquement, ce qui entraîne des données incorrectes sans aucune action de la part de votre application.
L'intervalle de temporisation est particulièrement important pour le SDK Java 2. Dans ce SDK, le délai d'expiration des appels d'API et le délai d'expiration du socket HTTP sont tous deux de 30 secondes par défaut. Voici un exemple de définition d'une valeur plus élevée pour ces délais :
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 RDS Data API (Data API). Cette bibliothèque cliente Java propose une autre méthode pour utiliser l'API de données. À l'aide de cette bibliothèque, vous pouvez mapper vos classes côté client aux demandes et 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 client 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-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 :
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>2.0.0</version> </dependency>
Pour la version 1.x, qui est compatible avec le AWS SDK 1.x, utilisez ce qui suit :
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.8</version> </dependency>
Exemples relatifs à la bibliothèque client Java
Vous trouverez, ci-dessous, quelques exemples d'utilisation de la bibliothèque client 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 client vous permet de passer des DTO en tant que paramètres d'entrée. Les exemples suivants montrent comment les DTO des clients sont mappés à des jeux 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 client fournit le mappage automatique aux DTO lorsqu'un résultat est retourné. Les exemples suivants illustrent la manière dont le résultat est mappé à vos DTO.
List<Account> 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 résultats des requêtes de l'API RDS Data au format JSON.
Traitement des résultats des requêtes de l'API 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.
Rubriques
Récupération des résultats des requêtes au format JSON
Pour recevoir le jeu de résultats sous forme de chaîne JSON, .withFormatRecordsAs(RecordsFormatType.JSON) incluez-le dans l'ExecuteStatementappel. 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 |
|---|---|
|
|
Numéro par défaut. Chaîne si l'option |
|
|
Nombre |
|
|
Chaîne par défaut. Nombre si l'option |
|
|
Chaîne |
|
|
Booléen |
|
|
Chaîne avec encodage base64. |
|
|
Chaîne |
|
|
Tableau |
|
|
|
|
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 clausesLIMITetOFFSET.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 par les paramètres DatabaseNameStoreArn, secret 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<List<Record>>() { }); }
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' JavaScript exemple suivant montre comment accéder aux valeurs issues du résultat d'un appel à la JavaScript executeStatement fonction. 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.
<script> const result = JSON.parse(response.formattedRecords); document.getElementById("display").innerHTML = result[0].id; </script>
Résolution des problèmes liés à l'API RDS Data
Utilisez les sections suivantes, intitulées avec les messages d'erreur courants, pour résoudre les problèmes que vous rencontrez avec l'API de données RDS (API de données).
Rubriques
Transaction <transaction_ID> Is Not 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 BeginTransactionappel. 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
CommitTransactionouRollbackTransaction. -
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 de plus amples informations sur l'exécution des transactions, veuillez consulter Appel de l'API de données RDS.
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 Data renvoient 1 MiB de données ou moins. Si vous avez besoin de renvoyer plus de 1 Mio, vous pouvez utiliser plusieurs appels ExecuteStatement avec la clause LIMIT dans votre requête.
Pour plus d'informations sur la clause LIMIT, veuillez consulter Syntaxe SELECT
HttpEndpointn'est pas activé pour le cluster <cluster_ID>
Vérifiez les causes potentielles suivantes de ce problème :
-
Le cluster de base de données Aurora ne prend pas en charge l'API de données. Par exemple, pour Aurora MySQL, vous ne pouvez utiliser l'API de données qu'avecAurora Serverless v1. Pour plus d'informations sur les types de clusters de base de données pris en charge par l'API de données RDS, consultezDisponibilité des régions et des versions.
-
L'API de données n'est pas activée pour le cluster de base de données Aurora. Pour utiliser l'API de données avec un cluster de base de données Aurora, l'API de données doit être activée pour le cluster de base de données. Pour plus d'informations sur l'activation de l'API de données, consultezActivation de l'API de données RDS.
-
Le cluster de base de données a été renommé après l'activation de l'API de données pour celui-ci. 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.
