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

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 Data di Amazon Redshift semplifica l'accesso al tuo 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'SDK. AWS Per ulteriori informazioni sulle operazioni dell'API Data, consulta Amazon Redshift Data API Reference.

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 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. È 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 Data, consulta Get started with the Amazon Redshift Data API nel 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: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 riutilizzo della sessione quando si chiama l'API Amazon Redshift Data

Quando si effettua 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, l'API Data ExecuteStatement e BatchExecuteStatement le operazioni dispongono di un SessionKeepAliveSeconds parametro opzionale. Un campo di SessionId risposta contiene l'identità della sessione che può quindi essere utilizzata nelle BatchExecuteStatement operazioni ExecuteStatement e nelle operazioni successive. Nelle chiamate successive è possibile specificarne un'altra SessionKeepAliveSeconds per modificare il tempo di timeout di inattività. Se il non SessionKeepAliveSeconds viene modificato, l'impostazione iniziale del timeout di inattività rimane. Quando utilizzate il riutilizzo della sessione, tenete presente quanto segue:

Per recuperare il SessionId che viene utilizzato dalle chiamate e dalle BatchExecuteStatement operazioni, dalle chiamate ExecuteStatement e dalle operazioni. DescribeStatement ListStatements

L'esempio seguente dimostra l'utilizzo dei SessionId parametri SessionKeepAliveSeconds and per mantenere attiva e riutilizzata una sessione. Innanzitutto, chiamate il execute-statement AWS CLI comando con il session-keep-alive-seconds parametro opzionale 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 di sessione.

{
    "WorkgroupName": "mywg",
    "CreatedAt": 1703022996.436,
    "Database": "dev",
    "DbUser": "awsuser",
    "Id": "07c5ffea-76d6-4786-b62c-4fe3ef529680",
    "SessionId": "5a254dc6-4fc2-4203-87a8-551155432ee4"
}

Quindi, chiama il execute-statement AWS CLI comando con il SessionId risultato della prima chiamata. E, facoltativamente, specifica il session-keep-alive-seconds parametro 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 Data API per recuperare i risultati SQL a seconda del formato dei risultati. Quando si effettuano chiamate ExecuteStatement e BatchExecuteStatement operazioni, è possibile specificare se i risultati sono formattati come JSON o CSV. Se non lo specifichi, l'impostazione predefinita è JSON. Per recuperare i risultati JSON, usa l'operazione. GetStatementResult Per recuperare i risultati CSV, usa 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>
}