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 des RDS données API

En utilisant RDS Data API (DataAPI), vous pouvez utiliser une interface de services Web pour votre cluster de base de données Aurora. Les données API ne nécessitent pas de connexion permanente au cluster de base de données. Au lieu de cela, il fournit un point de HTTP terminaison sécurisé et une intégration avec AWS SDKs. Vous pouvez utiliser le point de terminaison pour exécuter SQL des instructions sans gérer les connexions.

Les utilisateurs n'ont pas besoin de transmettre des informations d'identification lors des appels à DataAPI, car Data API 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 DataAPI. Pour plus d'informations sur les autorisations accordées aux utilisateurs, consultez Autoriser l'accès aux données RDS API.

Vous pouvez également utiliser Data API pour intégrer Amazon Aurora à d'autres AWS applications telles que AWS Lambda AWS AppSync, et AWS Cloud9. Les données API constituent un moyen d'utilisation plus sûr AWS Lambda. Il vous permet d'accéder à votre cluster de base de données sans avoir à configurer une fonction Lambda pour accéder aux ressources d'un cloud privé virtuel ()VPC. Pour plus d’informations, consultez AWS Lambda, AWS AppSync et AWS Cloud9.

Vous pouvez activer Data API lorsque vous créez le cluster de base de données Aurora. Vous pouvez également modifier la configuration ultérieurement. Pour de plus amples informations, veuillez consulter RDSDonnées habilitantes API.

Après avoir activé DataAPI, 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 unVPC. Pour de plus amples informations, veuillez consulter Utilisation de l'éditeur de requêtes Aurora.

Disponibilité des régions et des versions

Pour plus d'informations sur les régions et les versions du moteur disponibles pour DataAPI, consultez les sections suivantes.

Si vous avez besoin de modules cryptographiques validés par FIPS 140-2 lorsque vous accédez aux données API via une interface de ligne de commande ou unAPI, utilisez un point de terminaison. FIPS Pour plus d'informations sur les FIPS points de terminaison disponibles, voir Federal Information Processing Standard (FIPS) 140-2.

Limites liées aux RDS données API

RDSLes données API (donnéesAPI) présentent les limites suivantes :

Comparaison des RDS données API avec Serverless v2 et provisionnées, et Aurora Serverless v1

Les dernières améliorations apportées à RDS Data le API rendent disponible pour les clusters qui utilisent des versions récentes des SQL moteurs Postgre SQL ou My. Ces clusters peuvent être configurés pour utiliser Aurora Serverless v2, ou des classes d'instances provisionnées telles que db.r6g oudb.r6i.

Le tableau suivant décrit les différences entre les RDS données API (donnéesAPI) avec Aurora Serverless v2 et des clusters de bases de données provisionnés, et Aurora Serverless v1 Clusters de bases de données. Aurora Serverless v1 Les clusters de base de données utilisent le mode serverless moteur. Les clusters de base de données provisionnés utilisent le mode provisioned moteur. Un Aurora Serverless v2 Le cluster de base de données utilise également le mode provisioned moteur et contient un ou plusieurs Aurora Serverless v2 Instances de base de données avec la classe d'db.serverlessinstance.

Autoriser l'accès aux données RDS API

Les utilisateurs ne peuvent invoquer RDS des opérations de données API (donnéesAPI) que s'ils sont autorisés à le faire. Vous pouvez autoriser un utilisateur à utiliser les données API en joignant une politique AWS Identity and Access Management (IAM) qui définit ses privilèges. Vous pouvez également associer la politique à un rôle si vous utilisez IAM des rôles. Une politique AWS gérée inclut AmazonRDSDataFullAccess des autorisations pour les donnéesAPI.

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 lors de leurs appels à DataAPI. 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 à DataAPI. Data appelle Secrets Manager de API 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 les donnéesAPI, consultezStockage des identifiants de base de données dans AWS Secrets Manager.

La AmazonRDSDataFullAccess politique fournit un accès complet (par le biais des donnéesAPI) aux ressources. Vous pouvez réduire le champ d'application en définissant vos propres politiques qui spécifient le nom de ressource Amazon (ARN) d'une ressource.

Par exemple, la politique suivante montre un exemple des autorisations minimales requises pour qu'un utilisateur accède aux données API du cluster de base de données identifié par sonARN. 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 élément spécifique ARN pour l'élément « Ressources » dans vos déclarations de politique (comme indiqué dans l'exemple) plutôt qu'un caractère générique (*).

Utilisation de l'autorisation basée sur les balises

RDSData API (DataAPI) 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 RDS cluster, avec une valeur de chaîne supplémentaire, par exemple :

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 encore de balises sur vos ressources et que vous souhaitez les appliquer, vous pouvez en savoir plus sur Tagging Amazon RDS resources.) Vous pouvez utiliser les balises figurant dans vos déclarations de politique pour limiter l'accès aux RDS clusters é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 API demande de données soient tous deux dotés d'une environment:production balise.

Voici comment la politique est appliquée : lorsqu'un utilisateur passe un appel à l'aide de DataAPI, la demande est envoyée au service. Data vérifie API d'abord que le cluster ARN 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, Data utilise API ensuite la valeur récupérée pour le mot de passe de base de données de l'utilisateur. Enfin, si cela est également correct, la API demande de données est invoqué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 Data API and 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 la section Utilisation de politiques basées sur l'identité (IAMpolitiques) pour Secrets Manager.

Dans l'élément « Condition » de la politique, vous pouvez choisir les clés de balise parmi les suivantes :

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.

Stockage des identifiants de base de données dans AWS Secrets Manager

Lorsque vous appelez RDS Data API (DataAPI), vous transmettez les informations d'identification du cluster de base de données Aurora en utilisant un secret dans Secrets Manager. Pour transmettre les informations d'identification de cette manière, vous devez spécifier le nom du secret ou le nom de ressource Amazon (ARN) du secret.

Pour plus d'informations sur l'utilisation de Secrets Manager, consultez le Guide de l'utilisateur AWS Secrets Manager.

Pour comprendre comment Amazon Aurora gère la gestion des identités et des accès, consultez Comment fonctionne Amazon Aurora IAM.

Pour plus d'informations sur la création d'une IAM politique, consultez la section Création de IAM politiques dans le guide de IAM l'utilisateur. Pour plus d'informations sur l'ajout d'une IAM politique à un utilisateur, consultez la section Ajouter et supprimer des autorisations IAM d'identité dans le guide de IAM l'utilisateur.

RDSDonnées habilitantes API

Pour utiliser RDS Data API (DataAPI), activez-les pour votre cluster de base de données Aurora. Vous pouvez activer Data API lorsque vous créez ou modifiez le cluster de base de données.

Activation RDS des données API lors de la création d'une base de données

Lorsque vous créez une base de données qui prend en charge les RDS données API (donnéesAPI), vous pouvez activer cette fonctionnalité. Les procédures suivantes décrivent comment procéder lorsque vous utilisez le AWS Management Console, le AWS CLI, ou le RDSAPI.

Activation RDS des données API dans une base de données existante

Vous pouvez modifier un cluster de base de RDS données qui prend en charge les données API (donnéesAPI) pour activer ou désactiver cette fonctionnalité.

Activation ou désactivation des données API (Aurora Serverless v2 et approvisionné)

Utilisez les procédures suivantes pour activer ou désactiver les données API sur Aurora Serverless v2 et bases de données provisionnées. Pour activer ou désactiver les données API sur Aurora Serverless v1 bases de données, utilisez les procédures dansActivation ou désactivation des données API (Aurora Serverless v1 uniquement).

Activation ou désactivation des données API (Aurora Serverless v1 uniquement)

Utilisez les procédures suivantes pour activer ou désactiver les données API sur des données existantes Aurora Serverless v1 bases de données. Pour activer ou désactiver les données API sur Aurora Serverless v2 et bases de données provisionnées, utilisez les procédures décrites dansActivation ou désactivation des données API (Aurora Serverless v2 et approvisionné).

Création d'un point de VPC terminaison Amazon pour RDS les données API (AWS PrivateLink)

Amazon vous VPC permet de lancer AWS des ressources, telles que des clusters et des applications de base de données Aurora, 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 VPC points de terminaison Amazon, qui vous permettent de vous connecter à des services via différents comptes et VPCs en fonction d'AmazonVPC. Pour plus d'informations AWS PrivateLink, consultez VPCEndpoint Services (AWS PrivateLink) dans le guide de l'utilisateur d'Amazon Virtual Private Cloud.

Vous pouvez appeler RDS Data API (DataAPI) avec les VPC points de terminaison Amazon. L'utilisation d'un point de VPC terminaison Amazon permet de maintenir le trafic entre les applications de votre Amazon VPC et les données API du AWS réseau, sans utiliser d'adresses IP publiques. VPCLes points de terminaison Amazon 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 VPC terminaison Amazon, vous pouvez conserver le trafic entre une application exécutée sur une EC2 instance Amazon et les données contenues API dans l'instance VPCs qui les contient.

Après avoir créé le point de VPC terminaison Amazon, vous pouvez commencer à l'utiliser sans apporter de modifications au code ou à la configuration de votre application.

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 indique les DNS noms d'hôte générés lors de la création du point de VPC terminaison Amazon.

Vous pouvez utiliser le point de terminaison standard (rds-data.region.amazonaws.com) ou l'un des points de VPC terminaison spécifiques pour appeler les données au API sein d'Amazon. VPC Le point de API terminaison de données standard est automatiquement acheminé vers le point de VPC terminaison Amazon. Ce routage se produit parce que le DNS nom d'hôte privé a été activé lors de la création du point de VPC terminaison Amazon.

Lorsque vous utilisez un point de VPC terminaison Amazon dans le cadre d'un API appel de données, tout le trafic entre votre application et les données API reste dans l'Amazon VPCs qui les contient. Vous pouvez utiliser un point de VPC terminaison Amazon pour tout type d'APIappel de données. Pour plus d'informations sur l'appel de DataAPI, consultezRDSDonnées d'appel API.

RDSDonnées d'appel API

Lorsque RDS Data API (DataAPI) est activé sur votre cluster de base de données Aurora, vous pouvez exécuter SQL des instructions sur le cluster de base de données Aurora à l'aide de Data API ou du AWS CLI. Data API prend en charge les langages de programmation pris en charge par le AWS SDKs. Pour plus d'informations, consultez la section Outils sur lesquels vous pouvez vous appuyer AWS.

Référence des API opérations de données

Data API fournit les opérations suivantes pour exécuter des SQL instructions.

Vous pouvez utiliser l'une ou l'autre opération pour exécuter SQL des instructions individuelles ou pour exécuter des transactions. Pour les transactions, Data API fournit les opérations suivantes.

Les opérations d'établissement des SQL relevés et de support des transactions ont les API paramètres et AWS CLI options de données communs suivants. Certaines opérations prennent en charge d'autres paramètres et options.

RDSLes données API prennent en charge les types de données suivants pour Aurora My SQL :

RDSLes données API prennent en charge les types de SQL scalaires Aurora Postgre suivants :

RDSLes données API prennent en charge les types de SQL baies Aurora Postgre suivants :

Vous pouvez utiliser des paramètres dans les API appels 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 fait correspondre les types de données Java Database Connectivity (JDBC) aux types de données que vous spécifiez dans les API appels de données.

Certains types, tels que DECIMAL etTIME, nécessitent un indice pour que Data API 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 :

Appeler RDS des données API avec le AWS CLI

Vous pouvez appeler RDS Data API (DataAPI) à l'aide du AWS CLI.

Les exemples suivants utilisent le AWS CLI for DataAPI. Pour plus d'informations, voir la AWS CLI référence relative aux données API.

Dans chaque exemple, remplacez le nom de ressource Amazon (ARN) du cluster de base de données par celui de votre cluster ARN de base de données Aurora. Remplacez également le secret ARN par le ARN secret dans le Secrets Manager qui autorise l'accès au cluster de base de données.

Commencer une SQL transaction

Vous pouvez démarrer une SQL transaction à l'aide de la aws rds-data begin-transaction CLI commande. L'appel renvoie un identifiant de transaction.

En plus des options communes, spécifiez l'option --database qui indique le nom de la base de données.

Par exemple, la CLI commande suivante lance une SQL transaction.

Dans 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"

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 SQL déclaration

Vous pouvez exécuter une SQL instruction à l'aide de la aws rds-data execute-statement CLI commande.

Vous pouvez exécuter l'SQLinstruction dans une transaction en spécifiant l'identifiant de transaction à l'aide de l'--transaction-idoption. Vous pouvez démarrer une transaction à l'aide de la aws rds-data begin-transaction CLI commande. Vous pouvez terminer et valider une transaction à l'aide de la aws rds-data commit-transaction CLI commande.

En plus des options courantes, spécifiez les options suivantes :

Le cluster de bases de données renvoie une réponse pour l'appel.

Par exemple, la CLI commande suivante exécute une seule SQL instruction et omet les métadonnées dans les résultats (valeur par défaut).

Dans 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"

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 CLI commande suivante exécute une seule SQL instruction dans une transaction en spécifiant l'--transaction-idoption.

Dans 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"

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 CLI commande suivante exécute une seule SQL instruction avec des paramètres.

Dans 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\"}}]"

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 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 CLI commande suivante exécute une SQL instruction Data Definition Language (DDL). L'DDLinstruction renomme colonne job en colonnerole.

Dans 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

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
}

Exécution d'une SQL instruction batch sur un tableau de données

Vous pouvez exécuter une SQL instruction batch sur un tableau de données à l'aide de la aws rds-data batch-execute-statement CLI commande. Vous pouvez utiliser cette commande pour réaliser une opération d'importation ou de mise à jour en bloc.

Vous pouvez exécuter l'SQLinstruction dans une transaction en spécifiant l'identifiant de transaction à l'aide de l'--transaction-idoption. Vous pouvez démarrer une transaction à l'aide de la aws rds-data begin-transaction CLI commande. Vous pouvez terminer et valider une transaction à l'aide de la aws rds-data commit-transaction CLI commande.

En plus des options courantes, spécifiez les options suivantes :

Le cluster de bases de données renvoie une réponse à l'appel.

Par exemple, la CLI commande suivante exécute une SQL instruction batch sur un tableau de données avec un ensemble de paramètres.

Dans 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\"}}]]"

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 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\"}}]]"

Commettre une SQL transaction

À l'aide de cette aws rds-data commit-transaction CLI commande, vous pouvez mettre fin à une SQL transaction que vous avez commencée aws rds-data begin-transaction et valider les modifications.

En plus des options courantes, spécifiez l'option suivante :

Par exemple, la CLI commande suivante met fin à une SQL transaction et valide les modifications.

Dans 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"

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

Annulation d'une SQL transaction

À l'aide de cette aws rds-data rollback-transaction CLI commande, vous pouvez annuler une SQL transaction avec laquelle vous avez commencéaws rds-data begin-transaction. La restauration d'une transaction annule les changements apportés.

En plus des options courantes, spécifiez l'option suivante :

Par exemple, la AWS CLI commande suivante annule une SQL transaction.

Dans 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"

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 API de RDS données depuis une application Python

Vous pouvez appeler RDS Data API (DataAPI) depuis une application Python.

Les exemples suivants utilisent le AWS SDK for Python (Boto). Pour plus d'informations sur Boto, consultez la documentation AWS SDKpour Python (Boto 3).

Dans chaque exemple, remplacez le nom de ressource Amazon du cluster de bases de données (ARN) par celui ARN de votre cluster de base de données Aurora. Remplacez également le secret ARN par le ARN secret dans le Secrets Manager qui autorise l'accès au cluster de base de données.

Exécution d'une SQL requête

Vous pouvez exécuter une instruction SELECT puis extraire les résultats avec une application Python.

L'exemple suivant exécute une SQL requête.

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 DML SQL déclaration

Vous pouvez exécuter une instruction data manipulation language (DML) pour insérer, mettre à jour ou supprimer des données dans votre base de données. Vous pouvez également utiliser des paramètres dans DML les instructions.

L'exemple suivant exécute une SQL instruction d'insertion 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 SQL transaction

Vous pouvez démarrer une SQL transaction, exécuter une ou plusieurs SQL instructions, puis valider les modifications à l'aide d'une application Python.

L'exemple suivant exécute une SQL transaction 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

Appeler RDS des données API depuis une application Java

Vous pouvez appeler RDS Data API (DataAPI) depuis une application Java.

Les exemples suivants utilisent le AWS SDK pour Java. Pour plus d’informations, consultez le Guide du développeur AWS SDK for Java.

Dans chaque exemple, remplacez le nom de ressource Amazon du cluster de bases de données (ARN) par celui ARN de votre cluster de base de données Aurora. Remplacez également le secret ARN par le ARN secret dans le Secrets Manager qui autorise l'accès au cluster de base de données.

Exécution d'une SQL requête

Vous pouvez exécuter une instruction SELECT? puis extraire les résultats avec une application Java.

L'exemple suivant exécute une SQL requête.

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 SQL transaction

Vous pouvez démarrer une SQL transaction, exécuter une ou plusieurs SQL instructions, puis valider les modifications à l'aide d'une application Java.

L'exemple suivant exécute une SQL transaction.

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);
  }
}

Exécution d'une SQL opération 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 DML instruction avec un tableau de jeux de paramètres.

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'APIexpiration des données

Tous les appels vers Data API sont synchrones. Supposons que vous exécutiez une API opération Data qui exécute une SQL instruction telle que INSERT ouCREATE TABLE. Si l'APIappel Data est renvoyé avec succès, le SQL traitement est terminé lorsque l'appel revient.

Par défaut, Data API 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 les données API pour effectuer des opérations de longue durée qui ne peuvent pas être effectuées dans les 45 secondes. Si vous pensez qu'une opération, telle qu'une opération en bloc INSERT ou une DDL opération 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. Toutefois, l'opération continue et n'est pas annulée. Pour obtenir un exemple, consultez Exécution d'une SQL transaction.

Si votre langage de AWS SDK programmation dispose de son propre délai d'attente pour les API appels ou les connexions HTTP socket, assurez-vous que tous ces délais sont supérieurs à 45 secondes. Pour certainsSDKs, le délai d'expiration est inférieur à 45 secondes par défaut. Nous vous recommandons de définir des délais d'expiration SDK spécifiques ou spécifiques au client à au moins une minute. Cela permet d'éviter que votre application reçoive une erreur de temporisation alors que l'APIopération Data se termine 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'APIopération Data se termine toujours dans l'intervalle de API temporisation des 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. SDKIl se peut qu'ils réessayent 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 Java 2. SDK Dans ce casSDK, le délai API d'appel et le délai d'expiration du HTTP socket 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 RDS Data API

Vous pouvez télécharger et utiliser une bibliothèque cliente Java pour RDS Data API (DataAPI). Cette bibliothèque cliente Java propose une autre méthode d'utilisation des donnéesAPI. À l'aide de cette bibliothèque, vous pouvez mapper vos classes côté client aux API demandes et réponses 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 Data API

La bibliothèque cliente Data API Java est open source GitHub à l'emplacement suivant :

https://github.com/awslabs/rds-data-api-client-bibliothèque-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 POM fichier Maven.

Pour la version 2.x, qui est compatible avec 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 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 courants d'utilisation de la bibliothèque cliente Data API Java. 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 suivant (DTO).

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é à votreDTOs.

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 tels résultats, la bibliothèque cliente propose ce qui suit : API

int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

Traitement des résultats RDS de API la requête de données au JSON format

Lorsque vous appelez l'ExecuteStatementopération, vous pouvez choisir de renvoyer les résultats de la requête sous forme de chaîne au JSON format. Ainsi, vous pouvez utiliser les fonctionnalités d'JSONanalyse de votre langage de programmation pour interpréter et reformater le jeu 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 le jeu de résultats au JSON format, vous devez transmettre le formatRecordsAs paramètre facultatif avec une valeur deJSON. Le jeu de résultats JSON formaté est renvoyé dans le formattedRecords champ de la ExecuteStatementResponse structure.

L'action BatchExecuteStatement ne renvoie pas d'ensemble de résultats. L'JSONoption ne s'applique donc pas à cette action.

Pour personnaliser les clés de la structure de JSON hachage, définissez des alias de colonne dans le jeu de résultats. Vous pouvez le faire en utilisant la AS clause dans la liste des colonnes de votre SQL requête.

Vous pouvez utiliser JSON cette fonctionnalité pour rendre le jeu de résultats plus facile à lire et mapper son contenu à des cadres spécifiques au langage. Le volume du jeu de résultats ASCII codé étant supérieur à celui de la représentation par défaut, vous pouvez choisir la représentation par défaut pour les requêtes renvoyant un grand nombre de lignes ou de grandes valeurs de colonnes consommant plus de mémoire que celle dont dispose votre application.

Extraction des résultats de requête au format JSON

Pour recevoir le jeu de résultats sous JSON forme de chaîne, .withFormatRecordsAs(RecordsFormatType.JSON) incluez-le dans l'ExecuteStatementappel. La valeur renvoyée est renvoyée sous JSON forme de chaîne dans le formattedRecords champ. 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, ne sont pas conservées dans la JSON réponse.

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 SQL valeurs du jeu de résultats sont mappées à un ensemble de JSON types plus restreint. Les valeurs sont représentées JSON sous forme de chaînes, de nombres et de constantes spéciales telles que truefalse, etnull. Vous pouvez convertir ces valeurs en variables dans votre application, en utilisant un typage fort ou faible, selon le langage de programmation utilisé.

Résolution des problèmes

La JSON réponse 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 :

Exemples

Les exemples Java suivants montrent comment appeler ExecuteStatement avec la réponse sous forme de chaîne JSON formatée, puis comment interpréter le jeu de résultats. Remplacez les valeurs appropriées par databaseName, secretStoreArn, et clusterArn paramètres.

L'exemple Java suivant illustre une requête qui renvoie une valeur numérique décimale dans l'ensemble de résultats. Les assertThat appels vérifient que les champs de la réponse possèdent les propriétés attendues en fonction des règles relatives aux ensembles de JSON résultats.

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 ColumnMetadata champs Records et de la réponse sont tous deux nuls, en raison de la présence du jeu de JSON résultats.

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 à renvoyer uniquement la chaîne JSON formatée et à ignorer les autres champs de réponse 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 requis pour construire une structure de données contenant le jeu de résultats lorsque vous n'utilisez pas le JSON format. 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 du jeu de résultats est définie comme une expression, le texte de l'expression devient la JSON clé. 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 au jeu de JSON résultats sous forme de clés.

[{"count(*)":5,"max(id)":4,"4+7":11}]

L'ajout de AS colonnes avec des libellés descriptifs simplifie l'interprétation des clés dans le jeu de JSON résultats.

select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

Avec la SQL requête révisée, les libellés de colonne définis par les AS clauses sont utilisés comme noms clés.

[{"rows":5,"largest_id":4,"addition_result":11}]

La valeur de chaque paire clé-valeur de la JSON chaîne 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 de JSON chaînes suivants 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 de la JSON chaîne 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 de JSON chaînes suivants 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 de JSON chaînes suivants illustrent ces possibilités.

[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}] 

Si vous sélectionnez une valeur d'un BLOB type, le résultat est représenté dans la JSON chaîne sous la forme d'une valeur codée en 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 BLOB valeur de hello world et du renvoi du jeu de résultats sous JSON forme de chaîne.

[{"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 JSON chaîne en structure de données en appelant la json.loads fonction. 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 JSON chaîne en structure de données en appelant la JSON.parse fonction. 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 API liés aux RDS données

Utilisez les sections suivantes, intitulées avec les messages d'erreur courants, pour résoudre les problèmes que vous rencontrez avec RDS les données API (donnéesAPI).

Transaction <transaction_ID> Is Not Found

Dans ce cas, l'ID de transaction spécifié dans un API appel de données n'a pas été trouvé. La cause de ce problème, parmi les suivantes, est ajoutée au message d'erreur :

Pour de plus amples informations sur l'exécution des transactions, veuillez consulter RDSDonnées d'appel API.

Packet for query is too large

Dans ce cas, le jeu de résultats renvoyé pour une ligne était trop volumineux. La limite de API taille des données est de 64 Ko par ligne dans le jeu de résultats 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 API limite de données est de 1 MiB dans le jeu de résultats renvoyé par la base de données.

Pour résoudre ce problème, assurez-vous que les appels à Data API renvoient 1 Mo 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 LIMIT clause, consultez la section sur la SELECTsyntaxe dans Ma SQL documentation.

HttpEndpointn'est pas activé pour le cluster <cluster_ID>

Vérifiez les causes potentielles suivantes de ce problème :