Uso dell'API dati di Amazon Redshift

È possibile accedere al database Amazon Redshift utilizzando l'API dati integrata di Amazon Redshift. Utilizzando questa API, puoi accedere ai dati di Amazon Redshift con applicazioni basate su servizi Web, tra cui notebook AWS Lambda Amazon e. SageMaker AWS Cloud9 Per ulteriori informazioni su queste applicazioni AWS Lambda, consulta Amazon SageMaker e AWS Cloud9.

L'API dati non richiede una connessione permanente al database. Fornisce invece un endpoint HTTP sicuro e l'integrazione con gli AWS SDK. Puoi usare l'endpoint per eseguire istruzioni SQL senza gestire connessioni. Le chiamate all'API dati sono asincrone.

L'API Data utilizza credenziali archiviate nel database AWS Secrets Manager o credenziali temporanee del database. Non è necessario utilizzare alcuna password nelle chiamate API con entrambi i metodi di autorizzazione. Per ulteriori informazioni su AWS Secrets Manager, consulta What Is? AWS Secrets Manager nella Guida AWS Secrets Manager per l'utente.

Per ulteriori informazioni sulle operazioni API dati, consultare Guida di riferimento dell'API dati di Amazon Redshift.

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.

2. Determinare se si prevede di chiamare l'API dati con credenziali di autenticazione da Secrets Manager o con credenziali temporanee. Per ulteriori informazioni, consultare Scelta delle credenziali di autenticazione del database quando si richiama l'API dati di Amazon Redshift.

3. Se si utilizza Secrets Manager impostare un segreto per le credenziali di autenticazione. Per ulteriori informazioni, consultare Memorizzazione delle credenziali del database in AWS Secrets Manager.

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

5. 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 chiamate da AWS CLI, consultaChiamata dell'API dati.

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 Data API nel. Riferimenti generali di Amazon Web Services

• La durata massima di una query è di 24 ore.

• Il numero massimo di query attive (query STARTED e SUBMITTED) per cluster Amazon Redshift è 200.

• La dimensione massima dei risultati della query è 100 MB (dopo la compressione gzip). Se la chiamata restituisce più di 100 MB di dati di risposta, verrà terminata.

• 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.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 ruolo IAM o autorizzazioni IAM uguali all'utente che ha eseguito un'operazione API ExecuteStatement o BatchExecuteStatement possono agire sulla stessa istruzione con le operazioni API CancelStatement, DescribeStatement, GetStatementResult 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.

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

• 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. Se la frequenza della richiesta supera la quota, viene restituito ThrottlingException con codice di stato HTTP 400. Per rispondere alla limitazione (della larghezza di banda della rete), utilizza una strategia di ripetizione dei tentativi, come descritto in Retry behavior nella Guida di riferimento di AWS SDK e strumenti. Questa strategia viene implementata automaticamente per correggere gli errori di limitazione in alcuni SDK. AWS

  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 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 Secrets Manager

Con questo metodo, fornisci un segreto memorizzato in AWS Secrets Manager cui ha username epassword. 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 Memorizzazione delle credenziali del database in AWS Secrets Manager.

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.

Con questi metodi, 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

Al momento, l'API dati non supporta array di identificatori univoci universali (UUID).

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 esempioINSERT 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 \"FROM\"\n 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 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, vedereEsempi per l'API di dati di Amazon Redshift.

Il execute-statement AWS CLI comando seguente illustra il client-token parametro opzionale per l'idempotenza.

aws redshift-data execute-statement 
    --region us-west-2 
    --secret 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: Include un parametro o una combinazione di parametri non validi. Utilizza un'azione o una risorsa per la quale non si dispone delle autorizzazioni. Utilizza una risorsa che sta cambiando stato. 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 nella Documentazione di riferimento dell'API Amazon Redshift.