Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Elaborazione dei risultati delle query Amazon RDS Data API in formato JSON

Quando invochi l'operazione ExecuteStatement, puoi scegliere di restituire i risultati della query come stringa in formato JSON. In questo modo puoi utilizzare le funzionalità di parsificazione JSON del linguaggio di programmazione per interpretare e riformattare il set di risultati. Ciò può aiutare a evitare di scrivere codice aggiuntivo per scorrere il set di risultati e interpretare ogni valore di colonna.

Per richiedere il set di risultati in formato JSON, passi il parametro opzionaleformatRecordsAs con il valore di JSON. Il set di risultati in formato JSON viene restituito nel campo formattedRecords della struttura ExecuteStatementResponse.

L'operazione BatchExecuteStatement non restituisce un set di risultati. Pertanto, l'opzione JSON non si applica a tale operazione.

Per personalizzare le chiavi nella struttura hash JSON, definisci gli alias di colonna nel set di risultati. Puoi farlo utilizzando la clausola AS nell'elenco delle colonne della query SQL.

Puoi utilizzare la funzionalità JSON per semplificare la lettura del set di risultati e mappare il suo contenuto su framework specifici del linguaggio. Poiché il volume del set di risultati con codifica ASCII è maggiore della rappresentazione di default, puoi scegliere la rappresentazione di default per le query che restituiscono un numero elevato di righe o contenuti di colonne di grandi dimensioni che consumano più memoria di quella disponibile per l'applicazione.

Recupero dei risultati delle query in formato JSON

Per ricevere il set di risultati come stringa JSON, includetelo .withFormatRecordsAs(RecordsFormatType.JSON) nella ExecuteStatement chiamata. Il valore restituito è ritornato come stringa JSON nel campo formattedRecords. In questo caso, il valore di columnMetadata è null. Le etichette di colonna sono le chiavi dell'oggetto che rappresenta ogni riga. Questi nomi di colonna vengono ripetuti per ogni riga del set dei risultati. I valori delle colonne sono stringhe con virgolette, valori numerici o valori speciali che rappresentano true, false o null. I metadati delle colonne come i vincoli di lunghezza e il tipo specifico di numeri e stringhe non vengono conservati nella risposta JSON.

Se ometti la chiamata .withFormatRecordsAs() o specifichi un parametro di NONE, il set di risultati viene restituito in formato binario utilizzando i campi Records e columnMetadata.

Mappatura dei tipi di dati

I valori SQL nel set di risultati sono mappati su un set più piccolo di tipi JSON. I valori sono rappresentati in JSON come stringhe, numeri e alcune costanti speciali come true, false e null. Puoi convertire questi valori in variabili nell'applicazione, utilizzando una tipizzazione forte o debole secondo quanto previsto per il linguaggio di programmazione.

Risoluzione dei problemi

La risposta JSON è limitata a 10 megabyte. Se la risposta è superiore a questo limite, il programma riceve un errore BadRequestException. In questo caso, è possibile risolvere l'errore utilizzando una delle seguenti tecniche:

Esempi

I seguenti esempi Java mostrano come invocare ExecuteStatement richiedendo la risposta sotto forma di stringa in formato JSON e quindi come interpretare il set di risultati. Sostituite i valori appropriati per i parametri databaseNamesecretStoreArn, eclusterArn.

Nell'esempio Java seguente viene illustrata una query che restituisce un valore numerico decimale nel set di risultati. Le invocazioni di assertThat verificano che i campi della risposta presentino le proprietà attese in base alle regole per i set di risultati in formato JSON.

Questo esempio funziona con lo schema e i dati di esempio seguenti:

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

Il valore del campo formattedRecords del programma precedente è:

[{"a":10.0}]

I campi Records e ColumnMetadata nella risposta sono entrambi nulli, a causa della presenza del set di risultati JSON.

Nell'esempio Java seguente viene illustrata una query che restituisce un valore numerico decimale nel set di risultati. L'esempio invoca getFormattedRecords per restituire solo la stringa in formato JSON e ignorare gli altri campi di risposta che sono vuoti o nulli. L'esempio deserializza il risultato in una struttura che rappresenta un elenco di record. Ogni record presenta campi i cui nomi corrispondono agli alias di colonna del set di risultati. Questa tecnica semplifica il codice che analizza il set di risultati. L'applicazione non deve eseguire il ciclo tra le righe e le colonne del set di risultati e convertire ogni valore nel tipo appropriato.

Questo esempio funziona con lo schema e i dati di esempio seguenti:

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

Il valore del campo formattedRecords del programma precedente è:

[{"a":17}]

Per recuperare la colonna a della riga dei risultati 0, l'applicazione fa riferimento a recordsList.get(0).a.

Al contrario, l'esempio Java seguente mostra il tipo di codice necessario per costruire una struttura dati che contiene il set di risultati quando non si utilizza il formato JSON. In questo caso, ogni riga del set di risultati contiene campi con informazioni su un singolo utente. La creazione di una struttura dati per rappresentare il set di risultati richiede il ciclo tra le righe. Per ogni riga, il codice recupera il valore di ciascun campo, esegue una conversione di tipo appropriata e assegna il risultato al campo corrispondente dell'oggetto che rappresenta la riga. Quindi il codice aggiunge l'oggetto che rappresenta ogni utente alla struttura dati che rappresenta l'intero set di risultati. Se la query viene modificata per riordinare, aggiungere o rimuovere campi nel set di risultati, anche il codice dell'applicazione dovrebbe essere modificato.

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

I seguenti valori di esempio mostrano i valori del campo formattedRecords per set di risultati con diversi numeri di colonne, alias di colonna e tipi di dati di colonna.

Se il set di risultati include più righe, ogni riga viene rappresentata come un oggetto che è un elemento di una matrice. Ogni colonna del set di risultati diventa una chiave nell'oggetto. Le chiavi sono ripetute per ogni riga del set dei risultati. Pertanto, per i set di risultati costituiti da molte righe e colonne, potrebbe essere necessario definire alias di colonna brevi per evitare di superare il limite di lunghezza dell'intera risposta.

Questo esempio funziona con lo schema e i dati di esempio seguenti:

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

Se una colonna del set di risultati è definita come espressione, il testo dell'espressione diventa la chiave JSON. Pertanto, in genere è conveniente definire un alias di colonna descrittivo per ogni espressione nell'elenco di selezione della query. Ad esempio, la seguente query include espressioni come chiamate di funzione e operazioni aritmetiche nell'elenco di selezione.

select count(*), max(id), 4+7 from sample_names;

Tali espressioni vengono passate al set di risultati JSON come chiavi.

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

L'aggiunta di colonne AS con etichette descrittive rende le chiavi più semplici da interpretare nel set di risultati JSON.

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

Con la query SQL revisionata, le etichette di colonna definite dalle clausole AS vengono utilizzate come nomi chiave.

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

Il valore di ogni coppia chiave-valore nella stringa JSON può essere una stringa con virgolette. La stringa potrebbe contenere caratteri unicode. Se la stringa contiene sequenze di escape o i caratteri " o \, tali caratteri sono preceduti da caratteri backslash di escape. I seguenti esempi di stringhe JSON dimostrano queste possibilità. Ad esempio, il risultato string_with_escape_sequences contiene i caratteri speciali backspace, nuova riga, ritorno a capo, tabulazione, form feed e \.

[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}] 

Il valore di ogni coppia chiave-valore nella stringa JSON può rappresentare anche un numero. Il numero potrebbe essere un numero intero, un valore a virgola mobile, un valore negativo o un valore rappresentato come notazione esponenziale. I seguenti esempi di stringhe JSON dimostrano queste possibilità.

[{"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}] 

I valori booleani e null sono rappresentati con le parole chiave speciali senza virgolette true,false e null. I seguenti esempi di stringhe JSON dimostrano queste possibilità.

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

Se selezioni un valore di tipo BLOB, il risultato viene rappresentato nella stringa JSON come valore codificato in base64. Per riconvertire il valore nella sua rappresentazione originale puoi utilizzare la funzione di decodifica appropriata nella lingua dell'applicazione. Ad esempio, in Java invochi la funzione Base64.getDecoder().decode(). Il seguente output di esempio mostra il risultato della selezione di un valore BLOB di hello world e della restituzione del set di risultati come stringa in formato JSON.

[{"blob_column":"aGVsbG8gd29ybGQ="}]

L'esempio Python seguente mostra come accedere ai valori dal risultato di una chiamata alla funzione Python execute_statement. Il set di risultati è un valore stringa nel campo response['formattedRecords']. Il codice trasforma la stringa JSON in una struttura dati invocando la funzione json.loads. Quindi ogni riga del set di risultati è un elemento elenco all'interno della struttura dati e all'interno di ogni riga puoi fare riferimento a ciascun campo del set di risultati usandone il nome.

import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

L' JavaScript esempio seguente mostra come accedere ai valori del risultato di una chiamata alla JavaScript executeStatement funzione. Il set di risultati è un valore stringa nel campo response.formattedRecords. Il codice trasforma la stringa JSON in una struttura dati invocando la funzione JSON.parse. Quindi ogni riga del set di risultati è un elemento vettore all'interno della struttura dati e all'interno di ogni riga puoi fare riferimento a ciascun campo del set di risultati usandone il nome.

<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script>