Amazon Redshift unterstützt ab dem 1. November 2025 nicht mehr die Erstellung neuer Python-UDFs. Wenn Sie Python-UDFs verwenden möchten, erstellen Sie die UDFs vor diesem Datum. Bestehende Python-UDFs funktionieren weiterhin wie gewohnt. Weitere Informationen finden Sie im Blog-Posting.

Verwenden der Amazon Redshift Data API

Die Amazon Redshift Data API vereinfacht den Zugriff auf Ihr Amazon Redshift Data Warehouse, da keine Verwaltung von Datenbanktreibern, Verbindungen, Netzwerkkonfigurationen, Datenpufferung, Anmeldeinformationen usw. mehr erforderlich ist. Sie können SQL-Anweisungen mithilfe der Data-API-Operationen mit dem AWS-SDK ausführen. Weitere Informationen zu den Data-API-Operationen finden Sie in der Amazon-Redshift-Data-API-Referenz.

Die Data API erfordert keine persistente Verbindung zu Ihrer Datenbank. Stattdessen bietet sie einen sicheren HTTP-Endpunkt und Integration in AWS SDKs. Über den Endpunkt können Sie SQL-Anweisungen ausführen, ohne Verbindungen zu verwalten. Aufrufe der Data API erfolgen asynchron. Die Data API kann entweder Anmeldeinformationen, die in AWS Secrets Manager gespeichert sind, oder temporäre Datenbank-Anmeldeinformationen verwenden. Bei keiner der Autorisierungsmethoden müssen Sie Passwörter in den API-Aufrufen übergeben. Weitere Informationen zu AWS Secrets Manager finden Sie unter Was ist AWS Secrets Manager? im AWS Secrets Manager-Benutzerhandbuch. Sie können darüber hinaus auch AWS IAM Identity Center für die Autorisierung verwenden.

Mit der Data API können Sie mit Webservice-basierten Anwendungen wie AWS Lambda, Notebooks in Amazon SageMaker AI und AWS Cloud9 programmgesteuert auf Amazon-Redshift-Daten zugreifen. Weitere Informationen zu diesen Anwendungen finden Sie unter AWS Lambda, Amazon SageMaker AI und AWS Cloud9.

Weitere Informationen zur Data API finden Sie unter Get started with the Amazon Redshift Data API im AWSBig Data Blog.

Arbeiten mit der Amazon Redshift Data API

Bevor Sie die Amazon Redshift Data API verwenden, überprüfen Sie die folgenden Schritte:

Wichtige Punkte beim Aufrufen der Amazon Redshift Data API

Beachten Sie Folgendes, wenn Sie die Data API aufrufen:

Auswählen der Anmeldeinformationen für die Datenbankauthentifizierung beim Aufrufen der Amazon Redshift Data API

Zuordnen von JDBC-Datentypen beim Aufrufen der Amazon Redshift Data API

In der folgenden Tabelle sind den Datentypen, die Sie in Daten-API-Aufrufen angeben, JDBC-Datentypen (Java Database Connectivity) zugeordnet.

Zeichenfolgenwerte werden an die Amazon-Redshift-Datenbank übergeben und implizit in einen Datenbankdatentyp umgewandelt.

Ausführen von SQL-Anweisungen mit Parametern beim Aufrufen der Amazon Redshift Data API

Sie können den an die Datenbank-Engine übermittelten SQL-Text kontrollieren, indem Sie den Data-API-Vorgang mithilfe von Parametern für Teile der SQL-Anweisung aufrufen. Benannte Parameter bieten eine flexible Möglichkeit, Parameter zu übergeben, ohne sie im SQL-Text hart zu codieren. Sie helfen Ihnen, SQL-Text wiederzuverwenden und SQL-Injections-Probleme zu vermeiden.

Im folgenden Beispiel sehen Sie die benannten Parameter eines parameters-Felds eines execute-statement-AWS CLI-Befehls.

--parameters "[{\"name\": \"id\", \"value\": \"1\"},{\"name\": \"address\", \"value\": \"Seattle\"}]"

Beachten Sie Folgendes, wenn Sie benannte Parameter verwenden:

Ausführen von SQL-Anweisungen mit einem Idempotenz-Token beim Aufrufen der Amazon Redshift Data API

Wenn Sie eine ändernde API-Anfrage stellen, gibt die Anfrage in der Regel ein Ergebnis zurück, bevor die asynchronen Workflows der Operation abgeschlossen sind. Es können auch ein Timeout oder andere Serverprobleme auftreten, bevor Operationen abgeschlossen sind, obwohl die Anfrage bereits ein Ergebnis zurückgegeben hat. Dadurch lässt sich möglicherweise nur schwer feststellen, ob die Anfrage erfolgreich war oder nicht, und es werden möglicherweise mehrere Wiederholungsversuche vorgenommen, um sicherzustellen, dass die Operation erfolgreich abgeschlossen wird. Wenn die ursprüngliche Anfrage und die nachfolgenden Wiederholungsversuche jedoch erfolgreich sind, wird die Operation mehrmals abgeschlossen. Das bedeutet, dass Sie möglicherweise mehr Ressourcen aktualisieren als beabsichtigt.

Idempotenz stellt sicher, dass eine API-Anfrage nicht mehr als einmal abgeschlossen wird. Wenn bei einer idempotenten Anfrage die ursprüngliche Anfrage erfolgreich abgeschlossen wird, werden alle nachfolgenden Wiederholungen erfolgreich abgeschlossen, ohne dass weitere Aktionen ausgeführt werden. Die Data-API-Operationen ExecuteStatement und BatchExecuteStatement weisen den optionalen idempotenten Parameter ClientToken auf. Das ClientToken läuft nach 8 Stunden ab.

Der folgende AWS CLI-Befehl execute-statement veranschaulicht den optionalen client-token-Parameter für Idempotenz.

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                       

Die folgende Tabelle zeigt einige häufig vorkommende Antworten, die Sie auf idempotente API-Anfragen erhalten könnten, und stellt Empfehlungen zu Wiederholungsversuchen bereit.

Weitere Informationen zu den Amazon-Redshift-Antwortcodes finden Sie unter Häufige Fehler in der API-Referenz zu Amazon Redshift.

Ausführen von SQL-Anweisungen mit Sitzungswiederverwendung beim Aufrufen der Amazon Redshift Data API

Wenn Sie eine API-Anfrage zur Ausführung einer SQL-Anweisung stellen, wird die Sitzung, in der das SQL ausgeführt wird, normalerweise beendet, wenn die SQL-Anweisung beendet ist. Um die Sitzung für eine bestimmte Anzahl von Sekunden aktiv zu halten, verfügen die Data-API-Operationen ExecuteStatement und BatchExecuteStatement über einen optionalen Parameter SessionKeepAliveSeconds. In einem SessionId-Antwortfeld ist die Identität der Sitzung angegeben, die dann in nachfolgenden ExecuteStatement- und BatchExecuteStatement-Operationen verwendet werden kann. Bei nachfolgenden Aufrufen können Sie einen anderen SessionKeepAliveSeconds-Wert angeben, um die Leerlaufzeitüberschreitung zu ändern. Wenn SessionKeepAliveSeconds nicht geändert wird, bleibt die ursprüngliche Einstellung für die Leerlaufzeitüberschreitung bestehen. Beachten Sie Folgendes, wenn Sie die Sitzungswiederverwendung nutzen:

Um die SessionId abzurufen, die von Aufrufen der Operationen ExecuteStatement und BatchExecuteStatement verwendet wird, rufen Sie die Operationen DescribeStatement und ListStatements auf.

Das folgende Beispiel zeigt, wie die Parameter SessionKeepAliveSeconds und SessionId verwendet werden, um eine Sitzung aufrechtzuerhalten und wiederzuverwenden. Rufen Sie zunächst den AWS CLI-Befehl execute-statement auf, wobei der optionale Parameter session-keep-alive-seconds auf 2 gesetzt ist.

aws redshift-data execute-statement 
    --session-keep-alive-seconds 2 
    --sql "select 1" 
    --database dev 
    --workgroup-name mywg                     

Die Antwort enthält die Sitzungs-ID.

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

Rufen Sie dann den AWS CLI-Befehl execute-statement mit der vom ersten Aufruf zurückgegebenen SessionId auf. Geben Sie optional den Parameter session-keep-alive-seconds, der auf 10 gesetzt ist, an, um den Wert für die Leerlaufzeitüberschreitung zu ändern.

aws redshift-data execute-statement 
    --sql "select 1" 
    --session-id 5a254dc6-4fc2-4203-87a8-551155432ee4
    --session-keep-alive-seconds 10                  

Abrufen von Ergebnissen von SQL-Anweisungen

Je nach Ergebnisformat verwenden Sie unterschiedliche Daten-API-Operationen, um SQL-Ergebnisse abzurufen. Wenn Sie ExecuteStatement- und BatchExecuteStatement-Operationen aufrufen, können Sie angeben, ob die Ergebnisse als JSON oder CSV formatiert sein sollen. Wenn Sie nichts angeben, ist der Standardwert JSON. Verwenden Sie die Operation GetStatementResult, um JSON-Ergebnisse abzurufen. Verwenden Sie die Operation GetStatementResultV2, um CSV-Ergebnisse abzurufen.

Bei den im JSON-Format zurückgegebenen Ergebnissen handelt es sich um Datensätze, die Metadaten zu jeder Spalte enthalten. Jeder Datensatz liegt im JSON-Format vor. Die Antwort von GetStatementResult sieht beispielsweise ungefähr folgendermaßen aus:

{
   "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>
}

Bei den im CSV-Format zurückgegebenen Ergebnissen handelt es sich um Datensätze, die Metadaten zu jeder Spalte enthalten. Die Ergebnisse werden in 1-MB-Blöcken zurückgegeben, wobei in jedem Block eine beliebige Anzahl von Zeilen im CSV-Format gespeichert werden kann. Jede Anfrage gibt bis zu 15 MB an Ergebnissen zurück. Wenn die Ergebnisse mehr als 15 MB umfassen, wird ein Token für die nächste Seite zurückgegeben, um mit dem Abrufen der Ergebnisse fortzufahren. Die Antwort von GetStatementResultV2 sieht beispielsweise ungefähr folgendermaßen aus:

{
    "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>
}