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 RDS-Daten-API
Mithilfe der RDS-Daten-API (Daten-API) können Sie mit einer Webservices-Schnittstelle zu Ihrem Aurora-DB-Cluster arbeiten. Die Daten-API erfordert keine persistente Verbindung zum DB-Cluster. 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.
Alle Aufrufe der Data API sind synchron. Standardmäßig tritt eine Zeitüberschreitung für einen Aufruf ein, wenn die Verarbeitung nicht innerhalb von 45 Sekunden abgeschlossen wird. Sie können jedoch eine SQL-Anweisung weiter ausführen, wenn eine Zeitüberschreitung für den Aufruf eintritt, indem Sie den Parameter continueAfterTimeout verwenden. Ein Beispiel finden Sie unter Ausführen einer SQL-Transaktion.
Benutzer müssen keine Anmeldeinformationen mit Aufrufen an die Data API übergeben, da die Data API Datenbankanmeldeinformationen verwendet, die in gespeichert sindAWS Secrets Manager. Um Anmeldeinformationen in Secrets Manager zu speichern, müssen Benutzer über die entsprechenden Berechtigungen zur Verwendung von Secrets Manager sowie der Daten-API verfügen. Weitere Informationen zum Autorisieren von Benutzern finden Sie unter Autorisieren des Zugriffs auf die RDS-Daten-API.
Sie können die Daten-API auch verwenden, um Amazon Aurora in andere AWS Anwendungen wie AWS Lambda, AWS AppSyncund zu integrierenAWS Cloud9. Die Daten-API bietet eine sicherere Möglichkeit zur Verwendung von AWS Lambda. Sie können damit auf Ihr DB-Cluster zugreifen, ohne eine Lambda-Funktion für den Zugriff auf Ressourcen in einer Virtual Private Cloud (VPC) konfigurieren zu müssen. Weitere Informationen finden Sie unter AWS Lambda
Sie können die Daten-API aktivieren, wenn Sie den Aurora-DB-Cluster erstellen. Sie können die Konfiguration später auch ändern. Weitere Informationen finden Sie unter Aktivieren der RDS-Daten-API.
Nachdem Sie die Daten-API aktiviert haben, können Sie auch den Abfrage-Editor verwenden, um Ad-hoc-Abfragen auszuführen, ohne ein Abfragetool für den Zugriff auf Aurora in einer VPC zu konfigurieren. Weitere Informationen finden Sie unter Arbeiten mit dem Abfrage-Editor.
Themen
- Verfügbarkeit von Regionen und Versionen
- Einschränkungen bei der RDS-Daten-API
- Vergleich der RDS-Daten-API mit Serverless v2 und bereitgestelltem und Aurora Serverless v1
- Autorisieren des Zugriffs auf die RDS-Daten-API
- Aktivieren der RDS-Daten-API
- Erstellen eines Amazon-VPC-Endpunkts für die RDS-Daten-API (AWS PrivateLink)
- Aufrufen der RDS-Daten-API
- Verwenden der Java-Clientbibliothek für die RDS-Daten-API
- Verarbeitung von Abfrageergebnissen im JSON-Format
- Fehlerbehebung bei Problemen mit der RDS-Daten-API
- Protokollieren von RDS-Daten-API-Aufrufen mit AWS CloudTrail
Verfügbarkeit von Regionen und Versionen
Informationen zu den Regionen und Engine-Versionen, die für die Daten-API verfügbar sind, finden Sie in den folgenden Abschnitten.
| Cluster-Typ | Verfügbarkeit von Regionen und Versionen |
|---|---|
Von Aurora PostgreSQL bereitgestellt und Serverless v2 |
Daten-API mit Aurora PostgreSQL Serverless v2 und bereitgestellt |
Aurora PostgreSQL Serverless v1 |
|
Aurora MySQL Serverless v1 |
Anmerkung
Derzeit ist die Daten-API für von Aurora MySQL bereitgestellte oder Serverless v2-DB-Cluster nicht verfügbar.
Wenn Sie kryptografische Module benötigen, die von FIPS 140-2 validiert werden, wenn Sie über eine Befehlszeilenschnittstelle oder eine API auf die Daten-API zugreifen, verwenden Sie einen FIPS-Endpunkt. Weitere Informationen über verfügbare FIPS-Endpunkte finden Sie unter Federal Information Processing Standard (FIPS) 140-2
Einschränkungen bei der RDS-Daten-API
Die RDS-Daten-API (Daten-API) hat die folgenden Einschränkungen:
Sie können Daten-API-Abfragen nur auf Writer-Instances in einem DB-Cluster ausführen. Writer-Instances können jedoch sowohl Schreib- als auch Leseabfragen akzeptieren.
Mit globalen Aurora-Datenbanken können Sie die Daten-API sowohl auf primären als auch auf sekundären DB-Clustern aktivieren. Bis ein sekundärer Cluster jedoch zum primären Cluster hochgestuft wird, hat er keine Writer-Instance. Daher schlagen Daten-API-Abfragen, die Sie an den sekundären senden, fehl. Nachdem eine hochgestufte sekundäre Instance über eine verfügbare Writer-Instance verfügt, sollten Daten-API-Abfragen auf dieser DB-Instance erfolgreich sein.
Performance Insights unterstützt nicht die Überwachung von Datenbankabfragen, die Sie mit der Daten-API durchführen.
Die Daten-API wird in T DB-Instance-Klassen nicht unterstützt.
Für Aurora PostgreSQL Serverless v2 und bereitgestellte DB-Cluster unterstützt die RDS-Daten-API keine Aufzählungstypen. Eine Liste der unterstützten Typen finden Sie unter Vergleich der RDS-Daten-API mit Serverless v2 und bereitgestelltem und Aurora Serverless v1.
Für Datenbanken von Aurora PostgreSQL Version 14 und höher unterstützt die Daten-API nur scram-sha-256 für die Passwortverschlüsselung.
Vergleich der RDS-Daten-API mit Serverless v2 und bereitgestelltem und Aurora Serverless v1
In der folgenden Tabelle werden die Unterschiede zwischen der RDS-Daten-API (Daten-API) mit Aurora PostgreSQL Serverless v2 und bereitgestellten DB-Clustern und Aurora Serverless v1 DB-Clustern beschrieben.
| Unterschied | Aurora PostgreSQL Serverless v2 und bereitgestellt | Aurora Serverless v1 |
|---|---|---|
| Maximale Anzahl von Anforderungen pro Sekunde | Unbegrenzt | 1.000 |
| Aktivieren oder Deaktivieren der Daten-API für eine vorhandene Datenbank mithilfe der RDS-API oder AWS CLI |
|
|
| CloudTrail -Ereignisse | Ereignisse aus Daten-API-Aufrufen sind Datenereignisse. Diese Ereignisse werden standardmäßig automatisch in einem Trail ausgeschlossen. Weitere Informationen finden Sie unter Einschließen von Daten-API-Ereignissen in einen - AWS CloudTrail Trail. | Ereignisse aus Daten-API-Aufrufen sind Verwaltungsereignisse. Diese Ereignisse werden standardmäßig automatisch in einen Trail aufgenommen. Weitere Informationen finden Sie unter Ausschließen von Daten-API-Ereignissen aus einem - AWS CloudTrail Trail (Aurora Serverless v1nur ). |
| Unterstützung für mehrere Anweisungen | Multistatements werden nicht unterstützt. In diesem Fall löst die Daten-API ausValidationException: Multistatements aren't supported. |
Für Aurora PostgreSQL geben Multistatements nur die erste Abfrageantwort zurück. Für Aurora MySQL werden mehrzeilige Anweisungen nicht unterstützt. |
| BatchExecuteStatement | Das generierte Feldobjekt im Aktualisierungsergebnis ist leer. | Das generierte Feldobjekt im Aktualisierungsergebnis enthält eingefügte Werte. |
| ExecuteSQL | Nicht unterstützt | Als veraltet gekennzeichnet |
| ExecuteStatement |
Die Daten-API unterstützt einige Datentypen wie geometrische und monetäre Typen nicht. In diesem Fall löst die Daten-API aus Es werden nur die folgenden Typen unterstützt:
Es werden nur die folgenden Array-Typen unterstützt:
|
ExecuteStatement unterstützt das Abrufen von multidimentären Array-Spalten und allen erweiterten Datentypen. |
Autorisieren des Zugriffs auf die RDS-Daten-API
Benutzer können RDS Data API (Data API)-Operationen nur aufrufen, wenn sie dazu autorisiert sind. Sie können einem Benutzer die Berechtigung zur Verwendung der Daten-API erteilen, indem Sie eine AWS Identity and Access Management (IAM)-Richtlinie anfügen, die seine Berechtigungen definiert. Sie können die Richtlinie auch einer Rolle anfügen, wenn Sie IAM-Rollen verwenden. Eine von AWS verwaltete Richtlinie, AmazonRDSDataFullAccess, enthält Berechtigungen für die Daten-API.
Die Richtlinie AmazonRDSDataFullAccess enthält auch Berechtigungen für den Abruf des Werts für einen geheimen Schlüssel aus AWS Secrets Manager für den Benutzer. Benutzer müssen Secrets Manager verwenden, um Secrets zu speichern, die sie in ihren Aufrufen der Daten-API verwenden können. Die Verwendung von Secrets bedeutet, dass Benutzer keine Datenbankanmeldeinformationen für die Ressourcen einschließen müssen, auf die sie in ihren Aufrufen der Daten-API abzielen. Die Daten-API ruft Secrets Manager transparent auf, wodurch die Anforderung des Secrets durch den Benutzer zugelassen (oder abgelehnt) wird. Informationen zum Einrichten von Secrets zur Verwendung mit der Daten-API finden Sie unter Speichern von Datenbankanmeldeinformationen in AWS Secrets Manager.
Die AmazonRDSDataFullAccess Richtlinie bietet vollständigen Zugriff (über die Daten-API) auf -Ressourcen. Sie können den Geltungsbereich einschränken, indem Sie eigene Richtlinien definieren, die den Amazon-Ressourcennamen (ARN) einer Ressource angeben.
Die folgende Richtlinie zeigt beispielsweise ein Beispiel für die mindestens erforderlichen Berechtigungen für einen Benutzer für den Zugriff auf die Data API für den DB-Cluster, der durch seinen ARN identifiziert wird. Die Richtlinie enthält die nötigen Berechtigungen, um auf Secrets Manager zuzugreifen und die Autorisierung für die DB-Instance für den Benutzer zu erhalten.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "SecretsManagerDbCredentialsAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*" }, { "Sid": "RDSDataServiceAccess", "Effect": "Allow", "Action": [ "rds-data:BatchExecuteStatement", "rds-data:BeginTransaction", "rds-data:CommitTransaction", "rds-data:ExecuteStatement", "rds-data:RollbackTransaction" ], "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod" } ] }
Sie sollten für das Element „Ressourcen“ in Ihren Richtlinienanweisungen (wie im Beispiel gezeigt) einen spezifischen ARN anstelle eines Platzhalters (*) verwenden.
Arbeiten mit der Tag-basierten Autorisierung
RDS Data API (Daten-API) und Secrets Manager unterstützen beide die Tag-basierte Autorisierung. Tags sind Schlüssel-Wert-Paare, die eine Ressource, z. B. einen RDS-Cluster, mit einem zusätzlichen Zeichenfolgenwert kennzeichnen, z. B.
environment:productionenvironment:development
Sie können auf Ihre Ressourcen Tags zum Zweck der Kostenzuweisung, der Ausführungsunterstützung, der Zugriffskontrolle und zu vielen weiteren Zwecken anwenden. (Wenn Sie noch keine Tags für Ihre Ressourcen anwenden und Tags anwenden möchten, finden Sie weitere Informationen unter Markieren von Amazon RDS-Ressourcen.) Sie können die Tags in Ihren Richtlinienanweisungen verwenden, um den Zugriff auf die RDS-Cluster einzuschränken, die mit diesen Tags gekennzeichnet sind. Ein Aurora-DB-Cluster könnte beispielsweise Tags besitzen, die die Umgebung als Produktions- oder Entwicklungsumgebung kennzeichnen.
Das folgende Beispiel zeigt, wie Sie in Ihren Richtlinienanweisungen Tags verwenden können. Diese Anweisung erfordert, dass sowohl der Cluster als auch der in der Daten-API-Anforderung übergebene Schlüssel das Tag environment:production enthalten.
So wird die Richtlinie angewendet: Wenn ein Benutzer einen Aufruf über die Daten-API tätigt, wird die Anforderung an den Service gesendet. Die Daten-API überprüft zunächst, ob der in der Anforderung übergebene Cluster-ARN mit markiert istenvironment:production. Anschließend wird Secrets Manager aufgerufen, um den Wert des Geheimnisses des Benutzers in der Anforderung abzurufen. Secrets Manager überprüft auch, ob das Geheimnis des Benutzers mit environment:production markiert ist. Wenn ja, verwendet die Daten-API den abgerufenen Wert für das DB-Passwort des Benutzers. Wenn dieser ebenfalls korrekt ist, wird die Daten-API-Anforderung für den Benutzer erfolgreich aufgerufen.
{ "Version": "2012-10-17", "Statement": [ { "Sid": "SecretsManagerDbCredentialsAccess", "Effect": "Allow", "Action": [ "secretsmanager:GetSecretValue" ], "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*", "Condition": { "StringEquals": { "aws:ResourceTag/environment": [ "production" ] } } }, { "Sid": "RDSDataServiceAccess", "Effect": "Allow", "Action": [ "rds-data:*" ], "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*", "Condition": { "StringEquals": { "aws:ResourceTag/environment": [ "production" ] } } } ] }
Das Beispiel zeigt separate Aktionen für rds-data und secretsmanager für Data API und Secrets Manager. Sie können jedoch Aktionen kombinieren und Tag-Bedingungen auf viele verschiedene Arten definieren, um Ihre spezifischen Anwendungsfälle zu unterstützen. Weitere Informationen finden Sie unter Verwenden identitätsbasierter Richtlinien (IAM-Richtlinien) für Secrets Manager.
Im Element „Bedingung“ der Richtlinie können Sie Tag-Schlüssel aus den folgenden Optionen auswählen:
aws:TagKeysaws:ResourceTag/${TagKey}
Weitere Informationen zu Ressourcen-Tags und zur Verwendung von aws:TagKeys finden Sie unter Steuern des Zugriffs auf AWS-Ressourcen über Ressourcen-Tags.
Anmerkung
Sowohl die Daten-API als auch AWS Secrets Managerautorisieren Benutzer. Wenn Sie nicht für alle in einer Richtlinie definierten Aktionen Berechtigungen besitzen, erhalten Sie den Fehler AccessDeniedException.
Speichern von Datenbankanmeldeinformationen in AWS Secrets Manager
Wenn Sie die RDS-Daten-API (Daten-API) aufrufen, übergeben Sie Anmeldeinformationen für den Aurora-DB-Cluster, indem Sie ein Secret in Secrets Manager verwenden. Zum Übermitteln der Anmeldeinformationen auf diese Weise geben Sie den Namen des Secrets oder den Amazon-Ressourcennamen (ARN) des Secrets an.
So speichern Sie DB-Cluster-Anmeldeinformationen in einem Secret
-
Sie können in Secrets Manager einen geheimen Schlüssel erstellen, der Anmeldeinformationen für den Aurora-DB-Cluster enthält.
Anweisungen finden Sie unter Erstellen eines Datenbank-Secrets im AWS Secrets Manager-Benutzerhandbuch.
-
Sie können die Details des von Ihnen erstellten geheimen Schlüssel über die Secrets Manager-Konsole oder den
aws secretsmanager describe-secret-Befehl AWS CLI anzeigen.Notieren Sie sich den Namen und den ARN des Secrets. Sie können sie in Aufrufen der Daten-API verwenden.
Weitere Informationen zur Verwendung von Secrets Manager finden Sie im AWSSecrets-Manager-Benutzerhandbuch.
Informationen dazu, wie Amazon Aurora die Identitäts- und Zugriffsverwaltung steuert, finden Sie unter So funktioniert Amazon Aurora mit IAM.
Informationen zum Erstellen einer IAM-Richtlinie finden Sie unter Erstellen von IAM-Richtlinien im IAM-Benutzerhandbuch. Informationen zum Hinzufügen einer IAM-Richtlinie zu einem Benutzer finden Sie im Abschnitt Hinzufügen und Entfernen von IAM-Identitätsberechtigungen im IAM-Benutzerhandbuch.
Aktivieren der RDS-Daten-API
Um die RDS-Daten-API (Daten-API) zu verwenden, aktivieren Sie sie für Ihren Aurora-DB-Cluster. Sie können die Daten-API aktivieren, wenn Sie den DB-Cluster erstellen oder ändern.
Anmerkung
Für Aurora PostgreSQL wird die Daten-API mit Aurora Serverless v2, Aurora Serverless v1und bereitgestellten Datenbanken unterstützt. Für Aurora MySQL wird die Daten-API nur mit Aurora Serverless v1 Datenbanken unterstützt.
Themen
Aktivieren der RDS-Daten-API beim Erstellen einer Datenbank
Während Sie eine Datenbank erstellen, die die RDS-Daten-API (Data API) unterstützt, können Sie diese Funktion aktivieren. In den folgenden Verfahren wird beschriebenAWS Management Console, wie Sie dies tun, wenn Sie die AWS CLI, die oder die RDS-API verwenden.
Um die Daten-API beim Erstellen eines DB-Clusters zu aktivieren, aktivieren Sie das Kontrollkästchen Aktivieren der RDS-Daten-API im Abschnitt Konnektivität der Seite Datenbank erstellen, wie im folgenden Screenshot.
Anweisungen zum Erstellen einer Datenbank finden Sie im Folgenden:
Für Aurora PostgreSQL Serverless v2 und bereitgestellte Datenbanken – Erstellen eines Amazon Aurora-DB Clusters
Für Aurora Serverless v1 – Erstellen eines Aurora Serverless v1-DB Clusters
Um die Daten-API zu aktivieren, während Sie einen Aurora-DB-Cluster erstellen, führen Sie den create-db-cluster AWS CLI Befehl mit der --enable-http-endpoint Option aus.
Im folgenden Beispiel wird ein DB-Cluster von Aurora PostgreSQL mit aktivierter Daten-API erstellt.
Für Linux, macOSoder Unix:
aws rds create-db-cluster \ --db-cluster-identifiermy_pg_cluster\ --engine aurora-postgresql \ --enable-http-endpoint
Windows:
aws rds create-db-cluster ^ --db-cluster-identifiermy_pg_cluster^ --engine aurora-postgresql ^ --enable-http-endpoint
Um die Daten-API zu aktivieren, während Sie einen Aurora-DB-Cluster erstellen, verwenden Sie die CreateDBCluster-Operation, wobei der Wert des EnableHttpEndpoint Parameters auf festgelegt isttrue.
Aktivieren der RDS-Daten-API für eine vorhandene Datenbank
Sie können einen DB-Cluster ändern, der die RDS Data API (Data API) unterstützt, um diese Funktion zu aktivieren oder zu deaktivieren.
Themen
Aktivieren oder Deaktivieren der Daten-API (Aurora PostgreSQL Serverless v2 und bereitgestellt)
Gehen Sie wie folgt vor, um die Daten-API für Aurora PostgreSQL Serverless v2 und bereitgestellte Datenbanken zu aktivieren oder zu deaktivieren. Um die Daten-API für Aurora Serverless v1 Datenbanken zu aktivieren oder zu deaktivieren, verwenden Sie die Verfahren unter Aktivieren oder Deaktivieren der Daten-API (Aurora Serverless v1nur ).
Sie können die Daten-API mithilfe der RDS-Konsole für einen DB-Cluster aktivieren oder deaktivieren, der diese Funktion unterstützt. Öffnen Sie dazu die Cluster-Detailseite der Datenbank, in der Sie die Daten-API aktivieren oder deaktivieren möchten, und navigieren Sie auf der Registerkarte Konnektivität und Sicherheit zum Abschnitt RDS-Daten-API. In diesem Abschnitt wird der Status der Daten-API angezeigt und Sie können sie aktivieren oder deaktivieren.
Der folgende Screenshot zeigt, dass die RDS-Daten-API nicht aktiviert ist.
Um die Daten-API für eine vorhandene Datenbank zu aktivieren oder zu deaktivieren, führen Sie den disable-http-endpoint AWS CLI Befehl enable-http-endpoint oder aus und geben Sie den ARN Ihres DB-Clusters an.
Im folgenden Beispiel wird die Daten-API aktiviert.
Für Linux, macOSoder Unix:
aws rds enable-http-endpoint \ --resource-arncluster_arn
Windows:
aws rds enable-http-endpoint ^ --resource-arncluster_arn
Um die Daten-API für eine vorhandene Datenbank zu aktivieren oder zu deaktivieren, verwenden Sie die DisableHttpEndpoint Operationen EnableHttpEndpoint und .
Aktivieren oder Deaktivieren der Daten-API (Aurora Serverless v1nur )
Gehen Sie wie folgt vor, um die Daten-API für vorhandene Aurora Serverless v1 Datenbanken zu aktivieren oder zu deaktivieren. Um die Daten-API für Aurora PostgreSQL Serverless v2 und bereitgestellte Datenbanken zu aktivieren oder zu deaktivieren, verwenden Sie die Verfahren unter Aktivieren oder Deaktivieren der Daten-API (Aurora PostgreSQL Serverless v2 und bereitgestellt).
Wenn Sie einen -Aurora Serverless v1DB-Cluster ändern, aktivieren Sie die Daten-API im Abschnitt Konnektivität der RDS-Konsole.
Der folgende Screenshot zeigt die aktivierte Daten-API beim Ändern eines Aurora-DB-Clusters.
Anweisungen zum Ändern eines -DBAurora Serverless v1-Clusters finden Sie unter Ändern eines Aurora Serverless v1-DB-Clusters.
Um die Daten-API zu aktivieren oder zu deaktivieren, führen Sie den modify-db-cluster AWS CLI Befehl mit der --enable-http-endpoint oder aus--no-enable-http-endpoint, falls zutreffend.
Im folgenden Beispiel wird die Daten-API auf aktiviertsample-cluster.
Für Linux, macOSoder Unix:
aws rds modify-db-cluster \ --db-cluster-identifier sample-cluster \ --enable-http-endpoint
Windows:
aws rds modify-db-cluster ^ --db-cluster-identifier sample-cluster ^ --enable-http-endpoint
Um die Daten-API zu aktivieren, verwenden Sie die Operation ModifyDBCluster und setzen Sie den Wert von EnableHttpEndpoint auf true oder false, falls zutreffend.
Erstellen eines Amazon-VPC-Endpunkts für die RDS-Daten-API (AWS PrivateLink)
Amazon VPC ermöglicht Ihnen das Starten von AWS-Ressourcen wie Aurora-DB-Clustern und Anwendungen in einer virtuellen privaten Cloud (VPC). AWS PrivateLink stellt eine hoch sichere, private Konnektivität zwischen VPCs und AWS-Services im Amazon-Netzwerk bereit. Mit AWS PrivateLink können Sie Amazon-VPC-Endpunkte erstellen, mit denen Sie eine Verbindung zu Services über verschiedene Konten und VPCs basierend auf Amazon VPC herstellen können. Weitere Informationen über AWS PrivateLink finden Sie unter VPC-Endpunktservices (AWS PrivateLink) im Amazon-Virtual-Private-Cloud-Benutzerhandbuch.
Sie können die RDS-Daten-API (Data API) mit Amazon-VPC-Endpunkten aufrufen. Die Verwendung eines Amazon-VPC-Endpunkts hält den Datenverkehr zwischen Anwendungen in Ihrer Amazon VPC und der Daten-API im AWS Netzwerk aufrecht, ohne öffentliche IP-Adressen zu verwenden. Amazon-VPC-Endpunkte können Ihnen dabei helfen, Compliance- und behördliche Anforderungen im Zusammenhang mit der Einschränkung der öffentlichen Internetkonnektivität zu erfüllen. Wenn Sie beispielsweise einen Amazon-VPC-Endpunkt verwenden, können Sie den Datenverkehr zwischen einer Anwendung, die auf einer Amazon EC2-Instance ausgeführt wird, und der Daten-API in den VPCs, die sie enthalten, beibehalten.
Nachdem Sie den Amazon VPC-Endpunkt erstellt haben, können Sie ihn verwenden, ohne Code- oder Konfigurationsänderungen in der Anwendung vorzunehmen.
So erstellen Sie einen Amazon-VPC-Endpunkt für die Daten-API
Melden Sie sich bei der AWS Management Console an und öffnen Sie die Amazon-VPC-Konsole unter https://console.aws.amazon.com/vpc/
. -
Wählen Sie Endpunkte und dann Endpunkt erstellen aus.
-
Wählen Sie auf der Seite Create Endpoint (Endpunkt erstellen) für Service category (Servicekategorie) die Option AWS-Services aus. Wählen Sie für Servicename rds-data aus.
-
Wählen Sie für VPC die VPC aus, in der der Endpunkt erstellt werden soll.
Wählen Sie die VPC aus, die die Anwendung enthält, die Daten-API-Aufrufe ausführt.
-
Wählen Sie für Subnetze das Subnetz für jede Availability Zone (AZ) aus, die vom AWS-Service verwendet wird, auf dem Ihre Anwendung ausgeführt wird.
Um einen Amazon VPC-Endpunkt zu erstellen, geben Sie den privaten IP-Adressbereich an, in dem auf den Endpunkt zugegriffen werden soll. Wählen Sie dazu das Subnetz für jede Availability Zone aus. Dadurch wird der VPC-Endpunkt auf den privaten IP-Adressbereich beschränkt, der für jede Availability Zone spezifisch ist. Außerdem wird in jeder Availability Zone ein Amazon VPC-Endpunkt erstellt.
-
Wählen Sie für DNS-Namen aktivieren die Option Für diesen Endpunkt aktivieren aus.
Private DNS löst den standardmäßigen DNS-Hostnamen der Daten-API (
https://rds-data.) in die privaten IP-Adressen auf, die mit dem für Ihren Amazon VPC-Endpunkt spezifischen DNS-Hostnamen verknüpft sind. Daher können Sie über die AWS CLI oder AWS SDKs auf den VPC-Endpunkt der Daten-API zugreifen, ohne Code- oder Konfigurationsänderungen vorzunehmen, um die Endpunkt-URL der Daten-API zu aktualisieren.region.amazonaws.com -
Wählen Sie für Sicherheitsgruppe eine Sicherheitsgruppe aus, die dem Amazon VPC-Endpunkt zugeordnet werden soll.
Wählen Sie die Sicherheitsgruppe aus, die den Zugriff auf den AWS-Service ermöglicht, auf dem Ihre Anwendung ausgeführt wird. Wenn beispielsweise eine Amazon EC2-Instance Ihre Anwendung ausführt, wählen Sie die Sicherheitsgruppe aus, die den Zugriff auf die Amazon EC2-Instance ermöglicht. Mit der Sicherheitsgruppe können Sie den Datenverkehr zum Amazon VPC-Endpunkt von Ressourcen in Ihrer VPC steuern.
-
Wählen Sie unter Richtlinie die Option Voller Zugriff aus, damit jeder innerhalb der Amazon VPC über diesen Endpunkt auf die Daten-API zugreifen kann. Oder wählen Sie Benutzerdefiniert aus, um eine Richtlinie anzugeben, die den Zugriff einschränkt.
Wenn Sie Benutzerdefiniert auswählen, geben Sie die Richtlinie im Tool zur Richtlinienerstellung ein.
-
Wählen Sie Create endpoint.
Nachdem der Endpunkt erstellt wurde, wählen Sie den Link in der AWS Management Console aus, um die Endpunktdetails anzuzeigen.
Auf der Registerkarte Details des Endpunkts werden die DNS-Hostnamen angezeigt, die beim Erstellen des Amazon VPC-Endpunkts generiert wurden.
Sie können den Standardendpunkt (rds-data.) oder einen der VPC-spezifischen Endpunkte verwenden, um die Daten-API innerhalb der Amazon VPC aufzurufen. Der standardmäßige Daten-API-Endpunkt leitet automatisch an den Amazon VPC-Endpunkt weiter. Dieses Routing tritt auf, weil der private DNS-Hostname beim Erstellen des Amazon VPC-Endpunkts aktiviert wurde.region.amazonaws.com
Wenn Sie einen Amazon-VPC-Endpunkt in einem Daten-API-Aufruf verwenden, verbleibt der gesamte Datenverkehr zwischen Ihrer Anwendung und der Daten-API in den Amazon-VPCs, die sie enthalten. Sie können einen Amazon VPC-Endpunkt für jeden Typ von Daten-API-Aufruf verwenden. Informationen zum Aufrufen der Data API finden Sie unter Aufrufen der RDS-Daten-API.
Aufrufen der RDS-Daten-API
Wenn die RDS-Daten-API (Daten-API) auf Ihrem Aurora-DB-Cluster aktiviert ist, können Sie SQL-Anweisungen auf dem Aurora-DB-Cluster mithilfe der Daten-API oder der ausführenAWS CLI. Die Daten-API unterstützt die von den -AWSSDKs unterstützten Programmiersprachen. SDKs Weitere Informationen finden Sie unter Tools zum Aufbauen AWS
Anmerkung
Derzeit unterstützt die Daten-API keine Arrays von Universal Unique Identifiers (UUIDs ).
Die Daten-API bietet die folgenden Operationen zum Ausführen von SQL-Anweisungen.
|
Daten-API-Operation |
AWS CLI command |
Beschreibung |
|---|---|---|
|
Führt eine SQL-Anweisung in einer Datenbank aus. |
||
|
Führt eine Batch-SQL-Anweisung über ein Array von Daten für Massen-Update- und -Einfügeoperationen aus. Sie können eine DML-Anweisung (Data Manipulation Language) mit einem Array von Parametersätzen ausführen. Eine Batch-SQL-Anweisung kann gegenüber einzelnen Einfügungs- und Aktualisierungsanweisungen eine erhebliche Leistungsverbesserung bieten. |
Sie können beide Vorgänge verwenden, um einzelne SQL-Anweisungen oder Transaktionen auszuführen. Für Transaktionen stellt die Daten-API die folgenden Operationen bereit.
|
Daten-API-Operation |
AWS CLI command |
Beschreibung |
|---|---|---|
|
Startet eine SQL-Transaktion. |
||
|
Beendet eine SQL-Transaktion und schreibt die Änderungen fest. |
||
|
Führt ein Rollback einer Transaktion durch. |
Für die Operationen zur Ausführung von SQL-Anweisungen und zur Unterstützung von Transaktionen werden die folgenden allgemeinen Daten-API-Parameter und AWS CLI-Optionen verwendet. Einige Operationen unterstützen andere Parameter oder Optionen.
|
Daten-API-Operationsparameter |
AWS CLI-Befehlsoption |
Erforderlich |
Beschreibung |
|---|---|---|---|
|
|
|
Ja |
Der Amazon-Ressourcenname (ARN) des Aurora-DB-Clusters. |
|
|
|
Ja |
Der Name oder ARN des Secrets, das Zugriff auf das DB-Cluster ermöglicht. |
Sie können Parameter in Daten-API-Aufrufen von ExecuteStatement und BatchExecuteStatement, sowie bei Ausführung der AWS CLI-Befehle execute-statement und batch-execute-statement verwenden. Um einen Parameter zu verwenden, geben Sie ein Name-Wert-Paar im Datentyp SqlParameter an. Den Wert geben Sie mit dem Datentyp Field an. 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 |
|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Andere Typen (einschließlich datums- und zeitbezogener Typen) |
|
Anmerkung
Sie können den Datentyp LONG oder STRING in Ihrem Daten-API-Aufruf für von der Datenbank zurückgegebene LONG-Werte angeben. Wir empfehlen Ihnen, dies zu tun, um zu vermeiden, dass die Präzision für extrem große Zahlen verloren geht, was bei der Arbeit mit passieren kann JavaScript.
Bestimmte Typen wie DECIMAL und erfordern einen HinweisTIME, damit die Daten-API String Werte als richtigen Typ an die Datenbank übergibt. Um einen Hinweis zu verwenden, schließen Sie Werte für typeHint in den Datentyp SqlParameter ein. Die folgenden Werte sind für typeHint möglich:
-
DATE– Der entsprechendeString-Parameter wird als Objekt des TypsDATEan die Datenbank gesendet. Das akzeptierte Format istYYYY-MM-DD. -
DECIMAL– Der entsprechendeString-Parameter wird als Objekt des TypsDECIMALan die Datenbank gesendet. -
JSON– Der entsprechendeString-Parameter wird als Objekt des TypsJSONan die Datenbank gesendet. -
TIME– Der entsprechendeString-Parameter wird als Objekt des TypsTIMEan die Datenbank gesendet. Das akzeptierte Format istHH:MM:SS[.FFF]. -
TIMESTAMP– Der entsprechendeString-Parameter wird als Objekt des TypsTIMESTAMPan die Datenbank gesendet. Das akzeptierte Format istYYYY-MM-DD HH:MM:SS[.FFF]. UUID– Der entsprechendeString-Parameter wird als Objekt des TypsUUIDan die Datenbank gesendet.
Anmerkung
Für Amazon Aurora PostgreSQL gibt die Daten-API immer den Aurora PostgreSQL-Datentyp TIMESTAMPTZ in der UTC-Zeitzone zurück.
Aufrufen der RDS-Daten-API mit der AWS CLI
Sie können die RDS Data API (Data API) über die aufrufenAWS CLI.
In den folgenden Beispielen wird die AWS CLI für die Daten-API verwendet. Weitere Informationen finden Sie in der AWS CLI-Referenz für die Daten-API.
Ersetzen Sie in jedem Beispiel den Amazon-Ressourcennamen (ARN) für den DB-Cluster durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.
Anmerkung
Die AWS CLI kann Antworten in JSON formatieren.
Themen
Starten einer SQL-Transaktion
Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data
begin-transaction starten. Der Aufruf gibt eine Transaktions-ID zurück.
Wichtig
Bei einer Transaktion kommt es zu einer Zeitüberschreitung, wenn es innerhalb von drei Minuten keine Aufrufe gibt, die ihre Transaktions-ID verwenden. Wenn es zu einer Zeitüberschreitung kommt, bevor die Transaktion festgeschrieben wird, wird die Transaktion automatisch zurückgesetzt.
Data Definition Language (DDL)-Anweisungen innerhalb einer Transaktion führen zu einem impliziten Commit. Wir empfehlen Ihnen, die einzelnen DDL-Anweisungen jeweils in einem separaten Befehl execute-statement mit der Option --continue-after-timeout auszuführen.
Geben Sie zusätzlich zu den allgemeinen Optionen die Option --database an, die den Namen der Datenbank enthält.
Der folgende CLI-Befehl beispielsweise startet eine SQL-Transaktion.
Für Linux, macOSoder Unix:
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
Windows:
aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"transactionId": "ABC1234567890xyz"
}Ausführen einer SQL-Anweisung
Sie können mittels des CLI-Befehls aws rds-data execute-statement eine SQL-Anweisung ausführen.
Sie können die SQL-Anweisung in einer Transaktion ausführen, indem Sie die Transaktions-ID mit der Option --transaction-id angeben. Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data begin-transaction starten. Sie können eine Transaktion beenden und übergeben, indem Sie den CLI-Befehl aws rds-data
commit-transaction verwenden.
Wichtig
Wenn Sie die Option --transaction-id nicht angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.
Geben Sie zusätzlich zu den allgemeinen Optionen die folgenden Optionen an:
-
--sql(erforderlich) – eine SQL-Anweisung, die auf dem DB-Cluster ausgeführt werden soll. -
--transaction-id(optional) – die ID einer Transaktion, die über den CLI-Befehlbegin-transactiongestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL-Anweisung einfügen möchten. -
--parameters(optional) – die Parameter für die SQL-Anweisung. -
--include-result-metadata | --no-include-result-metadata(optional) – ein Wert, der angibt, ob Metadaten in die Ergebnisse eingefügt werden sollen. Der Standardwert ist--no-include-result-metadata. -
--database(optional) – der Name der Datenbank.Die
--database-Option funktioniert möglicherweise nicht, wenn Sie eine SQL-Anweisung ausführen, nachdem Sie bei der vorherige Anfrage--sql "useausgeführt haben. Es wird empfohlen, diedatabase_name;"--database-Option zu verwenden statt--sql "use-Anweisungen auszuführen.database_name;" -
--continue-after-timeout | --no-continue-after-timeout(optional) – ein Wert, der angibt, ob die Ausführung nach Ablauf des Aufrufs weiter ausgeführt werden soll. Der Standardwert ist--no-continue-after-timeout.Im Fall von Data Definition Language (DDL)-Anweisungen osllten Sie die Anweisung nach Ablauf des Aufrufs weiter ausführen, um Fehler und die Möglichkeit beschädigter Datenstrukturen zu vermeiden.
-
--format-records-as "JSON"|"NONE"– Ein optionaler Wert, der angibt, ob die Ergebnismenge als JSON-Zeichenfolge formatiert werden soll. Der Standardwert ist"NONE". Nutzungsinformationen über die Verarbeitung von JSON-Ergebnismengen finden Sie unter Verarbeitung von Abfrageergebnissen im JSON-Format.
Das DB-Cluster gibt für den Aufruf eine Antwort zurück.
Anmerkung
Das Limit für Antwortgrößen beträgt 1 MiB. Wenn der Aufruf mehr als 1 MiB an Antwortdaten zurückgibt, wird der Aufruf beendet.
Für beträgt Aurora Serverless v1die maximale Anzahl von Anforderungen pro Sekunde 1 000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.
Der folgende CLI-Befehl führt beispielsweise eine einzelne SQL-Anweisung aus und lässt die Metadaten in den Ergebnissen weg (Standard).
Für Linux, macOSoder Unix:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "select * from mytable"
Windows:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "select * from mytable"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"numberOfRecordsUpdated": 0,
"records": [
[
{
"longValue": 1
},
{
"stringValue": "ValueOne"
}
],
[
{
"longValue": 2
},
{
"stringValue": "ValueTwo"
}
],
[
{
"longValue": 3
},
{
"stringValue": "ValueThree"
}
]
]
}Der folgende CLI-Befehl führt eine einzelne SQL-Anweisung in einer Transaktion aus, indem die Option --transaction-id angegeben wird.
Für Linux, macOSoder Unix:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
Windows:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"numberOfRecordsUpdated": 1
}Der folgende CLI-Befehl führt eine einzelne SQL-Anweisung mit Parametern aus.
Für Linux, macOSoder Unix:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "insert intomytablevalues (:id,:val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
Windows:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "insert intomytablevalues (:id,:val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"numberOfRecordsUpdated": 1
}Der folgende CLI-Befehl führt eine Data Definition Language (DDL)-SQL-Anweisung aus. Die DDL-Anweisung benennt die Spalte job in die Spalte role um.
Wichtig
Im Fall von DDL-Anweisungen sollten Sie die Anweisung auch nach Ablauf des Aufrufs weiter ausführen. Wenn eine DDL-Anweisung vor Ende der Ausführung beendet wird, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um eine Anweisung nach Ablauf eines Aufrufs weiter auszuführen, geben Sie die Option --continue-after-timeout an.
Für Linux, macOSoder Unix:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
Windows:
aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "alter table mytable change column job role varchar(100)" --continue-after-timeout
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"generatedFields": [],
"numberOfRecordsUpdated": 0
}Anmerkung
Die generatedFields-Daten werden von Aurora PostgreSQL nicht unterstützt. Zum Abrufen der Werte von generierten Feldern verwenden Sie die RETURNING-Klausel. Weitere Informationen finden Sie in unter Returning Data From Modified Rows
Ausführen einer Stapel-SQL-Anweisung über ein Daten-Array
Sie können eine Batch-SQL-Anweisung über ein Daten-Array ausführen, indem Sie den CLI-Befehl aws rds-data batch-execute-statement verwenden. Sie können dieses Befehl verwenden, um einen Massenimport oder eine Update-Operation auszuführen.
Sie können die SQL-Anweisung in einer Transaktion ausführen, indem Sie die Transaktions-ID mit der Option --transaction-id angeben. Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data
begin-transaction starten. Sie können eine Transaktion mit dem CLI-Befehl aws rds-data commit-transaction beenden und übergeben.
Wichtig
Wenn Sie die Option --transaction-id nicht angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.
Geben Sie zusätzlich zu den allgemeinen Optionen die folgenden Optionen an:
-
--sql(erforderlich) – eine SQL-Anweisung, die auf dem DB-Cluster ausgeführt werden soll.Tipp
Fügen Sie bei MySQL-kompatiblen Anweisungen kein Semikolon am Ende des
--sql-Parameters ein. Ein abschließendes Semikolon kann einen Syntaxfehler verursachen. -
--transaction-id(optional) – die ID einer Transaktion, die über den CLI-Befehlbegin-transactiongestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL-Anweisung einfügen möchten. -
--parameter-set(optional) – die Parametersätze für die Batch-Operation. -
--database(optional) – der Name der Datenbank.
Das DB-Cluster gibt für den Aufruf eine Antwort zurück.
Anmerkung
Es gibt keine feste Obergrenze für die Anzahl der Parametersätze. Die maximale Größe der über die Daten-API übermittelten HTTP-Anforderung beträgt jedoch 4 MiB . Wenn die Anforderung dieses Limit überschreitet, gibt die Daten-API einen Fehler zurück und verarbeitet die Anforderung nicht. Dieses 4-MiB-Limit umfasst die Größe der HTTP-Header und der JSON-Notation in der Anforderung. Die Anzahl der Parametersätze, die Sie einbinden können, hängt demnach von mehreren Faktoren ab, z. B. von der Größe der SQL-Anweisung und der Größe der individuellen Parametersätze.
Das Limit für Antwortgrößen beträgt 1 MiB. Wenn der Aufruf mehr als 1 MiB an Antwortdaten zurückgibt, wird der Aufruf beendet.
Für beträgt Aurora Serverless v1die maximale Anzahl von Anforderungen pro Sekunde 1 000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.
Der folgende CLI-Befehl führt beispielsweise eine Batch-SQL-Anweisung für ein Daten-Array mit einem Parametersatz aus.
Für Linux, macOSoder Unix:
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --sql "insert intomytablevalues (:id,:val)" \ --parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
Windows:
aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --sql "insert intomytablevalues (:id,:val)" ^ --parameter-sets "[[{\"name\": \"id\", \"value\": {\"longValue\":1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueOne\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":2}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueTwo\"}}], [{\"name\": \"id\", \"value\": {\"longValue\":3}},{\"name\": \"val\", \"value\": {\"stringValue\": \"ValueThree\"}}]]"
Anmerkung
Verwenden Sie in der Option --parameter-sets keine Zeilenumbrüche.
Übergeben einer SQL-Transaktion
Mit dem CLI-Befehl aws rds-data commit-transaction können Sie eine SQL-Transaktion beenden, die mit aws rds-data
begin-transaction gestartet wurde, und die Änderungen übergeben.
Geben Sie zusätzlich zu den allgemeinen Optionen die folgende Option an:
-
--transaction-id(erforderlich) – die ID einer Transaktion, die über den CLI-Befehlbegin-transactiongestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, die Sie beenden und übergeben möchten.
Der folgende CLI-Befehl beendet beispielsweise eine SQL-Transaktion und übergibt die Änderungen.
Für Linux, macOSoder Unix:
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --transaction-id "ABC1234567890xyz"
Windows:
aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --transaction-id "ABC1234567890xyz"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"transactionStatus": "Transaction Committed"
}Rollback einer SQL-Transaktion
Mit dem CLI-Befehl aws rds-data rollback-transaction können Sie einen Rollback für eine SQL-Transaktion ausführen, die mit aws rds-data
begin-transaction gestartet wurde. Durch das Rollback einer Transaktion werden für sie ausgeführte Änderungen rückgängig gemacht.
Wichtig
Wenn die Transaktions-ID abgelaufen ist, wurde automatisch ein Rollback für die Transaktion ausgeführt. In diesem Fall gibt ein aws rds-data rollback-transaction-Befehl, der die abgelaufene Transaktions-ID angibt, einen Fehler zurück.
Geben Sie zusätzlich zu den allgemeinen Optionen die folgende Option an:
-
--transaction-id(erforderlich) – die ID einer Transaktion, die über den CLI-Befehlbegin-transactiongestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, für die Sie ein Rollback ausführen möchten.
Der folgende AWS CLI-Befehl führt beispielsweise einen Rollback für eine SQL-Transaktion aus.
Für Linux, macOSoder Unix:
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \ --transaction-id "ABC1234567890xyz"
Windows:
aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^ --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^ --transaction-id "ABC1234567890xyz"
Im Folgenden sehen Sie ein Beispiel für die Antwort.
{
"transactionStatus": "Rollback Complete"
}Aufrufen der RDS-Daten-API aus einer Python-Anwendung
Sie können die RDS Data API (Data API) aus einer Python-Anwendung aufrufen.
Die folgenden Beispiele verwenden den AWS SDK for Python (Boto). Weitere Informationen zu Boto finden Sie in der AWS SDK for Python (Boto 3)-Dokumentation
Ersetzen Sie in jedem Beispiel den Amazon-Ressourcennamen (ARN) des DB-Clusters durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.
Ausführen einer SQL-Abfrage
Sie können eine SELECT-Anweisung ausführen und die Ergebnisse mit einer Python-Anwendung abrufen.
Im folgenden Beispiel wird eine SQL-Abfrage ausgeführt.
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
response1 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'select * from employees limit 3')
print (response1['records'])
[
[
{
'longValue': 1
},
{
'stringValue': 'ROSALEZ'
},
{
'stringValue': 'ALEJANDRO'
},
{
'stringValue': '2016-02-15 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'DOE'
},
{
'stringValue': 'JANE'
},
{
'stringValue': '2014-05-09 04:34:33.0'
}
],
[
{
'longValue': 1
},
{
'stringValue': 'STILES'
},
{
'stringValue': 'JOHN'
},
{
'stringValue': '2017-09-20 04:34:33.0'
}
]
]Ausführen einer DML SQL-Anweisung
Sie können eine Data Manipulation Language (DML)-Anweisung ausführen, um in Ihrer Datenbank Daten einzufügen, zu aktualisieren oder zu löschen. Sie können in DML-Anweisungen auch Parameter verwenden.
Wichtig
Wenn ein Aufruf kein Teil einer Transaktion ist, da er den Parameter transactionID nicht enthält, werden Änderungen, die sich aus dem Aufruf ergeben, automatisch übergeben.
Im folgenden Beispiel werden eine SQL Insert-Anweisung ausgeführt und Parameter verwendet.
import boto3
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
rdsData = boto3.client('rds-data')
param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]
response2 = rdsData.execute_statement(resourceArn=cluster_arn,
secretArn=secret_arn,
database='mydb',
sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
parameters = paramSet)
print (response2["numberOfRecordsUpdated"])Ausführen einer SQL-Transaktion
Sie können eine SQL-Transaktion starten, eine oder mehrere SQL-Anweisungen ausführen und anschließend die Änderungen mit einer Python-Anwendung übergeben.
Wichtig
Bei einer Transaktion kommt es zu einer Zeitüberschreitung, wenn es innerhalb von drei Minuten keine Aufrufe gibt, die ihre Transaktions-ID verwenden. Wenn es zu einer Zeitüberschreitung kommt, bevor die Transaktion festgeschrieben wird, wird die Transaktion automatisch zurückgesetzt.
Wenn Sie keine Transaktions-ID angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.
Im folgenden Beispiel wird eine SQL-Transaktion ausgeführt, die eine Zeile in eine Tabelle einfügt.
import boto3
rdsData = boto3.client('rds-data')
cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'
tr = rdsData.begin_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb')
response3 = rdsData.execute_statement(
resourceArn = cluster_arn,
secretArn = secret_arn,
database = 'mydb',
sql = 'insert into employees(first_name, last_name) values('XIULAN', 'WANG')',
transactionId = tr['transactionId'])
cr = rdsData.commit_transaction(
resourceArn = cluster_arn,
secretArn = secret_arn,
transactionId = tr['transactionId'])
cr['transactionStatus']
'Transaction Committed'
response3['numberOfRecordsUpdated']
1Anmerkung
Wenn Sie eine DDL-Anweisung ausführen, sollten Sie die Anweisung auch nach Ablauf des Aufrufs weiter ausführen. Wenn eine DDL-Anweisung vor Ende der Ausführung beendet wird, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um eine Anweisung nach Ablauf eines Aufrufs weiter auszuführen, legen Sie den Parameter continueAfterTimeout auf true fest.
Aufrufen der RDS-Daten-API aus einer Java-Anwendung
Sie können die RDS Data API (Data API) aus einer Java-Anwendung aufrufen.
Die folgenden Beispiele verwenden den AWS SDK for Java. Weitere Informationen finden Sie im AWS SDK for Java-Entwicklerhandbuch.
Ersetzen Sie in jedem Beispiel den Amazon-Ressourcennamen (ARN) des DB-Clusters durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.
Themen
Ausführen einer SQL-Abfrage
Sie können eine SELECT-Anweisung ausführen und die Ergebnisse mit einer Java-Anwendung abrufen.
Im folgenden Beispiel wird eine SQL-Abfrage ausgeführt.
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;
import java.util.List;
public class FetchResultsExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
ExecuteStatementRequest request = new ExecuteStatementRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb")
.withSql("select * from mytable");
ExecuteStatementResult result = rdsData.executeStatement(request);
for (List<Field> fields: result.getRecords()) {
String stringValue = fields.get(0).getStringValue();
long numberValue = fields.get(1).getLongValue();
System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
}
}
}Ausführen einer SQL-Transaktion
Sie können eine SQL-Transaktion starten, eine oder mehrere SQL-Anweisungen ausführen und anschließend die Änderungen mit einer Java-Anwendung übergeben.
Wichtig
Bei einer Transaktion kommt es zu einer Zeitüberschreitung, wenn es innerhalb von drei Minuten keine Aufrufe gibt, die ihre Transaktions-ID verwenden. Wenn es zu einer Zeitüberschreitung kommt, bevor die Transaktion festgeschrieben wird, wird die Transaktion automatisch zurückgesetzt.
Wenn Sie keine Transaktions-ID angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.
Im folgenden Beispiel wird eine SQL-Transaktion ausgeführt.
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BeginTransactionRequest;
import com.amazonaws.services.rdsdata.model.BeginTransactionResult;
import com.amazonaws.services.rdsdata.model.CommitTransactionRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
public class TransactionExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BeginTransactionRequest beginTransactionRequest = new BeginTransactionRequest()
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withDatabase("mydb");
BeginTransactionResult beginTransactionResult = rdsData.beginTransaction(beginTransactionRequest);
String transactionId = beginTransactionResult.getTransactionId();
ExecuteStatementRequest executeStatementRequest = new ExecuteStatementRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table VALUES ('hello world!')");
rdsData.executeStatement(executeStatementRequest);
CommitTransactionRequest commitTransactionRequest = new CommitTransactionRequest()
.withTransactionId(transactionId)
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN);
rdsData.commitTransaction(commitTransactionRequest);
}
}Anmerkung
Wenn Sie eine DDL-Anweisung ausführen, sollten Sie die Anweisung auch nach Ablauf des Aufrufs weiter ausführen. Wenn eine DDL-Anweisung vor Ende der Ausführung beendet wird, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um eine Anweisung nach Ablauf eines Aufrufs weiter auszuführen, legen Sie den Parameter continueAfterTimeout auf true fest.
Ausführen einer Stapel-SQL-Operation
Sie können mit einer Java-Anwendung Operationen für Masseneinfügungen und -aktualisierungen für ein Daten-Array ausführen. Sie können eine DML-Anweisung mit einem Array von Parametersätzen ausführen.
Wichtig
Wenn Sie keine Transaktions-ID angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.
Im folgenden Beispiel wird eine Batch-Einfügungs-Operation ausgeführt.
package com.amazonaws.rdsdata.examples;
import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.BatchExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.Field;
import com.amazonaws.services.rdsdata.model.SqlParameter;
import java.util.Arrays;
public class BatchExecuteExample {
public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";
public static void main(String[] args) {
AWSRDSData rdsData = AWSRDSDataClient.builder().build();
BatchExecuteStatementRequest request = new BatchExecuteStatementRequest()
.withDatabase("test")
.withResourceArn(RESOURCE_ARN)
.withSecretArn(SECRET_ARN)
.withSql("INSERT INTO test_table2 VALUES (:string, :number)")
.withParameterSets(Arrays.asList(
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("Hello")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(1L))
),
Arrays.asList(
new SqlParameter().withName("string").withValue(new Field().withStringValue("World")),
new SqlParameter().withName("number").withValue(new Field().withLongValue(2L))
)
));
rdsData.batchExecuteStatement(request);
}
}Verwenden der Java-Clientbibliothek für die RDS-Daten-API
Sie können eine Java-Clientbibliothek für die RDS-Daten-API (Data API) herunterladen und verwenden. Diese Java-Clientbibliothek bietet eine alternative Möglichkeit, die Daten-API zu verwenden. Mit dieser Bibliothek können Sie Ihre clientseitigen Klassen Daten-API-Anforderungen und -Antworten zuordnen. Dieser Mapping-Support kann die Integration mit einigen bestimmten Java-Typen wie etwa Date, Time und BigDecimal erleichtern.
Herunterladen der Java Client-Bibliothek für die Daten-API
Die Java-Clientbibliothek der Data API ist Open Source in GitHub am folgenden Speicherort:
https://github.com/awslabs/rds-data-api-client-library-java
Sie können die Bibliothek manuell aus den Quelldateien aufbauen, die bewährte Methode ist jedoch, die Bibliothek unter Verwendung der Apache Maven-Dependenzverwaltung zu nutzen. Fügen Sie die folgende Abhängigkeit zu Ihrer Maven-POM-Datei hinzu.
Verwenden Sie für Version 2.x, die mit AWS-SDK-2.x kompatibel ist, Folgendes:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>2.0.0</version> </dependency>
Verwenden Sie für Version 1.x, die mit AWS-SDK-1.x kompatibel ist, Folgendes:
<dependency> <groupId>software.amazon.rdsdata</groupId> <artifactId>rds-data-api-client-library-java</artifactId> <version>1.0.8</version> </dependency>
Java Client-Bibliothek-Beispiele
Nachfolgend finden Sie einige typische Beispiele für die Verwendung der Daten-API-Java-Client-Bibliothek. Diese Beispiele gehen davon aus, dass Sie eine Tabelle accounts mit zwei Spalten haben: accountId und name. Weiterhin haben Sie das folgende Datentransferobjekt (DTO):
public class Account {
int accountId;
String name;
// getters and setters omitted
}Die Client-Bibliothek ermöglicht die Übergabe von DTOs als Eingabeparameter. Das folgende Beispiel zeigt, wie Kunden-DTOs Eingabeparametersätzen zugeordnet werden.
var account1 = new Account(1, "John");
var account2 = new Account(2, "Mary");
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParamSets(account1, account2)
.execute();In manchen Fällen ist es einfacher, mit einfachen Werten als Eingabeparametern zu arbeiten. Verwenden Sie dazu die folgende Syntax.
client.forSql("INSERT INTO accounts(accountId, name) VALUES(:accountId, :name)")
.withParameter("accountId", 3)
.withParameter("name", "Zhang")
.execute();Es folgt ein weiteres Beispiel, das mit einfachen Werten als Eingabeparametern arbeitet.
client.forSql("INSERT INTO accounts(accountId, name) VALUES(?, ?)", 4, "Carlos") .execute();
Die Client-Bibliothek bietet das automatische Mapping zu DTOs, wenn ein Ergebnis zurückgegeben wird. Die folgenden Beispiele zeigen, wie das Ergebnis Ihren DTOs zugeordnet wird.
List<Account> result = client.forSql("SELECT * FROM accounts")
.execute()
.mapToList(Account.class);
Account result = client.forSql("SELECT * FROM accounts WHERE account_id = 1")
.execute()
.mapToSingle(Account.class);In vielen Fällen enthält die Datenbank-Ergebnismenge einen einzigen Wert. Um das Abrufen solcher Ergebnisse zu vereinfachen, bietet die Kundenbibliothek die folgende API an:
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);Anmerkung
Die mapToList-Funktion konvertiert einen SQL-Ergebnissatz in eine benutzerdefinierte Objektliste. Wir unterstützen die Verwendung der .withFormatRecordsAs(RecordsFormatType.JSON)-Anweisung in einem ExecuteStatement-Anruf für die Java-Clientbibliothek nicht, weil sie dem gleichen Zweck dient. Weitere Informationen finden Sie unter Verarbeitung von Abfrageergebnissen im JSON-Format.
Verarbeitung von Abfrageergebnissen im JSON-Format
Wenn Sie die ExecuteStatement-Operation aufrufen, können Sie auswählen, ob die Abfrageergebnisse als Zeichenfolge im JSON-Format zurückgegeben werden sollen. Auf diese Weise können Sie die JSON-Parsing-Funktionen Ihrer Programmiersprache verwenden, um die Ergebnismenge zu interpretieren und neu zu formatieren. Dies kann dazu beitragen, zu vermeiden, zusätzlichen Code zu schreiben, um die Ergebnismenge zu durchlaufen und jeden Spaltenwert zu interpretieren.
Zum Anfordern der Ergebnismenge im JSON-Format übergeben Sie den optionalen formatRecordsAs-Parameter mit dem Wert JSON. Die JSON-formatierte Ergebnismenge wird im Feld formattedRecords der ExecuteStatementResponse-Struktur zurückgegeben.
Die BatchExecuteStatement-Aktion gibt keine Ergebnismenge zurück. Daher gilt die JSON-Option nicht für diese Aktion.
Wenn Sie die Schlüssel in der JSON-Hash-Struktur anpassen möchten, definieren Sie Spaltenaliasnamen in der Ergebnismenge. Verwenden Sie dazu die AS-Klausel in der Spaltenliste Ihrer SQL-Abfrage.
Sie können die JSON-Funktion verwenden, um die Ergebnismenge besser lesbar zu machen und den Inhalt sprachspezifischen Frameworks zuzuordnen. Da das Volume der ASCII-kodierten Ergebnismenge größer als die Standarddarstellung ist, können Sie die Standarddarstellung für Abfragen auswählen, die eine große Anzahl von Zeilen oder große Spaltenwerte zurückgeben, die mehr Speicher belegen, als für Ihre Anwendung verfügbar ist.
Abrufen von Abfrageergebnissen im JSON-Format
Um die Ergebnismenge als JSON-Zeichenfolge zu erhalten, fügen Sie .withFormatRecordsAs(RecordsFormatType.JSON) in den ExecuteStatement Aufruf ein. Der Rückgabewert wird im Feld formattedRecords als JSON-Zeichenfolge angezeigt. In diesem Fall hat columnMetadata den Wert null. Die Spaltenbeschriftungen sind die Schlüssel des Objekts, das jede Zeile darstellt. Diese Spaltennamen werden für jede Zeile in der Ergebnismenge wiederholt. Die Spaltenwerte sind in Anführungszeichen gesetzte Zeichenfolgen, numerische Werte oder Sonderwerte, die true, false oder null darstellen. Spaltenmetadaten wie Längenbeschränkungen und der genaue Typ für Zahlen und Zeichenfolgen werden in der JSON-Antwort nicht beibehalten.
Wenn Sie den .withFormatRecordsAs()-Aufruf weglassen oder einen Parameter NONE angeben, wird die Ergebnismenge im Binärformat unter Verwendung der Felder Records und columnMetadata zurückgegeben.
Datentypenzuordnung
Die SQL-Werte in der Ergebnismenge werden einem kleineren Satz von JSON-Typen zugeordnet. Die Werte werden in JSON als Zeichenfolgen, Zahlen und einige spezielle Konstanten wie true, false und null dargestellt. Sie können diese Werte in Variablen in Ihrer Anwendung umwandeln, indem Sie eine starke oder schwache Eingabe verwenden, die für Ihre Programmiersprache geeignet ist.
|
JDBC-Datentyp |
JSON-Datentyp |
|---|---|
|
|
Die Standardeinstellung ist Zahl. Zeichenfolge, wenn die Option |
|
|
Zahl |
|
|
Die Standardeinstellung ist Zeichenfolge. Zahl, wenn die Option |
|
|
String |
|
|
Boolesch |
|
|
Zeichenfolge in Base64-Kodierung. |
|
|
String |
|
|
Array |
|
|
|
|
Andere Typen (einschließlich datums- und zeitbezogener Typen) |
String |
Fehlerbehebung
Die JSON-Antwort ist auf 10 Megabyte begrenzt. Wenn die Antwort größer als dieses Limit ist, erhält Ihr Programm einen BadRequestException-Fehler. In diesem Fall können Sie den Fehler mit einer der folgenden Methoden beheben:
-
Reduzieren Sie die Anzahl der Zeilen in der Ergebnismenge. Fügen Sie dazu eine
LIMIT-Klausel hinzu. Sie können eine große Ergebnismenge in mehrere kleinere aufteilen, indem Sie mehrere Abfragen mit den KlauselnLIMITundOFFSETsenden.Wenn die Ergebnismenge Zeilen enthält, die durch die Anwendungslogik herausgefiltert werden, können Sie diese Zeilen aus der Ergebnismenge entfernen, indem Sie der
WHERE-Klausel weitere Bedingungen hinzufügen. -
Reduzieren Sie die Anzahl der Spalten in der Ergebnismenge. Entfernen Sie dazu Elemente aus der Auswahlliste der Abfrage.
-
Verkürzen Sie die Spaltenbeschriftungen, indem Sie Spaltenaliasnamen in der Abfrage verwenden. Jeder Spaltenname wird in der JSON-Zeichenfolge für jede Zeile der Ergebnismenge wiederholt. Daher könnte ein Abfrageergebnis mit langen Spaltennamen und vielen Zeilen die Größenbeschränkung überschreiten. Verwenden Sie insbesondere Spaltenaliasnamen für komplizierte Ausdrücke, um zu vermeiden, dass der gesamte Ausdruck in der JSON-Zeichenfolge wiederholt wird.
-
Während Sie mit SQL Spaltenaliasnamen verwenden können, um eine Ergebnismenge mit mehr als einer Spalte mit demselben Namen zu erzeugen, sind doppelte Schlüsselnamen in JSON nicht zulässig. Die RDS-Daten-API gibt einen Fehler zurück, wenn Sie die Ergebnismenge im JSON-Format anfordern und mehr als eine Spalte denselben Namen hat. Stellen Sie daher sicher, dass alle Spaltenbeschriftungen eindeutige Namen haben.
Beispiele
Die folgenden Java-Beispiele zeigen, wie Sie ExecuteStatement mit der Antwort als JSON-formatierte Zeichenfolge aufrufen und dann die Ergebnismenge interpretieren. Ersetzen Sie die entsprechenden Werte für die Parameter databaseNamesecretStoreArn , und clusterArn.
Das folgende Java-Beispiel veranschaulicht eine Abfrage, die einen numerischen Dezimalwert in der Ergebnismenge zurückgibt. assertThat-Aufrufe testen anhand der Regeln für JSON-Ergebnismengen, ob die Felder der Antwort die erwarteten Eigenschaften haben.
Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:
create table test_simplified_json (a float); insert into test_simplified_json values(10.0);
public void JSON_result_set_demo() { var sql = "select * from test_simplified_json"; var request = new ExecuteStatementRequest() .withDatabase(databaseName) .withSecretArn(secretStoreArn) .withResourceArn(clusterArn) .withSql(sql) .withFormatRecordsAs(RecordsFormatType.JSON); var result = rdsdataClient.executeStatement(request); }
Der Wert des Felds formattedRecords aus dem vorhergehenden Programm lautet:
[{"a":10.0}]
Die Felder Records und ColumnMetadata in der Antwort sind aufgrund des Vorhandenseins der JSON-Ergebnismenge beide null.
Das folgende Java-Beispiel veranschaulicht eine Abfrage, die einen numerischen Ganzzahlwert in der Ergebnismenge zurückgibt. Das Beispiel ruft getFormattedRecords auf, um nur die JSON-formatierte Zeichenfolge zurückzugeben und die anderen Antwortfelder zu ignorieren, die leer oder null sind. Im Beispiel wird das Ergebnis in eine Struktur deserialisiert, die eine Liste von Datensätzen darstellt. Jeder Datensatz enthält Felder, deren Namen den Spaltenaliasnamen aus der Ergebnismenge entsprechen. Diese Methode vereinfacht den Code, der die Ergebnismenge analysiert. Ihre Anwendung muss nicht die Zeilen und Spalten der Ergebnismenge durchlaufen und jeden Wert in den entsprechenden Typ konvertieren.
Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:
create table test_simplified_json (a int); insert into test_simplified_json values(17);
public void JSON_deserialization_demo() { var sql = "select * from test_simplified_json"; var request = new ExecuteStatementRequest() .withDatabase(databaseName) .withSecretArn(secretStoreArn) .withResourceArn(clusterArn) .withSql(sql) .withFormatRecordsAs(RecordsFormatType.JSON); var result = rdsdataClient.executeStatement(request) .getFormattedRecords(); /* Turn the result set into a Java object, a list of records. Each record has a field 'a' corresponding to the column labelled 'a' in the result set. */ private static class Record { public int a; } var recordsList = new ObjectMapper().readValue( response, new TypeReference<List<Record>>() { }); }
Der Wert des Felds formattedRecords aus dem vorhergehenden Programm lautet:
[{"a":17}]
Zum Abrufen der Spalte a der Ergebniszeile 0 würde sich die Anwendung auf recordsList.get(0).a beziehen.
Im Gegensatz dazu zeigt das folgende Java-Beispiel die Art von Code, der zum Erstellen einer Datenstruktur erforderlich ist, die die Ergebnismenge enthält, wenn Sie das JSON-Format nicht verwenden. In diesem Fall enthält jede Zeile der Ergebnismenge Felder mit Informationen über einen einzelnen Benutzer. Das Erstellen einer Datenstruktur zur Darstellung der Ergebnismenge erfordert das Durchlaufen der Zeilen. Für jede Zeile ruft der Code den Wert jedes Felds ab, führt eine entsprechende Typkonvertierung durch und weist das Ergebnis dem entsprechenden Feld im Objekt zu, das die Zeile darstellt. Dann fügt der Code das Objekt, das jeden Benutzer repräsentiert, der Datenstruktur hinzu, die die gesamte Ergebnismenge darstellt. Wenn die Abfrage geändert wurde, um Felder in der Ergebnismenge neu anzuordnen, hinzuzufügen oder zu entfernen, müsste sich der Anwendungscode ebenfalls ändern.
/* Verbose result-parsing code that doesn't use the JSON result set format */ for (var row: response.getRecords()) { var user = User.builder() .userId(row.get(0).getLongValue()) .firstName(row.get(1).getStringValue()) .lastName(row.get(2).getStringValue()) .dob(Instant.parse(row.get(3).getStringValue())) .build(); result.add(user); }
Die folgenden Beispielwerte zeigen die Werte des Felds formattedRecords für Ergebnismengen mit unterschiedlicher Anzahl von Spalten, Spaltenaliasnamen und Spaltendatentypen.
Wenn die Ergebnismenge mehrere Zeilen enthält, wird jede Zeile als Objekt dargestellt, das ein Array-Element ist. Jede Spalte in der Ergebnismenge wird zu einem Schlüssel im Objekt. Die Schlüssel werden für jede Zeile in der Ergebnismenge wiederholt. Daher müssen Sie für Ergebnismengen, die aus vielen Zeilen und Spalten bestehen, möglicherweise kurze Spaltenaliasnamen definieren, um zu vermeiden, dass das Längenlimit für die gesamte Antwort überschritten wird.
Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:
create table sample_names (id int, name varchar(128)); insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");
[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"}, {"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]
Wenn eine Spalte in der Ergebnismenge als Ausdruck definiert ist, wird der Text des Ausdrucks zum JSON-Schlüssel. Daher ist es normalerweise praktisch, einen beschreibenden Spaltenalias für jeden Ausdruck in der Auswahlliste der Abfrage zu definieren. Die folgende Abfrage enthält beispielsweise Ausdrücke wie Funktionsaufrufe und arithmetische Operationen in ihrer Auswahlliste.
select count(*), max(id), 4+7 from sample_names;
Diese Ausdrücke werden als Schlüssel an die JSON-Ergebnismenge übergeben.
[{"count(*)":5,"max(id)":4,"4+7":11}]
Wenn Sie AS-Spalten mit beschreibenden Beschriftungen hinzufügen, können die Schlüssel in der JSON-Ergebnismenge einfacher interpretiert werden.
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
Bei der überarbeiteten SQL-Abfrage werden die Spaltenbeschriftungen, die durch die AS-Klauseln definiert werden, als Schlüsselnamen verwendet.
[{"rows":5,"largest_id":4,"addition_result":11}]
Der Wert für jedes Schlüssel-Wert-Paar in der JSON-Zeichenfolge kann eine Zeichenfolge in Anführungszeichen sein. Die Zeichenfolge enthält möglicherweise Unicode-Zeichen. Wenn die Zeichenfolge Escape-Sequenzen oder die Zeichen " oder \ enthält, wird diesen Zeichen ein Escape-Zeichen mit umgekehrtem Schrägstrich vorangestellt. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten. Das Ergebnis string_with_escape_sequences enthält z. B. die Sonderzeichen Rücktaste, Zeilenumbruch, Wagenrücklauf, Tabulator, Seitenvorschub und \.
[{"quoted_string":"hello"}] [{"unicode_string":"邓不利多"}] [{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}]
Der Wert für jedes Schlüssel-Wert-Paar in der JSON-Zeichenfolge kann auch eine Zahl darstellen. Die Zahl kann eine Ganzzahl, ein Gleitkommawert, ein negativer Wert oder ein Wert sein, der in Exponentialschreibweise dargestellt wird. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten.
[{"integer_value":17}] [{"float_value":10.0}] [{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}] [{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}]
Boolesche und Nullwerte werden mit den Sonderschlüsselwörtern true, false und null ohne Anführungszeichen dargestellt. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten.
[{"boolean_value_1":true,"boolean_value_2":false}] [{"unknown_value":null}]
Wenn Sie einen Wert eines BLOB-Typs auswählen, wird das Ergebnis in der JSON-Zeichenfolge als Base64-kodierter Wert dargestellt. Wenn Sie den Wert wieder in seine ursprüngliche Darstellung umwandeln möchten, können Sie die entsprechende Dekodierungsfunktion in der Sprache Ihrer Anwendung verwenden. In Java rufen Sie beispielsweise die Funktion Base64.getDecoder().decode() auf. Die folgende Beispielausgabe zeigt das Ergebnis der Auswahl des BLOB-Werts hello world und gibt die Ergebnismenge als JSON-Zeichenfolge zurück.
[{"blob_column":"aGVsbG8gd29ybGQ="}]
Das folgende Python-Beispiel zeigt, wie Sie auf die Werte aus dem Ergebnis eines Aufrufs der Python-Funktion execute_statement zugreifen. Die Ergebnismenge ist ein Zeichenfolgenwert im Feld response['formattedRecords']. Der Code verwandelt die JSON-Zeichenfolge durch Aufrufen der Funktion json.loads in eine Datenstruktur. Dann ist jede Zeile der Ergebnismenge ein Listenelement innerhalb der Datenstruktur und innerhalb jeder Zeile können Sie auf jedes Feld der Ergebnismenge nach Namen verweisen.
import json result = json.loads(response['formattedRecords']) print (result[0]["id"])
Das folgende JavaScript Beispiel zeigt, wie Sie auf die Werte aus dem Ergebnis eines Aufrufs der JavaScript executeStatement Funktion zugreifen. Die Ergebnismenge ist ein Zeichenfolgenwert im Feld response.formattedRecords. Der Code verwandelt die JSON-Zeichenfolge durch Aufrufen der Funktion JSON.parse in eine Datenstruktur. Dann ist jede Zeile der Ergebnismenge ein Array-Element innerhalb der Datenstruktur und innerhalb jeder Zeile können Sie auf jedes Feld der Ergebnismenge nach Namen verweisen.
<script> const result = JSON.parse(response.formattedRecords); document.getElementById("display").innerHTML = result[0].id; </script>
Fehlerbehebung bei Problemen mit der RDS-Daten-API
Verwenden Sie die folgenden Abschnitte mit dem Titel mit häufigen Fehlermeldungen, um Probleme zu beheben, die Sie mit der RDS Data API (Data API) haben.
Themen
Transaction <transaction_ID> Is Not Found (Transaktion nicht gefunden)
In diesem Fall wurde die in einem Data-API-Aufruf angegebene Transaktions-ID nicht gefunden. Die Ursache für dieses Problem wird an die Fehlermeldung angehängt und ist eine der folgenden:
-
Die Transaktion ist möglicherweise abgelaufen.Stellen Sie sicher, dass jeder Transaktionsaufruf innerhalb von drei Minuten nach dem letzten ausgeführt wird.
Es ist auch möglich, dass die angegebene Transaktions-ID nicht durch einen -BeginTransactionAufruf erstellt wurde. Stellen Sie sicher, dass Ihr Aufruf eine gültige Transaktions-ID hat.
-
Ein vorheriger Aufruf führte zu einer Beendigung Ihrer Transaktion.Die Transaktion wurde bereits von Ihrem
CommitTransaction- oderRollbackTransaction-Aufruf beendet. -
Die Transaktion wurde aufgrund eines Fehlers eines früheren Aufrufs abgebrochen.Prüfen Sie, ob Ihre vorherigen Aufrufe Ausnahmen ausgelöst haben.
Informationen zum Ausführen von Transaktionen finden Sie unter Aufrufen der RDS-Daten-API.
Packet for Query Is Too Large (Paket für Abfrage zu groß)
In diesem Fall war die zurückgegebene Ergebnismenge für eine Zeile zu groß. Die Größenbegrenzung der Data-API beträgt 64 KB pro Zeile in der von der Datenbank zurückgegebenen Ergebnismenge.
Um dieses Problem zu beheben, stellen Sie sicher, dass jede Zeile in einem Ergebnissatz höchstens 64 KB groß ist.
Database Response Exceeded Size Limit Datenbankantwort überschreitet Größenlimit)
In diesem Fall war die Größe der von der Datenbank zurückgegebenen Ergebnismenge zu groß. Das Data-API-Limit beträgt 1 MiB für die von der Datenbank zurückgegebene Ergebnismenge.
Um dieses Problem zu lösen, stellen Sie sicher, dass Aufrufe der Data API 1 MiB Daten oder weniger zurückgeben. Wenn Sie mehr als 1 MiB zurückgeben müssen, können Sie mit der LIMIT-Klausel in Ihrer Abfrage mehrere ExecuteStatement-Aufrufe verwenden.
Weitere Informationen über die LIMIT-Klausel finden Sie unter SELECT-Syntax
HttpEndpoint ist für Cluster <cluster_ID> nicht aktiviert
Überprüfen Sie die folgenden möglichen Ursachen für dieses Problem:
-
Der Aurora-DB-Cluster unterstützt die Daten-API nicht. Für Aurora MySQL können Sie beispielsweise die Daten-API nur mit verwendenAurora Serverless v1. Informationen zu den Arten von DB-Clustern, die die RDS-Daten-API unterstützt, finden Sie unter Verfügbarkeit von Regionen und Versionen.
-
Die Daten-API ist für den Aurora-DB-Cluster nicht aktiviert. Um die Daten-API mit einem Aurora-DB-Cluster verwenden zu können, muss die Daten-API für den DB-Cluster aktiviert sein. Informationen zum Aktivieren der Data API finden Sie unter Aktivieren der RDS-Daten-API.
-
Der DB-Cluster wurde umbenannt, nachdem die Daten-API dafür aktiviert wurde. Deaktivieren Sie in diesem Fall die Daten-API für diesen Cluster und aktivieren Sie sie dann erneut.
-
Der von Ihnen angegebene ARN stimmt nicht genau mit dem ARN des Clusters überein. Stellen Sie sicher, dass der von einer anderen Quelle zurückgegebene oder durch Programmlogik erstellte ARN genau mit dem ARN des Clusters übereinstimmt. Stellen Sie beispielsweise sicher, dass der von Ihnen verwendete ARN die richtigen Groß-/Kleinschreibung für alle alphabetischen Zeichen aufweist.
