Verwenden der Amazon Redshift Data API

Sie können über die integrierte Amazon Redshift Data API auf Ihre Amazon-Redshift-Datenbank zugreifen. Mithilfe dieser API können Sie mit Webservice-basierten Anwendungen, einschließlich AWS Lambda SageMaker Amazon-Notebooks und, auf Amazon Redshift-Daten zugreifen. AWS Cloud9 Weitere Informationen zu diesen Anwendungen finden Sie AWS Lambdaunter Amazon SageMaker und AWS Cloud9.

Die Data API erfordert keine persistente Verbindung zu Ihrer Datenbank. Stattdessen bietet es einen sicheren HTTP-Endpunkt und die Integration mit AWS SDKs. Über den Endpunkt können Sie SQL-Anweisungen ausführen, ohne Verbindungen zu verwalten. Aufrufe der Data API erfolgen asynchron.

Die Daten-API verwendet entweder in gespeicherten Anmeldeinformationen AWS Secrets Manager oder temporäre Datenbankanmeldeinformationen. 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.

Weitere Informationen zu den Data-API-Vorgängen finden Sie in der Amazon-Redshift-Data-API-Referenz.

Arbeiten mit der Amazon Redshift Data API

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

1. Ermitteln Sie, ob Sie als Aufrufer der Data API autorisiert sind. Weitere Informationen zur -Autorisierung finden Sie unter Autorisieren des Zugriffs auf die Amazon Redshift Data API.

2. Ermitteln Sie, ob Sie planen, die Data API mit Authentifizierungsanmeldeinformationen von Secrets Manager oder temporären Anmeldeinformationen aufzurufen. Weitere Informationen finden Sie unter Auswählen der Anmeldeinformationen für die Datenbankauthentifizierung beim Aufrufen der Amazon Redshift Data API.

3. Richten Sie ein Secret ein, wenn Sie Secrets Manager für die Authentifizierungsanmeldeinformationen verwenden. Weitere Informationen finden Sie unter Speichern von Datenbankanmeldedaten in AWS Secrets Manager.

4. Beachten Sie die Punkte und Einschränkungen, die beim Aufrufen der Data API zu berücksichtigen sind. Weitere Informationen finden Sie unter Wichtige Punkte beim Aufrufen der Amazon Redshift Data API.

5. Rufen Sie die Daten-API über AWS Command Line Interface (AWS CLI), über Ihren eigenen Code oder mithilfe des Abfrage-Editors in der Amazon Redshift Redshift-Konsole auf. Beispiele für das Aufrufen von der aus finden Sie AWS CLI unterAufrufen der Daten-API.

Wichtige Punkte beim Aufrufen der Amazon Redshift Data API

Beachten Sie Folgendes, wenn Sie die Data API aufrufen:

• Die Amazon Redshift Data API kann auf Datenbanken in von Amazon Redshift bereitgestellten Clustern und Redshift-Serverless-Arbeitsgruppen zugreifen. Eine Liste, AWS-Regionen wo die Redshift Data API verfügbar ist, finden Sie in den Endpunkten, die für die Redshift Data API aufgeführt sind. Allgemeine Amazon Web Services-Referenz

• Die maximale Dauer einer Abfrage beträgt 24 Stunden.

• Die maximale Anzahl aktiver Abfragen (STARTED- undSUBMITTED-Abfragen) pro Amazon-Redshift-Cluster beträgt 200.

• Die maximale Größe der Abfrageergebnisse beträgt 100 MB (nach Gzip-Komprimierung). Wenn ein Aufruf mehr als 100 MB an Antwortdaten zurückgibt, wird der Aufruf beendet.

• Die maximale Aufbewahrungszeit für Abfrageergebnisse beträgt 24 Stunden.

• Die maximale Größe von Abfrageanweisungen beträgt 100 KB.

• Die Data API ist für die Abfrage von Clustern mit einem Knoten und mehreren Knoten der folgenden Knotentypen verfügbar:

  • dc2.large

  • dc2.8xlarge

  • ds2.xlarge

  • ds2.8xlarge

  • ra3.xlplus

  • ra3.4xlarge

  • ra3.16xlarge

• Der Cluster muss sich in einer auf dem Amazon-VPC-Service basierenden Virtual Private Cloud (VPC) befinden.

• Standardmäßig können Benutzer mit derselben IAM-Rolle oder denselben IAM-Berechtigungen wie der Ausführer eines ExecuteStatement- oder BatchExecuteStatement-API-Vorgangs auf dieselbe Anweisung mit CancelStatement-, DescribeStatement-, GetStatementResult- und ListStatements-API-Vorgängen reagieren. Um auf dieselbe SQL-Anweisung eines anderen Benutzers reagieren zu können, muss der Benutzer die IAM-Rolle des Benutzers übernehmen können, der die SQL-Anweisung ausgeführt hat. Weitere Informationen zum Übernehmen einer Rolle finden Sie unter Autorisieren des Zugriffs auf die Amazon Redshift Data API.

• Die SQL-Anweisungen im Parameter Sqls der API-Operation BatchExecuteStatement werden als eine einzige Transaktion ausgeführt. Sie werden seriell in der Reihenfolge des Arrays ausgeführt. Nachfolgende SQL-Anweisungen werden erst gestartet, wenn die vorherige Anweisung im Array abgeschlossen ist. Wenn eine SQL-Anweisung fehlschlägt, wird die gesamte Arbeit zurückgesetzt, da die Anweisungen als eine Transaktion ausgeführt werden.

• Die maximale Aufbewahrungszeit für ein Client-Token, das in der API-Operation ExecuteStatement oder BatchExecuteStatement verwendet wird, beträgt 8 Stunden.

• Jede API in der Redshift-Daten-API verfügt über ein Kontingent von Transaktionen pro Sekunde, bevor Anforderungen gedrosselt werden. Informationen zu dem Kontingent finden Sie unter Kontingente für die Amazon-Redshift-Daten-API. Wenn die Anforderungsrate das Kontingent überschreitet, wird eine ThrottlingException mit dem HTTP-Statuscode: 400 zurückgegeben. Um auf die Drosselung zu reagieren, verwenden Sie eine Wiederholungsstrategie, wie unter Wiederholungsverhalten im Referenzhandbuch zu AWS -SDKs und Tools beschrieben. Diese Strategie wird in einigen SDKs automatisch implementiert, um Fehler zu drosseln. AWS

  Anmerkung

  Standardmäßig sind AWS Step Functions Wiederholungsversuche nicht aktiviert. Wenn Sie eine Redshift-Daten-API in einem Step-Functions-Zustandsautomat aufrufen müssen, fügen Sie den Idempotenzparameter ClientToken in Ihren Redshift-Daten-API-Aufruf ein. Der Wert für ClientToken muss auch bei Wiederholungsversuchen beibehalten werden. Im folgenden Beispielausschnitt einer Anforderung an die ExecuteStatement-API verwendet der Ausdruck States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7) eine intrinsische Funktion, um den UUID-Teil von $$.Execution.Id zu extrahieren, der für jede Ausführung des Zustandsautomats eindeutig ist. Weitere Informationen finden Sie unter Intrinsische Funktionen im AWS Step Functions -Entwicklerhandbuch.

  {
    "Database": "dev",
    "Sql": "select 1;",
    "ClusterIdentifier": "MyCluster",
    "ClientToken.$": "States.ArrayGetItem(States.StringSplit($$.Execution.Id, ':'), 7)"
  }

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

Wenn Sie die Data API aufrufen, verwenden Sie eine der folgenden Authentifizierungsmethoden für einige API-Vorgänge. Jede Methode erfordert eine andere Kombination von Parametern.

AWS Secrets Manager

Geben Sie bei dieser Methode den Wert secret-arn eines Geheimnisses an AWS Secrets Manager , in dem username und password gespeichert ist. Das angegebene Secret enthält Anmeldeinformationen zum Verbinden mit der von Ihnen angegebenen database. Wenn Sie eine Verbindung zu einem Cluster herstellen, geben Sie auch den Datenbanknamen an. Wenn Sie eine Clusterkennung (dbClusterIdentifier) angeben, muss diese mit der in dem Secret gespeicherten Clusterkennung übereinstimmen. Wenn Sie eine Verbindung zu einer Serverless-Arbeitsgruppe herstellen, geben Sie auch den Datenbanknamen an. Weitere Informationen finden Sie unter Speichern von Datenbankanmeldedaten in AWS Secrets Manager.

Temporäre Anmeldeinformationen

Wählen Sie bei dieser Methode eine der folgenden Optionen aus:

• Wenn Sie eine Verbindung zu einer Serverless-Arbeitsgruppe herstellen, geben Sie den Arbeitsgruppennamen und den Datenbanknamen an. Der Datenbankbenutzername wird von der IAM-Identität abgeleitet. Für arn:iam::123456789012:user:foo lautet der Datenbankbenutzername beispielsweise IAM:foo. Auch die Berechtigung zum Aufruf der redshift-serverless:GetCredentials-Operation ist erforderlich.

• Geben Sie die Clusterkennung und den Datenbanknamen an, wenn Sie eine Verbindung zu einem Cluster als IAM-Identität herstellen. Der Datenbankbenutzername wird von der IAM-Identität abgeleitet. Für arn:iam::123456789012:user:foo lautet der Datenbankbenutzername beispielsweise IAM:foo. Auch die Berechtigung zum Aufruf der redshift:GetClusterCredentialsWithIAM-Operation ist erforderlich.

• Geben Sie die Clusterkennung, den Datenbanknamen und den Namen des Datenbankbenutzers an, wenn Sie eine Verbindung zu einem Cluster als Datenbankbenutzer herstellen. Auch die Berechtigung zum Aufruf der redshift:GetClusterCredentials-Operation ist erforderlich. Hinweise dazu, wie Sie Datenbankgruppen beitreten, wenn Sie mit dieser Methode eine Verbindung herstellen, finden Sie unter Beitreten zu Datenbankgruppen beim Herstellen einer Verbindung mit einem Cluster.

Mit diesen Methoden können Sie auch einen region Wert angeben, der angibt, AWS-Region wo sich Ihre Daten befinden.

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.

JDBC-Datentyp	Daten-API-Datentyp
INTEGER, SMALLINT, BIGINT	LONG
FLOAT, REAL, DOUBLE	DOUBLE
DECIMAL	STRING
BOOLEAN, BIT	BOOLEAN
BLOB, BINARY, LONGVARBINARY, VARBINARY	BLOB
VARBINARY	STRING
CLOB	STRING
Andere Typen (einschließlich datums- und zeitbezogener Typen)	STRING

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

Anmerkung

Derzeit unterstützt die Data API keine Arrays von Universal Unique Identifiers (UUIDs).

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 execute-statement AWS CLI Befehlsfeldes.

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

Beachten Sie Folgendes, wenn Sie benannte Parameter verwenden:

• Benannte Parameter können nur verwendet werden, um Werte in SQL-Anweisungen zu ersetzen.

  • Sie können die Werte in einer INSERT-Anweisung, wie z. B. INSERT INTO mytable VALUES(:val1), ersetzen.

    Die benannten Parameter können in beliebiger Reihenfolge vorliegen und Parameter können mehrmals im SQL-Text verwendet werden. Die in einem vorherigen Beispiel gezeigte Parameteroption, die Werte 1 und Seattle werden in die Tabellenspalten id und address eingefügt. Im SQL-Text geben Sie die benannten Parameter wie folgt an:

    --sql "insert into mytable values (:id, :address)"

  • Sie können die Werte in einer Bedingungsklausel ersetzen, z. B. WHERE attr >= :val1, WHERE attr BETWEEN :val1 AND :val2 und HAVING COUNT(attr) > :val.

  • Sie können in einer SQL-Anweisung keine Spaltennamen ersetzen, wie z. B. SELECT column-name, ORDER BY column-name oder GROUP BY column-name.

    Die folgende SELECT-Anweisung schlägt beispielsweise aufgrund bei einer ungültigen Syntax fehl.

    --sql "SELECT :colname, FROM event" --parameters "[{\"name\": \"colname\", \"value\": \"eventname\"}]"

    Wenn Sie die Anweisung mit dem Syntaxfehler beschreiben (describe-statement-Operation), ersetzt der zurückgegebene QueryString nicht den Spaltennamen für den Parameter ("QueryString": "SELECT :colname, FROM event") und es wird ein Fehler gemeldet (ERROR: Syntaxfehler bei oder nahe \"FROM\"\n Position: 12).

  • Sie können in einer Aggregatfunktion keine Spaltennamen ersetzen, wie z. B. COUNT(column-name), AVG(column-name) oder SUM(column-name).

  • Sie können Spaltennamen in einer JOIN-Klausel nicht ersetzen.

• Wenn die SQL-Anweisung ausgeführt wird, werden Daten implizit in einen Datentyp umgewandelt. Weitere Informationen zur Datentypumwandlung finden Sie unter Datentypen im Datenbankentwicklerhandbuch zu Amazon Redshift.

• Sie können einen Wert nicht auf NULL setzen. Die Data API interpretiert ihn als Literalzeichenfolge NULL. Im folgenden Beispiel wird id durch die Literalzeichenfolge null ersetzt, nicht durch den SQL-NULL-Wert.

  --parameters "[{\"name\": \"id\", \"value\": \"null\"}]"

• Sie können keinen Wert mit Länge null festlegen. Die SQL-Anweisung der Data API schlägt fehl. Im folgenden Beispiel wird versucht, id mit einem Wert der Länge null festzulegen, was zum Fehlschlagen der SQL-Anweisung führt.

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

• Sie können einen Tabellennamen in der SQL-Anweisung nicht mit einem Parameter festlegen. Die Data API folgt der Regel des JDBC-PreparedStatement.

• Die Ausgabe der Operation describe-statement gibt die Abfrageparameter einer SQL-Anweisung zurück.

• Nur der execute-statement-Vorgang unterstützt SQL-Anweisungen mit Parametern.

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.

Wichtig

Wenn Sie von einem AWS SDK aus aufrufen ExecuteStatement und BatchExecuteStatement Operationen ausführen, generiert es automatisch ein Client-Token, das bei einem erneuten Versuch verwendet wird. In diesem Fall empfehlen wir, den Parameter client-token nicht mit den Operationen ExecuteStatement und BatchExecuteStatement zu verwenden. Sehen Sie CloudTrail sich das Protokoll an, um das ClientToken zu sehen. Ein Beispiel für ein CloudTrail Protokoll finden Sie unterAmazon-Redshift-Daten-API – Beispiele.

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

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                       

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

Antwort	Empfehlung	Kommentare
200 (OK)	Nicht erneut versuchen	Die ursprüngliche Anfrage wurde erfolgreich abgeschlossen. Alle nachfolgenden Wiederholungsversuche werden als erfolgreich zurückgegeben.
Antwortcodes der Serie 400	Nicht erneut versuchen	Es liegt eins der folgenden Probleme mit der Anfrage vor: Sie enthält einen Parameter oder eine Parameterkombination, der/die nicht gültig ist. Sie verwendet eine Aktion oder Ressource, für die Sie keine Berechtigungen haben. Sie verwendet eine Ressource, deren Status sich gerade ändert. Wenn die Anfrage eine Ressource umfasst, deren Status sich gerade ändert, könnte ein erneuter Anfrageversuch möglicherweise erfolgreich sein.
Antwortcodes der Serie 500	Erneut versuchen	Der Fehler wird durch ein AWS serverseitiges Problem verursacht und ist im Allgemeinen vorübergehend. Wiederholen Sie die Anfrage mit einer geeigneten Backoff-Strategie.

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