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 di Amazon RDS
Utilizzando l’API dati di RDS (API dati), puoi lavorare con un’interfaccia di servizi web per il cluster di database Aurora. L’API dati non richiede una connessione persistente al cluster di database. 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. Gestione dei segreti AWS Per archiviare le credenziali in Secrets Manager, agli utenti devono essere concesse le autorizzazioni appropriate per l’utilizzo di Secrets Manager e anche l’API dati. Per ulteriori informazioni sull'autorizzazione degli utenti, consulta [Autorizzazione di accesso all’API dati di Amazon RDS](data-api.access.md).
Puoi anche utilizzare Data API per integrare Amazon Aurora con altre AWS applicazioni come AWS Lambda AWS AppSync, e. AWS Cloud9 L’API dati fornisce un modo più sicuro per utilizzare 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](https://aws.amazon.com/lambda/), [AWS AppSync](https://aws.amazon.com/appsync/) e [AWS Cloud9](https://aws.amazon.com/cloud9/).
Puoi abilitare l’API dati al momento della creazione del cluster di database Aurora. È inoltre possibile modificare la configurazione in un secondo momento. Per ulteriori informazioni, consulta [Abilitazione dell’API dati di Amazon RDS](data-api.enabling.md).
Dopo aver abilitato l’API dati, 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](query-editor.md).
**Topics**
+ [
# Disponibilità per Regione e versione dell’API dati di Amazon RDS
](data-api.regions.md)
+ [
# Utilizzo IPv6 con Amazon RDS Data API
](data-api.ipv6.md)
+ [
# Limitazioni dell’API dati di Amazon RDS
](data-api.limitations.md)
+ [
# Confronto dei comportamenti delle API dati di Amazon RDS per i cluster Aurora Serverless v2 e con provisioning con i cluster Aurora Serverless v1
](data-api.differences.md)
+ [
# Autorizzazione di accesso all’API dati di Amazon RDS
](data-api.access.md)
+ [
# Abilitazione dell’API dati di Amazon RDS
](data-api.enabling.md)
+ [
# Creazione di un endpoint Amazon VPC per l’API dati di Amazon RDS (AWS PrivateLink)
](data-api.vpc-endpoint.md)
+ [
# Chiamata dell’API dati di Amazon RDS
](data-api.calling.md)
+ [
# Utilizzo della libreria client Java per l’API dati
](data-api.java-client-library.md)
+ [
# Elaborazione dei risultati delle query dell’API dati di Amazon RDS in formato JSON
](data-api-json.md)
+ [
# Risoluzione dei problemi relativi all’API dati di Amazon RDS
](data-api.troubleshooting.md)
+ [
# Registrazione delle chiamate Amazon RDS Data API con AWS CloudTrail
](logging-using-cloudtrail-data-api.md)
+ [
# Monitoraggio delle query dell’API dati RDS con Approfondimenti sulle prestazioni
](monitoring-using-performance-insights-data-api.md)
# Disponibilità per Regione e versione dell’API dati di Amazon RDS
Per informazioni sulle Regioni e sulle versioni del motore disponibili per l’API dati, consulta le sezioni seguenti.
| Tipo di cluster | Disponibilità di regioni e versioni |
| --- | --- |
| Aurora PostgreSQL con provisioning e Serverless v2 | [API dati con Aurora PostgreSQL Serverless v2 e cluster allocati](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg) |
| Aurora MySQL con provisioning e Serverless v2 | [API dati con Aurora MySQL Serverless v2 e cluster allocati](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.ams) |
| Aurora PostgreSQL Serverless v1 | [API dati con Aurora PostgreSQL Serverless v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.apg-sv1) |
| Aurora MySQL Serverless v1 | [API dati con Aurora MySQL Serverless v1](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md#Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.amy) |
Se richiedi moduli crittografici convalidati da FIPS 140-2 quando accedi all’API dati tramite interfaccia a riga di comando o API, utilizza un endpoint FIPS. Per ulteriori informazioni sugli endpoint FIPS disponibili, consulta il [Federal Information Processing Standard (FIPS) 140-2](https://aws.amazon.com/compliance/fips/).
# Utilizzo IPv6 con Amazon RDS Data API
Amazon RDS Data API supporta la IPv6 connettività tramite endpoint dual-stack. Ciò consente di connettersi a Data API utilizzando IPv6 gli indirizzi mantenendo la compatibilità con le versioni precedenti con. IPv4
## IPv6 supporto per endpoint
Data API fornisce endpoint dual-stack che supportano sia le connessioni che le connessioni. IPv4 IPv6 Questi endpoint utilizzano il dominio `.aws` anziché il tradizionale dominio `.amazonaws.com`.
### I tipi di endpoint disponibili sono:
Endpoint pubblici dual stack
Formato: `rds-data.region.api.aws`
Ad esempio: `rds-data.us-east-1.api.aws`
Endpoint dual stack FIPS
Formato: `rds-data-fips.region.api.aws`
Ad esempio: `rds-data-fips.us-east-1.api.aws`
PrivateLink IPv6 endpoint
Disponibile tramite endpoint VPC con supporto IPv6
Consente la IPv6 connettività privata all'interno del tuo VPC
### Endpoint solo per versioni precedenti IPv4
Gli `.amazonaws.com` endpoint esistenti continuano a supportare IPv4 solo connessioni:
+ `rds-data.region.amazonaws.com`
+ `rds-data-fips.region.amazonaws.com`
**Nota**
Gli endpoint legacy restano invariati per garantire la compatibilità con le applicazioni esistenti.
## Utilizzo degli endpoint IPv6
Per utilizzarla IPv6 con Data API, aggiorna l'applicazione per utilizzare i nuovi endpoint dual-stack. L'applicazione verrà utilizzata automaticamente, IPv6 se disponibile, oppure ricorrerà a. IPv4
Per indicazioni generali sulla configurazione del tuo VPC, consulta la sezione [Migrazione verso IPv6 IPv6](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-migrate-ipv6.html) nella Amazon *VPC* User Guide.
Puoi configurare gli IPv6 endpoint in due modi:
+ **Utilizzo della variabile di ambiente**: impostata `AWS_USE_DUALSTACK_ENDPOINT=true` nel proprio IPv6 ambiente. AWS CLI and AWS SDKs costruirà automaticamente gli `api.aws` endpoint appropriati senza la necessità di specificare l'endpoint URLs manualmente.
+ **Utilizzo di un endpoint esplicito URLs**: specifica l'URL dell'endpoint dual-stack direttamente nei AWS CLI comandi o nella configurazione dell'SDK, come mostrato negli esempi seguenti.
### AWS CLI configurazione
Configura AWS CLI gli IPv6 endpoint da utilizzare specificando l'URL dell'endpoint:
Per Linux, macOS o Unix:
```
aws rds-data execute-statement \
--endpoint-url https://rds-data.us-east-1.api.aws \
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" \
--database "mydb" \
--sql "SELECT * FROM users LIMIT 10"
```
Per Windows:
```
aws rds-data execute-statement ^
--endpoint-url https://rds-data.us-east-1.api.aws ^
--resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret" ^
--database "mydb" ^
--sql "SELECT * FROM users LIMIT 10"
```
### AWS Configurazione SDK
Configura AWS SDKs per utilizzare gli endpoint dual-stack:
------
#### [ Python ]
```
import boto3
# Create RDS Data API client with IPv6 dual-stack endpoint
client = boto3.client(
'rds-data',
endpoint_url='https://rds-data.us-east-1.api.aws'
)
# Execute a SQL statement
response = client.execute_statement(
resourceArn='arn:aws:rds:us-east-1:123456789012:cluster:my-cluster',
secretArn='arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret',
database='mydb',
sql='SELECT * FROM users LIMIT 10'
)
print(response['records'])
```
------
#### [ Java ]
```
import software.amazon.awssdk.services.rdsdata.RdsDataClient;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementRequest;
import software.amazon.awssdk.services.rdsdata.model.ExecuteStatementResponse;
import java.net.URI;
// Create RDS Data API client with IPv6 dual-stack endpoint
RdsDataClient client = RdsDataClient.builder()
.endpointOverride(URI.create("https://rds-data.us-east-1.api.aws"))
.build();
// Execute a SQL statement
ExecuteStatementRequest request = ExecuteStatementRequest.builder()
.resourceArn("arn:aws:rds:us-east-1:123456789012:cluster:my-cluster")
.secretArn("arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret")
.database("mydb")
.sql("SELECT * FROM users LIMIT 10")
.build();
ExecuteStatementResponse response = client.executeStatement(request);
System.out.println(response.records());
```
------
#### [ JavaScript ]
```
const { RDSDataClient, ExecuteStatementCommand } = require("@aws-sdk/client-rds-data");
// Create RDS Data API client with IPv6 dual-stack endpoint
const client = new RDSDataClient({
endpoint: "https://rds-data.us-east-1.api.aws"
});
// Execute a SQL statement
const command = new ExecuteStatementCommand({
resourceArn: "arn:aws:rds:us-east-1:123456789012:cluster:my-cluster",
secretArn: "arn:aws:secretsmanager:us-east-1:123456789012:secret:my-secret",
database: "mydb",
sql: "SELECT * FROM users LIMIT 10"
});
const response = await client.send(command);
console.log(response.records);
```
------
## Utilizzo con AWS PrivateLink IPv6
Puoi creare endpoint VPC per Data API che supportano la IPv6 connettività all'interno del tuo VPC. Per istruzioni dettagliate sulla creazione di endpoint VPC per l’API dati, consulta [Creazione di un endpoint Amazon VPC per l’API dati di Amazon RDS (AWS PrivateLink)](data-api.vpc-endpoint.md).
Quando crei un endpoint VPC per il IPv6 supporto, assicurati che:
+ Il VPC e le sottoreti sono configurati per supportare IPv6
+ I gruppi di sicurezza consentono il IPv6 traffico sulle porte richieste (in genere 443 per HTTPS)
+ ACLs Le reti sono configurate per consentire il traffico IPv6
## Considerazioni sulla migrazione
Durante la migrazione agli IPv6 endpoint, considera quanto segue:
+ **Migrazione graduale**: è possibile migrare le applicazioni gradualmente aggiornando l'endpoint URLs un'applicazione alla volta.
+ **Compatibilità di rete**: assicuratevi che l'infrastruttura di rete supporti IPv6 prima della migrazione.
+ **Politiche di sicurezza**: aggiorna le regole del gruppo di sicurezza e la rete ACLs per consentire IPv6 il traffico, se necessario.
+ **Monitoraggio**: aggiorna le configurazioni di monitoraggio e registrazione per gestire gli indirizzi. IPv6
**Nota**
**Indirizzi di connessione al database**: quando si utilizzano gli IPv6 endpoint for Data API, le connessioni al database e i registri del database sottostanti continueranno a mostrare gli indirizzi. IPv4 Si tratta di un comportamento previsto e non influisce sulla funzionalità delle applicazioni IPv6 abilitate.
## Risoluzione dei problemi IPv6 di connessione
Se riscontri problemi di IPv6 connettività, controlla quanto segue:
Configurazione della rete
Verifica che la rete supporti IPv6 e che il IPv6 routing sia configurato correttamente.
Risoluzione DNS
Verifica che il risolutore DNS sia in grado di risolvere i record AAAA per gli endpoint dual stack.
Gruppi di sicurezza
Aggiorna le regole del gruppo di sicurezza per consentire il IPv6 traffico sulle porte richieste (in genere 443 per HTTPS).
Librerie client
Verifica che le librerie dei client HTTP IPv6 supportino la connettività dual-stack.
# Limitazioni dell’API dati di Amazon RDS
L’API dati di RDS presenta le seguenti limitazioni:
+ È possibile eseguire query dell’API dati solo sulle istanze di scrittura di un cluster di database. Tuttavia, le istanze di scrittura possono accettare sia query di scrittura che di lettura.
+ Con i database globali Aurora, è possibile abilitare l’API dati sia sul cluster di database primario che su quello secondario. Tuttavia, un cluster secondario non dispone di un’istanza di scrittura finché non viene promosso a primario. L’API dati richiede l’accesso all’istanza di scrittura per l’elaborazione delle query, anche per le query di sola lettura. Di conseguenza, le query di lettura e scrittura inviate al cluster secondario non riescono finché questo non dispone di un’istanza di scrittura. Una volta che il cluster secondario viene promosso e dispone di un’istanza di scrittura, le query dell’API dati su tale istanza database vengono eseguite correttamente.
+ L’API dati non è supportata sulle classi di istanza database T.
+ Per i cluster di database Aurora Serverless v2 e con provisioning, l’API dati di RDS non supporta alcuni tipi di dati. Per l’elenco dei tipi supportati, consulta [Confronto dei comportamenti delle API dati di Amazon RDS per i cluster Aurora Serverless v2 e con provisioning con i cluster Aurora Serverless v1](data-api.differences.md).
+ Per i database Aurora PostgreSQL versione 14 e successive, l’API dati supporta solo `scram-sha-256` per la crittografia delle password.
+ 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.
+ Il limite delle dimensioni dell'API dati è 64 KB per riga nel set di risultati restituito dal database. Assicurati che ogni riga di un set di risultati non superi i 64 KB.
# Confronto dei comportamenti delle API dati di Amazon RDS per i cluster Aurora Serverless v2 e con provisioning con i cluster Aurora Serverless v1
I miglioramenti più recenti apportati alle API dati di Amazon RDS rendono le API dati disponibili per i cluster che utilizzano versioni recenti dei motori PostgreSQL o MySQL. Questi cluster possono essere configurati per utilizzare Aurora Serverless v2 oppure classi di istanza con provisioning, come `db.r6g` o `db.r6i`.
Le sezioni seguenti descrivono le differenze delle API dati di Amazon RDS tra cluster Aurora Serverless v2 e cluster di database con provisioning e cluster di database Aurora Serverless v1. Aurora Serverless v1 I cluster di database utilizzano la modalità motore `serverless`. I cluster di database con provisioning utilizzano la modalità motore `provisioned`. Un cluster di database Aurora Serverless v2 utilizza anch’esso la modalità motore `provisioned` e contiene una o più istanze database Aurora Serverless v2 con la classe di istanza `db.serverless`.
## Numero massimo di richieste al secondo
**Aurora Serverless v1**
Le API dati possono eseguire fino a 1.000 richieste al secondo.
**Aurora Serverless v2**
Le API dati possono eseguire un numero illimitato di richieste al secondo.
## Abilitazione o disabilitazione dell’API dati di Amazon RDS su un database esistente
**Aurora Serverless v1**
+ **Con l’API Amazon RDS**: utilizza l’operazione `ModifyCluster` e specifica `True` o `False`, a seconda dei casi, per il parametro `EnableHttpEndpoint`.
+ **Con la AWS CLI**: utilizza l’operazione `modify-db-cluster` con l’opzione `--enable-http-endpoint` o `--no-enable-http-endpoint`, a seconda dei casi.
**Aurora Serverless v2**
+ **Con l’API Amazon RDS**: utilizza le operazioni `EnableHttpEndpoint` e `DisableHttpEndpoint`.
+ **Con la AWS CLI**: utilizza le operazioni `enable-http-endpoint` e `disable-http-endpoint`.
## Eventi CloudTrail
**Aurora Serverless v1**
Gli eventi derivanti dalle chiamate API dati sono eventi di gestione. Questi eventi vengono automaticamente inclusi in un trail per impostazione predefinita. Per ulteriori informazioni, consulta [Esclusione degli eventi Data API da un AWS CloudTrail trail (Aurora Serverless v1solo)](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.excluding-cloudtrail-events).
**Aurora Serverless v2**
Gli eventi derivanti dalle chiamate API dati sono eventi di dati. Questi eventi vengono automaticamente esclusi da un trail per impostazione predefinita. Per ulteriori informazioni, consulta [Inclusione degli eventi Data API in un AWS CloudTrail percorso](logging-using-cloudtrail-data-api.md#logging-using-cloudtrail-data-api.including-cloudtrail-events).
## Supporto per istruzioni multiple
**Aurora Serverless v1**
+ Per Aurora MySQL, le istruzioni multiple non sono supportate.
+ Per Aurora PostgreSQL, le istruzioni multiple restituiscono solo la risposta della prima query.
**Aurora Serverless v2**
Le istruzioni multiple non sono supportate. Il tentativo di eseguire più istruzioni in una singola chiamata API restituisce `“An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.”`. Per eseguire più istruzioni, effettua chiamate API `ExecuteStatement` separate oppure utilizza `BatchExecuteStatement` per l’elaborazione in batch.
L’esempio seguente mostra il messaggio di errore risultante da una chiamata API che tenta di eseguire più istruzioni.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table; Select * FROM next_table;
"An error occurred (ValidationException) when calling the ExecuteStatement operation: Multistatements aren't supported.
```
L’esempio seguente mostra l’esecuzione di più istruzioni tramite chiamate API `ExecuteStatement` separate.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table;"
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM next_table;"
```
## Richieste simultanee per lo stesso ID transazione
**Aurora Serverless v1**
Le richieste successive attendono fino al completamento della richiesta corrente. L’applicazione deve gestire gli errori di timeout se il periodo di attesa è troppo lungo.
**Aurora Serverless v2**
Quando l’API dati riceve più richieste con lo stesso ID transazione, restituisce immediatamente questo errore:
`DatabaseErrorException: Transaction is still running a query`
Questo errore si verifica in due situazioni:
+ L’applicazione effettua richieste asincrone (ad esempio con promesse JavaScript) utilizzando lo stesso ID transazione.
+ Una richiesta precedente con tale ID transazione è ancora in elaborazione.
L’esempio seguente mostra tutte le richieste eseguite in parallelo con `promise.all()`.
```
const api_calls = [];
for (let i = 0; i < 10; i++) {
api_calls.push(
client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
)
);
}
await Promise.all(api_calls);
```
Per risolvere questo errore, attendi il completamento della richiesta corrente prima di inviare un’altra richiesta con lo stesso ID transazione o rimuovi l’ID transazione per consentire le richieste parallele.
L’esempio seguente mostra una chiamata API che utilizza l’esecuzione sequenziale con lo stesso ID transazione.
```
for (let i = 0; i < 10; i++) {
await client.send(
new ExecuteStatementCommand({
...params,
sql: `insert into table_name values (i);`,
transactionId
})
).promise()
);
}
```
## Comportamento di BatchExecuteStatement
Per ulteriori informazioni su `BatchExecuteStatement`, consulta [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html).
**Aurora Serverless v1**
L’oggetto dei campi generati nel risultato dell’aggiornamento include i valori inseriti.
**Aurora Serverless v2**
+ Per Aurora MySQL, l’oggetto campi generati nel risultato dell’aggiornamento include i valori inseriti.
+ Per Aurora PostgreSQL, l’oggetto campi generati è vuoto.
## Comportamento di ExecuteSQL
Per ulteriori informazioni su `ExecuteSQL`, consulta [ExecuteSQL](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteSql.html).
**Aurora Serverless v1**
L’operazione `ExecuteSQL` è obsoleta.
**Aurora Serverless v2**
L’operazione `ExecuteSQL` non è supportata.
## Comportamento di ExecuteStatement
Per ulteriori informazioni su `ExecuteStatement`, consulta [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html).
**Aurora Serverless v1**
Il parametro `ExecuteStatement` supporta lo strumento di recupero di colonne di array multidimensionali e di tutti i tipi di dati avanzati.
**Aurora Serverless v2**
Il parametro `ExecuteStatement` non supporta di colonne di array multidimensionali. Non supporta inoltre alcuni tipi di dati PostgreSQL, inclusi i tipi geometrici e monetari. Quando l’API dati rileva un tipo di dato non supportato, restituisce l’errore: `UnsupportedResultException: The result contains the unsupported data type data_type`.
Per risolvere il problema, esegui il casting del tipo di dati non supportato su `TEXT`. L’esempio seguente mostra come eseguire il casting di un tipo di dati non supportato su `TEXT`.
```
SELECT custom_type::TEXT FROM my_table;--
ORSELECT CAST(custom_type AS TEXT) FROM my_table;
```
Per un elenco dei tipi di dati supportati per ciascun motore di database Aurora, consulta il [riferimento alle operazioni dell’API dati](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/data-api.html#data-api-operations).
## Comportamento del parametro Schema
**Aurora Serverless v1**
Il parametro `Schema` non è supportato. Quando includi il parametro `Schema` in una chiamata API, l’API dati ignora il parametro.
**Aurora Serverless v2**
Il parametro `Schema` è obsoleto. Quando includi il parametro `Schema` in una chiamata API, l’API dati restituisce l’errore: `ValidationException: The schema parameter isn't supported`. L’esempio seguente mostra una chiamata API dati che restituisce l’errore `ValidationException`.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--schema "your_schema" \
--sql "SELECT * FROM your_table LIMIT 10"
```
Per risolvere questo problema, rimuovi il parametro `Schema` dalla chiamata API.
L’esempio seguente mostra una chiamata API dati con il parametro `Schema` rimosso.
```
aws rds-data execute-statement \
--resource-arn "arn:aws:rds:region:account:cluster:cluster-name" \
--secret-arn "arn:aws:secretsmanager:region:account:secret:secret-name" \
--database "your_database" \
--sql "SELECT * FROM your_table LIMIT 10"
```
# Autorizzazione di accesso all’API dati di Amazon RDS
Gli utenti possono invocare le operazioni dell’API dati di Amazon RDS (API dati) 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. Gestione dei segreti AWS Gli utenti devono utilizzare Secrets Manager per archiviare i segreti che possono utilizzare nelle loro chiamate all’API dati. Utilizzare segreti significa che gli utenti non devono includere le credenziali del database per le risorse target nelle chiamate all’API dati. L’API dati chiama in modo trasparente Secrets Manager, che consente (o nega) la richiesta dell’utente per il segreto. Per informazioni sulla configurazione di segreti da utilizzare con l’API dati, consulta [Archiviazione delle credenziali del database in Gestione dei segreti AWS](#data-api.secrets).
La policy `AmazonRDSDataFullAccess` fornisce l’accesso completo (tramite l’API dati) alle risorse. Puoi restringere l'ambito definendo le tue policy che specificano l'Amazon Resource Name (ARN) di una risorsa.
Ad esempio, la policy seguente mostra un esempio delle autorizzazioni minime richieste per un utente per accedere all’API dati per il cluster di database identificato dal relativo ARN. La policy include le autorizzazioni necessarie per accedere Secrets Manager e ottenere l'autorizzazione all'istanza DB per l'utente.
------
#### [ JSON ]
****
```
{
"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 (\$1).
## Utilizzo dell'autorizzazione basata su tag
L’API dati di RDS (API dati) e Secrets Manager supportano entrambi l’autorizzazione basata su tag. I*tag* sono coppie chiave-valore che etichettano una risorsa, ad esempio un cluster RDS, con un valore stringa aggiuntivo, ad esempio:
+ `environment:production`
+ `environment:development`
È 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](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/USER_Tagging.html). È 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 l’API dati, la richiesta viene inviata al servizio. L’API dati verifica innanzitutto che l’ARN del cluster passato nella richiesta sia contrassegnato 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.
------
#### [ JSON ]
****
```
{
"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 operazioni separate per `rds-data` e `secretsmanager` per l’API dati 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](https://docs.aws.amazon.com/secretsmanager/latest/userguide/auth-and-access_identity-based-policies.html#permissions_grant-limited-condition).
Nell'elemento "Condizione" delle policy, è possibile scegliere le chiavi tag tra le seguenti:
+ `aws:TagKeys`
+ `aws:ResourceTag/${TagKey}`
Per ulteriori informazioni sui tag delle risorse e su come utilizzarli`aws:TagKeys`, consulta [Controllo dell'accesso alle AWS risorse tramite i tag delle risorse](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_tags.html#access_tags_control-tag-keys).
**Nota**
Sia Data API che Gestione dei segreti AWS autorizzano gli utenti. Se non si dispone delle autorizzazioni per tutte le azioni definite in una policy, viene visualizzato un errore `AccessDeniedException`.
## Archiviazione delle credenziali del database in Gestione dei segreti AWS
Quando chiami l’API dati di Amazon RDS, passi le credenziali per il cluster di database Aurora usando 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 archiviare le credenziali del cluster database in un segreto**
1. Utilizzare Secrets Manager per creare un segreto contenente le credenziali per il cluster DB Aurora.
Per le istruzioni, consulta [Creazione di un segreto del database](https://docs.aws.amazon.com/secretsmanager/latest/userguide/create_database_secret.html) nella *Guida per l'utente di Gestione dei segreti AWS *.
1. Usa la console Secrets Manager per visualizzare i dettagli del segreto che hai creato o esegui il `aws secretsmanager describe-secret` AWS CLI comando.
Prendere nota del nome e dell'ARN del segreto, poiché possono essere utilizzati nelle chiamate all’API dati.
Per ulteriori informazioni relative all'utilizzo di Secrets Manager, consulta la [Guida per l'utente di AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html).
Per informazioni su come Amazon Aurora gestisce la gestione delle identità e degli accessi, consulta [Come funziona Amazon Aurora con IAM](https://docs.aws.amazon.com/AmazonRDS/latest/AuroraUserGuide/security_iam_service-with-iam.html).
Per informazioni sulla creazione di una policy IAM, consulta [Creazione di policy IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html) 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](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html) nella *Guida per l'utente di IAM*.
# Abilitazione dell’API dati di Amazon RDS
Per utilizzare l’API dati di Amazon RDS (API dati), è necessario abilitarla per il cluster di database Aurora. Puoi abilitare l’API dati durante la creazione o la modifica del cluster di database.
**Nota**
La disponibilità dell'API Data per il cluster dipende dalla versione di Aurora, dal motore di database e AWS dalla regione in uso. Per le versioni meno recenti di Aurora, l’API dati funziona solo con i cluster Aurora Serverless v1. Per le versioni più recenti di Aurora, l’API dati è compatibile con i cluster che utilizzano sia istanze con provisioning sia istanze Aurora Serverless v2. Per verificare se il cluster può utilizzare l’API dati, consulta [Regioni e motori di database Aurora supportati per l’API dati RDS](Concepts.Aurora_Fea_Regions_DB-eng.Feature.Data_API.md).
**Topics**
+ [
## Abilitazione dell’API dati di RDS durante la creazione di un database
](#data-api.enabling.creating)
+ [
## Abilitazione dell’API dati RDS su un database esistente
](#data-api.enabling.modifying)
## Abilitazione dell’API dati di RDS durante la creazione di un database
Durante la creazione di un database che supporta l’API dati RDS (API dati), puoi abilitare questa funzionalità. Le procedure seguenti descrivono come eseguire questa operazione quando si utilizza la Console di gestione AWS AWS CLI, la o l'API RDS.
### Console
Per abilitare l’API dati durante la creazione di un cluster di database, seleziona la casella di controllo **Abilita l’API dati in RDS** nella sezione **Connettività** della pagina **Crea database**, come mostrato nello screenshot seguente.
![\[La sezione Connettività nella pagina Crea database, con la casella di controllo Abilita l’API dati in RDS selezionata.\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-on-create.png)
Per istruzioni su come creare un cluster di database Aurora in grado di utilizzare l’API dati RDS, consulta:
+ Per i cluster Aurora Serverless v2 e con provisioning: [Creazione di un cluster database Amazon Aurora](Aurora.CreateInstance.md)
+ Per Aurora Serverless v1: [Creazione di un cluster di database Aurora Serverless v1](aurora-serverless.create.md)
### AWS CLI
Per abilitare Data API durante la creazione di un cluster Aurora DB, esegui il [create-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/create-db-cluster.html) AWS CLI comando con l'`--enable-http-endpoint`opzione.
Nell’esempio seguente viene creato un cluster di database Aurora PostgreSQL con l’API dati abilitata.
Per Linux, macOS o Unix:
```
aws rds create-db-cluster \
--db-cluster-identifier my_pg_cluster \
--engine aurora-postgresql \
--enable-http-endpoint
```
Per Windows:
```
aws rds create-db-cluster ^
--db-cluster-identifier my_pg_cluster ^
--engine aurora-postgresql ^
--enable-http-endpoint
```
### API RDS
Per abilitare Data API durante la creazione di un cluster Aurora DB, utilizza l'DBClusteroperazione [Create](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_CreateDBCluster.html) con il valore del `EnableHttpEndpoint` parametro impostato su. `true`
## Abilitazione dell’API dati RDS su un database esistente
Puoi modificare un cluster di database che supporta l’API dati RDS (API dati) per abilitare o disabilitare questa funzionalità.
**Topics**
+ [
### Abilitazione o disabilitazione dell’API dati (Aurora Serverless v2 e con provisioning)
](#data-api.enabling.modifying.all)
+ [
### Abilitazione o disabilitazione dell’API dati (solo Aurora Serverless v1)
](#data-api.enabling.modifying.sv1)
### Abilitazione o disabilitazione dell’API dati (Aurora Serverless v2 e con provisioning)
Utilizza le seguenti procedure per abilitare o disabilitare l’API dati su database Aurora Serverless v2 e con provisioning. Per abilitare o disabilitare l’API dati su database Aurora Serverless v1, utilizza le procedure descritte in [Abilitazione o disabilitazione dell’API dati (solo Aurora Serverless v1)](#data-api.enabling.modifying.sv1).
#### Console
Puoi abilitare o disabilitare l’API dati utilizzando la console RDS per un cluster di database che supporta questa funzionalità. A tale scopo, apri la pagina dei dettagli del cluster del database su cui vuoi agire e, nella scheda **Connettività e sicurezza**, vai alla sezione **API dati RDS**. Questa sezione mostra lo stato dell’API dati e consente di abilitarla o disabilitarla.
Lo screenshot seguente mostra che l’opzione **API dati RDS** non è abilitata.
![\[La sezione API dati RDS nella scheda Connettività e sicurezza della pagina dei dettagli di un cluster di database. Lo stato di API di dati viene visualizzato come disabilitato ed è presente il pulsante Abilita l’API dati in RDS.\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-enable-from-details.png)
#### AWS CLI
Per abilitare o disabilitare Data API su un database esistente, esegui il [disable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/disable-http-endpoint.html) AWS CLI comando [enable-http-endpoint](https://docs.aws.amazon.com/cli/latest/reference/rds/enable-http-endpoint.html)o e specifica l'ARN del tuo cluster DB.
L’esempio seguente mostra come abilitare l’API dati.
Per Linux, macOS o Unix:
```
aws rds enable-http-endpoint \
--resource-arn cluster_arn
```
Per Windows:
```
aws rds enable-http-endpoint ^
--resource-arn cluster_arn
```
#### API RDS
Per abilitare o disabilitare Data API su un database esistente, usa le [DisableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_DisableHttpEndpoint.html)operazioni [EnableHttpEndpoint](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_EnableHttpEndpoint.html)and.
### Abilitazione o disabilitazione dell’API dati (solo Aurora Serverless v1)
Utilizza le seguenti procedure per abilitare o disabilitare l’API dati su database Aurora Serverless v1 esistenti. Per abilitare o disabilitare l’API dati su database Aurora Serverless v2 e con provisioning, utilizza le procedure descritte in [Abilitazione o disabilitazione dell’API dati (Aurora Serverless v2 e con provisioning)](#data-api.enabling.modifying.all).
#### Console
Quando modifichi un cluster di database Aurora Serverless v1, puoi abilitare l’API dati nella sezione **Connettività** della console RDS.
Lo screenshot seguente mostra la funzione **API di dati** abilitata durante la modifica di un cluster di database Aurora.
![\[Nella sezione Connettività della pagina Modifica il cluster DB, la casella di controllo API di dati è selezionata.\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-modify-serverlessv1.png)
Per istruzioni su come modificare un cluster di database Aurora Serverless v1, consulta [Modifica di un cluster di database Aurora Serverless v1](aurora-serverless.modifying.md).
#### AWS CLI
Per abilitare o disabilitare Data API, esegui il [modify-db-cluster](https://docs.aws.amazon.com/cli/latest/reference/rds/modify-db-cluster.html) AWS CLI comando con `--enable-http-endpoint` o`--no-enable-http-endpoint`, a seconda dei casi.
L’esempio seguente mostra come abilitare l’API dati su `sample-cluster`.
Per Linux, macOS o Unix:
```
aws rds modify-db-cluster \
--db-cluster-identifier sample-cluster \
--enable-http-endpoint
```
Per Windows:
```
aws rds modify-db-cluster ^
--db-cluster-identifier sample-cluster ^
--enable-http-endpoint
```
#### API RDS
Per abilitare Data API, utilizza l'DBClusteroperazione [Modifica](https://docs.aws.amazon.com/AmazonRDS/latest/APIReference/API_ModifyDBCluster.html) e imposta il valore di su `true` o`false`, `EnableHttpEndpoint` a seconda dei casi.
# Creazione di un endpoint Amazon VPC per l’API dati di Amazon RDS (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)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) nella *Guida per l'utente di Amazon Virtual Private Cloud*.
Puoi chiamare l’API dati di RDS (API dati) utilizzando gli 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'istanza Amazon EC2 e l'API Data che li contiene. VPCs
Dopo aver creato l'endpoint Amazon VPC, puoi iniziare a utilizzarlo senza apportare modifiche al codice o alla configurazione nell'applicazione.
**Per creare un endpoint Amazon VPC per l’API dati**
1. Accedi Console di gestione AWS e apri la console Amazon VPC all'indirizzo. [https://console.aws.amazon.com/vpc/](https://console.aws.amazon.com/vpc/)
1. Scegliere **Endpoint**, quindi **Create Endpoint (Crea endpoint)**.
1. Nella pagina **Crea endpoint**, per **Categoria di servizio**, seleziona **Servizi AWS **. Per **Service Name (Nome servizio)**, scegliere **rds-data**.
![\[Creazione di un endpoint Amazon VPC per l’API dati\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-create-endpoint.png)
1. Per **VPC**, scegliere il VPC in cui creare l'endpoint.
Scegliere il VPC che contiene l'applicazione che effettua chiamate API dati.
1. Per le **sottoreti**, scegli la sottorete per ogni zona di disponibilità (AZ) utilizzata dal AWS servizio che esegue l'applicazione.
![\[Scegliere le sottoreti per l'endpoint Amazon VPC\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-subnets.png)
Per creare un endpoint Amazon VPC, specificare l'intervallo di indirizzi IP privati in cui l'endpoint sarà accessibile. A tale scopo, scegliere la sottorete per ogni zona di disponibilità. Questo ha l'effetto di limitare l'endpoint VPC all'intervallo di indirizzi IP privati specifico per ciascuna zona di disponibilità e crea inoltre un endpoint Amazon VPC in ogni zona di disponibilità.
1. Per **Enable DNS Name (Abilita nome DNS)**, seleziona **Enable for this endpoint (Abilita per questo endpoint)**.
![\[Abilita nome DNS per l'endpoint Amazon VPC\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-enable-endpoint.png)
Il DNS privato risolve il nome host DNS dell'API dati standard (`https://rds-data.region.amazonaws.com`) negli indirizzi IP privati associati al nome host DNS specifico dell'endpoint Amazon VPC. Di conseguenza, puoi accedere all'endpoint VPC Data API utilizzando AWS CLI o AWS SDKs senza apportare modifiche al codice o alla configurazione per aggiornare l'URL dell'endpoint di Data API.
1. Per **Security group (Gruppo di sicurezza)**, scegli un gruppo di sicurezza da associare all'endpoint Amazon VPC.
Scegli il gruppo di sicurezza che consente l'accesso al AWS servizio su cui è in esecuzione l'applicazione. Ad esempio, se un'istanza Amazon EC2 esegue l'applicazione, scegli il gruppo di sicurezza che consente l'accesso all'istanza Amazon EC2. Il gruppo di sicurezza consente di controllare il traffico verso l'endpoint Amazon VPC dalle risorse del VPC.
1. Per **Policy**, scegli **Full Access (Accesso completo)** per consentire a chiunque all'interno del Amazon VPC di accedere all'API dati tramite questo endpoint. Oppure scegli **Custom (Personalizzato)** per specificare una policy che limita l'accesso.
Se scegli **Personalizzato**, immetti la policy nello strumento di creazione delle policy.
1. Selezionare **Create endpoint (Crea endpoint)**.
Dopo aver creato l'endpoint, scegli il link in Console di gestione AWS per visualizzare i dettagli dell'endpoint.
![\[Collegamento ai dettagli dell'endpoint Amazon VPC\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-link-to-details.png)
La scheda **Details (Dettagli)** dell'endpoint mostra i nomi host DNS generati durante la creazione dell'endpoint Amazon VPC.
![\[Collegamento ai dettagli dell'endpoint Amazon VPC\]](http://docs.aws.amazon.com/it_it/AmazonRDS/latest/AuroraUserGuide/images/data-api-vpc-endpoint-dns-names.png)
È 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 dell’API dati, consulta [Chiamata dell’API dati di Amazon RDS](data-api.calling.md).
# 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));
}
```
# Utilizzo della libreria client Java per l’API dati
Puoi scaricare e utilizzare una libreria client Java per l’API dati di RDS (API dati). Questa è la libreria client Java fornisce un modo alternativo per utilizzare l’API dati. Utilizzando questa libreria, puoi mappare le tue classi lato client alle richieste e alle risposte dell’API dati. 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](https://github.com/awslabs/rds-data-api-client-library-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:
```
software.amazon.rdsdata
rds-data-api-client-library-java
2.0.0
```
Per la versione 1.x, che è compatibile con AWS SDK 1.x, utilizzate quanto segue:
```
software.amazon.rdsdata
rds-data-api-client-library-java
1.0.8
```
## 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 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);
```
**Nota**
La funzione `mapToList` converte un set di risultati SQL in un elenco di oggetti definito dall'utente. Non è supportato l'utilizzo dell'istruzione `.withFormatRecordsAs(RecordsFormatType.JSON)` in una chiamata `ExecuteStatement` per la libreria client Java, perché ha lo stesso scopo. Per ulteriori informazioni, consulta [Elaborazione dei risultati delle query dell’API dati di Amazon RDS in formato JSON](data-api-json.md).
# Elaborazione dei risultati delle query dell’API dati di Amazon RDS 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 opzionale`formatRecordsAs` 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.
**Topics**
+ [
## Recupero dei risultati delle query in formato JSON
](#data-api-json-querying)
+ [
## Mappatura dei tipi di dati
](#data-api-json-datatypes)
+ [
## Risoluzione dei problemi
](#data-api-json-troubleshooting)
+ [
## Esempi
](#data-api-json-examples)
## Recupero dei risultati delle query in formato JSON
Per ricevere il set di risultati come stringa JSON, includi `.withFormatRecordsAs(RecordsFormatType.JSON)` nella chiamata di `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.
****
| Tipo di dati JDBC | Tipo di dati JSON |
| --- | --- |
| `INTEGER`, `TINYINT`, `SMALLINT`, `BIGINT` | Numero di default. Stringa se l'opzione `LongReturnType` è impostata su `STRING`. |
| `FLOAT`, `REAL`, `DOUBLE` | Numero |
| `DECIMAL` | Stringa di default. Numero se l'opzione `DecimalReturnType` è impostata su `DOUBLE_OR_LONG`. |
| `STRING` | Stringa |
| `BOOLEAN`, `BIT` | Booleano |
| `BLOB`, `BINARY`, `VARBINARY`, `LONGVARBINARY` | Stringa nella codifica base64. |
| `CLOB` | Stringa |
| `ARRAY` | Array |
| `NULL` | `null` |
| Altri tipi (inclusi i tipi correlati a data e ora) | Stringa |
## 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:
+ Ridurre il numero di righe nel set dei risultati. A tale scopo, aggiungi una clausola `LIMIT`. Puoi dividere un set di risultati di grandi dimensioni in blocchi più piccoli inviando diverse query con clausole `LIMIT` e `OFFSET`.
Se il set di risultati include righe filtrate in base alla logica dell'applicazione, puoi rimuovere tali righe dal set di risultati aggiungendo ulteriori condizioni nella clausola `WHERE`.
+ Ridurre il numero di colonne nel set dei risultati. A tale scopo, rimuovi gli elementi dall'elenco di selezione della query.
+ Abbrevia le etichette delle colonne utilizzando gli alias di colonna nella query. Il nome di ogni colonna viene ripetuto nella stringa JSON per ogni riga del set di risultati. Pertanto, il risultato di una query con nomi di colonna lunghi e molte righe potrebbe superare il limite di dimensione. In particolare, utilizza alias di colonna per espressioni complicate al fine di evitare di ripetere l'intera espressione nella stringa JSON.
+ Sebbene con SQL sia possibile utilizzare alias di colonna per generare un set di risultati con più di una colonna con lo stesso nome, i nomi di chiave duplicati non sono consentiti in JSON. La Data API di RDS restituisce un errore se si richiede il set di risultati in formato JSON e più di una colonna ha lo stesso nome. Assicurati quindi che tutte le etichette delle colonne abbiano nomi univoci.
## 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. Sostituisci i valori appropriati per i parametri *databaseName*, *secretStoreArn* e *clusterArn*.
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>() {
});
}
```
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’esempio JavaScript seguente mostra come accedere ai valori dal risultato di una chiamata alla funzione JavaScript `executeStatement`. 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.
```
```
# Risoluzione dei problemi relativi all’API dati di Amazon RDS
Utilizza le seguenti sezioni, identificate dai messaggi di errore più comuni, per individuare e risolvere i problemi che possono verificarsi con l’API dati di Amazon RDS (API dati).
**Topics**
+ [
## La transazione non è stata trovata
](#data-api.troubleshooting.tran-id-not-found)
+ [
## Il pacchetto per la query è troppo grande
](#data-api.troubleshooting.packet-too-large)
+ [
## La risposta del database è andata oltre il limite delle dimensioni
](#data-api.troubleshooting.response-size-too-large)
+ [
## HttpEndpoint non è abilitato per il cluster
](#data-api.troubleshooting.http-endpoint-not-enabled)
+ [
## DatabaseErrorException: Transaction sta ancora eseguendo una query
](#data-api.troubleshooting.txn-concurrent-requests-rejected)
+ [
## Eccezione per risultato non supportato
](#data-api.troubleshooting.unsupported-result)
+ [
## Le istruzioni multiple non sono supportate
](#data-api.troubleshooting.multi-statements)
+ [
## Il parametro Schema non è supportato
](#data-api.troubleshooting.schema-parameter)
+ [
## IPv6 problemi di connettività
](#data-api.troubleshooting.ipv6-connectivity)
## La transazione 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:
+ La transazione potrebbe essere scaduta.
Assicurati che ogni chiamata della transazione venga eseguita entro tre minuti dalla precedente.
È anche possibile che l'ID di transazione specificato non sia stato creato da una [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)chiamata. Assicurati che la chiamata abbia un ID transazione valido.
+ Una chiamata precedente ha comportato l'interruzione della transazione.
La transazione era già terminata dalla chiamata `CommitTransaction` o `RollbackTransaction`.
+ La transazione è stata interrotta a causa di un errore di una chiamata precedente.
Verifica se le chiamate precedenti hanno generato eccezioni.
Per informazioni sull'esecuzione di transazioni, consulta [Chiamata dell’API dati di Amazon RDS](data-api.calling.md).
## 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 API dati restituiscano 1 MiB di dati o meno. Se devi restituire più di 1 MiB, è possibile utilizzare chiamate [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html) molteplici con la clausola `LIMIT` nella query.
Per ulteriori informazioni sulla clausola `LIMIT`, consulta [SELECT Syntax](https://dev.mysql.com/doc/refman/8.0/en/select.html) nella documentazione MySQL.
## HttpEndpoint non è abilitato per il cluster
Controlla le seguenti potenziali cause di questo problema:
+ Il cluster di database Aurora non supporta l’API dati. Per informazioni sui tipi di cluster di database supportati dall’API dati di RDS, consulta [Disponibilità per Regione e versione dell’API dati di Amazon RDS](data-api.regions.md).
+ L’API dati non è abilitata per il cluster di database Aurora. Per utilizzare l’API dati con un cluster di database Aurora, è necessario abilitarla per il cluster di database. Per informazioni su come abilitare l’API dati, consulta [Abilitazione dell’API dati di Amazon RDS](data-api.enabling.md).
+ Il cluster di database è stato rinominato dopo che l’API dati era stata abilitata. In tal caso, disattiva l’API dati per quel cluster e poi riabilitala.
+ L'ARN specificato non corrisponde esattamente all'ARN del cluster. Verifica che l'ARN restituito da un'altra origine o costruito dalla logica del programma corrisponda esattamente all'ARN del cluster. Ad esempio, assicurati che l'ARN utilizzato presenti il corretto formato maiuscolo/minuscolo per tutti i caratteri alfabetici.
## DatabaseErrorException: Transaction sta ancora eseguendo una query
Se l’applicazione invia una richiesta con un ID transazione e tale transazione sta attualmente elaborando un’altra richiesta, l’API dati 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 finché l’applicazione non riceve un errore di tipo diverso.
Questa condizione può verificarsi con l’API dati per le istanze Aurora Serverless v2 e con provisioning. Nell’API dati per Aurora Serverless v1, le richieste successive con lo stesso ID transazione attendono automaticamente che la richiesta precedente venga completata. Tuttavia, quel comportamento precedente poteva generare timeout se la richiesta precedente impiegava troppo tempo. Se stai trasferendo un’applicazione precedente che utilizza l’API dati e invia richieste concorrenti, modifica la logica di gestione delle eccezioni per gestire questo nuovo tipo di errore.
## Eccezione per risultato non supportato
L’API dati non supporta tutti i tipi di dati. Questo errore si verifica quando viene eseguita una query che restituisce un tipo di dato non supportato.
Per risolvere il problema, esegui il casting del tipo di dati non supportato su `TEXT`. Esempio:
```
SELECT custom_type::TEXT FROM my_table;
-- OR
SELECT CAST(custom_type AS TEXT) FROM my_table;
```
## Le istruzioni multiple non sono supportate
Le istruzioni multiple non sono supportate nell’API dati per Aurora Serverless v2 e per i cluster con provisioning. Il tentativo di eseguire più istruzioni in una singola chiamata API restituisce questo errore.
Per eseguire più istruzioni, utilizza chiamate API `ExecuteStatement` separate oppure utilizza l’API `BatchExecuteStatement` per l’elaborazione in batch.
## Il parametro Schema non è supportato
Aurora Serverless v1 ignora silenziosamente il parametro Schema. Tuttavia, Aurora Serverless v2 e i cluster con provisioning rifiutano esplicitamente le chiamate API che includono il parametro Schema.
Per risolvere questo problema, rimuovi il parametro Schema da tutte le chiamate API dati quando utilizzi Aurora Serverless v2 o cluster con provisioning.
## IPv6 problemi di connettività
Se riscontri problemi durante la connessione a Data API tramite IPv6 endpoint, verifica le seguenti cause potenziali:
+ **La rete non supporta IPv6**: verifica che l'infrastruttura di rete supporti IPv6 e che il IPv6 routing sia configurato correttamente.
+ **Problemi di risoluzione DNS**: che il risolutore DNS sia in grado di risolvere i record AAAA per gli endpoint dual stack (ad esempio `rds-data.us-east-1.api.aws`).
+ **Configurazione del gruppo di** sicurezza: aggiorna le regole del gruppo di sicurezza per consentire IPv6 il traffico sulla porta 443 (HTTPS). Aggiungi regole per i blocchi IPv6 CIDR (ad esempio, `::/0` per tutti gli IPv6 indirizzi).
+ **Configurazione ACL di rete**: assicurati che la rete ACLs consenta il IPv6 traffico sulle porte richieste.
+ **Compatibilità con le librerie client**: verifica che le librerie e i client HTTP AWS SDKs IPv6 supportino la connettività dual-stack.
+ **Configurazione degli endpoint VPC**: se in uso PrivateLink, assicurati che l'endpoint VPC sia configurato per il supporto IPv6 e che alle sottoreti associate siano assegnati blocchi CIDR. IPv6
Per risolvere i problemi di connettività: IPv6
1. Verifica la connettività utilizzando IPv4 -only endpoints (`.amazonaws.com`) per verificare che il problema sia specifico per. IPv6
1. Utilizza gli strumenti di diagnostica di rete per verificare la IPv6 connettività agli endpoint dual-stack.
1. Controlla CloudTrail i log per eventuali errori di autenticazione o autorizzazione quando usi gli endpoint. IPv6
1. Verifica che l'applicazione sia configurata correttamente per utilizzare il nuovo endpoint dual-stack. URLs
# Registrazione delle chiamate Amazon RDS Data API con AWS CloudTrail
RDS Data API (Data API) è integrato con AWS CloudTrail, un servizio che fornisce un registro delle azioni intraprese da un utente, ruolo o AWS servizio in Data API. CloudTrail acquisisce tutte le chiamate API per Data API come eventi, incluse le chiamate dalla console Amazon RDS e dalle chiamate di codice alle operazioni Data API. Se crei un trail, puoi abilitare la distribuzione continua di CloudTrail eventi a un bucket Amazon S3, inclusi gli eventi per Data API. Utilizzando i dati raccolti da CloudTrail, puoi determinare molte informazioni. Queste informazioni includono la richiesta che è stata fatta all’API dati, l'indirizzo IP da cui è stata effettuata la richiesta, chi ha effettuato la richiesta, quando è stata fatta e ulteriori dettagli.
Per ulteriori informazioni CloudTrail, consulta la [Guida AWS CloudTrail per l'utente](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
## Utilizzo delle informazioni dell'API Data in CloudTrail
CloudTrail è abilitato sul tuo AWS account al momento della creazione dell'account. Quando si verifica un'attività supportata (eventi di gestione) in Data API, tale attività viene registrata in un CloudTrail evento insieme ad altri eventi di AWS servizio nella **cronologia** degli eventi. Puoi visualizzare, cercare e scaricare gli eventi di gestione recenti nel tuo AWS account. Per ulteriori informazioni, consulta [Lavorare con la cronologia degli CloudTrail eventi](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/view-cloudtrail-events.html) nella *Guida AWS CloudTrail per l'utente.*
Per una registrazione continua degli eventi nel tuo AWS account, inclusi gli eventi per Data API, crea un percorso. Un *trail* consente di CloudTrail inviare file di log a un bucket Amazon S3. Per impostazione predefinita, quando crei un percorso nella console, il percorso si applica a tutte le AWS regioni. Il trail registra gli eventi di tutte le AWS regioni della AWS partizione e consegna i file di log al bucket Amazon S3 specificato. Inoltre, puoi configurare altri AWS servizi per analizzare ulteriormente e agire in base ai dati sugli eventi raccolti nei log. CloudTrail Per ulteriori informazioni, consulta gli argomenti seguenti nella *Guida per l'utente di AWS CloudTrail *:
+ [Panoramica della creazione di un percorso](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail.html)
+ [CloudTrail servizi e integrazioni supportati](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-aws-service-specific-topics.html#cloudtrail-aws-service-specific-topics-integrations)
+ [Configurazione delle notifiche Amazon SNS per CloudTrail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/getting_notifications_top_level.html)
+ [Ricezione di file di CloudTrail registro da più regioni](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/receive-cloudtrail-log-files-from-multiple-regions.html) e [ricezione di file di CloudTrail registro da](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-receive-logs-from-multiple-accounts.html) più account
Tutte le operazioni Data API vengono registrate CloudTrail e documentate nel riferimento dell'API del [https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/Welcome.html). Ad esempio, le chiamate alle `ExecuteStatement` operazioni`BatchExecuteStatement`, `BeginTransaction``CommitTransaction`, e generano voci nei file di registro. CloudTrail
Ogni evento o voce di log contiene informazioni sull’utente che ha generato la richiesta. Le informazioni di identità consentono di determinare quanto segue:
+ Se la richiesta è stata effettuata con credenziali utente o root.
+ Se la richiesta è stata effettuata con le credenziali di sicurezza temporanee per un ruolo o un utente federato.
+ Se la richiesta è stata effettuata da un altro AWS servizio.
Per ulteriori informazioni, consulta [Elemento CloudTrail userIdentity](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-event-reference-user-identity.html).
## Inclusione ed esclusione degli eventi Data API da un AWS CloudTrail percorso
La maggior parte degli utenti di Data API si affida agli eventi di un AWS CloudTrail trail per registrare le operazioni di Data API. I dati degli eventi non rivelano il nome del database, il nome dello schema o le istruzioni SQL nelle richieste all’API dati. Tuttavia, sapere quale utente ha effettuato un tipo di chiamata su uno specifico cluster di database in un determinato momento può aiutare a rilevare modelli di accesso anomali.
### Inclusione degli eventi Data API in un AWS CloudTrail percorso
*Per i database Aurora PostgreSQL Serverless v2 e con provisioning, le seguenti operazioni Data API vengono registrate come eventi di dati. AWS CloudTrail * [Gli eventi relativi ai dati sono operazioni API](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#logging-data-events) data-plane ad alto volume che non vengono registrate per impostazione predefinita. CloudTrail Per gli eventi di dati sono previsti costi aggiuntivi. [Per informazioni sui CloudTrail prezzi, consulta Prezzi.AWS CloudTrail](https://aws.amazon.com/cloudtrail/pricing/)
+ [BatchExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BatchExecuteStatement.html)
+ [BeginTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_BeginTransaction.html)
+ [CommitTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_CommitTransaction.html)
+ [ExecuteStatement](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_ExecuteStatement.html)
+ [RollbackTransaction](https://docs.aws.amazon.com/rdsdataservice/latest/APIReference/API_RollbackTransaction.html)
Puoi utilizzare la CloudTrail console o AWS CLI le operazioni CloudTrail API per registrare queste operazioni Data API. Nella CloudTrail console, scegli **RDS Data API - DB Cluster** per il tipo di evento Data. Per ulteriori informazioni, consulta [Registrazione di log degli eventi di dati con la Console di gestione AWS](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-data-events-with-cloudtrail.html#creating-data-event-selectors-with-the-AWS-CLI) nella *Guida per l’utente di AWS CloudTrail *.
Utilizzando AWS CLI, esegui il `aws cloudtrail put-event-selectors` comando per registrare queste operazioni Data API per il tuo percorso. Per registrare log di tutti gli eventi API dati nei cluster di database, specifica `AWS::RDS::DBCluster` per il tipo di risorsa. L’esempio seguente registra tutti gli eventi API dati nei cluster di database. Per ulteriori informazioni, consulta [Registrazione degli eventi di dati con AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-and-update-a-trail-by-using-the-aws-cli.html) nella *Guida per l’utente di AWS CloudTrail *.
```
aws cloudtrail put-event-selectors --trail-name trail_name --advanced-event-selectors \
'{
"Name": "RDS Data API Selector",
"FieldSelectors": [
{
"Field": "eventCategory",
"Equals": [
"Data"
]
},
{
"Field": "resources.type",
"Equals": [
"AWS::RDS::DBCluster"
]
}
]
}'
```
È possibile configurare selettori di eventi avanzati per filtrare ulteriormente i campi `readOnly`, `eventName,` e `resources.ARN`. Per ulteriori informazioni su questi campi, consultare [AdvancedFieldSelector](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_AdvancedFieldSelector.html).
### Esclusione degli eventi Data API da un AWS CloudTrail trail (Aurora Serverless v1solo)
Per Aurora Serverless v1, gli eventi API dati sono eventi di gestione. Per impostazione predefinita, tutti gli eventi Data API sono inclusi in un AWS CloudTrail trail. Tuttavia, poiché Data API può generare un gran numero di eventi, potresti voler escludere questi eventi dal tuo CloudTrail percorso. L’impostazione **Escludi eventi API dei dati Amazon RDS** esclude tutti gli eventi API dati dal trail. Non è possibile escludere eventi API dati specifici.
Per escludere gli eventi API dati da un percorso, procedi nel seguente modo:
+ Nella CloudTrail console, scegli l'impostazione **Exclude Amazon RDS Data API events** quando [crei un trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-create-a-trail-using-the-console-first-time.html) o [aggiorni un trail](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/cloudtrail-update-a-trail-console.html).
+ Nell' CloudTrail API, usa l'[PutEventSelectors](https://docs.aws.amazon.com/awscloudtrail/latest/APIReference/API_PutEventSelectors.html)operazione. Se si utilizzano selettori di eventi avanzati, è possibile escludere gli eventi API dati impostando il campo `eventSource` su un valore diverso da `rdsdata.amazonaws.com`. Se si utilizzano selettori di eventi di base, è possibile escludere gli eventi API dati impostando il valore dell’attributo `ExcludeManagementEventSources` su `rdsdata.amazonaws.com`. Per ulteriori informazioni, consulta [Registrazione degli eventi con AWS Command Line Interface](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html#creating-mgmt-event-selectors-with-the-AWS-CLI) nella *Guida per l’utente di AWS CloudTrail *.
**avvertimento**
L'esclusione degli eventi Data API da un CloudTrail registro può oscurare le azioni dell'API Data. Presta attenzione quando concedi alle entità principali l'autorizzazione `cloudtrail:PutEventSelectors` necessaria per eseguire questa operazione.
È possibile disattivare questa esclusione in qualsiasi momento modificando l'impostazione della console o i selettori di eventi per un percorso. Il percorso inizierà quindi a registrare gli eventi API dati. Tuttavia, non è possibile ripristinare gli eventi API dati che si sono verificati mentre era in atto l'esclusione.
Quando escludi gli eventi Data API utilizzando la console o l'API, anche l'operazione CloudTrail `PutEventSelectors` API risultante viene registrata nei tuoi CloudTrail log. Se gli eventi Data API non vengono visualizzati nei CloudTrail log, cerca un `PutEventSelectors` evento con l'`ExcludeManagementEventSources`attributo impostato su. `rdsdata.amazonaws.com`
Per ulteriori informazioni, consulta [Registrazione di eventi di gestione per i percorsi](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/logging-management-events-with-cloudtrail.html) nella *Guida per l'utente di AWS CloudTrail *.
## Informazioni sulle voci dei file di registro dell'API dei dati
Un *trail* è una configurazione che consente la distribuzione di eventi come file di log in un bucket Amazon S3 specificato dall'utente. CloudTrail i file di registro contengono una o più voci di registro. Un *evento* rappresenta una singola richiesta proveniente da qualsiasi fonte e include informazioni sull'azione richiesta, la data e l'ora dell'azione, i parametri della richiesta e così via. CloudTrail i file di registro non sono una traccia ordinata dello stack delle chiamate API pubbliche, quindi non vengono visualizzati in un ordine specifico.
**Aurora PostgreSQL Serverless v2 e database con provisioning**
L'esempio seguente mostra una voce di CloudTrail registro che dimostra il `ExecuteStatement` funzionamento per Aurora PostgreSQL Serverless v2 e i database con provisioning. Per questi database, tutti gli eventi API dati sono eventi di dati in cui l’origine dell’evento è **rdsdataapi.amazonaws.com** e il tipo di evento è **Rds Data Service**.
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdataapi.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "Rds Data Service",
"recipientAccountId": "123456789012"
}
```
**Aurora Serverless v1**
L'esempio seguente mostra come viene visualizzata la voce di registro dell'esempio precedente per. CloudTrail Aurora Serverless v1 InfattiAurora Serverless v1, tutti gli eventi sono eventi di gestione la cui origine è **rdsdata.amazonaws.com** e il tipo di evento è. **AwsApiCall**
```
{
"eventVersion": "1.05",
"userIdentity": {
"type": "IAMUser",
"principalId": "AKIAIOSFODNN7EXAMPLE",
"arn": "arn:aws:iam::123456789012:user/johndoe",
"accountId": "123456789012",
"accessKeyId": "AKIAI44QH8DHBEXAMPLE",
"userName": "johndoe"
},
"eventTime": "2019-12-18T00:49:34Z",
"eventSource": "rdsdata.amazonaws.com",
"eventName": "ExecuteStatement",
"awsRegion": "us-east-1",
"sourceIPAddress": "192.0.2.0",
"userAgent": "aws-cli/1.16.102 Python/3.7.2 Windows/10 botocore/1.12.92",
"requestParameters": {
"continueAfterTimeout": false,
"database": "**********",
"includeResultMetadata": false,
"parameters": [],
"resourceArn": "arn:aws:rds:us-east-1:123456789012:cluster:my-database-1",
"schema": "**********",
"secretArn": "arn:aws:secretsmanager:us-east-1:123456789012:secret:dataapisecret-ABC123",
"sql": "**********"
},
"responseElements": null,
"requestID": "6ba9a36e-b3aa-4ca8-9a2e-15a9eada988e",
"eventID": "a2c7a357-ee8e-4755-a0d0-aed11ed4253a",
"eventType": "AwsApiCall",
"recipientAccountId": "123456789012"
}
```
# Monitoraggio delle query dell’API dati RDS con Approfondimenti sulle prestazioni
Se il cluster Aurora esegue istanze Aurora Serverless v2 o con provisioning, è possibile utilizzare Approfondimenti sulle prestazioni con l’API dati RDS.
Per ulteriori informazioni su come utilizzare Approfondimenti sulle prestazioni con Aurora, consulta [Monitoraggio del carico DB con Performance Insights su Amazon Aurora](USER_PerfInsights.md).
## Come vengono rappresentate le query dell’API dati RDS in Approfondimenti sulle prestazioni
Con l’API dati, il cluster Aurora elabora le query in base alle chiamate API dati inviate dall’applicazione. L’API dati esegue anche alcune istruzioni SQL come parte del proprio funzionamento interno, come l’annullamento di query che superano la soglia di timeout. Entrambi i tipi di operazioni SQL sono mostrati nelle statistiche e nei grafici di Approfondimenti sulle prestazioni.
+ Per le query dell’API dati inviate a un cluster Aurora, il campo **Host** nella dashboard delle API è contrassegnato come **API dati RDS**. Per Aurora PostgreSQL, il campo **application\$1name** ha il valore `rds-data-api`. Cercare queste etichette quando si analizza il carico del database utilizzando **Host principali** o **Applicazioni principali** come dimensione.
+ Tutte le query interne eseguite dall’API dati per gestire aspetti del database, come il pool di connessioni e i timeout delle query, sono annotate con il prefisso **API dati RDS**. Esempio: `/* RDS Data API */ select * from my_table;` cerca questi prefissi quando si analizza il carico del database tramite **SQL principale** come dimensione. Le istruzioni sono annotate con un commento SQL di `/* RDS Data API */`.