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.

Traitement des résultats des requêtes de l'API Amazon RDS Data au format JSON

Lorsque vous appelez l'opération ExecuteStatement, vous pouvez choisir que les résultats de la requête soient retournés sous forme de chaîne au format JSON. Ainsi, vous pouvez utiliser les capacités d'analyse JSON de votre langage de programmation pour interpréter et reformater l'ensemble de résultats. Cela permet d'éviter d'écrire du code supplémentaire pour boucler sur l'ensemble de résultats et interpréter chaque valeur de colonne.

Pour demander l'ensemble de résultats au format JSON, vous transmettez le paramètre formatRecordsAs facultatif avec une valeur JSON. L'ensemble de résultats au format JSON est renvoyé dans le champ formattedRecords de la structure ExecuteStatementResponse.

L'action BatchExecuteStatement ne renvoie pas d'ensemble de résultats. Ainsi, l'option JSON ne s'applique pas à cette action.

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

Vous pouvez utiliser la fonctionnalité JSON pour faciliter la lecture de l'ensemble des résultats et faire correspondre son contenu à des cadres spécifiques à la langue. Étant donné que le volume de l'ensemble des résultats codés en ASCII est plus important que celui de la représentation par défaut, vous pouvez choisir cette dernière pour les requêtes qui renvoient un grand nombre de lignes ou des valeurs de colonnes importantes qui consomment plus de mémoire que celle dont dispose votre application.

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

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 :

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 clusterArn paramètres databaseNamesecretStoreArn,, et.

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>