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

Utilizzo dell'API dati RDS

Utilizzando RDS Data API (Data API), puoi lavorare con un'interfaccia di servizi Web per il tuo cluster Aurora DB. Data API non richiede una connessione persistente al cluster DB. Fornisce invece un endpoint HTTP sicuro e l'integrazione con AWS SDKs. Puoi usare l'endpoint per eseguire istruzioni SQL senza gestire connessioni.

Gli utenti non devono passare le credenziali con le chiamate a Data API, poiché Data API utilizza le credenziali del database archiviate in. AWS Secrets Manager Per archiviare le credenziali in Secrets Manager, agli utenti devono essere concesse le autorizzazioni appropriate per utilizzare Secrets Manager e anche Data API. Per ulteriori informazioni sull'autorizzazione degli utenti, consulta Autorizzazione dell'accesso a RDS Data API.

Puoi anche utilizzare Data API per integrare Amazon Aurora con altre AWS applicazioni come AWS Lambda AWS AppSync, e. AWS Cloud9 Data API offre un modo più sicuro di utilizzo AWS Lambda. Consente di accedere al cluster database senza dover configurare una funzione Lambda per accedere alle risorse in un cloud privato virtuale (VPC). Per ulteriori informazioni, consulta AWS Lambda, AWS AppSync e AWS Cloud9.

Puoi abilitare Data API quando crei il cluster Aurora DB. È inoltre possibile modificare la configurazione in un secondo momento. Per ulteriori informazioni, consulta Abilitazione dell'API RDS Data.

Dopo aver abilitato Data API, puoi anche utilizzare l'editor di query per eseguire query ad hoc senza configurare uno strumento di query per accedere ad Aurora in un VPC. Per ulteriori informazioni, consulta Utilizzo dell'editor di query Aurora.

Disponibilità di regioni e versioni

Per informazioni sulle regioni e le versioni del motore disponibili per Data API, consulta le seguenti sezioni.

Se hai bisogno di moduli crittografici convalidati da FIPS 140-2 quando accedi a Data API tramite un'interfaccia a riga di comando o un'API, usa un endpoint FIPS. Per ulteriori informazioni sugli endpoint FIPS disponibili, consulta il Federal Information Processing Standard (FIPS) 140-2.

Limitazioni con RDS Data API

RDS Data API presenta le seguenti limitazioni:

Confronto tra RDS Data API e Serverless v2 e provisioned, e Aurora Serverless v1

I miglioramenti più recenti all'API RDS Data la rendono disponibile per i cluster che utilizzano versioni recenti dei motori PostgreSQL o MySQL. Questi cluster potrebbero essere configurati per l'uso Aurora Serverless v2, o classi di istanze predisposte come db.r6g o. db.r6i

La tabella seguente descrive le differenze tra RDS Data API (Data API) con Aurora Serverless v2 e cluster DB a cui è stato effettuato il provisioning e Aurora Serverless v1 cluster DB. Aurora Serverless v1 I cluster DB utilizzano la modalità serverless motore. I cluster DB predisposti utilizzano la provisioned modalità motore. Un record Aurora Serverless v2 Il cluster DB utilizza anche la modalità provisioned motore e ne contiene una o più Aurora Serverless v2 Istanze DB con la classe di db.serverless istanza.

Autorizzazione dell'accesso a RDS Data API

Gli utenti possono richiamare le operazioni RDS Data API (Data API) solo se sono autorizzati a farlo. Puoi concedere a un utente l'autorizzazione a utilizzare Data API allegando una policy AWS Identity and Access Management (IAM) che ne definisce i privilegi. È inoltre possibile associare la policy a un ruolo se si utilizzano ruoli IAM. Una policy AWS gestita include AmazonRDSDataFullAccess le autorizzazioni per Data API.

La AmazonRDSDataFullAccess politica include anche le autorizzazioni da cui l'utente può ottenere il valore di un segreto. AWS Secrets Manager Gli utenti devono utilizzare Secrets Manager per archiviare segreti da utilizzare nelle chiamate a Data API. L'utilizzo dei segreti significa che gli utenti non devono includere le credenziali del database per le risorse a cui destinano nelle chiamate a Data API. Data API chiama in modo trasparente Secrets Manager, che consente (o nega) la richiesta del segreto da parte dell'utente. Per informazioni sulla configurazione dei segreti da utilizzare con Data API, consulta. Archiviazione delle credenziali del database in AWS Secrets Manager

La AmazonRDSDataFullAccess policy fornisce l'accesso completo (tramite Data API) alle risorse. Puoi restringere l'ambito definendo le tue policy che specificano l'Amazon Resource Name (ARN) di una risorsa.

Ad esempio, la seguente politica mostra un esempio delle autorizzazioni minime richieste a un utente per accedere all'API Data per il cluster DB identificato dal relativo ARN. La policy include le autorizzazioni necessarie per accedere Secrets Manager e ottenere l'autorizzazione all'istanza DB per l'utente.

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

Si consiglia di utilizzare un ARN specifico per l'elemento "Risorse" nelle istruzioni delle policy (come illustrato nell'esempio) anziché un carattere jolly (*).

Utilizzo dell'autorizzazione basata su tag

RDS Data API (Data API) e Secrets Manager supportano entrambi l'autorizzazione basata su tag. Itag sono coppie chiave-valore che etichettano una risorsa, ad esempio un cluster RDS, con un valore stringa aggiuntivo, ad esempio:

È possibile applicare tag alle risorse per l'allocazione dei costi, il supporto delle operazioni, il controllo degli accessi e molti altri motivi. Se non disponi già di tag sulle tue risorse e desideri applicarli, puoi saperne di più alla pagina Applicazione di tag alle risorse Amazon RDS. È possibile utilizzare i tag nelle istruzioni delle policy per limitare l'accesso ai cluster RDS etichettati con questi tag. Ad esempio, un cluster DB Aurora potrebbe avere tag che identificano l'ambiente come produzione o sviluppo.

Nell'esempio seguente viene illustrato come utilizzare i tag nelle istruzioni delle policy. Questa istruzione richiede che sia il cluster e il segreto passato nella richiesta API dati abbiano un tag environment:production.

Ecco come viene applicata la policy: quando un utente effettua una chiamata utilizzando Data API, la richiesta viene inviata al servizio. L'API Data verifica innanzitutto che l'ARN del cluster passato nella richiesta sia taggato con. environment:production Quindi chiama Secrets Manager per recuperare il valore del segreto dell'utente nella richiesta. Secrets Manager verifica inoltre che il segreto dell'utente sia contrassegnato con environment:production. In tal caso, l'API dati utilizza quindi il valore recuperato per la password DB dell'utente. Infine, se anche questo è corretto, la richiesta dell'API dati viene richiamata correttamente per l'utente.

{
    "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'esempio mostra azioni separate per rds-data e secretsmanager per Data API e Secrets Manager. Tuttavia, è possibile combinare azioni e definire le condizioni dei tag in molti modi diversi per supportare i casi d'uso specifici. Per ulteriori informazioni, consulta Utilizzo delle policy basate su identità (policy IAM) per Secrets Manager.

Nell'elemento "Condizione" delle policy, è possibile scegliere le chiavi tag tra le seguenti:

Per ulteriori informazioni sui tag delle risorse e su come utilizzarliaws:TagKeys, consulta Controllo dell'accesso alle AWS risorse mediante i tag delle risorse.

Archiviazione delle credenziali del database in AWS Secrets Manager

Quando si chiama RDS Data API (Data API), si passano le credenziali per il cluster Aurora DB utilizzando un segreto in Secrets Manager. Per utilizzare questo metodo per passare le credenziali, specifica il nome del segreto o l'Amazon Resource Name (ARN) del segreto.

Per ulteriori informazioni relative all'utilizzo di Secrets Manager, consulta la Guida per l'utente di AWS Secrets Manager.

Per informazioni su come Amazon Aurora gestisce la gestione delle identità e degli accessi, consulta Come funziona Amazon Aurora con IAM.

Per informazioni sulla creazione di una policy IAM, consulta Creazione di policy IAM nella Guida per l'utente di IAM. Per informazioni sull'aggiunta di una policy IAM a un utente, consulta Aggiunta e rimozione di autorizzazioni per identità IAM nella Guida per l'utente di IAM.

Abilitazione dell'API RDS Data

Per utilizzare RDS Data API (Data API), abilitala per il tuo cluster Aurora DB. Puoi abilitare Data API quando crei o modifichi il cluster DB.

Abilitazione dell'API RDS Data quando crei un database

Durante la creazione di un database che supporta RDS Data API (Data API), puoi abilitare questa funzionalità. Le seguenti procedure descrivono come eseguire questa operazione quando si utilizza la AWS Management Console AWS CLI, la o l'API RDS.

Abilitazione dell'API RDS Data su un database esistente

È possibile modificare un cluster DB che supporta RDS Data API (Data API) per abilitare o disabilitare questa funzionalità.

Abilitazione o disabilitazione di Data API (Aurora Serverless v2 e fornito)

Utilizza le seguenti procedure per abilitare o disabilitare Data API su Aurora Serverless v2 e database predisposti. Per abilitare o disabilitare Data API su Aurora Serverless v1 database, utilizzare le procedure inAbilitazione o disabilitazione di Data API (Aurora Serverless v1 solo).

Abilitazione o disabilitazione di Data API (Aurora Serverless v1 solo)

Utilizza le seguenti procedure per abilitare o disabilitare Data API su sistemi esistenti Aurora Serverless v1 database. Per abilitare o disabilitare Data API su Aurora Serverless v2 e i database predisposti, utilizza le procedure inAbilitazione o disabilitazione di Data API (Aurora Serverless v2 e fornito).

Creazione di un endpoint Amazon VPC per RDS Data API ()AWS PrivateLink

Amazon VPC ti consente di lanciare AWS risorse, come cluster e applicazioni Aurora DB, in un cloud privato virtuale (VPC). AWS PrivateLink fornisce connettività privata tra VPCs e AWS servizi con elevata sicurezza sulla rete Amazon. Utilizzando AWS PrivateLink, puoi creare endpoint Amazon VPC, che ti consentono di connetterti ai servizi su diversi account e basati VPCs su Amazon VPC. Per ulteriori informazioni su AWS PrivateLink, consultare Servizi endpoint VPC (AWS PrivateLink) nella Guida per l'utente di Amazon Virtual Private Cloud.

Puoi chiamare RDS Data API (Data API) con endpoint Amazon VPC. L'uso di un endpoint Amazon VPC mantiene il traffico tra le applicazioni in Amazon VPC e Data API nella AWS rete, senza utilizzare indirizzi IP pubblici. Gli endpoint Amazon VPC consentono di soddisfare i requisiti di conformità e normativi relativi alla limitazione della connettività Internet. Ad esempio, se utilizzi un endpoint Amazon VPC, puoi mantenere il traffico tra un'applicazione in esecuzione su un' EC2 istanza Amazon e l'API Data VPCs che li contiene.

Dopo aver creato l'endpoint Amazon VPC, puoi iniziare a utilizzarlo senza apportare modifiche al codice o alla configurazione nell'applicazione.

Dopo aver creato l'endpoint, scegli il link in AWS Management Console per visualizzare i dettagli dell'endpoint.

La scheda Details (Dettagli) dell'endpoint mostra i nomi host DNS generati durante la creazione dell'endpoint Amazon VPC.

È possibile utilizzare l'endpoint standard (rds-data.region.amazonaws.com) o uno degli endpoint specifici di VPC per chiamare l'API dati all'interno di Amazon VPC. L'endpoint API dati standard esegue automaticamente l'instradamento all'endpoint Amazon VPC. Questo routing si verifica perché il nome host DNS privato è stato abilitato al momento della creazione dell'endpoint Amazon VPC.

Quando utilizzi un endpoint Amazon VPC in una chiamata Data API, tutto il traffico tra l'applicazione e l'API Data rimane nell'Amazon VPCs che lo contiene. Puoi utilizzare un endpoint Amazon VPC per qualsiasi tipo di chiamata API dati. Per informazioni sulla chiamata a Data API, consulta. Chiamata RDS Data API

Chiamata RDS Data API

Con RDS Data API (Data API) abilitata sul tuo cluster Aurora DB, puoi eseguire istruzioni SQL sul cluster Aurora DB utilizzando Data API o. AWS CLI Data API supporta i linguaggi di programmazione supportati da. AWS SDKs Per ulteriori informazioni, consulta Strumenti su cui costruire AWS.

Riferimento alle operazioni dell'API Data

Data API fornisce le seguenti operazioni per eseguire istruzioni SQL.

Puoi utilizzare entrambe le operazioni per eseguire singole istruzioni SQL o per eseguire transazioni. Per le transazioni, Data API fornisce le seguenti operazioni.

Le operazioni per l'esecuzione di istruzioni SQL e il supporto delle transazioni hanno i seguenti parametri e AWS CLI opzioni comuni di Data API. Alcune operazioni supportano altri parametri o opzioni.

RDS Data API supporta i seguenti tipi di dati per Aurora MySQL:

RDS Data API supporta i seguenti tipi scalari Aurora PostgreSQL:

RDS Data API supporta i seguenti tipi di array Aurora PostgreSQL:

È possibile utilizzare i parametri nelle chiamate Data API verso ExecuteStatement eBatchExecuteStatement, quando si eseguono i comandi e. AWS CLI execute-statement batch-execute-statement Per utilizzare un parametro, specifica una coppia nome-valore nel tipo di dati SqlParameter. Specifica il valore con il tipo di dati Field. La tabella seguente associa i tipi di dati Java Database Connectivity (JDBC) ai tipi di dati specificati nelle chiamate API dati.

Alcuni tipi, come DECIMAL eTIME, richiedono un suggerimento affinché Data API passi String i valori al database come tipo corretto. Per utilizzare un suggerimento, includere i valori per typeHint nel tipo di dati SqlParameter. i seguito sono riportati i valori possibili per typeHint:

Chiamata dell'API RDS Data con AWS CLI

È possibile chiamare RDS Data API (Data API) utilizzando il. AWS CLI

I seguenti esempi utilizzano l'API AWS CLI for Data. Per ulteriori informazioni, consulta la Documentazione di riferimento AWS CLI per l'API dati.

In ogni esempio, sostituisci l'Amazon Resource Name (ARN) per il cluster DB con l'ARN per il tuo cluster Aurora DB. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.

Avvio di una transazione SQL

Puoi avviare una transazione SQL utilizzando il comando CLI aws rds-data begin-transaction. La chiamata restituisce un identificatore di transazione.

Oltre alle opzioni comuni, specifica l'opzione --database, che fornisce il nome del database.

Ad esempio, il comando CLI seguente avvia una transazione SQL.

In Linux, macOS, oppure 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"

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

Di seguito è riportato un esempio della risposta.

{
    "transactionId": "ABC1234567890xyz"
}

Esecuzione di un'istruzione SQL

Puoi eseguire un'istruzione SQL utilizzando il comando CLI aws rds-data execute-statement.

Puoi eseguire un'istruzione SQL in una transazione specificando l'identificatore di transazione con l'opzione --transaction-id. Puoi avviare una transazione utilizzando il comando CLI aws rds-data begin-transaction. Puoi terminare ed eseguire il commit di una transazione utilizzando il comando CLI aws rds-data commit-transaction.

Oltre alle opzioni comuni, specifica le seguenti opzioni:

Il cluster database restituisce una risposta per la chiamata.

Ad esempio, il comando CLI seguente esegue una singola istruzione SQL e omette i metadati nei risultati (il valore predefinito).

In Linux, macOS, oppure 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"

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

Di seguito è riportato un esempio della risposta.

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

Il comando CLI seguente esegue una singola istruzione SQL in una transazione specificando l'opzione --transaction-id.

In Linux, macOS, oppure 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"

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

Di seguito è riportato un esempio della risposta.

{
    "numberOfRecordsUpdated": 1
}

Il comando CLI seguente esegue una singola istruzione SQL con parametri.

In Linux, macOS, oppure 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\"}}]"

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

Di seguito è riportato un esempio della risposta.

{
    "numberOfRecordsUpdated": 1
}

Il comando CLI seguente esegue un'istruzione SQL DDL (Data Definition Language). L'istruzione DDL rinomina la colonna job nella colonna role.

In Linux, macOS, oppure 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

In 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

Di seguito è riportato un esempio della risposta.

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}

Esecuzione di un'istruzione SQL batch su un array di dati

Puoi eseguire un'istruzione SQL batch su un'array di dati utilizzando il comando CLI aws rds-data batch-execute-statement. Puoi utilizzare questo comando per eseguire un'operazione di importazione in blocco o di aggiornamento.

Puoi eseguire un'istruzione SQL in una transazione specificando l'identificatore di transazione con l'opzione --transaction-id. Puoi avviare una transazione utilizzando il comando CLI aws rds-data begin-transaction. Puoi terminare ed eseguire il commit di una transazione utilizzando il comando CLI aws rds-data commit-transaction.

Oltre alle opzioni comuni, specifica le seguenti opzioni:

Il cluster database restituisce una risposta alla chiamata.

Ad esempio, il seguente comando CLI esegue un'istruzione SQL batch su un'array di dati con un set di parametri.

In Linux, macOS, oppure 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\"}}]]"

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

Esecuzione del commit di una transazione SQL

Utilizzando il comando CLI aws rds-data commit-transaction, puoi terminare una transazione SQL avviata con aws rds-data begin-transaction ed eseguire il commit delle modifiche.

Oltre alle opzioni di comando, specifica l'opzione seguente:

Ad esempio, il comando CLI seguente termina una transazione SQL ed esegue il commit delle modifiche.

In Linux, macOS, oppure 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"

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

Di seguito è riportato un esempio della risposta.

{
    "transactionStatus": "Transaction Committed"
}

Rollback di una transazione SQL

Utilizzando il comando CLI aws rds-data rollback-transaction, puoi eseguire il rollback di una transazione SQL avviata con aws rds-data begin-transaction. Il rollback di una transazione annulla le relative modifiche.

Oltre alle opzioni di comando, specifica l'opzione seguente:

Ad esempio, il AWS CLI comando seguente ripristina una transazione SQL.

In Linux, macOS, oppure 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"

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

Di seguito è riportato un esempio della risposta.

{
    "transactionStatus": "Rollback Complete"
    }

Chiamata dell'API RDS Data da un'applicazione Python

Puoi chiamare RDS Data API (Data API) da un'applicazione Python.

I seguenti esempi utilizzano l' AWS SDK per Python (Boto). Per ulteriori informazioni su Boto, consulta la documentazione di SDK AWS for Python (Boto 3).

In ogni esempio, sostituisci l'Amazon Resource Name (ARN) del cluster DB con l'ARN per il tuo cluster Aurora DB. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.

Esecuzione di una query SQL

Puoi eseguire un'istruzione SELECT e recuperare i risultati da un'applicazione Python.

L'esempio seguente esegue una query 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'
        }
    ]
]

Esecuzione di un'istruzione SQL DML

Puoi eseguire un'istruzione DML (Data Manipulation Language) per inserire, aggiornare o eliminare dati nel database. Puoi anche utilizzare parametri in istruzioni DML.

L'esempio seguente esegue un'istruzione SQL insert e utilizza i parametri.

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

Esecuzione di una transazione SQL

Puoi avviare una transazione SQL, eseguire una o più istruzioni SQL, quindi eseguire il commit delle modifiche con un'applicazione Python.

L'esempio seguente esegue una transazione SQL che inserisce una riga in una tabella.

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

Chiamata dell'API RDS Data da un'applicazione Java

È possibile chiamare RDS Data API (Data API) da un'applicazione Java.

Gli esempi seguenti utilizzano l' AWS SDK for Java. Per ulteriori informazioni, consulta la Guida per gli sviluppatori di AWS SDK for Java.

In ogni esempio, sostituisci l'Amazon Resource Name (ARN) del cluster DB con l'ARN per il tuo cluster Aurora DB. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.

Esecuzione di una query SQL

Puoi eseguire un'istruzione SELECT e recuperare i risultati con un'applicazione Java.

L'esempio seguente esegue una query 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));
    }
  }
}

Esecuzione di una transazione SQL

Puoi avviare una transazione SQL, eseguire una o più istruzioni SQL, quindi eseguire il commit delle modifiche con un'applicazione Java.

L'esempio seguente esegue una transazione 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);
  }
}

Esecuzione di un'operazione SQL batch

Puoi eseguire operazioni di inserimento a blocchi e di aggiornamento su un'array di dati con un'applicazione Java. Puoi eseguire un'istruzione DML con un array di set di parametri.

L'esempio seguente illustra un'operazione di inserimento in batch.

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

Controllo del comportamento di timeout dell'API Data

Tutte le chiamate a Data API sono sincrone. Supponiamo di eseguire un'operazione Data API che esegue un'istruzione SQL come INSERT o. CREATE TABLE Se la chiamata Data API viene restituita correttamente, l'elaborazione SQL viene completata al ritorno della chiamata.

Per impostazione predefinita, Data API annulla un'operazione e restituisce un errore di timeout se l'operazione non termina l'elaborazione entro 45 secondi. In tal caso, i dati non vengono inseriti, la tabella non viene creata e così via.

Puoi utilizzare Data API per eseguire operazioni di lunga durata che non possono essere completate entro 45 secondi. Se prevedi che un'operazione come un'operazione in blocco INSERT o un'operazione DDL su una tabella di grandi dimensioni richieda più di 45 secondi, puoi specificare il continueAfterTimeout parametro per l'operazione. ExecuteStatement L'applicazione continua a ricevere l'errore di timeout. Tuttavia, l'operazione continua a essere eseguita e non viene annullata. Per vedere un esempio, consulta Esecuzione di una transazione SQL.

Se l' AWS SDK per il tuo linguaggio di programmazione ha un proprio periodo di timeout per le chiamate API o le connessioni socket HTTP, assicurati che tutti questi periodi di timeout siano superiori a 45 secondi. Per alcuni SDKs, il periodo di timeout è inferiore a 45 secondi per impostazione predefinita. Ti consigliamo di impostare qualsiasi periodo di timeout specifico dell'SDK o del client su almeno un minuto. In questo modo si evita la possibilità che l'applicazione riceva un errore di timeout mentre l'operazione Data API viene ancora completata correttamente. In questo modo, puoi essere sicuro se riprovare l'operazione o meno.

Ad esempio, supponiamo che l'SDK restituisca un errore di timeout all'applicazione, ma che l'operazione Data API venga comunque completata entro l'intervallo di timeout dell'API Data. In tal caso, ritentare l'operazione potrebbe inserire dati duplicati o altrimenti produrre risultati errati. L'SDK potrebbe ritentare l'operazione automaticamente, causando dati errati senza alcuna azione da parte dell'applicazione.

L'intervallo di timeout è particolarmente importante per Java 2 SDK. In quell'SDK, il timeout delle chiamate API e il timeout del socket HTTP sono entrambi di 30 secondi per impostazione predefinita. Ecco un esempio di impostazione di tali timeout su un valore più alto:

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

Ecco un esempio equivalente che utilizza il client di dati asincrono:

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

Utilizzo della libreria client Java per RDS Data API

È possibile scaricare e utilizzare una libreria client Java per RDS Data API (Data API). Questa libreria client Java offre un modo alternativo di utilizzare Data API. Utilizzando questa libreria, puoi mappare le tue classi lato client alle richieste e alle risposte di Data API. Questo supporto per la mappatura può facilitare l'integrazione con alcuni tipi Java specifici, ad esempio Date, Time e BigDecimal.

Download della libreria client Java per l'API dati

La libreria client Java Data API è open source GitHub nella seguente posizione:

https://github.com/awslabs/rds-data-api-client-libreria-java

Puoi creare manualmente la libreria dai file di origine, ma la best practice consiste nell'utilizzare la libreria utilizzando la gestione delle dipendenze di Apache Maven. Aggiungi la seguente dipendenza al file Maven POM.

Per la versione 2.x, che è compatibile con AWS SDK 2.x, usa quanto segue:

<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>

Per la versione 1.x, che è compatibile con AWS SDK 1.x, utilizzate quanto segue:

<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>

Esempi di librerie client Java

Di seguito puoi trovare alcuni esempi comuni di utilizzo della libreria client Java dell'API dati. Questi esempi presuppongono che sia disponibile una tabella accounts con due colonne: accountId e name. Hai anche il seguente oggetto di trasferimento dati (DTO).

public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

La libreria client consente di passare DTOs come parametri di input. L'esempio seguente mostra come i clienti DTOs vengono mappati ai set di parametri di input.

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

In alcuni casi, è più facile lavorare con valori semplici come parametri di input. Puoi farlo con la seguente sintassi.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
         .withParameter("accountId", 3)
         .withParameter("name", "Zhang")
         .execute();

Di seguito è riportato un altro esempio che funziona con valori semplici come parametri di input.

client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos")
         .execute();
                

La libreria client fornisce la mappatura automatica del DTOs momento in cui viene restituito un risultato. Gli esempi seguenti mostrano come il risultato viene mappato al tuo. DTOs

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

In molti casi, il set di risultati del database contiene solo un singolo valore. Al fine di semplificare il recupero di tali risultati, la libreria client offre le seguenti API:

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

Elaborazione dei risultati delle query 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 chiamata. ExecuteStatement 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> 

Risoluzione dei problemi relativi all'API RDS Data

Utilizza le seguenti sezioni, intitolate con i messaggi di errore più comuni, per risolvere i problemi riscontrati con RDS Data API (Data API).

La transazione <transaction_ID> non è stata trovata

In questo caso, l'ID transazione specificato in una chiamata API dati non è stato trovato. Al messaggio di errore viene aggiunta la causa di questo problema, ovvero una delle seguenti:

Per informazioni sull'esecuzione di transazioni, consulta Chiamata RDS Data API.

Il pacchetto per la query è troppo grande

In questo caso, il set di risultati restituito per una riga era troppo grande. Il limite delle dimensioni dell'API dati è 64 KB per riga nel set di risultati restituito dal database.

Per risolvere questo problema, verifica che ogni riga in un set di risultati sia corrispondente o inferiore a 64 KB.

La risposta del database è andata oltre il limite delle dimensioni

In questo caso, le dimensioni del set di risultati restituito dal database erano troppo grandi. Il limite dell'API dati è 1 MiB nel set di risultati restituito dal database.

Per risolvere questo problema, assicurati che le chiamate a Data API restituiscano 1 MiB di dati o meno. Se devi restituire più di 1 MiB, è possibile utilizzare chiamate ExecuteStatement molteplici con la clausola LIMIT nella query.

Per ulteriori informazioni sulla clausola LIMIT, consulta SELECT Syntax nella documentazione MySQL.

HttpEndpointnon è abilitato per il cluster <cluster_ID>

Controlla le seguenti potenziali cause di questo problema:

DatabaseErrorException: Transaction sta ancora eseguendo una query

Se l'applicazione invia una richiesta con un ID di transazione e tale transazione sta attualmente elaborando un'altra richiesta, Data API restituisce immediatamente questo errore all'applicazione. Questa condizione potrebbe verificarsi se l'applicazione effettua richieste asincrone, utilizzando un meccanismo come le «promesse» in Javascript.

Per risolvere questo problema, attendi il completamento della richiesta precedente, quindi riprova. Puoi continuare a riprovare finché l'errore non si verifica più o l'applicazione non riceve un tipo di errore diverso.

Questa condizione può verificarsi con Data API for Aurora Serverless v2 e istanze predisposte. In Data API per Aurora Serverless v1, le richieste successive per lo stesso ID di transazione attendono automaticamente il completamento della richiesta precedente. Tuttavia, questo comportamento precedente potrebbe potenzialmente comportare dei timeout dovuti al fatto che la richiesta precedente richiedeva troppo tempo. Se stai eseguendo il porting di un'applicazione Data API precedente che effettua richieste simultanee, modifica la logica di gestione delle eccezioni per tenere conto di questo nuovo tipo di errore.