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à.
# Chiamata dell’API dati di Amazon RDS
Con l’API dati di Amazon RDS (API dati) abilitata sul cluster di database Aurora, puoi eseguire istruzioni SQL sul cluster di database Aurora utilizzando l’API dati o la AWS CLI. L’API dati supporta i linguaggi di programmazione supportati dagli SDK AWS. Per ulteriori informazioni, consulta [Strumenti per creare in AWS](https://aws.amazon.com/tools/).
**Topics**
+ [Riferimento alle operazioni dell’API dati di Amazon RDS](data-api-operations.md)
+ [Chiamata dell’API dati di Amazon RDS con la AWS CLI](data-api.calling.cli.md)
+ [Chiamata dell’API dati di Amazon RDS da un’applicazione Python](data-api.calling.python.md)
+ [Chiamata dell’API dati di Amazon RDS da un’applicazione Java](data-api.calling.java.md)
+ [Controllo del comportamento di timeout dell’API dati](data-api-timeouts.md)
# Riferimento alle operazioni dell’API dati di Amazon RDS
L’API dati di Amazon RDS fornisce le seguenti operazioni per eseguire istruzioni SQL.
****
| Operazione API dati | AWS CLI comando | Description |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/execute-statement.html) | Esegue un'istruzione SQL in un database. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/batch-execute-statement.html) | Esegue un'istruzione SQL batch su un array di dati per operazioni di aggiornamento in blocco e di inserimento. Puoi eseguire un'istruzione DML (Data Manipolation Language) con una matrice di set di parametri. Un'istruzione SQL batch può fornire un miglioramento significativo delle prestazioni su singole operazioni di inserimento e aggiornamento. |
Puoi utilizzare entrambe le operazioni per eseguire singole istruzioni SQL o per eseguire transazioni. L’API dati fornisce le seguenti operazioni per le transazioni.
****
| Operazione API dati | AWS CLI comando | Description |
| --- | --- | --- |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/begin-transaction.html) | Inizia una transazione SQL. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/commit-transaction.html) | Termina una transazione SQL ed esegue il commit delle modifiche. |
| [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html) | [https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html](https://docs.aws.amazon.com/cli/latest/reference/rds-data/rollback-transaction.html) | Esegue un rollback di una transazione. |
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.
****
| Parametro operazione API dati | AWS CLI opzione di comando | Richiesto | Descrizione |
| --- | --- | --- | --- |
| `resourceArn` | `--resource-arn` | Sì | Il nome della risorsa Amazon (ARN) del cluster di database Aurora. Il cluster deve avere lo stesso Account AWS ruolo o utente IAM che richiama l'API Data. Per accedere a un cluster in un account diverso, assumi un ruolo in tale account. |
| `secretArn` | `--secret-arn` | Sì | Il nome o l'ARN del secreto che abilita l'accesso al cluster database. |
L’API dati di RDS supporta i seguenti tipi di dati per Aurora MySQL:
+ `TINYINT(1)`, `BOOLEAN`, `BOOL`
+ `TINYINT`
+ `SMALLINT` [`SIGNED` \$1 `UNSIGNED`]
+ `MEDIUMINT` [`SIGNED` \$1 `UNSIGNED`]
+ `INT` [`SIGNED` \$1 `UNSIGNED`]
+ `BIGINT` [`SIGNED` \$1 `UNSIGNED`]
+ `FLOAT`
+ `DOUBLE`
+ `VARCHAR`, `CHAR`, `TEXT`, `ENUM`
+ `VARBINARY`, `BINARY`, `BLOB`
+ `DATE`, `TIME`, `DATETIME`, `TIMESTAMP`
+ `DECIMAL`
+ `JSON`
+ `BIT`, `BIT(N)`
L’API dati di RDS supporta i seguenti tipi scalari di Aurora PostgreSQL:
+ `BOOL`
+ `BYTEA`
+ `DATE`
+ `CIDR`
+ `DECIMAL`, `NUMERIC`
+ `ENUM`
+ `FLOAT8`, `DOUBLE PRECISION`
+ `INET`
+ `INT`, `INT4`, `SERIAL`
+ `INT2`, `SMALLINT`, `SMALLSERIAL`
+ `INT8`, `BIGINT`, `BIGSERIAL`
+ `JSONB`, `JSON`
+ `REAL`, `FLOAT`
+ `TEXT`, `CHAR(N)`, `VARCHAR`, `NAME`
+ `TIME`
+ `TIMESTAMP`
+ `UUID`
+ `VECTOR`
L’API dati di RDS supporta i seguenti tipi di array di Aurora PostgreSQL:
+ `BOOL[]`, `BIT[]`
+ `DATE[]`
+ `DECIMAL[]`, `NUMERIC[]`
+ `FLOAT8[]`, `DOUBLE PRECISION[]`
+ `INT[]`, `INT4[]`
+ `INT2[]`
+ `INT8[]`, `BIGINT[]`
+ `JSON[]`
+ `REAL[]`, `FLOAT[]`
+ `TEXT[]`, `CHAR(N)[]`, `VARCHAR[]`, `NAME[]`
+ `TIME[]`
+ `TIMESTAMP[]`
+ `UUID[]`
Puoi utilizzare i parametri nelle chiamate Data API a `ExecuteStatement` e`BatchExecuteStatement`, quando AWS CLI esegui i comandi `execute-statement` e. `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.
****
| Tipo di dati JDBC | Tipo di dati API dati |
| --- | --- |
| `INTEGER, TINYINT, SMALLINT, BIGINT` | `LONG` (o `STRING`) |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY, VARBINARY` | `BLOB` |
| `CLOB` | `STRING` |
| Altri tipi (inclusi i tipi correlati a data e ora) | `STRING` |
**Nota**
Puoi specificare il tipo di dati `LONG` o `STRING` nella chiamata all’API data per i valori `LONG` restituiti dal database. Ti consigliamo di farlo per evitare di perdere la precisione per numeri estremamente grandi, cosa che può succedere quando lavori con JavaScript.
Alcuni tipi, ad esempio `DECIMAL` e `TIME`, richiedono un suggerimento in modo che l’API dati passi i valori `String` 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`:
+ `DATE` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `DATE` al database. Il formato accettato è `YYYY-MM-DD`.
+ `DECIMAL` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `DECIMAL` al database.
+ `JSON` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `JSON` al database.
+ `TIME` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `TIME` al database. Il formato accettato è `HH:MM:SS[.FFF]`.
+ `TIMESTAMP` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `TIMESTAMP` al database. Il formato accettato è `YYYY-MM-DD HH:MM:SS[.FFF]`.
+ `UUID` – Il valore del parametro `String` corrispondente viene inviato come oggetto di tipo `UUID` al database.
**Nota**
Attualmente, Data API non supporta array di Universal Unique Identifiers ()UUIDs.
**Nota**
Per Amazon Aurora PostgreSQL, l’API dati restituisce sempre il tipo di dati Aurora PostgreSQL `TIMESTAMPTZ` nel fuso orario UTC.
# Chiamata dell’API dati di Amazon RDS con la AWS CLI
Puoi chiamare l’API dati di Amazon RDS (API dati) utilizzando la AWS CLI.
Gli esempi seguenti utilizzano la AWS CLI per l’API dati. Per ulteriori informazioni, consulta la [Documentazione di riferimento AWS CLI per l'API dati](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html).
In ogni esempio, sostituisci il nome della risorsa Amazon (ARN) del cluster di database con l’ARN per il cluster di database Aurora. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.
**Nota**
AWS CLI può formattare le risposte in JSON.
**Topics**
+ [Avvio di una transazione SQL](#data-api.calling.cli.begin-transaction)
+ [Esecuzione di un'istruzione SQL](#data-api.calling.cli.execute-statement)
+ [Esecuzione di un'istruzione SQL batch su un array di dati](#data-api.calling.cli.batch-execute-statement)
+ [Esecuzione del commit di una transazione SQL](#data-api.calling.cli.commit-transaction)
+ [Rollback di una transazione SQL](#data-api.calling.cli.rollback-transaction)
## 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.
**Importante**
All’interno dell’API dati, una transazione scade se non ci sono chiamate che utilizzano il suo ID transazione in un periodo di tre minuti. Se una transazione scade prima del commit, viene automaticamente sottoposta a rollback dall’API dati.
Le istruzioni DDL (Data Definition Language) MySQL all’interno di una transazione causano un commit implicito. Consigliamo di eseguire ogni istruzioni DDL MySQL in un comando `execute-statement` separato con l’opzione `--continue-after-timeout`.
Oltre alle opzioni comuni, specifica l'opzione `--database`, che fornisce il nome del database.
Ad esempio, il comando CLI seguente avvia una transazione SQL.
Per Linux, macOS o 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"
```
Per 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`.
**Importante**
Se non specifichi l'opzione `--transaction-id`, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
Oltre alle opzioni comuni, specifica le seguenti opzioni:
+ `--sql` (obbligatoria) – Un'istruzione SQL da eseguire sul cluster database.
+ `--transaction-id` (facoltativa) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI `begin-transaction`. Specifica l'ID transazione della transazione in cui desideri includere l'istruzione SQL.
+ `--parameters` (facoltativa) – I parametri per l'istruzione SQL.
+ `--include-result-metadata | --no-include-result-metadata` (opzionale) – Un valore che indica se includere metadati nei risultati. Il valore di default è `--no-include-result-metadata`.
+ `--database` (opzionale) – Il nome del database.
L'opzione `--database` potrebbe non funzionare quando si esegue un'istruzione SQL dopo l'esecuzione di `--sql "use database_name;"` nella richiesta precedente. Si consiglia di utilizzare l'opzione `--database` invece di eseguire le istruzioni `--sql "use database_name;"`.
+ `--continue-after-timeout | --no-continue-after-timeout` (facoltativo): un valore che indica se continuare l’esecuzione dell’istruzione dopo che la chiamata supera l’intervallo di timeout di 45 secondi dell’API dati. Il valore di default è `--no-continue-after-timeout`.
Per istruzioni DDL (Data Definition Language), è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata per evitare errori e la possibilità di strutture dati danneggiate.
+ `--format-records-as "JSON"|"NONE"` - Un valore facoltativo che specifica se formattare il set di risultati come stringa JSON. Il valore di default è `"NONE"`. Per informazioni sull'utilizzo dell'elaborazione di set di risultati JSON, consulta [Elaborazione dei risultati delle query dell’API dati di Amazon RDS in formato JSON](data-api-json.md).
Il cluster database restituisce una risposta per la chiamata.
**Nota**
Il limite di dimensioni della risposta è 1 MiB. Se la chiamata restituisce più di 1 MiB di dati di risposta, verrà terminata.
Per Aurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non esiste alcun limite.
Ad esempio, il comando CLI seguente esegue una singola istruzione SQL e omette i metadati nei risultati (il valore predefinito).
Per Linux, macOS o 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"
```
Per 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`.
Per Linux, macOS o 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"
```
Per 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.
Per Linux, macOS o 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\"}}]"
```
Per 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`.
**Importante**
Per istruzioni DDL, è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata. Quando un'istruzione DDL termina prima che l'esecuzione sia terminata, può causare errori e verosimilmente strutture dati danneggiate. Per continuare l’esecuzione di un’istruzione dopo che una chiamata supera il timeout di 45 secondi dell’API dati di RDS, specifica l’opzione `--continue-after-timeout`.
Per Linux, macOS o 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
```
Per 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
}
```
**Nota**
I dati `generatedFields` non sono supportati da Aurora PostgreSQL. Per ottenere i valori dei campi generati, utilizza la clausola `RETURNING`. Per ulteriori informazioni, consulta [ Returning Data From Modified Rows](https://www.postgresql.org/docs/10/dml-returning.html) nella documentazione PostgreSQL.
## 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`.
**Importante**
Se non specifichi l'opzione `--transaction-id`, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
Oltre alle opzioni comuni, specifica le seguenti opzioni:
+ `--sql` (obbligatoria) – Un'istruzione SQL da eseguire sul cluster database.
**Suggerimento**
Perché le istruzioni siano compatibili con MySQL, non includere un punto e virgola alla fine del parametro `--sql`. Un punto e virgola finale potrebbe causare un errore di sintassi.
+ `--transaction-id` (facoltativa) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI `begin-transaction`. Specifica l'ID transazione della transazione in cui desideri includere l'istruzione SQL.
+ `--parameter-set` (facoltativa) – Il set di parametri per l'operazione batch.
+ `--database` (opzionale) – Il nome del database.
Il cluster database restituisce una risposta alla chiamata.
**Nota**
Non è previsto alcun limite massimo al numero di set di parametri. Tuttavia, la dimensione massima della richiesta HTTP inviata tramite l’API dati è 4 MiB. Se la richiesta supera questo limite, l’API dati restituisce un errore e non elabora la richiesta. Questo limite di 4 MiB include la dimensione delle intestazioni HTTP e la notazione JSON nella richiesta. Pertanto, il numero di set di parametri che è possibile includere dipende da una combinazione di fattori, ad esempio la dimensione dell'istruzione SQL e la dimensione di ogni set di parametri.
Il limite di dimensioni della risposta è 1 MiB. Se la chiamata restituisce più di 1 MiB di dati di risposta, verrà terminata.
Per Aurora Serverless v1, il numero massimo di richieste al secondo è 1.000. Per tutti gli altri database supportati, non esiste alcun limite.
Ad esempio, il seguente comando CLI esegue un'istruzione SQL batch su un'array di dati con un set di parametri.
Per Linux, macOS o 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\"}}]]"
```
Per 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\"}}]]"
```
**Nota**
Non includere interruzioni di riga nell'opzione `--parameter-sets`.
## 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:
+ `--transaction-id` (obbligatorio) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI `begin-transaction`. Specifica l'ID transazione della transazione che desideri terminare e di cui eseguire il commit.
Ad esempio, il comando CLI seguente termina una transazione SQL ed esegue il commit delle modifiche.
Per Linux, macOS o 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"
```
Per 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.
**Importante**
Se l'ID transazione è scaduto, il rollback della transazione è stato eseguito automaticamente. In questo caso, un comando `aws rds-data rollback-transaction` che specifica l'ID transazione scaduto restituisce un errore.
Oltre alle opzioni di comando, specifica l'opzione seguente:
+ `--transaction-id` (obbligatorio) – L'identificatore di una transazione che è stata avviata utilizzando il comando CLI `begin-transaction`. Specifica l'ID transazione della transazione di cui si desidera eseguire il rollback.
Ad esempio, il comando AWS CLI seguente esegue il rollback di una transazione SQL.
Per Linux, macOS o 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"
```
Per 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 dati di Amazon RDS da un’applicazione Python
Puoi chiamare l’API dati di Amazon RDS (API dati) da un’applicazione Python.
Gli esempi seguenti utilizzano il kit SDK AWS for Python (Boto). Per ulteriori informazioni su Boto, consulta la [documentazione di SDK AWS for Python (Boto 3)](https://boto3.amazonaws.com/v1/documentation/api/latest/index.html).
In ogni esempio, sostituisci il nome della risorsa Amazon (ARN) del cluster di database con l’ARN del cluster di database Aurora. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.
**Topics**
+ [Esecuzione di una query SQL](#data-api.calling.python.run-query)
+ [Esecuzione di un'istruzione SQL DML](#data-api.calling.python.run-inert)
+ [Esecuzione di una transazione SQL](#data-api.calling.python.run-transaction)
## 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.
**Importante**
Se una chiamata non fa parte di una transazione perché non include il parametro `transactionID`, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
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.
**Importante**
Una transazione scade se non ci sono chiamate che utilizzano il suo ID transazione in un periodo di tre minuti. Se una transazione scade prima che venga eseguito il commit della stessa, viene automaticamente sottoposta a rollback.
Se non specifichi un ID transazione, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
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
```
**Nota**
Se esegui un'istruzione DDL (Data Definition Language), è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata. Quando un'istruzione DDL termina prima che l'esecuzione sia terminata, può causare errori e verosimilmente strutture dati danneggiate. Per continuare l’esecuzione di un’istruzione dopo che una chiamata supera l’intervallo di timeout di 45 secondi dell’API dati di RDS, imposta il parametro `continueAfterTimeout` su `true`.
# Chiamata dell’API dati di Amazon RDS da un’applicazione Java
Puoi chiamare l’API dati di Amazon RDS (API dati) da un’applicazione Java.
Gli esempi seguenti utilizzano il kit SDK AWS per Java. Per ulteriori informazioni, consulta la [Guida per sviluppatori di AWS SDK per Java](https://docs.aws.amazon.com/sdk-for-java/latest/developer-guide/welcome.html).
In ogni esempio, sostituisci il nome della risorsa Amazon (ARN) del cluster di database con l’ARN del cluster di database Aurora. Inoltre, sostituisci l'ARN segreto con l'ARN del segreto in Secrets Manager che consente l'accesso al cluster database.
**Topics**
+ [Esecuzione di una query SQL](#data-api.calling.java.run-query)
+ [Esecuzione di una transazione SQL](#data-api.calling.java.run-transaction)
+ [Esecuzione di un'operazione SQL batch](#data-api.calling.java.run-batch)
## 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 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.
**Importante**
Una transazione scade se non ci sono chiamate che utilizzano il suo ID transazione in un periodo di tre minuti. Se una transazione scade prima che venga eseguito il commit della stessa, viene automaticamente sottoposta a rollback.
Se non specifichi un ID transazione, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
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);
}
}
```
**Nota**
Se esegui un'istruzione DDL (Data Definition Language), è consigliabile continuare a eseguire l'istruzione dopo il timeout della chiamata. Quando un'istruzione DDL termina prima che l'esecuzione sia terminata, può causare errori e verosimilmente strutture dati danneggiate. Per continuare l’esecuzione di un’istruzione dopo che una chiamata supera l’intervallo di timeout di 45 secondi dell’API dati di RDS, imposta il parametro `continueAfterTimeout` su `true`.
## 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.
**Importante**
Se non specifichi un ID transazione, viene eseguito automaticamente il commit delle modifiche risultanti dalla chiamata.
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 dati
Tutte le chiamate all'API dati sono sincrone. Supponiamo di eseguire un’operazione dell’API dati che esegue un’istruzione SQL come `INSERT` o `CREATE TABLE`. Se la chiamata API dati viene completata correttamente, l’elaborazione SQL è terminata al momento del ritorno della chiamata.
Per impostazione predefinita, l’API dati annulla un’operazione e restituisce un errore di timeout se l’elaborazione non termina entro 45 secondi. In tal caso, i dati non vengono inseriti, la tabella non viene creata e così via.
Puoi utilizzare l’API dati per eseguire operazioni di lunga durata che non possono essere completate entro 45 secondi. Se prevedi che un’operazione, come `INSERT` in blocco o un’operazione DDL su una tabella di grandi dimensioni, richieda più di 45 secondi, puoi specificare il parametro `continueAfterTimeout` per l’operazione `ExecuteStatement`. L’applicazione riceve comunque 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](data-api.calling.java.md#data-api.calling.java.run-transaction).
Se l’SDK AWS per il linguaggio di programmazione ha un proprio periodo di timeout per le chiamate API o per le connessioni socket HTTP, assicurati che tutti questi periodi di timeout siano superiori a 45 secondi. Per alcuni SDK, il periodo di timeout è inferiore a 45 secondi per impostazione predefinita. Consigliamo di impostare qualsiasi periodo di timeout specifico dell’SDK o del client su almeno un minuto. Così eviti che l’applicazione riceva un errore di timeout mentre l’operazione dell’API dati viene completata correttamente. In tal modo, puoi sapere con certezza se ripetere o meno l’operazione.
Ad esempio, supponiamo che l’SDK restituisca un errore di timeout all’applicazione, ma che l’operazione dell’API dati venga comunque completata entro l’intervallo di timeout dell’API dati. In tal caso, ripetere l’operazione potrebbe inserire dati duplicati o produrre risultati non corretti. L’SDK potrebbe ripetere automaticamente l’operazione, causando dati errati senza alcun intervento dell’applicazione.
L’intervallo di timeout è particolarmente importante per l’SDK Java 2. In tale SDK, il timeout della chiamata API e il timeout del socket HTTP sono entrambi pari a 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));
}
```