Amazon Redshift non supporterà più la creazione di nuovi Python a UDFs partire dal 1° novembre 2025. Se vuoi usare Python UDFs, crea la UDFs data precedente a quella data. Python esistente UDFs continuerà a funzionare normalmente. Per ulteriori informazioni, consulta il post del blog.

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'AWSSDK. Per ulteriori informazioni sulle operazioni dell’API dati, consulta la documentazione di riferimento dell’API dati Amazon Redshift.

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 suGestione dei segreti AWS, consulta What 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, consulta Amazon SageMaker AI e AWS Cloud9.

Per ulteriori informazioni sull’API dati, consulta 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:

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:

Scelta delle credenziali di autenticazione del database quando si richiama l'API dati di Amazon Redshift

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.

I valori stringa vengono passati al database Amazon Redshift e convertiti implicitamente in un tipo di dati del database.

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:

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.

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.

Per ulteriori informazioni sui codici di risposta di Amazon Redshift, consulta Errori comuni 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:

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": "<token>",
   "Records": [
        [
            {
                "longValue": 1
            }
        ]
    ],
   "TotalNumRows": <number>
}

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": "<token>",
    "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": <number>
}