Amazon Redshift wird UDFs ab dem 1. November 2025 die Erstellung von neuem Python nicht mehr unterstützen. Wenn Sie Python verwenden möchten UDFs, erstellen Sie das UDFs vor diesem Datum liegende. Bestehendes Python UDFs wird weiterhin wie gewohnt funktionieren. Weitere Informationen finden Sie im Blog-Posting.

Die vorliegende Übersetzung wurde maschinell erstellt. Im Falle eines Konflikts oder eines Widerspruchs zwischen dieser übersetzten Fassung und der englischen Fassung (einschließlich infolge von Verzögerungen bei der Übersetzung) ist die englische Fassung maßgeblich.

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 Daten-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 es einen sicheren HTTP-Endpunkt und eine Integration mit AWSSDKs. Über den Endpunkt können Sie SQL-Anweisungen ausführen, ohne Verbindungen zu verwalten. Aufrufe der Data API erfolgen asynchron. Die Daten-API kann entweder in gespeicherten Anmeldeinformationen AWS Secrets Manager oder temporäre Datenbankanmeldeinformationen 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 istAWS Secrets Manager? im AWS Secrets ManagerBenutzerhandbuch. Sie können es auch AWS IAM Identity Center für die Autorisierung verwenden.

Mit der Daten-API können Sie mit Webservice-basierten Anwendungen, einschließlich AWS Lambda Amazon AI-Notebooks und, programmgesteuert auf Amazon SageMaker Redshift-Daten zugreifen. AWS Cloud9 Weitere Informationen zu diesen Anwendungen finden Sie AWS Lambdaunter 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.

Das folgende Beispiel zeigt 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 execute-statement AWS CLI Befehl 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 execute-statement AWS CLI Befehl auf, wobei der optionale session-keep-alive-seconds Parameter auf gesetzt ist. 2

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 execute-statement AWS CLI Befehl mit dem vom ersten Aufruf SessionId zurückgegebenen Befehl 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>
}