Amazon Redshift non supporterà più la creazione di nuovi Python UDFs a partire dalla Patch 198. Python esistente UDFs continuerà a funzionare fino al 30 giugno 2026. Per ulteriori informazioni, consulta il [post del blog](https://aws.amazon.com/blogs/big-data/amazon-redshift-python-user-defined-functions-will-reach-end-of-support-after-june-30-2026/).
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à.
# Uso dell'API dati di Amazon Redshift
L’API dati Amazon Redshift semplifica l’accesso al data warehouse Amazon Redshift eliminando la necessità di gestire driver di database, connessioni, configurazioni di rete, buffering dei dati, credenziali e altro ancora. Puoi eseguire istruzioni SQL utilizzando le operazioni Data API con l' AWS SDK. Per ulteriori informazioni sulle operazioni dell’API dati, consulta la [documentazione di riferimento dell’API dati Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
L'API dati non richiede una connessione permanente al database. Fornisce invece un endpoint HTTP sicuro e l'integrazione con. AWS SDKs Puoi usare l'endpoint per eseguire istruzioni SQL senza gestire connessioni. Le chiamate all'API dati sono asincrone. L'API Data può utilizzare credenziali archiviate nel database Gestione dei segreti AWS o credenziali temporanee del database. Non è necessario utilizzare alcuna password nelle chiamate API con entrambi i metodi di autorizzazione. Per ulteriori informazioni su Gestione dei segreti AWS, consulta [What](https://docs.aws.amazon.com/secretsmanager/latest/userguide/intro.html) Is? Gestione dei segreti AWS nella *Guida Gestione dei segreti AWS per l'utente*. È possibile utilizzare anche AWS IAM Identity Center per l'autorizzazione.
Con l'API Data, puoi accedere in modo programmatico ai dati di Amazon Redshift con applicazioni basate su servizi Web, AWS Lambda SageMaker tra cui notebook Amazon AI e. AWS Cloud9 Per ulteriori informazioni su queste applicazioni [AWS Lambda](https://aws.amazon.com/lambda/), consulta [Amazon SageMaker AI](https://aws.amazon.com/sagemaker/) e [AWS Cloud9](https://aws.amazon.com/cloud9/).
Per ulteriori informazioni sull’API dati, consulta [Get started with the Amazon Redshift Data API](https://aws.amazon.com/blogs/big-data/get-started-with-the-amazon-redshift-data-api/) in *AWS Big Data Blog*.
## Operazioni con l'API dati Amazon Redshift
Prima di utilizzare l'API dati Amazon Redshift, verificare quanto riportato di seguito:
1. Determinare se l'utente, come chiamante dell'API dati, è autorizzato. Per ulteriori informazioni sull'autorizzazione , consultare [Autorizzazione di accesso all'API dati di Amazon Redshift](data-api-access.md).
1. Determina se prevedi di chiamare l’API dati con credenziali di autenticazione da Secrets Manager o con credenziali temporanee oppure utilizza AWS IAM Identity Center. Per ulteriori informazioni, consulta [Scelta delle credenziali di autenticazione del database quando si richiama l'API dati di Amazon Redshift](#data-api-calling-considerations-authentication).
1. Se si utilizza Secrets Manager impostare un segreto per le credenziali di autenticazione. Per ulteriori informazioni, consultare [Archiviazione delle credenziali del database in Gestione dei segreti AWS](data-api-secrets.md).
1. Esaminare le considerazioni e le limitazioni quando si chiama l'API dati. Per ulteriori informazioni, consulta [Considerazioni da fare durante la chiamata all'API dati di Amazon Redshift](#data-api-calling-considerations).
1. Chiama l'API Data da AWS Command Line Interface (AWS CLI), dal tuo codice o utilizzando l'editor di query nella console Amazon Redshift. Per esempi di chiamata dalla AWS CLI, consultare [Chiamata dell'API dati](data-api-calling.md).
## Considerazioni da fare durante la chiamata all'API dati di Amazon Redshift
Considerare quanto riportato di seguito quando si effettua la chiamata dell'API dati:
+ L'API dati di Amazon Redshift può accedere ai database nei cluster sottoposti a provisioning di Amazon Redshift e nei gruppi di lavoro Redshift serverless. Per un elenco delle aree Regioni AWS in cui è disponibile l'API Redshift Data, consulta gli endpoint elencati per [Redshift](https://docs.aws.amazon.com/general/latest/gr/redshift-service.html) Data API nel. *Riferimenti generali di Amazon Web Services*
+ La durata massima di una query è di 24 ore.
+ Il numero massimo di query (`STARTED`e `SUBMITTED` query) attive per cluster Amazon Redshift è 500.
+ La dimensione massima del risultato della query è 500 MB (dopo la compressione gzip). Se una chiamata restituisce più di 500 MB di dati di risposta, la chiamata viene interrotta.
+ Il tempo massimo di conservazione dei risultati delle query è 24 ore.
+ La dimensione massima dell'istruzione della query è 100 KB.
+ L'API dati è disponibile per eseguire query su cluster a nodo singolo e a più nodi dei seguenti tipi di nodo:
+ dc2.large
+ dc2.8xlarge
+ ra3.large
+ ra3.xlplus
+ ra3.4xlarge
+ ra3.16xlarge
+ Il cluster deve trovarsi in un Virtual Private Cloud (VPC) basato sul servizio Amazon VPC.
+ Per impostazione predefinita, gli utenti con lo stesso ruolo IAM del runner di un’operazione API `ExecuteStatement` o `BatchExecuteStatement` possono intervenire sulla stessa istruzione con le operazioni API `CancelStatement`, `DescribeStatement`, `GetStatementResult`, `GetStatementResultV2` e `ListStatements`. Per agire sulla stessa istruzione SQL di un altro utente, l'utente deve essere in grado di assumere il ruolo IAM dell'utente che ha eseguito l'istruzione SQL. Per ulteriori informazioni su come assumere un ruolo, consulta [Autorizzazione di accesso all'API dati di Amazon Redshift](data-api-access.md).
+ Le istruzioni SQL nel parametro `Sqls` dell'operazione API `BatchExecuteStatement` vengono eseguite come una singola transazione. Vengono eseguiti in serie nell'ordine dell'array. Le istruzioni SQL successive non vengono avviate fino al completamento dell'istruzione precedente nell'array. Se un'istruzione SQL ha esito negativo, dal momento che viene eseguita come un'unica transazione, viene eseguito il rollback di tutta l'operazione.
+ Il tempo massimo di conservazione per un token client utilizzato nell'operazione API `ExecuteStatement` o `BatchExecuteStatement` è di 8 ore.
+ Se i cluster forniti da Amazon Redshift e il gruppo di lavoro Redshift Serverless sono crittografati utilizzando una chiave gestita dal cliente, Redshift crea una concessione che consente all'API Redshift Data di utilizzare la chiave per le proprie operazioni. Per ulteriori informazioni, consulta [Utilizzo AWS KMS con l'API dati Amazon Redshift](data-api-kms.md).
+ Ogni API nell'API di dati Redshift ha una quota di transazioni al secondo prima della limitazione (della larghezza di banda della rete) delle richieste. Per la quota, consulta [Quote per l'API di dati Amazon Redshift](amazon-redshift-limits.md#data-api-quotas-account). Se la frequenza della richiesta supera la quota, viene restituito `ThrottlingException` con codice di stato HTTP 400. [https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html](https://docs.aws.amazon.com/sdkref/latest/guide/feature-retry-behavior.html) In alcuni casi, questa strategia viene implementata automaticamente per correggere gli errori di limitazione. AWS SDKs
**Nota**
Per impostazione predefinita AWS Step Functions, i nuovi tentativi non sono abilitati. Se devi chiamare un'API di dati Redshift in una macchina a stati Step Functions, includi il parametro di idempotenza `ClientToken` nella chiamata API di dati Redshift. Il valore di `ClientToken` deve persistere tra un tentativo e l'altro. Nel frammento di esempio seguente di una richiesta all'API `ExecuteStatement`, l'espressione `States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)` utilizza una funzione intrinseca per estrarre la parte UUID di `$$.Execution.Id`, che è univoca per ogni esecuzione della macchina a stati. Per ulteriori informazioni, consulta [Intrinsic functions](https://docs.aws.amazon.com/step-functions/latest/dg/amazon-states-language-intrinsic-functions.html) nella *Guida per sviluppatori di AWS Step Functions *.
```
{
"Database": "dev",
"Sql": "select 1;",
"ClusterIdentifier": "MyCluster",
"ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
}
```
## Scelta delle credenziali di autenticazione del database quando si richiama l'API dati di Amazon Redshift
Quando si chiama l'API dati, è possibile utilizzare uno dei seguenti metodi di autenticazione per alcune operazioni API. Ogni metodo richiede una diversa combinazione di parametri.
**AWS IAM Identity Center**
È possibile accedere all’API dati con un utente single sign-on registrato in AWS IAM Identity Center. Per ulteriori informazioni sulle fasi per configurare Centro identità IAM, consulta [Utilizzo dell’API dati con la propagazione affidabile delle identità](data-api-trusted-identity-propagation.md).
**Gestione dei segreti AWS**
Con questo metodo, fornisci un segreto memorizzato in Gestione dei segreti AWS cui ha `username` e`password`. `secret-arn` Il segreto specificato contiene le credenziali per la connessione al `database` specificato. Quando ci si connette a un cluster, si forniscono anche il nome del database; se si fornisce un identificatore del cluster (`dbClusterIdentifier`), questo deve corrispondere all'identificatore del cluster archiviato nel segreto. Quando ci si connette a un gruppo di lavoro serverless, si fornisce anche il nome del database. Per ulteriori informazioni, consulta [Archiviazione delle credenziali del database in Gestione dei segreti AWS](data-api-secrets.md).
Con questo metodo, puoi anche fornire un `region` valore che specifica Regione AWS dove si trovano i tuoi dati.
**Credenziali temporanee**
Con questo metodo, scegli una delle seguenti opzioni:
+ Quando ti connetti a un gruppo di lavoro serverless, specifica il nome del gruppo di lavoro e del database. Il nome utente del database deriva dall'identità IAM. Ad esempio, `arn:iam::123456789012:user:foo` ha il nome utente di database `IAM:foo`. Inoltre, è richiesta l'autorizzazione a richiamare l'operazione `redshift-serverless:GetCredentials`.
+ Quando ti connetti a un cluster come identità IAM, specifica l'identificatore del cluster e il nome del database. Il nome utente del database deriva dall'identità IAM. Ad esempio, `arn:iam::123456789012:user:foo` ha il nome utente di database `IAM:foo`. Inoltre, è richiesta l'autorizzazione a richiamare l'operazione `redshift:GetClusterCredentialsWithIAM`.
+ Quando ti connetti a un cluster come utente del database, specifica l'identificatore del cluster, il nome del database e il nome utente del database. Inoltre, è richiesta l'autorizzazione a richiamare l'operazione `redshift:GetClusterCredentials`. Per informazioni su come unirsi a gruppi di database durante la connessione con questo metodo, vedere [Unirsi a gruppi di database durante la connessione a un cluster](data-api-dbgroups.md).
Con questo metodo, puoi anche fornire un `region` valore che specifica Regione AWS dove si trovano i tuoi dati.
## Mappatura dei tipi di dati JDBC quando si chiama l'API dati di Amazon Redshift
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, SMALLINT, BIGINT` | `LONG` |
| `FLOAT, REAL, DOUBLE` | `DOUBLE` |
| `DECIMAL` | `STRING` |
| `BOOLEAN, BIT` | `BOOLEAN` |
| `BLOB, BINARY, LONGVARBINARY` | `BLOB` |
| `VARBINARY` | `STRING` |
| `CLOB` | `STRING` |
| Altri tipi (inclusi i tipi correlati a data e ora) | `STRING` |
I valori stringa vengono passati al database Amazon Redshift e convertiti implicitamente in un tipo di dati del database.
**Nota**
Attualmente, l'API Data non supporta matrici di identificatori univoci universali (). UUIDs
## Esecuzione di istruzioni SQL con parametri quando si chiama l'API dati di Amazon Redshift
È possibile controllare il testo SQL inviato al modulo di gestione di database chiamando l'operazione dell'API dati utilizzando i parametri per parti dell'istruzione SQL. I parametri specificati forniscono un modo flessibile per passare i parametri nel testo SQL senza codificarli. Aiutano a riutilizzare il testo SQL ed evitare problemi di SQL injection.
L'esempio seguente mostra i parametri denominati di un `parameters` campo di un `execute-statement` AWS CLI comando.
```
--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"
```
Considerare le informazioni seguenti durante l'utilizzo dei parametri specificati:
+ I parametri denominati possono essere utilizzati solo per sostituire i valori nelle istruzioni SQL.
+ È possibile sostituire i valori in un'istruzione INSERT, ad esempio`INSERT INTO mytable VALUES(:val1)`.
I parametri specificati possono essere in qualsiasi ordine e possono essere utilizzati più di una volta nel testo SQL. Nell'opzione dei parametri mostrata nell'esempio precedente, i valori `1` e `Seattle` vengono inseriti nelle colonne della tabella `id` e `address`. Nel testo SQL, specificare i parametri denominati come segue:
```
--sql "insert into mytable values (:id, :address)"
```
+ È possibile sostituire i valori in una clausola di condizioni, ad esempio `WHERE attr >= :val1`, `WHERE attr BETWEEN :val1 AND :val2` e `HAVING COUNT(attr) > :val`.
+ Non è possibile sostituire i nomi delle colonne in un'istruzione SQL, ad esempio `SELECT column-name`, `ORDER BY column-name` o `GROUP BY column-name`.
Ad esempio, l'istruzione SELECT seguente restituisce un errore con sintassi non valida.
```
--sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"
```
Se si descrive (operazione `describe-statement`) l'istruzione con l'errore di sintassi, il valore `QueryString` restituito non sostituisce il nome della colonna per il parametro (`"QueryString": "SELECT :colname, FROM event"`) e viene segnalato un errore (ERROR: syntax error at or near \$1"FROM\$1"\$1n Position: 12).
+ Non è possibile sostituire i nomi delle colonne in una funzione aggregata, ad esempio `COUNT(column-name)`, `AVG(column-name)` o `SUM(column-name)`.
+ Non è possibile sostituire i nomi delle colonne in una clausola JOIN.
+ Quando viene eseguito l'SQL, i dati vengono trasformati implicitamente in un tipo di dati. Per ulteriori informazioni sul casting del tipo di dati, consultare [Tipi di dati](https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html) nella *Guida per gli sviluppatori di database di Amazon Redshift*.
+ Non è possibile impostare un valore su NULL. L'API dati interpreta questo valore come la stringa letterale `NULL`. Nell'esempio seguente `id` viene sostituito con la stringa letterale `null`. Non il valore SQL NULL.
```
--parameters "[{\"name\": \"id\", \"value\": \"null\"}]"
```
+ Non è possibile impostare un valore con lunghezza zero. L'istruzione SQL dell'API dati non riesce. Nell'esempio seguente si prova a impostare `id` con un valore di lunghezza zero e ciò si traduce in un errore dell'istruzione SQL.
```
--parameters "[{\"name\": \"id\", \"value\": \"\"}]"
```
+ Non è possibile impostare un nome di tabella nell'istruzione SQL con un parametro. L'API dati segue la regola di `PreparedStatement` JDBC.
+ L'output dell'operazione `describe-statement` restituisce i parametri di query di un'istruzione SQL.
+ Solo l'operazione `execute-statement` supporta le istruzioni SQL con parametri.
## Esecuzione di istruzioni SQL con un token di idempotenza quando si chiama l'API dati di Amazon Redshift
Quando si effettua una richiesta API mutante, di solito restituisce un risultato prima del completamento dei flussi di lavoro asincroni dell'operazione. Le operazioni potrebbero inoltre scadere o riscontrare altri problemi relativi al server prima del completamento, anche se la richiesta ha già restituito un risultato. Ciò potrebbe rendere difficile determinare l'esito della richiesta e potrebbe comportare più tentativi per garantire che l'operazione venga completata correttamente. Tuttavia, se la richiesta originale e i tentativi successivi hanno esito positivo, l'operazione viene completata più volte, il che significa che potresti aggiornare più risorse del previsto.
L'*idempotenza* assicura che una richiesta API venga completata solo una volta. Quando si utilizza una richiesta idempotente, se la richiesta originale viene completata correttamente, tutti i tentativi successivi vengono completati correttamente senza alcuna azione aggiuntiva. Le operazioni delle API dei dati `ExecuteStatement` e `BatchExecuteStatement` hanno un parametro idempotente `ClientToken` opzionale. Il `ClientToken` scade dopo 8 ore.
**Importante**
Se chiami `ExecuteStatement` e esegui `BatchExecuteStatement` operazioni da un AWS SDK, questo genera automaticamente un token client da utilizzare in caso di nuovo tentativo. In questo caso, non è consigliabile utilizzare il parametro `client-token` con le operazioni `ExecuteStatement` e `BatchExecuteStatement`. Visualizza il CloudTrail registro per vedere il. `ClientToken` Per un esempio di CloudTrail registro, vedere[Esempi per l'API di dati di Amazon Redshift](logging-with-cloudtrail.md#data-api-cloudtrail).
Il `execute-statement` AWS CLI comando seguente illustra il `client-token` parametro opzionale per l'idempotenza.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
La tabella seguente mostra alcune risposte comuni che si potrebbero ricevere per richieste API idempotenti e fornisce consigli per effettuare nuovi tentativi.
| Risposta | Raccomandazione | Commenti |
| --- | --- | --- |
| 200 (OK) | Non riprovare | La richiesta originale è stata completata con successo. Qualsiasi tentativo successivo ottiene esito positivo. |
| Codici di risposta serie 400 | Non riprovare | La richiesta presenta uno dei problemi seguenti: [\[See the AWS documentation website for more details\]](http://docs.aws.amazon.com/it_it/redshift/latest/mgmt/data-api.html) Se la richiesta riguarda una risorsa che sta cambiando stato, un nuovo tentativo potrebbe avere esito positivo. |
| Codici di risposta serie 500 | Riprova | L'errore è causato da un problema AWS sul lato server ed è generalmente temporaneo. Ripeti la richiesta con una strategia di backoff appropriata. |
Per ulteriori informazioni sui codici di risposta di Amazon Redshift, consulta [Errori comuni](https://docs.aws.amazon.com/redshift/latest/APIReference/CommonErrors.html) nella *Documentazione di riferimento dell'API Amazon Redshift*.
## Esecuzione di istruzioni SQL con il riutilizzo della sessione quando chiami l’API dati Amazon Redshift
Quando effettui una richiesta API per eseguire un’istruzione SQL, la sessione in cui viene eseguita l’istruzione SQL viene in genere terminata al termine dell’istruzione SQL. Per mantenere la sessione attiva per un determinato numero di secondi, le operazioni `ExecuteStatement` e `BatchExecuteStatement` dell’API dati dispongono di un parametro `SessionKeepAliveSeconds` opzionale. Un campo di risposta `SessionId` contiene l’identità della sessione che può quindi essere utilizzata nelle operazioni `ExecuteStatement` e `BatchExecuteStatement` successive. Nelle chiamate successive puoi specificare un altro codice `SessionKeepAliveSeconds` per modificare il tempo di timeout di inattività. Se il codice `SessionKeepAliveSeconds` non viene modificato, l’impostazione iniziale del timeout di inattività rimane invariata. Durante il riutilizzo della sessione considera quanto segue:
+ Il valore massimo di `SessionKeepAliveSeconds` è 24 ore.
+ La sessione può durare al massimo 24 ore. Dopo 24 ore, la sessione viene chiusa forzatamente e le query in corso vengono terminate.
+ Il numero massimo di sessioni per cluster Amazon Redshift o gruppo di lavoro Redshift serverless è 500.
+ Puoi eseguire solo una query alla volta in una sessione. Devi attendere il completamento di una query prima di eseguire quella successiva nella stessa sessione. In altre parole non puoi eseguire query in parallelo in una sessione fornita.
+ L’API dati non può mettere in coda le query per una determinata sessione.
Per recuperare `SessionId` che viene utilizzato dalle chiamate alle operazioni `ExecuteStatement` e `BatchExecuteStatement`, chiama le operazioni `DescribeStatement` e `ListStatements`.
L’esempio seguente dimostra l’utilizzo dei parametri `SessionKeepAliveSeconds` e `SessionId` per mantenere attiva e riutilizzata una sessione. Innanzitutto, chiamate il `execute-statement` AWS CLI comando con il parametro opzionale `session-keep-alive-seconds` impostato su. `2`
```
aws redshift-data execute-statement
--session-keep-alive-seconds 2
--sql "select 1"
--database dev
--workgroup-name mywg
```
La risposta contiene l’identificatore della sessione.
```
{
"WorkgroupName": "mywg",
"CreatedAt": 1703022996.436,
"Database": "dev",
"DbUser": "awsuser",
"Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
"SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}
```
Quindi, chiamate il `execute-statement` AWS CLI comando con `SessionId` il risultato della prima chiamata. E, facoltativamente, specifica il parametro `session-keep-alive-seconds` impostato su `10` per modificare il valore del timeout di inattività.
```
aws redshift-data execute-statement
--sql "select 1"
--session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
--session-keep-alive-seconds 10
```
## Recupero dei risultati delle istruzioni SQL
Utilizzi diverse operazioni dell’API dati per recuperare i risultati SQL a seconda del formato dei risultati. Quando chiami le operazioni `ExecuteStatement` e `BatchExecuteStatement`, puoi specificare se i risultati sono formattati come JSON o CSV. Se non lo specifichi, il valore predefinito è JSON. Per recuperare i risultati JSON, utilizza l’operazione `GetStatementResult`. Per recuperare i risultati CSV, utilizza l’operazione `GetStatementResultV2`.
I risultati restituiti in formato JSON sono record che includono metadati su ogni colonna. Ogni record è in formato JSON. Ad esempio, la risposta di `GetStatementResult` è simile alla seguente:
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"longValue": 1
}
]
],
"TotalNumRows":
}
```
I risultati restituiti in formato CSV sono record che includono metadati su ogni colonna. I risultati vengono restituiti in blocchi da 1 MB, in cui ogni blocco può memorizzare un numero qualsiasi di righe in formato CSV. Ogni richiesta restituisce fino a 15 MB di risultati. Se i risultati sono superiori a 15 MB, viene restituito un token di pagina successiva per continuare a recuperare i risultati. Ad esempio, la risposta di `GetStatementResultV2` è simile alla seguente:
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "?column?",
"name": "?column?",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "",
"typeName": "int4",
"length": 0
}
],
"NextToken": "",
"Records": [
[
{
"CSVRecords":"1,2,3\r\n4,5,6\r\n7,8,9\rn, .... 1MB" // First 1MB Chunk
},
{
"CSVRecords":"1025,1026,1027\r\n1028,1029,1030\r\n....2MB" // Second 1MB chunk
}
...
]
],
"ResultFormat" : "CSV",
"TotalNumRows":
}
```
# Autorizzazione di accesso all'API dati di Amazon Redshift
Per accedere all'API dati, un utente deve essere autorizzato. È possibile consentire a un utente di accedere all'API dati aggiungendo una policy gestita, che è una policy AWS Identity and Access Management (IAM) predefinita, a tale utente. Come best practice, consigliamo di collegare le policy di autorizzazioni a un ruolo IAM, che quindi viene assegnato a utenti e gruppi secondo le necessità. Per ulteriori informazioni, consulta [Identity and access management in Amazon Redshift](https://docs.aws.amazon.com/redshift/latest/mgmt/redshift-iam-authentication-access-control.html). Per vedere le autorizzazioni consentite e negate dalle policy gestite, consulta la console IAM ([https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)).
# Configurazione delle autorizzazioni IAM
Amazon Redshift fornisce la policy gestita `AmazonRedshiftDataFullAccess`. Questa policy fornisce accesso completo alle operazioni API dati di Amazon Redshift. Questa policy consente inoltre l'accesso mirato a specifiche operazioni di Amazon Redshift Gestione dei segreti AWS e API IAM necessarie per autenticare e accedere a un cluster Amazon Redshift o a un gruppo di lavoro Serverless Redshift.
È possibile anche creare una policy IAM personalizzata che consente l'accesso a risorse specifiche. Per creare la policy, utilizzare la policy `AmazonRedshiftDataFullAccess` come modello di partenza. Dopo aver creato la policy, aggiungerla a ciascun utente che richiede l'accesso all'API dati.
Considera i seguenti requisiti della policy IAM associata all'utente:
+ Se la utilizzi Gestione dei segreti AWS per l'autenticazione, conferma che la policy consenta l'utilizzo dell'`secretsmanager:GetSecretValue`azione per recuperare il segreto etichettato con la chiave. `RedshiftDataFullAccess`
+ Se per l'autenticazione in un cluster vengono utilizzate credenziali temporanee, confermare che la policy consente l'uso dell'operazione `redshift:GetClusterCredentials` al nome utente del database `redshift_data_api_user` per qualsiasi database nel cluster. Questo nome utente deve essere già stato creato nel database.
+ Se utilizzi credenziali temporanee per eseguire l'autenticazione in un gruppo di lavoro serverless, verifica che la policy consenta l'uso dell'operazione `redshift-serverless:GetCredentials` per richiamare il gruppo di lavoro taggato con la chiave `RedshiftDataFullAccess`. L'utente del database viene mappato 1:1 all'identità di origine AWS Identity and Access Management (IAM). Ad esempio, l'utente sample\$1user è mappato all'utente del database `IAM:sample_user` e il ruolo IAM sample\$1role è mappato a `IAMR:sample_role`. Per ulteriori informazioni sulle diverse identità IAM, consulta [Identità IAM (utenti, gruppi di utenti e ruoli)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id.html) nella Guida per l'utente IAM.
+ L’azione IAM `redshift-data:GetStatementResult` consente l’accesso a entrambe le operazioni API `GetStatementResult` e `GetStatementResultV2`.
I seguenti collegamenti forniscono ulteriori informazioni sulla Guida per AWS Identity and Access Management l'*utente IAM*.
+ Per ulteriori informazioni sulla creazione dei ruoli IAM, consultare [Creazione di ruoli IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create.html).
+ Per informazioni sulla creazione di una policy IAM, consultare [Creazione di policy IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_create.html).
+ Per informazioni sull'aggiunta di una policy IAM a un utente, consultare [Aggiunta e rimozione di autorizzazioni per identità IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/access_policies_manage-attach-detach.html).
## Esecuzione di una query su un cluster di proprietà di un altro account
Per eseguire una query su un cluster di proprietà di un altro account, l'account proprietario deve fornire un ruolo IAM che l'API dati può assumere nell'account chiamante. Si supponga, ad esempio, che l'Account B sia proprietario di un cluster a cui l'Account A deve accedere. L'account B può allegare la policy AWS gestita `AmazonRedshiftDataFullAccess` al ruolo IAM dell'account B. Quindi l'Account B considera attendibile l'Account A utilizzando una policy di attendibilità come la seguente: ``
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": [
"arn:aws:iam::111122223333:role/someRoleA"
]
},
"Action": "sts:AssumeRole"
}
]
}
```
------
Infine, il ruolo IAM dell'Account A deve essere in grado di assumere il ruolo IAM dell'Account B.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": {
"Effect": "Allow",
"Action": "sts:AssumeRole",
"Resource": "arn:aws:iam::111122223333:role/someRoleB"
}
}
```
------
## Specificare un ruolo IAM che limiti le risorse ai gruppi di lavoro Serverless Redshift e ai cluster Amazon Redshift in un Account AWS
Puoi specificare la risorsa ARNs nella tua policy basata sull'identità per controllare l'accesso ai gruppi di lavoro Serverless Redshift e ai cluster Amazon Redshift in un unico. Account AWS Questo esempio mostra come creare una policy che consente l’accesso all’API dati solo per il gruppo di lavoro e i cluster nell’ Account AWS specificato.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*"
},
{
"Effect": "Allow",
"Action": "redshift-data:*",
"Resource": [
"arn:aws:redshift:us-east-1:111122223333:workgroup/*",
"arn:aws:redshift:us-east-1:111122223333:cluster:*"
]
}
]
}
```
------
## Configurare una policy IAM che limiti l’accesso alle informazioni sull’istruzione SQL solo al proprietario dell’istruzione
Per impostazione predefinita, l’API dati di Amazon Redshift considera il ruolo IAM utilizzato durante la chiamata di `ExecuteStatement` e `BatchExecuteStatement` come proprietario dell’istruzione SQL. Chiunque sia autorizzato ad assumere il ruolo è in grado di accedere alle informazioni sull’istruzione SQL, compresi i relativi risultati. Per limitare l’accesso alle informazioni sull’istruzione SQL a una sessione di ruolo IAM con un particolare proprietario, aggiungi la condizione `redshift-data:statement-owner-iam-userid: "${aws:userid}"`. La seguente policy IAM limita l’accesso.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:CancelStatement",
"redshift-data:DescribeStatement",
"redshift-data:GetStatementResult",
"redshift-data:ListStatements"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:statement-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Puoi utilizzare la condizione `statement-owner-iam-userid` con `CancelStatement`, `DescribeStatement`, `GetStatementResult` e `ListStatements`. Per ulteriori informazioni, consulta [Azioni definite dall’API dati Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
## Configurare una policy IAM che limiti l’accesso ai risultati SQL solo al proprietario della sessione
Per impostazione predefinita, l’API dati di Amazon Redshift considera il ruolo IAM utilizzato durante la chiamata di `ExecuteStatement` e `BatchExecuteStatement` come proprietario della sessione del database che esegue l’istruzione SQL. Chiunque sia autorizzato ad assumere il ruolo è in grado di inviare domande alla sessione del database. Per limitare l’accesso alla sessione a una sessione come ruolo IAM con un particolare proprietario, aggiungi la condizione ` redshift-data:session-owner-iam-userid: "${aws:userid}"`. La seguente policy IAM limita l’accesso.
La seguente policy IAM consente solo al proprietario della sessione di ottenere i risultati dell’istruzione. La condizione `session-owner-iam-userid` viene utilizzata per limitare l’accesso alle risorse al valore specificato `userid`.
------
#### [ JSON ]
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"redshift-data:ExecuteStatement",
"redshift-data:BatchExecuteStatement"
],
"Resource": "*",
"Condition": {
"StringEquals": {
"redshift-data:session-owner-iam-userid": "${aws:userid}"
}
}
}
]
}
```
------
Puoi utilizzare la condizione `session-owner-iam-userid` con `ExecuteStatement` e `BatchExecuteStatement`. Per ulteriori informazioni, consulta [Azioni definite dall’API dati Amazon Redshift](https://docs.aws.amazon.com/service-authorization/latest/reference/list_amazonredshiftdataapi.html#amazonredshiftdataapi-redshift-data_statement-owner-iam-userid).
# Archiviazione delle credenziali del database in Gestione dei segreti AWS
Quando si richiama l'API dati, è possibile passare le credenziali per il cluster o il gruppo di lavoro serverless utilizzando un secreto in Gestione dei segreti AWS. 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 con Secrets Manager, è necessaria l'autorizzazione per la policy gestita da `SecretManagerReadWrite`. Per ulteriori informazioni sulle autorizzazioni minime, vedere [Creating and Managing Secrets with AWS Secrets Manager](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) nella *Guida per l'Gestione dei segreti AWS utente*.
**Come archiviare le credenziali in un segreto per un cluster Amazon Redshift**
1. Usa la Gestione dei segreti AWS console per creare un segreto che contenga le credenziali per il tuo cluster:
+ Quando si sceglie **Archivia un nuovo segreto**, selezionare **Credenziali per il cluster Redshift**.
+ Archiviare i valori per **Nome utente** (utente del database), **Password** e **Cluster database**(identificatore del cluster) nel segreto.
+ Taggare il segreto con la chiave `RedshiftDataFullAccess`. La policy AWS gestita consente l'azione `AmazonRedshiftDataFullAccess` solo `secretsmanager:GetSecretValue` per i segreti etichettati con la chiave`RedshiftDataFullAccess`.
Per le istruzioni, consultare [Creazione di un segreto di base](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html) nella *Guida per l'utente di Gestione dei segreti AWS *.
1. Usa la Gestione dei segreti AWS console 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, Possono essere utilizzati nelle chiamate all'API dati.
**Archiviazione delle credenziali in un segreto per un gruppo di lavoro serverless**
1. Usa Gestione dei segreti AWS AWS CLI i comandi per archiviare un segreto che contiene le credenziali per il tuo gruppo di lavoro serverless:
+ Crea il tuo segreto in un file, ad esempio un file JSON denominato `mycreds.json`. Fornire i i valori per **User name** (Nome utente) (utente del database) e **Password** nel file.
```
{
"username": "myusername",
"password": "mypassword"
}
```
+ Memorizzare i valori nel segreto e taggare il segreto con la chiave `RedshiftDataFullAccess`.
```
aws secretsmanager create-secret --name MyRedshiftSecret --tags Key="RedshiftDataFullAccess",Value="serverless" --secret-string file://mycreds.json
```
Di seguito è riportato l'output.
```
{
"ARN": "arn:aws:secretsmanager:region:accountId:secret:MyRedshiftSecret-mvLHxf",
"Name": "MyRedshiftSecret",
"VersionId": "a1603925-e8ea-4739-9ae9-e509eEXAMPLE"
}
```
Per ulteriori informazioni, consulta l'argomento relativo alla [creazione di un segreto di base con AWS CLI](https://docs.aws.amazon.com/secretsmanager/latest/userguide/manage_create-basic-secret.html#proc-create-api) nella *Guida per l'utente di Gestione dei segreti AWS *.
1. Usa la Gestione dei segreti AWS console per visualizzare i dettagli del segreto che hai creato o esegui il comando. `aws secretsmanager describe-secret` AWS CLI
Prendere nota del nome e dell'ARN del segreto, Possono essere utilizzati nelle chiamate all'API dati.
# Creazione di un endpoint Amazon VPC (AWS PrivateLink) per l'API dati
Amazon Virtual Private Cloud (Amazon VPC) consente di lanciare AWS risorse, come cluster e applicazioni Amazon Redshift, in un cloud privato virtuale (VPC). AWS PrivateLink fornisce connettività privata tra cloud privati virtuali (VPCs) e AWS servizi in modo sicuro sulla rete Amazon. In questo modo AWS PrivateLink, puoi creare endpoint VPC, che puoi utilizzare per connetterti a servizi su diversi account e basati VPCs su Amazon VPC. Per ulteriori informazioni AWS PrivateLink, consulta [VPC Endpoint Services (AWS PrivateLink)](https://docs.aws.amazon.com/vpc/latest/userguide/endpoint-service.html) nella *Amazon Virtual Private Cloud* User Guide.
Puoi chiamare l'API dati con gli endpoint Amazon VPC. L'utilizzo di un endpoint Amazon VPC mantiene il traffico tra le applicazioni nel tuo Amazon VPC e l'API dati nella rete AWS , 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 **Nome servizio**, scegliere **redshift-data** (`com.amazonaws.region.redshift-data`).
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.
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)**.
Il DNS privato risolve il nome host DNS dell'API dati standard (`https://redshift-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 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. Seleziona **Crea endpoint**.
Dopo aver creato l'endpoint, scegli il link in Console di gestione AWS per visualizzare i dettagli dell'endpoint.
La scheda **Details (Dettagli)** dell'endpoint mostra i nomi host DNS generati durante la creazione dell'endpoint Amazon VPC.
È possibile utilizzare l'endpoint standard (`redshift-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, consultare [Considerazioni da fare durante la chiamata all'API dati di Amazon Redshift](data-api.md#data-api-calling-considerations).
# Unirsi a gruppi di database durante la connessione a un cluster
I gruppi di database sono raccolte di utenti del database. I privilegi del database possono essere concessi ai gruppi. Un amministratore può configurare un ruolo IAM in modo che questi gruppi di database vengano presi in considerazione quando SQL viene eseguito con l'API Data. Per ulteriori informazioni sui gruppi di database, consultare [Gruppi](https://docs.aws.amazon.com/redshift/latest/dg/r_Groups.html) nella *Guida per gli sviluppatori di database di Amazon Redshift*.
Puoi configurare il ruolo IAM di un chiamante dell'API Data in modo che l'utente del database specificato nella chiamata si unisca ai gruppi del database quando l'API dei dati si connette a un cluster. Questa funzionalità è supportata solo quando ci si connette a cluster forniti. Non è supportato durante la connessione a gruppi di lavoro Redshift Serverless. Il ruolo IAM del chiamante dell'API Data deve inoltre consentire l'azione `redshift:JoinGroup`.
Configuralo aggiungendo tag ai ruoli IAM. L'amministratore del ruolo IAM del chiamante aggiunge i tag con la chiave `RedshiftDbGroups` e un valore chiave di un elenco di gruppi di database. Il valore è un elenco di nomi separati da due punti (:) di gruppi di database fino a una lunghezza totale di 256 caratteri. I gruppi di database devono essere precedentemente definiti nel database connesso. Se un gruppo specificato non viene trovato nel database, viene ignorato. Ad esempio, per i gruppi di database `accounting` e `retail`, il valore-chiave è `accounting:retail`. La coppia chiave-valore del tag `{"Key":"RedshiftDbGroups","Value":"accounting:retail"}` viene utilizzato dall'API Data per determinare quali gruppi di database sono associati all'utente del database fornito nella chiamata alla Data API.
**Come effettuare il join ai gruppi di database**
1. Accedi Console di gestione AWS e apri la console IAM all'indirizzo. [https://console.aws.amazon.com/iam/](https://console.aws.amazon.com/iam/)
1. Nel riquadro di navigazione della console, scegliere **Roles (Ruoli)** e selezionare il nome del ruolo che si desidera modificare.
1. Scegliere la scheda **Tag**, quindi scegliere **Gestisci tag**.
1. Scegli **Aggiungi tag**, quindi aggiungi la chiave **RedshiftDbGroups**e un valore che è un elenco di*database-groups-colon-separated*.
1. Scegli **Save changes** (Salva modifiche).
Ora, quando un principal IAM (con questo ruolo IAM associato) chiama l'API dei dati, l'utente del database specificato si unisce ai gruppi di database specificati nel ruolo IAM.
Per ulteriori informazioni su come collegare un tag a un principale, inclusi i ruoli e gli utenti IAM, consultare [Assegnazione di tag di risorse IAM](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_tags.html) nella *Guida per l'utente di IAM*.
# Utilizzo dell’API dati con la propagazione affidabile delle identità
In qualità di amministratore di account Amazon Redshift, puoi integrare il tuo cluster o gruppo di lavoro Amazon Redshift AWS IAM Identity Center con, il che aiuta a gestire l'accesso della forza lavoro ad Amazon Redshift con Single Sign-On. Per ulteriori informazioni, consulta [Configurazione dell'integrazione di AWS IAM Identity Center con Amazon Redshift](redshift-iam-access-control-idp-connect-console.md). L'API Amazon Redshift Data supporta la propagazione delle identità utente di IAM Identity Center a un cluster o gruppo di lavoro Amazon Redshift e ad altri servizi, ad esempio, lungo la catena. AWS Lake Formation Puoi configurare ed eseguire query utilizzando l'API Data seguendo i passaggi dei [AWS servizi di Access in modo programmatico](https://aws.amazon.com/blogs//security/access-aws-services-programmatically-using-trusted-identity-propagation/) utilizzando la propagazione affidabile delle identità.
Quando chiami l’API dati utilizzando un’identità utente di Centro identità IAM da una sessione del ruolo IAM rafforzata con l’identità, puoi accedere solo all’istruzione e al risultato dell’istruzione risultanti utilizzando lo stesso utente di Centro identità IAM. Ad esempio, il AWS CLI comando seguente richiama l'`execute-statement`operazione per eseguire un comando SQL con propagazione di identità affidabili.
```
aws redshift-data execute-statement
--sql "select current_user;"
--cluster-id mycluster
--database dev
```
Il AWS CLI comando seguente richiama l'`batch-execute-statement`operazione per eseguire due comandi SQL.
```
aws redshift-data batch-execute-statement
--sqls "select current_user;" "select current_date;"
--cluster-id mycluster
--database dev
```
Per accedere alle istruzioni con `cancel-statement`, `describe-statement`, `get-statement-result` e `get-statement-result-v2` inviate dalle sessioni del ruolo IAM rafforzate con l’identità, l’utente e il ruolo IAM di Centro identità IAM devono corrispondere alle credenziali utilizzate per eseguire `execute-statment` o `batch-execute-statement`. Ad esempio, il AWS CLI comando seguente ottiene i risultati di un'istruzione SQL.
```
aws redshift-data get-statement-result
--id a1b2c3d4-5678-90ab-cdef-EXAMPLE11111
```
Per elencare le istruzioni, è necessario fornire un parametro `cluster-identifier` o `workgroup-name` per garantire che l’utente di Centro identità IAM abbia accesso solo alle applicazioni di Centro identità IAM di Amazon Redshift a cui è assegnato. Ad esempio, il AWS CLI comando seguente elenca le istruzioni per un cluster specifico.
```
aws redshift-data list-statements
--cluster-identifier mycluster
```
Puoi inoltre invocare le operazioni dell’API dati che accedono agli oggetti del database in un cluster o un gruppo di lavoro utilizzando una propagazione affidabile delle identità. Sono incluse le operazioni `list-databases`, `list-schemas`, `list-tables` e `describe-table`.
Le chiamate API effettuate dall’utente di Centro identità IAM possono essere monitorate in AWS CloudTrail. Una `onBehalfOf` sezione dell' CloudTrail evento mostra l'ID utente di IAM Identity Center e l'ARN dell'archivio di identità. L'esempio seguente mostra un frammento di un CloudTrail evento che mostra la `onBehalfOf` sezione con l'ID utente IAM Identity Center di `a1b2c3d4-5678-90ab-cdef-EXAMPLE11111` e l'ARN dell'archivio di identità di. `arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2`
```
{
"eventVersion":"1.10",
"userIdentity":{
"type":"AssumedRole",
...
},
"onBehalfOf":{
"userId":"a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"identityStoreArn":"arn:aws:identitystore::123456789012:identitystore/d-9067bc44d2"
}
},
"eventTime":"2025-01-13T04:46:27Z",
"eventSource":"redshift-data.amazonaws.com",
"eventName":"ExecuteStatement",
"awsRegion":"us-east-1"
}
```
Puoi eseguire il seguente comando SQL per verificare la query inviata dall’utente di Centro identità IAM. In questo esempio l’e-mail registrata in Centro identità è `username@example.com`.
```
SELECT
h.query_id,
h.database_name,
h.status,
h.query_text,
u.usename,
h.start_time,
h.end_time
FROM
sys_query_history h
LEFT JOIN
pg_user u
ON
h.user_id = u.usesysid
where u.usename='awsidc:username@example.com'
ORDER BY
h.start_time DESC;
```
# Chiamata dell'API dati
Puoi chiamare l'API Data o AWS CLI eseguire istruzioni SQL sul tuo cluster o gruppo di lavoro serverless. Le operazioni principali per eseguire le istruzioni SQL sono [https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_ExecuteStatement.html) e[https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html](https://docs.aws.amazon.com/redshift-data/latest/APIReference/API_BatchExecuteStatement.html) nel *Riferimento all'API dati di Amazon Redshift*. L'API Data supporta i linguaggi di programmazione supportati dall' AWS SDK. Per ulteriori informazioni, consultare [Strumenti per creare in AWS](https://aws.amazon.com/tools/).
Per vedere esempi di codice di chiamata all'API Data, consulta [Getting Started with Redshift Data API](https://github.com/aws-samples/getting-started-with-amazon-redshift-data-api#getting-started-with-redshift-data-api) in. *GitHub* Questo repository contiene esempi di utilizzo AWS Lambda per accedere ai dati di Amazon Redshift da Amazon EC2 e Amazon Runtime AWS Glue Data Catalog. SageMaker Esempi di linguaggi di programmazione includono Python, Go, Java e Javascript.
Puoi chiamare l'API dati utilizzando AWS CLI.
Gli esempi seguenti utilizzano AWS CLI per chiamare l'API Data. Per eseguire gli esempi, modificare i valori dei parametri in modo che corrispondano all'ambiente in uso. In molti esempi viene fornito un `cluster-identifier` per l'esecuzione in un cluster. Quando l'esecuzione avviene in un gruppo di lavoro serverless, viene fornito invece un `workgroup-name`. In questi esempi sono illustrate alcune delle operazioni dell'API dati. Per ulteriori informazioni, consultare la sezione relativa alle *informazioni di riferimento ai comandi della AWS CLI *.
I comandi nei seguenti esempi sono stati divisi e formattati per una maggiore leggibilità. Non tutti i parametri e le risposte vengono mostrati in tutti gli esempi. Per la definizione API della sintassi completa della richiesta, dei parametri di richiesta, della sintassi di risposta e degli elementi di risposta, consulta la [documentazione di riferimento dell’API dati Amazon Redshift](https://docs.aws.amazon.com/redshift-data/latest/APIReference/).
# Passaggio delle istruzioni SQL a un data warehouse Amazon Redshift
Gli esempi in questa pagina illustrano diversi modi per passare un’istruzione SQL al data warehouse
## Eseguire un’istruzione SQL
Per eseguire un'istruzione SQL, utilizzare il `aws redshift-data execute-statement` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione Gestione dei segreti AWS .
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sql "select * from stl_query limit 1"
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un gruppo di lavoro senza server e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data execute-statement
--database dev
--workgroup-name myworkgroup
--sql "select 1;"
```
Di seguito è riportato un esempio della risposta.
```
{
"CreatedAt": "2022-02-11T06:25:28.748000+00:00",
"Database": "dev",
"DbUser": "IAMR:RoleName",
"Id": "89dd91f5-2d43-43d3-8461-f33aa093c41e",
"WorkgroupName": "myworkgroup"
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione Gestione dei segreti AWS e un token di idempotenza.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "select * from stl_query limit 1"
--database dev
--client-token b855dced-259b-444c-bc7b-d3e8e33f94g1
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
## Eseguire un’istruzione SQL con i parametri
Per eseguire un'istruzione SQL, utilizzare il `aws redshift-data execute-statement` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione Gestione dei segreti AWS . Il testo SQL ha un parametro denominato `distance`. In questo caso, la distanza utilizzata nel predicato è `5`. In un'istruzione SELECT, i parametri denominati per i nomi delle colonne possono essere utilizzati solo nel predicato. I valori per i parametri specificati per l'istruzione SQL vengono specificati nell'opzione `parameters`.
```
aws redshift-data execute-statement
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--sql "SELECT ratecode FROM demo_table WHERE trip_distance > :distance"
--parameters "[{\"name\": \"distance\", \"value\": \"5\"}]"
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598323175.823,
"Database": "dev",
"Id": "c016234e-5c6c-4bc5-bb16-2c5b8ff61814",
"SecretArn": "arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn"
}
```
La query seguente utilizza la tabella `EVENT` dal database di esempio. Per ulteriori informazioni, consultare [Tabella EVENT](https://docs.aws.amazon.com/redshift/latest/dg/r_eventtable.html) nella *Guida per gli sviluppatori di database di Amazon Redshift*.
Se non si dispone già della tabella `EVENT` nel database, è possibile crearne una utilizzando l'API dati come segue:
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "create table event( eventid integer not null distkey,
venueid smallint not null,
catid smallint not null,
dateid smallint not null sortkey,
eventname varchar(200),
starttime timestamp)"
```
Il comando seguente inserisce una riga nella tabella `EVENT`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:eventid, :venueid::smallint, :catid, :dateid, :eventname, :starttime)"
--parameters "[{\"name\": \"eventid\", \"value\": \"1\"}, {\"name\": \"venueid\", \"value\": \"1\"},
{\"name\": \"catid\", \"value\": \"1\"},
{\"name\": \"dateid\", \"value\": \"1\"},
{\"name\": \"eventname\", \"value\": \"event 1\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"}]"
```
Il comando seguente inserisce una seconda riga nella tabella `EVENT`. Questo esempio esegue le operazioni seguenti:
+ Il parametro denominato `id` viene utilizzato quattro volte nel testo SQL.
+ Il tipo di conversione implicita viene applicato automaticamente quando si inserisce il parametro `starttime`.
+ La colonna `venueid` è tipo cast per il tipo di dati SMALLINT.
+ Le stringhe di caratteri che rappresentano il tipo di dati DATE vengono convertite implicitamente nel tipo di dati TIMESTAMP.
+ All'interno del testo SQL è possibile utilizzare i commenti.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "insert into event values(:id, :id::smallint, :id, :id, :eventname, :starttime) /*this is comment, and it won't apply parameterization for :id, :eventname or :starttime here*/"
--parameters "[{\"name\": \"eventname\", \"value\": \"event 2\"},
{\"name\": \"starttime\", \"value\": \"2022-02-22\"},
{\"name\": \"id\", \"value\": \"2\"}]"
```
Di seguito sono riportate le due righe inserite:
```
eventid | venueid | catid | dateid | eventname | starttime
---------+---------+-------+--------+-----------+---------------------
1 | 1 | 1 | 1 | event 1 | 2022-02-22 00:00:00
2 | 2 | 2 | 2 | event 2 | 2022-02-22 00:00:00
```
Il comando seguente utilizza un parametro denominato in una clausola WHERE per recuperare la riga in cui `eventid` è `1`.
```
aws redshift-data execute-statement
--database dev
--cluster-id mycluster-test
--db-user awsuser
--sql "select * from event where eventid=:id"
--parameters "[{\"name\": \"id\", \"value\": \"1\"}]"
```
Eseguire il comando seguente per ottenere i risultati SQL dell'istruzione SQL precedente:
```
aws redshift-data get-statement-result --id 7529ad05-b905-4d71-9ec6-8b333836eb5a
```
Vengono restituiti i risultati seguenti:
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"longValue": 1
},
{
"stringValue": "event 1"
},
{
"stringValue": "2022-02-22 00:00:00.0"
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "eventid",
"length": 0,
"name": "eventid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "venueid",
"length": 0,
"name": "venueid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "catid",
"length": 0,
"name": "catid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "dateid",
"length": 0,
"name": "dateid",
"nullable": 0,
"precision": 5,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "int2"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "eventname",
"length": 0,
"name": "eventname",
"nullable": 1,
"precision": 200,
"scale": 0,
"schemaName": "public",
"tableName": "event",
"typeName": "varchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 1,
"precision": 29,
"scale": 6,
"schemaName": "public",
"tableName": "event",
"typeName": "timestamp"
}
],
"TotalNumRows": 1
}
```
## Eseguire più istruzioni SQL
Per eseguire più istruzioni SQL con un solo comando, utilizzare il `aws redshift-data batch-execute-statement` AWS CLI comando.
Il AWS CLI comando seguente esegue tre istruzioni SQL su un cluster e restituisce un identificatore per recuperare i risultati. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data batch-execute-statement
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--sqls "set timezone to BST" "select * from mytable" "select * from another_table"
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Database": "dev",
"DbUser": "myuser",
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766"
}
```
# Elencare i metadati sulle istruzioni SQL
Per elencare i metadati relativi alle istruzioni SQL, utilizzate il comando. `aws redshift-data list-statements` AWS CLI L'autorizzazione per eseguire questo comando si basa sulle autorizzazioni IAM del chiamante.
Il AWS CLI comando seguente elenca le istruzioni SQL eseguite.
```
aws redshift-data list-statements
--status ALL
```
Di seguito è riportato un esempio della risposta.
```
{
"Statements": [
{
"CreatedAt": 1598306924.632,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
},
{
"CreatedAt": 1598311717.437,
"Id": "e0ebd578-58b3-46cc-8e52-8163fd7e01aa",
"QueryString": "select * from stl_query limit 1",
"Status": "FAILED",
"UpdatedAt": 1598311719.008
},
{
"CreatedAt": 1598313683.65,
"Id": "c361d4f7-8c53-4343-8c45-6b2b1166330c",
"QueryString": "select * from stl_query limit 1",
"Status": "ABORTED",
"UpdatedAt": 1598313685.495
},
{
"CreatedAt": 1598306653.333,
"Id": "a512b7bd-98c7-45d5-985b-a715f3cfde7f",
"QueryString": "select 1",
"Status": "FINISHED",
"UpdatedAt": 1598306653.992
}
]
}
```
# Descrivere i metadati relativi a un’istruzione SQL
Per ottenere le descrizioni dei metadati per un'istruzione SQL, utilizzate il `aws redshift-data describe-statement` AWS CLI comando. L'autorizzazione per eseguire questo comando si basa sulle autorizzazioni IAM del chiamante.
Il AWS CLI comando seguente descrive un'istruzione SQL.
```
aws redshift-data describe-statement
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
Di seguito è riportato un esempio della risposta.
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": 1598306924.632,
"Duration": 1095981511,
"Id": "d9b6c0c9-0747-4bf4-b142-e8883122f766",
"QueryString": "select * from stl_query limit 1",
"RedshiftPid": 20859,
"RedshiftQueryId": 48879,
"ResultRows": 1,
"ResultSize": 4489,
"Status": "FINISHED",
"UpdatedAt": 1598306926.667
}
```
Di seguito è riportato un esempio di una risposta `describe-statement` dopo aver eseguito un comando `batch-execute-statement` con più istruzioni SQL.
```
{
"ClusterIdentifier": "mayo",
"CreatedAt": 1623979777.126,
"Duration": 6591877,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652",
"RedshiftPid": 31459,
"RedshiftQueryId": 0,
"ResultRows": 2,
"ResultSize": 22,
"Status": "FINISHED",
"SubStatements": [
{
"CreatedAt": 1623979777.274,
"Duration": 3396637,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:1",
"QueryString": "select 1;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979777.903
},
{
"CreatedAt": 1623979777.274,
"Duration": 3195240,
"HasResultSet": true,
"Id": "b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2",
"QueryString": "select 2;",
"RedshiftQueryId": -1,
"ResultRows": 1,
"ResultSize": 11,
"Status": "FINISHED",
"UpdatedAt": 1623979778.076
}
],
"UpdatedAt": 1623979778.183
}
```
# Recuperare i risultati di un’istruzione SQL
Per recuperare il risultato da un'istruzione SQL eseguita, utilizzare il `redshift-data get-statement-result-v2` AWS CLI comando `redshift-data get-statement-result` or. I risultati di `get-statement-result` sono in formato JSON. I risultati di `get-statement-result-v2` sono in formato CSV. È possibile fornire un `Id` che viene ricevuto nella risposta a `execute-statement` o `batch-execute-statement`. Il valore `Id` per un'istruzione SQL eseguita da `batch-execute-statement` può essere recuperato nel risultato di `describe-statement` ed ha un suffisso formato da due punti e un numero di sequenza, ad esempio `b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2`. Se con `batch-execute-statement` vengono eseguite più istruzioni SQL, ogni istruzione SQL avrà un valore `Id` come mostrato nella`describe-statement`. L'autorizzazione per eseguire questo comando si basa sulle autorizzazioni IAM del chiamante.
L’istruzione seguente restituisce il risultato di un’istruzione SQL eseguita da `execute-statement` che ha lasciato il valore predefinito di `ResultFormat` su `JSON`. Per recuperare i risultati, chiama l’operazione `get-statement-result`.
```
aws redshift-data get-statement-result
--id d9b6c0c9-0747-4bf4-b142-e8883122f766
```
L'istruzione seguente restituisce il risultato della seconda istruzione SQL eseguita da `batch-execute-statement`.
```
aws redshift-data get-statement-result
--id b2906c76-fa6e-4cdf-8c5f-4de1ff9b7652:2
```
Di seguito è riportato un esempio della risposta a una chiamata a `get-statement-result` in cui il risultato SQL viene restituito in formato JSON nella chiave `Records` della risposta.
```
{
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "userid",
"length": 0,
"name": "userid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "query",
"length": 0,
"name": "query",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "label",
"length": 0,
"name": "label",
"nullable": 0,
"precision": 320,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "xid",
"length": 0,
"name": "xid",
"nullable": 0,
"precision": 19,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int8"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "pid",
"length": 0,
"name": "pid",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "database",
"length": 0,
"name": "database",
"nullable": 0,
"precision": 32,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": true,
"isCurrency": false,
"isSigned": false,
"label": "querytxt",
"length": 0,
"name": "querytxt",
"nullable": 0,
"precision": 4000,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "bpchar"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "starttime",
"length": 0,
"name": "starttime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"label": "endtime",
"length": 0,
"name": "endtime",
"nullable": 0,
"precision": 29,
"scale": 6,
"schemaName": "",
"tableName": "stll_query",
"type": 93,
"typeName": "timestamp"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "aborted",
"length": 0,
"name": "aborted",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "insert_pristine",
"length": 0,
"name": "insert_pristine",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "concurrency_scaling_status",
"length": 0,
"name": "concurrency_scaling_status",
"nullable": 0,
"precision": 10,
"scale": 0,
"schemaName": "",
"tableName": "stll_query",
"typeName": "int4"
}
],
"Records": [
[
{
"longValue": 1
},
{
"longValue": 3
},
{
"stringValue": "health"
},
{
"longValue": 1023
},
{
"longValue": 15279
},
{
"stringValue": "dev"
},
{
"stringValue": "select system_status from stv_gui_status;"
},
{
"stringValue": "2020-08-21 17:33:51.88712"
},
{
"stringValue": "2020-08-21 17:33:52.974306"
},
{
"longValue": 0
},
{
"longValue": 0
},
{
"longValue": 6
}
]
],
"TotalNumRows": 1
}
```
L’esempio seguente mostra un’istruzione SQL eseguita da `execute-statement` per restituire risultati come JSON. La tabella `testingtable` ha tre colonne di numeri interi (col1, col2, col3) e tre righe con valori (1, 2, 3), (4, 5, 6) e (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format JSON
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
Di seguito è riportato un esempio della risposta a una chiamata a `get-statement-result` in cui il risultato SQL viene restituito in formato JSON nella chiave `Records` della risposta.
```
aws redshift-data get-statement-result
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
[
{
"longValue": 1
},
{
"longValue": 2
},
{
"longValue": 3
}
],
[
{
"longValue": 4
},
{
"longValue": 5
},
{
"longValue": 6
}
],
[
{
"longValue": 7
},
{
"longValue": 8
},
{
"longValue": 9
}
]
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3
}
```
L’esempio seguente mostra un’istruzione SQL eseguita da `execute-statement` per restituire i risultati in formato CSV. La tabella `testingtable` ha tre colonne di numeri interi (col1, col2, col3) e tre righe con valori (1, 2, 3), (4, 5, 6) e (7, 8, 9).
```
aws redshift-data execute-statement
--database dev
--sql "SELECT col1, col2, col3 FROM testingtable"
--cluster-id mycluster-test
--result-format CSV
```
```
{
"ClusterIdentifier": "mycluster-test",
"CreatedAt": "2024-04-02T16:45:25.144000+00:00",
"Database": "dev",
"DbUser": "IAMR:Administrator",
"Id": "d468d942-6df9-4f85-8ae3-bac01a61aec3"
}
```
Di seguito è riportato un esempio della risposta a una chiamata a `get-statement-result-v2` in cui il risultato SQL viene restituito in formato CSV nella chiave `Records` della risposta. Le righe sono separate da un ritorno a capo e una nuova riga (\$1r\$1n). La prima riga restituita in `Records` sono le intestazioni delle colonne. I risultati restituiti in formato CSV vengono restituiti in 1 MB, dove ogni blocco può memorizzare un numero qualsiasi di righe fino a 1 MB.
```
aws redshift-data get-statement-result-v2
--id d468d942-6df9-4f85-8ae3-bac01a61aec3
```
```
{
"Records": [
{
"CSVRecords": "col1,col2,col3\r\n1,2,3\r\n4,5,6\r\n7,8,9\r\n"
}
],
"ColumnMetadata": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col1",
"name": "col1",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col2",
"name": "col2",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": true,
"label": "col3",
"name": "col3",
"nullable": 1,
"precision": 10,
"scale": 0,
"schemaName": "public",
"tableName": "testingtable",
"typeName": "int4",
"length": 0
}
],
"TotalNumRows": 3,
"ResultFormat": "csv"
}
```
# Descrivere una tabella
Per ottenere i metadati che descrivono una tabella, utilizzate il `aws redshift-data describe-table` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster e restituisce i metadati che descrivono una tabella. In questo esempio viene utilizzato il metodo Gestione dei segreti AWS di autenticazione.
```
aws redshift-data describe-table
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
```
Di seguito è riportato un esempio della risposta.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster che descrive una tabella. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data describe-table
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
--table sql_features
```
Di seguito è riportato un esempio della risposta.
```
{
"ColumnList": [
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_id",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "sub_feature_name",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_supported",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "is_verified_by",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
},
{
"isCaseSensitive": false,
"isCurrency": false,
"isSigned": false,
"length": 2147483647,
"name": "comments",
"nullable": 1,
"precision": 2147483647,
"scale": 0,
"schemaName": "information_schema",
"tableName": "sql_features",
"typeName": "character_data"
}
]
}
```
# Elencare i database in un cluster
Per elencare i database in un cluster, utilizzare il `aws redshift-data list-databases` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare i database. In questo esempio viene utilizzato il metodo di Gestione dei segreti AWS autenticazione.
```
aws redshift-data list-databases
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"Databases": [
"dev"
]
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare i database. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data list-databases
--db-user myuser
--cluster-identifier mycluster-test
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"Databases": [
"dev"
]
}
```
# Elencare gli schemi in un database
Per elencare gli schemi in un database, utilizzare il `aws redshift-data list-schemas` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare gli schemi in un database. In questo esempio viene utilizzato il metodo Gestione dei segreti AWS di autenticazione.
```
aws redshift-data list-schemas
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare gli schemi in un database. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data list-schemas
--db-user mysuser
--cluster-identifier mycluster-test
--database dev
```
Di seguito è riportato un esempio della risposta.
```
{
"Schemas": [
"information_schema",
"pg_catalog",
"pg_internal",
"public"
]
}
```
# Elencare le tabelle in un database
Per elencare le tabelle in un database, utilizzare il `aws redshift-data list-tables` AWS CLI comando.
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare le tabelle in un database. In questo esempio viene utilizzato il metodo di Gestione dei segreti AWS autenticazione.
```
aws redshift-data list-tables
--secret-arn arn:aws:secretsmanager:us-west-2:123456789012:secret:myuser-secret-hKgPWn
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
Di seguito è riportato un esempio della risposta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
}
```
Il AWS CLI comando seguente esegue un'istruzione SQL su un cluster per elencare le tabelle in un database. In questo esempio viene utilizzato il metodo di autenticazione con le credenziali temporanee.
```
aws redshift-data list-tables
--db-user myuser
--cluster-identifier mycluster-test
--database dev
--schema information_schema
```
Di seguito è riportato un esempio della risposta.
```
{
"Tables": [
{
"name": "sql_features",
"schema": "information_schema",
"type": "SYSTEM TABLE"
},
{
"name": "sql_implementation_info",
"schema": "information_schema",
"type": "SYSTEM TABLE"
}
]
}
```
# Risoluzione dei problemi relativi all'API dati di Amazon Redshift
Utilizza le seguenti sezioni, intitolate con messaggi di errori comuni, per aiutare a risolvere i problemi con l'API dati.
**Topics**
+ [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)
## Il pacchetto per la query è troppo grande
Se viene visualizzato un errore che indica che il pacchetto per una query è troppo grande, in genere il set di risultati restituito per una riga è 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
Se viene visualizzato un errore che indica che la risposta del database ha superato il limite delle dimensioni, in genere le dimensioni del set di risultati restituito dal database erano troppo grandi. Il limite dell'API Data è di 500 MB nel set di risultati restituito dal database.
Per risolvere questo problema, assicurati che le chiamate all'API Data restituiscano 500 MB di dati o meno. Se devi restituire più di 500 MB, puoi eseguire più chiamate di istruzioni con la `LIMIT` clausola nella query.
# Pianificazione delle operazioni di Amazon Redshift Data API con Amazon EventBridge
È possibile creare regole corrispondenti agli eventi selezionati nel flusso e instradarle alle destinazioni per le operazioni. È possibile anche utilizzare le regole per eseguire operazioni in base a una pianificazione prestabilita. Per ulteriori informazioni, consulta la [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
Per pianificare le operazioni Data API con EventBridge, il ruolo IAM associato deve affidarsi al principal for CloudWatch Events (events.amazonaws.com). Questo ruolo deve avere l'equivalente della policy gestita `AmazonEventBridgeFullAccess` collegata. Dovrebbe inoltre disporre delle autorizzazioni della policy `AmazonRedshiftDataFullAccess` che sono gestite dall'API dati. È possibile creare un ruolo IAM con queste autorizzazioni nella console IAM. Quando crei un ruolo sulla console IAM, scegli l'entità affidabile del AWS servizio per gli eventi. CloudWatch Specificate il ruolo IAM nel valore `RoleArn` JSON nella EventBridge destinazione. Per ulteriori informazioni sulla creazione di un ruolo IAM, consulta [Creating a Role for an AWS Service (Console)](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-service.html#roles-creatingrole-service-console) nella *IAM User Guide*.
La `name` regola che crei in Amazon EventBridge deve corrispondere `StatementName` a quella in`RedshiftDataParameters`.
Gli esempi seguenti mostrano le variazioni della creazione di EventBridge regole con una o più istruzioni SQL e con un cluster Amazon Redshift o un gruppo di lavoro Amazon Redshift Serverless come data warehouse.
## Richiamo con un'unica istruzione SQL e un unico cluster
L'esempio seguente utilizza AWS CLI per creare una EventBridge regola che viene utilizzata per eseguire un'istruzione SQL su un cluster Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Quindi viene creato un EventBridge obiettivo da eseguire secondo la pianificazione specificata nella regola.
```
aws events put-targets
--cli-input-json file://data.json
```
Di seguito è riportato il file data.json di input. La chiave JSON `Sql` indica che esiste una singola istruzione SQL. Il valore JSON `Arn` contiene un identificatore del cluster. Il valore JSON `RoleArn` contiene il ruolo IAM utilizzato per eseguire l'istruzione SQL come descritto in precedenza.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"DbUser": "root",
"Sql": "select 1;",
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Richiamo con un'unica istruzione SQL e un unico gruppo di lavoro
L'esempio seguente utilizza AWS CLI per creare una EventBridge regola che viene utilizzata per eseguire un'istruzione SQL su un gruppo di lavoro Amazon Redshift Serverless.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Quindi viene creato un EventBridge obiettivo da eseguire secondo la pianificazione specificata nella regola.
```
aws events put-targets
--cli-input-json file://data.json
```
Di seguito è riportato il file data.json di input. La chiave JSON `Sql` indica che esiste una singola istruzione SQL. Il valore JSON `Arn` contiene un nome del gruppo di lavoro. Il valore JSON `RoleArn` contiene il ruolo IAM utilizzato per eseguire l'istruzione SQL come descritto in precedenza.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sql": "select 1;",
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
## Richiamo con più istruzioni SQL e cluster
L'esempio seguente utilizza AWS CLI per creare una EventBridge regola che viene utilizzata per eseguire più istruzioni SQL su un cluster Amazon Redshift.
```
aws events put-rule
--name test-redshift-cluster-data
--schedule-expression "rate(1 minute)"
```
Quindi viene creato un EventBridge obiettivo da eseguire secondo la pianificazione specificata nella regola.
```
aws events put-targets
--cli-input-json file://data.json
```
Di seguito è riportato il file data.json di input. La chiave JSON `Sqls` indica che esistono più istruzioni SQL. Il valore JSON `Arn` contiene un identificatore del cluster. Il valore JSON `RoleArn` contiene il ruolo IAM utilizzato per eseguire l'istruzione SQL come descritto in precedenza.
```
{
"Rule": "test-redshift-cluster-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift:us-east-1:123456789012:cluster:mycluster",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-cluster-data",
"WithEvent": true
}
}
]
}
```
## Richiamo con più istruzioni SQL e gruppi di lavoro
L'esempio seguente utilizza AWS CLI per creare una EventBridge regola che viene utilizzata per eseguire più istruzioni SQL su un gruppo di lavoro Amazon Redshift Serverless.
```
aws events put-rule
--name test-redshift-serverless-workgroup-data
--schedule-expression "rate(1 minute)"
```
Quindi viene creato un EventBridge obiettivo da eseguire secondo la pianificazione specificata nella regola.
```
aws events put-targets
--cli-input-json file://data.json
```
Di seguito è riportato il file data.json di input. La chiave JSON `Sqls` indica che esistono più istruzioni SQL. Il valore JSON `Arn` contiene un nome del gruppo di lavoro. Il valore JSON `RoleArn` contiene il ruolo IAM utilizzato per eseguire l'istruzione SQL come descritto in precedenza.
```
{
"Rule": "test-redshift-serverless-workgroup-data",
"EventBusName": "default",
"Targets": [
{
"Id": "2",
"Arn": "arn:aws:redshift-serverless:us-east-1:123456789012:workgroup/a1b2c3d4-5678-90ab-cdef-EXAMPLE11111",
"RoleArn": "arn:aws:iam::123456789012:role/Administrator",
"RedshiftDataParameters": {
"Database": "dev",
"Sqls": ["select 1;", "select 2;", "select 3;"],
"StatementName": "test-redshift-serverless-workgroup-data",
"WithEvent": true
}
}
]
}
```
# Monitoraggio dell'API dati
Il monitoraggio è una parte importante per mantenere l'affidabilità, la disponibilità e le prestazioni della Data API e delle altre AWS soluzioni. AWS fornisce i seguenti strumenti di monitoraggio per monitorare la Data API, segnalare quando qualcosa non va e intraprendere azioni automatiche se necessario:
+ Amazon EventBridge può essere utilizzato per automatizzare AWS i tuoi servizi e rispondere automaticamente agli eventi di sistema, come problemi di disponibilità delle applicazioni o modifiche delle risorse. Gli eventi AWS relativi ai servizi vengono forniti quasi EventBridge in tempo reale. Puoi compilare regole semplici che indichino quali eventi sono considerati di interesse per te e quali operazioni automatizzate intraprendere quando un evento corrisponde a una regola. Per ulteriori informazioni, consulta la [Amazon EventBridge User Guide](https://docs.aws.amazon.com/eventbridge/latest/userguide/).
+ AWS CloudTrail acquisisce le chiamate API e gli eventi correlati effettuati da o per conto del tuo AWS account e invia i file di log a un bucket Amazon S3 da te specificato. Puoi identificare quali utenti e account hanno chiamato AWS, l'indirizzo IP di origine da cui sono state effettuate le chiamate e quando sono avvenute le chiamate. Per ulteriori informazioni su come è integrato Amazon Redshift AWS CloudTrail, consulta [Logging](https://docs.aws.amazon.com/redshift/latest/mgmt/logging-with-cloudtrail.html) with. CloudTrail Per ulteriori informazioni su CloudTrail, consulta la Guida per l'[AWS CloudTrail utente](https://docs.aws.amazon.com/awscloudtrail/latest/userguide/).
**Topics**
+ [Eventi di monitoraggio per l'Amazon Redshift Data API in Amazon EventBridge](data-api-monitoring-events.md)
# Eventi di monitoraggio per l'Amazon Redshift Data API in Amazon EventBridge
Puoi monitorare gli eventi dell'API Data in EventBridge, che fornisce un flusso di dati in tempo reale dalle tue applicazioni, applicazioni software-as-a-service (SaaS) e AWS servizi. EventBridge indirizza tali dati verso destinazioni come AWS Lambda Amazon SNS. Questi eventi sono gli stessi che compaiono in CloudWatch Events, che fornisce un flusso quasi in tempo reale di eventi di sistema che descrivono i cambiamenti nelle risorse. AWS Gli eventi vengono inviati all'account che contiene il database Amazon Redshift. Ad esempio, se si assume un ruolo in un altro account, gli eventi vengono inviati a tale account. Per ulteriori informazioni, consulta [ EventBridge gli eventi Amazon](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-events.html) nella *Amazon EventBridge User Guide.* .
Gli eventi dell'API dati vengono inviati quando l'operazione dell'API dati `ExecuteStatement` o `BatchExecuteStatement` imposta l'opzione `WithEvent` su `true`. Il campo `state` dell'evento può contenere uno dei seguenti valori:
+ INTERROTTO: l'esecuzione della query è stata interrotta dall'utente.
+ FAILED: l'esecuzione della query non è riuscita.
+ FINISHED: l'esecuzione della query è terminata.
Gli eventi vengono consegnati su base garantita. Per ulteriori informazioni, consulta [Events from AWS services](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-service-event.html) nella *Amazon EventBridge User Guide*.
## Esempio di l'evento terminato dell'API dati
L'esempio seguente mostra un evento per l'API dati quando l'operazione dell'API `ExecuteStatement` termina. Nell'esempio, un'istruzione denominata `test.testtable` ha completato l'esecuzione.
```
{
"version": "0",
"id": "18e7079c-dd4b-dd64-caf9-e2a31640dab0",
"detail-type": "Redshift Data Statement Status Change",
"source": "aws.redshift-data",
"account": "123456789012",
"time": "2020-10-01T21:14:26Z",
"region": "us-east-1",
"resources": [
"arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster-1"
],
"detail": {
"principal": "arn:aws:iam::123456789012:user/myuser",
"statementName": "test.testtable",
"statementId": "dd2e1ec9-2ee3-49a0-819f-905fa7d75a4a",
"redshiftQueryId": -1,
"state": "FINISHED",
"rows": 1,
"expireAt": 1601673265
}
}
```
# Utilizzo AWS KMS con l'API dati Amazon Redshift
Quando crittografi il tuo cluster Amazon Redshift o il gruppo di lavoro Redshift Serverless con una chiave gestita dal cliente, l'API dati di Amazon Redshift utilizza la stessa chiave gestita dal cliente per archiviare e crittografare le tue query e i tuoi risultati.
L'API Data crittografa i dati per impostazione predefinita per proteggere le informazioni sensibili, come il testo delle query e i risultati delle query. Per questa protezione utilizza chiavi di AWS KMS crittografia AWS di proprietà di.
La crittografia predefinita per i dati archiviati riduce il sovraccarico operativo e la complessità quando si proteggono i dati sensibili. Questo approccio consente di creare applicazioni sicure che soddisfano i rigorosi requisiti normativi e di conformità alla crittografia.
## Utilizzo delle sovvenzioni in AWS KMS
L'API Data richiede una concessione per utilizzare la chiave gestita dal cliente.
Quando chiami `ExecuteStatement` o `BatchExecuteStatement` contro un cluster crittografato con una chiave gestita dal cliente, Amazon Redshift crea una concessione per tuo conto inviando una [https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_CreateGrant.html)richiesta a. AWS KMS AWS KMS utilizza le concessioni per consentire all'API Data di accedere a una chiave KMS nel tuo account.
L'API Data richiede la concessione dell'utilizzo della chiave gestita dal cliente per le seguenti operazioni:
+ Invia [https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Encrypt.html)richieste per AWS KMS crittografare i metadati delle query con la tua chiave gestita dal cliente.
+ Invia [https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_GenerateDataKey.html)richieste per AWS KMS generare chiavi di dati crittografate dalla chiave gestita dal cliente.
+ Invia [https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html](https://docs.aws.amazon.com/kms/latest/APIReference/API_Decrypt.html)richieste a per AWS KMS decrittografare le chiavi di dati crittografate in modo che possano crittografare i tuoi dati.
Puoi revocare l'accesso alla concessione o rimuovere l'accesso di Amazon Redshift alla tua chiave gestita dai clienti in qualsiasi momento. In tal caso, l'API Data non può più accedere ai dati crittografati dalla chiave gestita dal cliente, il che influisce sulle operazioni che dipendono da tali dati. Ad esempio, se tenti di recuperare i risultati della query o di tenere traccia dello stato della query dopo la revoca della concessione, l'API Data restituisce un. `AccessDeniedException`
## Politiche chiave per la chiave gestita dai clienti
Le policy della chiave controllano l’accesso alla chiave gestita dal cliente. Ogni chiave gestita dal cliente deve avere esattamente una policy della chiave, che contiene istruzioni che determinano chi può usare la chiave e come la possono usare. Quando crei la chiave gestita dal cliente, è possibile specificare una policy della chiave. Per ulteriori informazioni, consulta [Customer managed keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#customer-mgn-key) nella *Guida per sviluppatori AWS Key Management Service *.
Per utilizzare le chiavi gestite dai clienti con l'API Data, devi prima consentire l'accesso ad Amazon Redshift. Le seguenti operazioni API devono essere consentite nella policy chiave:
+ `kms:CreateGrant`: aggiunge una concessione a una chiave gestita dal cliente. Concede l'accesso di controllo a una AWS KMS chiave specificata, che consente l'accesso alle operazioni di concessione richieste da Amazon Redshift. Per ulteriori informazioni, consulta [Using grants](https://docs.aws.amazon.com/kms/latest/developerguide/grants.html#terms-grant-operations) in. AWS KMS
Di seguito è riportato un esempio di politica chiave:
```
"Statement":[
{
"Sid":"Allow access to principals authorized to use Amazon Redshift",
"Effect":"Allow",
"Principal":{
"AWS":"*"
},
"Action":[
"kms:DescribeKey",
"kms:CreateGrant"
],
"Resource":"*",
"Condition":{
"StringEquals":{
"kms:ViaService":"redshift.amazonaws.com",
"kms:CallerAccount":"111122223333"
}
}
},
{
"Sid":"AllowKeyAdministratorsAccess",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleAdminRole"
},
"Action":"kms:*",
"Resource":"*"
},
{
"Sid":"AllowKeyUseForExampleRole",
"Effect":"Allow",
"Principal":{
"AWS":"arn:aws:iam::111122223333:role/ExampleUserRole"
},
"Action":[
"kms:Encrypt",
"kms:Decrypt",
"kms:ReEncrypt*",
"kms:GenerateDataKey*",
"kms:DescribeKey"
],
"Resource":"*"
}
]
```
## Contesto di crittografia dell'API dei dati
Un contesto di crittografia è un insieme opzionale di coppie chiave-valore che contiene informazioni contestuali aggiuntive sui dati. AWS KMS utilizza il contesto di crittografia come dati autenticati aggiuntivi per supportare la crittografia autenticata. Quando includi un contesto di crittografia in una richiesta di crittografia dei dati, AWS KMS associa il contesto di crittografia ai dati crittografati. Per decrittografare i dati, è necessario includere lo stesso contesto di crittografia nella richiesta.
L'API Data utilizza le stesse tre coppie chiave-valore del contesto di crittografia in tutte le operazioni AWS KMS crittografiche per i cluster predisposti:
+ `aws:redshift:arn`— Amazon Resource Name (ARN) del cluster
+ `aws:redshift:createtime`— Il timestamp in cui è stata richiesta la creazione del cluster
+ `serviceName` – `RedshiftDataAPI`
```
"EncryptionContextSubset": {
"aws:redshift:arn": "arn:aws:redshift:us-east-1:123456789012:cluster:redshift-cluster",
"aws:redshift:createtime": "20250815T0000Z",
"serviceName": "RedshiftDataAPI",
}
```
L'API Data utilizza due coppie chiave-valore del contesto di crittografia in tutte le operazioni AWS KMS crittografiche per gruppi di lavoro senza server:
+ `aws:redshift-serverless:arn`— L'Amazon Resource Name (ARN) del namespace
+ `serviceName`— RedshiftData API
```
"EncryptionContextSubset": {
"aws:redshift-serverless:arn": "arn:aws:redshift-serverless:us-east-1:123456789012:namespace:12345678-1234-1234-1234-123456789012",
"serviceName": "RedshiftDataAPI"
}
```
Per ulteriori informazioni sulla crittografia, vedere [Introduzione ai dettagli crittografici di AWS KMS](https://docs.aws.amazon.com/kms/latest/cryptographic-details/intro.html). Per ulteriori informazioni su Amazon Redshift e l' AWS KMS integrazione, consulta [Come utilizza Amazon Redshift](https://docs.aws.amazon.com/kms/latest/developerguide/services-redshift.html). AWS KMS