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.
RDSDaten verwenden API
Mithilfe von RDS Data API (DataAPI) können Sie mit einer Web-Services-Schnittstelle zu Ihrem Aurora-DB-Cluster arbeiten. Für Daten API ist keine dauerhafte Verbindung zum DB-Cluster erforderlich. Stattdessen bietet es einen sicheren HTTP Endpunkt und eine sichere Integration mit AWS SDKs. Sie können den Endpunkt verwenden, um SQL Anweisungen auszuführen, ohne Verbindungen zu verwalten.
Benutzer müssen bei Aufrufen von Data keine Anmeldeinformationen übergebenAPI, da Data Datenbankanmeldeinformationen API verwendet, die in gespeichert sind AWS Secrets Manager. Um Anmeldeinformationen in Secrets Manager zu speichern, müssen Benutzern die entsprechenden Berechtigungen zur Verwendung von Secrets Manager und auch Data erteilt werdenAPI. Weitere Informationen zum Autorisieren von Benutzern finden Sie unter Autorisieren des Zugriffs auf Daten RDS API.
Sie können Data auch verwendenAPI, um Amazon Aurora in andere AWS Anwendungen wie AWS Lambda AWS AppSync, und zu integrieren AWS Cloud9. Daten API bieten eine sicherere Art der Nutzung AWS Lambda. Es ermöglicht Ihnen den Zugriff auf Ihren DB-Cluster, ohne dass Sie eine Lambda-Funktion für den Zugriff auf Ressourcen in einer virtuellen privaten Cloud () VPC konfigurieren müssen. Weitere Informationen finden Sie unter AWS Lambda
Sie können Data aktivierenAPI, wenn Sie den Aurora-DB-Cluster erstellen. Sie können die Konfiguration später auch ändern. Weitere Informationen finden Sie unter RDSDaten aktivieren API.
Nachdem Sie Data aktiviert habenAPI, können Sie den Abfrage-Editor auch verwenden, um Ad-hoc-Abfragen auszuführen, ohne ein Abfragetool für den Zugriff auf Aurora in a zu konfigurierenVPC. Weitere Informationen finden Sie unter Verwenden des Aurora-Abfrage-Editors.
Themen
- Verfügbarkeit von Regionen und Versionen
- Einschränkungen im Zusammenhang mit Daten RDS API
- Vergleich von RDS Daten API mit Serverless v2 und bereitgestellten Daten und Aurora Serverless v1
- Autorisieren des Zugriffs auf Daten RDS API
- RDSDaten aktivieren API
- Einen VPC Amazon-Endpunkt für RDS Daten erstellen API (AWS PrivateLink)
- RDSDaten aufrufen API
- Verwendung der Java-Clientbibliothek für Daten RDS API
- Verarbeitung von RDS API Datenabfrageergebnissen im Format JSON
- Behebung RDS von API Datenproblemen
- 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 Data verfügbar sindAPI, finden Sie in den folgenden Abschnitten.
Cluster-Typ | Verfügbarkeit von Regionen und Versionen |
---|---|
Aurora Postgre SQL bereitgestellt und Serverless v2 |
Daten API mit Aurora Postgre SQL Serverless v2 und bereitgestellt |
Aurora Postgre SQL Serverlos v1 |
|
Aurora My SQL Serverless v1 |
Anmerkung
Derzeit sind Daten API nicht für bereitgestellte oder Aurora Serverless v2 DB-Cluster verfügbar, die die My SQL Engine verwenden.
Wenn Sie beim Zugriff auf Daten API über eine Befehlszeilenschnittstelle oder eine andere kryptografische Module benötigen, die mit FIPS 140-2 validiert wurdenAPI, verwenden Sie einen Endpunkt. FIPS Weitere Informationen zu den verfügbaren FIPS Endpunkten finden Sie unter Federal Information Processing Standard
Einschränkungen im Zusammenhang mit Daten RDS API
RDSFür Daten API (DatenAPI) gelten die folgenden Einschränkungen:
Sie können API Datenabfragen nur auf Writer-Instances in einem DB-Cluster ausführen. Writer-Instances können jedoch sowohl Schreib- als auch Leseabfragen akzeptieren.
Mit den globalen Aurora-Datenbanken können Sie Daten sowohl API auf primären als auch auf sekundären DB-Clustern aktivieren. Solange ein sekundärer Cluster jedoch nicht zum primären Cluster heraufgestuft wird, hat er keine Writer-Instance. Daher schlagen API Datenabfragen fehl, die Sie an den sekundären Server senden. Sobald eine beförderte sekundäre Instanz über eine verfügbare Writer-Instance verfügt, sollten API Datenabfragen auf dieser DB-Instance erfolgreich sein.
Performance Insights unterstützt keine Überwachung von Datenbankabfragen, die Sie mithilfe von Data durchführenAPI.
Daten werden in T-DB-Instance-Klassen API nicht unterstützt.
Für Aurora Serverless v2 und bereitgestellte DB-Cluster, die die SQL Postgre-Engine verwenden, unterstützt RDS Data einige Datentypen API nicht. Eine Liste der unterstützten Typen finden Sie unter. Vergleich von RDS Daten API mit Serverless v2 und bereitgestellten Daten und Aurora Serverless v1
Für Datenbanken mit Aurora SQL Postgre-Version 14 und höher unterstützt Data API nur die
scram-sha-256
Passwortverschlüsselung.-
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 Aurora Serverless v1 ist die maximale Anzahl von Anfragen pro Sekunde 1.000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.
-
Die API Datengrößenbeschränkung beträgt 64 KB pro Zeile in der von der Datenbank zurückgegebenen Ergebnismenge. Stellen Sie sicher, dass jede Zeile in einer Ergebnismenge 64 KB oder weniger groß ist.
Vergleich von RDS Daten API mit Serverless v2 und bereitgestellten Daten und Aurora Serverless v1
Die neuesten Verbesserungen von RDS Data API machen es für Cluster verfügbar, die aktuelle Versionen der SQL Postgre-Engine verwenden. Diese Cluster könnten so konfiguriert werdenAurora Serverless v2, dass sie Instanzklassen wie db.t4g
oder verwenden oder bereitstellen. db.r6i
In der folgenden Tabelle werden die Unterschiede zwischen RDS Data API (DataAPI) mit Aurora Postgre SQL Serverless v2 und bereitgestellten DB-Clustern sowie RDS API zwischen DB-Clustern beschrieben. Aurora Serverless v1
Unterschied | Aurora Postgre SQL Serverless v2 und bereitgestellt | Aurora Serverless v1 |
---|---|---|
Maximale Anzahl von Anfragen pro Sekunde | Unbegrenzt | 1.000 |
Aktivieren oder Deaktivieren von Daten API in einer vorhandenen Datenbank mithilfe von oder RDS API AWS CLI |
|
|
CloudTrail Ereignisse | Ereignisse aus API Datenaufrufen 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 API Datenaufrufen 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 mehrerer Anweisungen | Multistatements werden nicht unterstützt. In diesem Fall API wirft ValidationException: Multistatements aren't
supported Data. |
Für Aurora Postgre SQL geben Multistatements nur die erste Abfrageantwort zurück. Für Aurora My SQL werden Multistatements nicht unterstützt. |
BatchExecuteStatement | Das generierte Feldobjekt im Aktualisierungsergebnis ist leer. | Das generierte Feldobjekt im Aktualisierungsergebnis enthält eingefügte Werte. |
Führen Sie aus SQL | Nicht unterstützt | Als veraltet gekennzeichnet |
ExecuteStatement |
Data unterstützt einige Datentypen API nicht, z. B. geometrische und monetäre Typen. In diesem Fall API wirft Nur die folgenden Typen werden unterstützt:
Nur die folgenden Array-Typen werden unterstützt:
|
ExecuteStatement unterstützt das Abrufen multidimensionaler Array-Spalten und aller erweiterten Datentypen. |
Autorisieren des Zugriffs auf Daten RDS API
Benutzer können Datenoperationen API (RDSDatenAPI) nur aufrufen, wenn sie dazu autorisiert sind. Sie können einem Benutzer die Erlaubnis zur Verwendung API von Daten erteilen, indem Sie eine AWS Identity and Access Management (IAM) -Richtlinie anhängen, die seine Rechte definiert. Sie können die Richtlinie auch an eine Rolle anhängen, wenn Sie IAM Rollen verwenden. Eine AWS verwaltete AmazonRDSDataFullAccess
Richtlinie umfasst Berechtigungen für DatenAPI.
Die AmazonRDSDataFullAccess
Richtlinie umfasst auch Berechtigungen, aus denen der Benutzer den Wert eines Geheimnisses abrufen kann AWS Secrets Manager. Benutzer müssen Secrets Manager verwenden, um Geheimnisse zu speichern, die sie bei ihren Aufrufen von Data verwenden könnenAPI. Die Verwendung von Geheimnissen bedeutet, dass Benutzer keine Datenbankanmeldeinformationen für die Ressourcen angeben müssen, auf die sie bei ihren Aufrufen von Data abzielenAPI. Data ruft Secrets Manager API transparent auf, wodurch die Anfrage des Benutzers nach dem Secret zugelassen (oder abgelehnt) wird. Hinweise zum Einrichten von Geheimnissen für die Verwendung mit Daten finden Sie API unter. Speichern von Datenbankanmeldedaten in AWS Secrets Manager
Die AmazonRDSDataFullAccess
Richtlinie bietet vollständigen Zugriff (über DatenAPI) auf Ressourcen. Sie können den Umfang einschränken, indem Sie Ihre eigenen Richtlinien definieren, die den Amazon-Ressourcennamen (ARN) einer Ressource angeben.
Die folgende Richtlinie zeigt beispielsweise ein Beispiel für die Mindestberechtigungen, die ein Benutzer für den Zugriff auf Daten API für den anhand seiner identifizierten DB-Cluster benötigtARN. 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
" } ] }
Wir empfehlen, dass Sie in Ihren Richtlinienerklärungen ein spezifisches Element ARN für das „Ressourcen“ -Element verwenden (wie im Beispiel gezeigt), anstatt einen Platzhalter (*) zu verwenden.
Arbeiten mit der Tag-basierten Autorisierung
RDSData API (DataAPI) 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 Zeichenkettenwert kennzeichnen, zum Beispiel:
environment:production
environment: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 haben und diese anwenden möchten, finden Sie weitere Informationen unter RDSAmazon-Ressourcen taggen.) Sie können die Tags in Ihren Richtlinienerklärungen verwenden, um den Zugriff auf die RDS Cluster zu beschrä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 Aussage setzt voraus, dass sowohl der Cluster als auch das in der API Datenanforderung übergebene Geheimnis über ein environment:production
Tag verfügen.
Die Richtlinie wird wie folgt angewendet: Wenn ein Benutzer mithilfe von Data einen Anruf tätigtAPI, wird die Anfrage an den Dienst gesendet. Data überprüft API zunächst, ob der Cluster, der die Anfrage ARN übergeben hat, mit environment:production
markiert ist. 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 Data API dann den abgerufenen Wert für das DB-Passwort des Benutzers. Wenn das auch korrekt ist, wird die API Datenanforderung schließlich erfolgreich für den Benutzer 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 and 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 von identitätsbasierten Richtlinien (IAMRichtlinien) für Secrets Manager.
Im Element „Bedingung“ der Richtlinie können Sie Tag-Schlüssel aus den folgenden Optionen auswählen:
aws:TagKeys
aws:ResourceTag/${TagKey}
Weitere Informationen zu Ressourcen-Tags und deren Verwendung aws:TagKeys
finden Sie unter Steuern des Zugriffs auf AWS Ressourcen mithilfe von Resource-Tags.
Anmerkung
Sowohl Daten API als auch Benutzer AWS Secrets Manager autorisieren. Wenn Sie nicht für alle in einer Richtlinie definierten Aktionen Berechtigungen besitzen, erhalten Sie den Fehler AccessDeniedException
.
Speichern von Datenbankanmeldedaten in AWS Secrets Manager
Wenn Sie RDS Data API (DataAPI) aufrufen, übergeben Sie Anmeldeinformationen für den Aurora-DB-Cluster mithilfe eines Secrets in Secrets Manager. Um Anmeldeinformationen auf diese Weise zu übergeben, geben Sie den Namen des Geheimnisses oder den Amazon-Ressourcennamen (ARN) des Geheimnisses 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.
-
Verwenden Sie die Secrets Manager Manager-Konsole, um die Details für das von Ihnen erstellte Geheimnis anzuzeigen, oder führen Sie den
aws secretsmanager describe-secret
AWS CLI Befehl aus.Notieren Sie sich den Namen und ARN das Geheimnis. Sie können sie bei Aufrufen von Data verwendenAPI.
Weitere Informationen zur Verwendung von Secrets Manager finden Sie im AWS Secrets-Manager-Benutzerhandbuch.
Informationen darüber, wie Amazon Aurora das Identitäts- und Zugriffsmanagement verwaltet, finden Sie unter So arbeitet Amazon Aurora mit IAM.
Weitere Informationen zum Erstellen einer IAM Richtlinie finden Sie unter IAMRichtlinien erstellen im IAMBenutzerhandbuch. Informationen zum Hinzufügen einer IAM Richtlinie zu einem Benutzer finden Sie unter Hinzufügen und Entfernen von IAM Identitätsberechtigungen im IAMBenutzerhandbuch.
RDSDaten aktivieren API
Um RDS Data API (DataAPI) zu verwenden, aktivieren Sie es für Ihren Aurora-DB-Cluster. Sie können Data aktivierenAPI, wenn Sie den DB-Cluster erstellen oder ändern.
Anmerkung
Für Aurora Postgre SQL werden Daten API mit Aurora Serverless v2Aurora Serverless v1, und bereitgestellten Datenbanken unterstützt. Für Aurora My SQL werden Daten API nur mit Aurora Serverless v1 Datenbanken unterstützt.
Themen
RDSDaten aktivierenAPI, wenn Sie eine Datenbank erstellen
Während Sie eine Datenbank erstellen, die RDS Daten API (DatenAPI) unterstützt, können Sie diese Funktion aktivieren. In den folgenden Verfahren wird beschrieben, wie Sie dies tun, wenn Sie die AWS Management Console AWS CLI, die oder die verwenden RDSAPI.
Um Daten API beim Erstellen eines DB-Clusters zu aktivieren, aktivieren Sie das API Kontrollkästchen RDS Daten aktivieren im Abschnitt Konnektivität der Seite Datenbank erstellen, wie im folgenden Screenshot gezeigt.
Anweisungen zum Erstellen eines Aurora-DB-Clusters, der die RDS Daten verwenden kannAPI, finden Sie im Folgenden:
Für Aurora Postgre SQL Serverless v2 und bereitgestellte Cluster — Erstellen eines Amazon Aurora-DB Clusters
Aurora Serverless v1Für — Erstellen eines Aurora Serverless v1-DB Clusters
Um Data zu aktivieren, API 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 Aurora SQL Postgre-DB-Cluster mit API aktivierten Daten erstellt.
Für LinuxmacOS, oderUnix:
aws rds create-db-cluster \ --db-cluster-identifier
my_pg_cluster
\ --engine aurora-postgresql \ --enable-http-endpoint
Windows:
aws rds create-db-cluster ^ --db-cluster-identifier
my_pg_cluster
^ --engine aurora-postgresql ^ --enable-http-endpoint
Um Data zu aktivieren, API während Sie einen Aurora-DB-Cluster erstellen, verwenden Sie die reateDBCluster Operation C, wobei der Wert des EnableHttpEndpoint
Parameters auf gesetzt isttrue
.
RDSDaten in API einer vorhandenen Datenbank aktivieren
Sie können einen DB-Cluster ändern, der RDS Daten API (DatenAPI) unterstützt, um diese Funktion zu aktivieren oder zu deaktivieren.
Themen
Daten aktivieren oder deaktivieren API (Aurora Postgre SQL Serverless v2 und bereitgestellt)
Verwenden Sie die folgenden Verfahren, um Daten API auf Aurora Postgre SQL Serverless v2 und bereitgestellten Datenbanken zu aktivieren oder zu deaktivieren. Verwenden Sie die Verfahren unter, um Daten API in Aurora Serverless v1 Datenbanken zu aktivieren oder zu deaktivieren. Daten aktivieren oder deaktivieren API (Aurora Serverless v1nur)
Sie können Daten aktivieren oder deaktivieren, API indem Sie die RDS Konsole für einen DB-Cluster verwenden, der diese Funktion unterstützt. Öffnen Sie dazu die Cluster-Detailseite der Datenbank, in der Sie Daten aktivieren oder deaktivieren möchtenAPI, und wechseln Sie auf der Registerkarte Konnektivität und Sicherheit zum API Abschnitt RDSDaten. In diesem Abschnitt wird der Status der Daten API angezeigt und Sie können sie aktivieren oder deaktivieren.
Der folgende Screenshot zeigt, dass die RDSDaten API nicht aktiviert sind.
Um Daten API in einer vorhandenen Datenbank zu aktivieren oder zu deaktivieren, führen Sie den disable-http-endpoint AWS CLI Befehl enable-http-endpointor aus und geben Sie den ARN Ihres DB-Clusters an.
Das folgende Beispiel aktiviert DataAPI.
Für LinuxmacOS, oderUnix:
aws rds enable-http-endpoint \ --resource-arn
cluster_arn
Windows:
aws rds enable-http-endpoint ^ --resource-arn
cluster_arn
Verwenden Sie die DisableHttpEndpointOperationen EnableHttpEndpointund, um Daten API in einer vorhandenen Datenbank zu aktivieren oder zu deaktivieren.
Daten aktivieren oder deaktivieren API (Aurora Serverless v1nur)
Gehen Sie wie folgt vor, um Daten in vorhandenen Aurora Serverless v1 Datenbanken zu aktivieren oder API zu deaktivieren. Um Daten API auf Aurora Postgre SQL Serverless v2 und bereitgestellten Datenbanken zu aktivieren oder zu deaktivieren, verwenden Sie die Verfahren unter. Daten aktivieren oder deaktivieren API (Aurora Postgre SQL Serverless v2 und bereitgestellt)
Wenn Sie einen Aurora Serverless v1 DB-Cluster ändern, aktivieren Sie Data API im Bereich Konnektivität der RDS Konsole.
Der folgende Screenshot zeigt die aktivierten Daten API beim Ändern eines Aurora-DB-Clusters.
Anweisungen zum Ändern eines Aurora Serverless v1 DB-Clusters finden Sie unterÄndern eines Aurora Serverless v1-DB-Clusters.
Um Data zu aktivieren oder zu deaktivierenAPI, führen Sie den modify-db-cluster AWS CLI Befehl, je nach Bedarf--no-enable-http-endpoint
, mit dem --enable-http-endpoint
oder aus.
Im folgenden Beispiel wird Data API on aktiviertsample-cluster
.
Für LinuxmacOS, oderUnix:
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 Data zu aktivierenAPI, verwenden Sie die odifyDBClusterM-Operation und setzen Sie den Wert von EnableHttpEndpoint
auf true
oderfalse
, falls zutreffend.
Einen VPC Amazon-Endpunkt für RDS Daten erstellen API (AWS PrivateLink)
VPCMit Amazon können Sie AWS Ressourcen wie Aurora-DB-Cluster und -Anwendungen in einer virtuellen privaten Cloud (VPC) starten. AWS PrivateLink bietet private Konnektivität zwischen VPCs und AWS Diensten mit hoher Sicherheit im Amazon-Netzwerk. Mithilfe AWS PrivateLink können Sie VPC Amazon-Endpunkte erstellen, mit denen Sie eine Verbindung zu Diensten herstellen können, die über verschiedene Konten hinweg und auf Amazon VPCs VPC basieren. Weitere Informationen zu AWS PrivateLink finden Sie unter VPCEndpoint Services (AWS PrivateLink) im Amazon Virtual Private Cloud Cloud-Benutzerhandbuch.
Sie können RDS Data API (DataAPI) mit VPC Amazon-Endpunkten aufrufen. Durch die Verwendung eines VPC Amazon-Endpunkts wird der Verkehr zwischen Anwendungen API in Ihrem Amazon VPC und Daten im AWS Netzwerk aufrechterhalten, ohne öffentliche IP-Adressen zu verwenden. VPCAmazon-Endgeräte können Ihnen dabei helfen, die Compliance-Anforderungen und behördlichen Anforderungen im Zusammenhang mit der Einschränkung der öffentlichen Internetkonnektivität zu erfüllen. Wenn Sie beispielsweise einen VPC Amazon-Endpunkt verwenden, können Sie den Verkehr zwischen einer Anwendung, die auf einer EC2 Amazon-Instance ausgeführt wird, und Daten API in den AnwendungenVPCs, die sie enthalten, aufrechterhalten.
Nachdem Sie den VPC Amazon-Endpunkt erstellt haben, können Sie ihn verwenden, ohne Code- oder Konfigurationsänderungen in Ihrer Anwendung vornehmen zu müssen.
So erstellen Sie einen VPC Amazon-Endpunkt für Daten API
Melden Sie sich bei der an AWS Management Console und öffnen Sie die VPC Amazon-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 das aus VPC, in VPC dem der Endpunkt erstellt werden soll.
Wählen Sie die ausVPC, die die Anwendung enthält, die API Datenanrufe tätigt.
-
Wählen Sie für Subnetze das Subnetz für jede Availability Zone (AZ) aus, die von dem AWS Dienst verwendet wird, auf dem Ihre Anwendung ausgeführt wird.
Um einen VPC Amazon-Endpunkt zu erstellen, geben Sie den privaten IP-Adressbereich an, in dem auf den Endpunkt zugegriffen werden kann. 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, und außerdem wird in jeder Availability Zone ein VPC Amazon-Endpunkt erstellt.
-
Wählen Sie als DNSNamen aktivieren die Option Für diesen Endpunkt aktivieren aus.
Private DNS löst den standardmäßigen API DNS Daten-Hostnamen (
https://rds-data.
) in die privaten IP-Adressen auf, die mit dem für Ihren Amazon-Endpunkt spezifischen DNS Hostnamen verknüpft sind. VPC Daher können Sie mit oder auf den API VPC Datenendpunkt zugreifen, AWS SDKs ohne Code AWS CLI - oder Konfigurationsänderungen vorzunehmen, um den API Datenendpunkt zu aktualisieren. URLregion
.amazonaws.com -
Wählen Sie unter Sicherheitsgruppe eine Sicherheitsgruppe aus, die dem VPC Amazon-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 Ihre Anwendung beispielsweise auf einer EC2 Amazon-Instance ausgeführt wird, wählen Sie die Sicherheitsgruppe aus, die den Zugriff auf die EC2 Amazon-Instance ermöglicht. Die Sicherheitsgruppe ermöglicht es Ihnen, den Verkehr zum VPC Amazon-Endpunkt von Ressourcen in Ihrem zu kontrollierenVPC.
-
Wählen Sie unter Richtlinie die Option Vollzugriff aus, damit jeder innerhalb von Amazon VPC API über diesen Endpunkt auf die Daten 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 Endpunkt erstellen aus.
Nachdem der Endpunkt erstellt wurde, wählen Sie den Link in, AWS Management Console um die Endpunktdetails anzuzeigen.
Auf der Registerkarte Endpunktdetails werden die DNS Hostnamen angezeigt, die bei der Erstellung des VPC Amazon-Endpunkts generiert wurden.
Sie können den Standardendpunkt (rds-data.
) oder einen der VPC spezifischen Endpunkte verwenden, um die Daten API innerhalb des Amazon aufzurufen. VPC Der API Standard-Datenendpunkt leitet automatisch zum VPC Amazon-Endpunkt weiter. Dieses Routing erfolgt, weil der private DNS Hostname aktiviert wurde, als der VPC Amazon-Endpunkt erstellt wurde.region
.amazonaws.com
Wenn Sie einen VPC Amazon-Endpunkt in einem API Datenaufruf verwenden, API verbleibt der gesamte Datenverkehr zwischen Ihrer Anwendung und den Daten in dem AmazonVPCs, in dem sie gespeichert sind. Sie können einen VPC Amazon-Endpunkt für jede Art von API Datenaufrufen verwenden. Informationen zum Aufrufen von Daten API finden Sie unterRDSDaten aufrufen API.
RDSDaten aufrufen API
Wenn RDS Data API (DataAPI) auf Ihrem Aurora-DB-Cluster aktiviert ist, können Sie SQL Anweisungen auf dem Aurora-DB-Cluster ausführen, indem Sie Data API oder den verwenden AWS CLI. Data API unterstützt die Programmiersprachen, die von der unterstützt werden AWS SDKs. Weitere Informationen finden Sie unter Tools, auf denen Sie aufbauen können AWS
Themen
Referenz zu API Datenoperationen
Data API bietet die folgenden Operationen zum Ausführen von SQL Anweisungen.
APIBetrieb von Daten |
AWS CLI Befehl |
Beschreibung |
---|---|---|
Führt eine SQL Anweisung in einer Datenbank aus. |
||
Führt eine SQL Batch-Anweisung für Massenaktualisierungs- und Einfügevorgänge über ein Datenarray aus. Sie können eine Data Manipulation Language (DML) -Anweisung mit einer Reihe von Parametersätzen ausführen. Eine SQL Batch-Anweisung kann im Vergleich zu einzelnen Insert- und Aktualisierungsanweisungen zu einer deutlichen Leistungsverbesserung führen. |
Sie können beide Operationen verwenden, um einzelne SQL Anweisungen oder Transaktionen auszuführen. Für Transaktionen API bietet Data die folgenden Operationen.
APIBetrieb der Daten |
AWS CLI Befehl |
Beschreibung |
---|---|---|
Startet eine SQL Transaktion. |
||
Beendet eine SQL Transaktion und schreibt die Änderungen fest. |
||
Führt ein Rollback einer Transaktion durch. |
Die Operationen zur Ausführung von SQL Anweisungen und zur Unterstützung von Transaktionen haben die folgenden gemeinsamen API Datenparameter und AWS CLI -optionen. Einige Operationen unterstützen andere Parameter oder Optionen.
Parameter für die API Datenoperation |
AWS CLI Befehlsoption |
Erforderlich |
Beschreibung |
---|---|---|---|
|
|
Ja |
Der Amazon-Ressourcenname (ARN) des Aurora-DB-Clusters. |
|
|
Ja |
Der Name oder ARN das Geheimnis, das den Zugriff auf den DB-Cluster ermöglicht. |
Sie können Parameter in API Datenaufrufen an ExecuteStatement
und und verwendenBatchExecuteStatement
, wenn Sie die AWS CLI Befehle execute-statement
und ausführenbatch-execute-statement
. 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 werden die Datentypen von Java Database Connectivity (JDBC) den Datentypen zugeordnet, die Sie in API Datenaufrufen angeben.
JDBCDatentyp |
Datentyp der API Daten |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
Andere Typen (einschließlich datums- und zeitbezogener Typen) |
|
Anmerkung
Sie können den STRING
Datentyp LONG
oder in Ihrem API Datenaufruf für LONG
Werte angeben, die von der Datenbank zurückgegeben werden. Wir empfehlen Ihnen, dies zu tun, um zu vermeiden, dass bei extrem großen Zahlen die Genauigkeit verloren geht, was passieren kann, wenn Sie mit JavaScript
Für bestimmte Typen, wie z. B. DECIMAL
undTIME
, ist ein Hinweis erforderlich, damit Data String
Werte als den richtigen Typ an die Datenbank API weitergibt. 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 TypsDATE
an die Datenbank gesendet. Das akzeptierte Format istYYYY-MM-DD
. -
DECIMAL
– Der entsprechendeString
-Parameter wird als Objekt des TypsDECIMAL
an die Datenbank gesendet. -
JSON
– Der entsprechendeString
-Parameter wird als Objekt des TypsJSON
an die Datenbank gesendet. -
TIME
– Der entsprechendeString
-Parameter wird als Objekt des TypsTIME
an die Datenbank gesendet. Das akzeptierte Format istHH:MM:SS[.FFF]
. -
TIMESTAMP
– Der entsprechendeString
-Parameter wird als Objekt des TypsTIMESTAMP
an die Datenbank gesendet. Das akzeptierte Format istYYYY-MM-DD HH:MM:SS[.FFF]
. -
UUID
– Der entsprechendeString
-Parameter wird als Objekt des TypsUUID
an die Datenbank gesendet.Anmerkung
Derzeit unterstützt Data API keine Arrays von Universal Unique Identifiers ()UUIDs.
Anmerkung
Für Amazon Aurora Postgre SQL gibt Data API immer den Aurora SQL Postgre-Datentyp TIMESTAMPTZ
in der Zeitzone zurückUTC.
Aufrufen von RDS Daten API mit dem AWS CLI
Sie können RDS Data API (DataAPI) mit dem aufrufen AWS CLI.
In den folgenden Beispielen wird AWS CLI for Data verwendetAPI. 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 das Geheimnis ARN durch das ARN Geheimnis in Secrets Manager, das den Zugriff auf den DB-Cluster ermöglicht.
Anmerkung
Sie AWS CLI können Antworten formatieren inJSON.
Themen
Eine SQL Transaktion starten
Sie können eine SQL Transaktion mit dem aws rds-data
begin-transaction
CLI Befehl starten. Der Aufruf gibt eine Transaktions-ID zurück.
Wichtig
Innerhalb von Data API tritt bei einer Transaktion ein Timeout auf, wenn innerhalb von drei Minuten keine Aufrufe erfolgen, die ihre Transaktions-ID verwenden. Wenn bei einer Transaktion das Timeout überschritten wird, bevor sie festgeschrieben wurde, wird API sie von Data automatisch zurückgesetzt.
Meine Anweisungen in der SQL Datendefinitionssprache (DDL) innerhalb einer Transaktion führen zu einem impliziten Commit. Wir empfehlen, dass Sie jede SQL DDL My-Anweisung in einem separaten execute-statement
Befehl mit der --continue-after-timeout
Option ausführen.
Geben Sie zusätzlich zu den allgemeinen Optionen die Option --database
an, die den Namen der Datenbank enthält.
Mit dem folgenden CLI Befehl wird beispielsweise eine SQL Transaktion gestartet.
Für LinuxmacOS, oderUnix:
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
"
}
Eine SQL Anweisung ausführen
Sie können eine SQL Anweisung mit dem aws rds-data execute-statement
CLI Befehl ausführen.
Sie können die SQL Anweisung in einer Transaktion ausführen, indem Sie die Transaktions-ID mit der --transaction-id
Option angeben. Sie können eine Transaktion mit dem aws rds-data begin-transaction
CLI Befehl starten. Sie können eine Transaktion mit dem aws rds-data
commit-transaction
CLI Befehl beenden und festschreiben.
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) — Der Bezeichner einer Transaktion, die mit dembegin-transaction
CLI Befehl gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL Anweisung aufnehmen 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 sie--sql "use
in der vorherigen Anforderung ausgefü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 Anweisung weiter ausgeführt werden soll, nachdem der Aufruf das API Daten-Timeout-Intervall von 45 Sekunden überschritten hat. Der Standardwert ist--no-continue-after-timeout
.Bei Anweisungen in der Datendefinitionssprache (DDL) empfehlen wir, die Anweisung nach Ablauf des Aufrufs weiter auszufü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"
. Hinweise zur Verwendung der Verarbeitung von JSON Ergebnismengen finden Sie unterVerarbeitung von RDS API Datenabfrageergebnissen im Format JSON.
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.
Denn Aurora Serverless v1 die maximale Anzahl von Anfragen pro Sekunde beträgt 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 (Standardeinstellung).
Für LinuxmacOS, oderUnix:
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
"
}
]
]
}
Mit dem folgenden CLI Befehl wird eine einzelne SQL Anweisung in einer Transaktion ausgeführt, indem die --transaction-id
Option angegeben wird.
Für LinuxmacOS, oderUnix:
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 LinuxmacOS, oderUnix:
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 intomytable
values (: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 intomytable
values (: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
}
Mit dem folgenden CLI Befehl wird eine Data Definition Language (DDL) SQL -Anweisung ausgeführt. Die DDL Anweisung benennt Spalte job
für Spalte role
um.
Wichtig
Bei DDL Kontoauszügen empfehlen wir, die Anweisung auch nach Ablauf des Aufrufs weiter auszuführen. Wenn eine DDL Anweisung beendet wird, bevor ihre Ausführung abgeschlossen ist, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um die Ausführung einer Anweisung fortzusetzen, nachdem ein Aufruf das RDS API Daten-Timeout-Intervall von 45 Sekunden überschritten hat, geben Sie die --continue-after-timeout
Option an.
Für LinuxmacOS, oderUnix:
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 Postgre SQL nicht unterstützt. Zum Abrufen der Werte von generierten Feldern verwenden Sie die RETURNING
-Klausel. Weitere Informationen finden Sie in der Postgre-Dokumentation unter Rückgabe von Daten aus geänderten Zeilen
Eine SQL Batch-Anweisung über ein Datenarray ausführen
Mit dem aws rds-data batch-execute-statement
CLI Befehl können Sie eine SQL Batch-Anweisung für ein Datenarray ausführen. 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 --transaction-id
Option angeben. Sie können eine Transaktion mit dem aws rds-data
begin-transaction
CLI Befehl starten. Sie können eine Transaktion beenden und festschreiben, indem Sie den aws rds-data commit-transaction
CLI Befehl 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.Tipp
Fügen Sie bei My SQL -kompatiblen Anweisungen kein Semikolon am Ende des Parameters ein.
--sql
Ein abschließendes Semikolon kann einen Syntaxfehler verursachen. -
--transaction-id
(optional) — Der Bezeichner einer Transaktion, die mit dem Befehl gestartet wurde.begin-transaction
CLI Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL Anweisung aufnehmen 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 Data eingereichten HTTP Anfrage API beträgt jedoch 4 MiB. Wenn die Anfrage dieses Limit überschreitet, API gibt Data einen Fehler zurück und verarbeitet die Anfrage nicht. Dieses Limit von 4 MiB beinhaltet die Größe der HTTP Header und die JSON Notation in der Anfrage. Daher hängt die Anzahl der Parametersätze, die Sie einbeziehen können, von einer Kombination von Faktoren ab, z. B. von der Größe der SQL Anweisung und der Größe der einzelnen 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.
Denn Aurora Serverless v1 die maximale Anzahl von Anfragen pro Sekunde beträgt 1.000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.
Mit dem folgenden CLI Befehl wird beispielsweise eine SQL Batch-Anweisung über ein Datenarray mit einem Parametersatz ausgeführt.
Für LinuxmacOS, oderUnix:
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 intomytable
values (: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 intomytable
values (: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.
Eine Transaktion festschreiben SQL
Mit dem aws rds-data commit-transaction
CLI Befehl können Sie eine SQL Transaktion beenden, mit der Sie begonnen haben, aws rds-data
begin-transaction
und die Änderungen festschreiben.
Geben Sie zusätzlich zu den allgemeinen Optionen die folgende Option an:
-
--transaction-id
(erforderlich) — Die Kennung einer Transaktion, die mit dembegin-transaction
CLI Befehl gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, die Sie beenden und übergeben möchten.
Mit dem folgenden CLI Befehl wird beispielsweise eine SQL Transaktion beendet und die Änderungen werden festgeschrieben.
Für LinuxmacOS, oderUnix:
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"
}
Eine SQL Transaktion rückgängig machen
Mit dem aws rds-data rollback-transaction
CLI Befehl können Sie eine SQL Transaktion rückgängig machen, mit der Sie begonnen habenaws rds-data
begin-transaction
. 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 Kennung einer Transaktion, die mit dembegin-transaction
CLI Befehl gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, für die Sie ein Rollback ausführen möchten.
Mit dem folgenden AWS CLI Befehl wird beispielsweise eine SQL Transaktion rückgängig gemacht.
Für LinuxmacOS, oderUnix:
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"
}
RDSDaten API aus einer Python-Anwendung aufrufen
Sie können RDS Data API (DataAPI) von einer Python-Anwendung aus aufrufen.
In den folgenden Beispielen wird das AWS SDK für Python (Boto) verwendet. Weitere Informationen zu Boto finden Sie in der Dokumentation AWS SDKfür Python (Boto 3)
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 das Geheimnis ARN durch das ARN Geheimnis in Secrets Manager, das den Zugriff auf den DB-Cluster ermöglicht.
Eine SQL Abfrage ausführen
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'
}
]
]
Eine DML SQL Anweisung ausführen
Sie können eine Data Manipulation Language (DML) -Anweisung ausführen, um Daten in Ihre Datenbank einzufügen, zu aktualisieren oder zu löschen. Sie können Parameter auch in DML Anweisungen 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 wird 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"])
Eine SQL Transaktion ausführen
Sie können eine SQL Transaktion starten, eine oder mehrere SQL Anweisungen ausführen und dann die Änderungen mit einer Python-Anwendung festschreiben.
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']
1
Anmerkung
Wenn Sie eine Data Definition Language (DDL) -Anweisung ausführen, empfehlen wir, die Anweisung nach dem Timeout des Aufrufs weiter auszuführen. Wenn eine DDL Anweisung beendet wird, bevor ihre Ausführung abgeschlossen ist, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um die Ausführung einer Anweisung fortzusetzen, nachdem ein Aufruf das RDS API Daten-Timeout-Intervall von 45 Sekunden überschritten hat, setzen Sie den continueAfterTimeout
Parameter auf. true
Aufrufen API von RDS Daten aus einer Java-Anwendung
Sie können RDS Data API (DataAPI) von einer Java-Anwendung aus aufrufen.
In den folgenden Beispielen wird der AWS SDK für Java verwendet. 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 das Geheimnis ARN durch das ARN Geheimnis in Secrets Manager, das den Zugriff auf den DB-Cluster ermöglicht.
Themen
Eine SQL Abfrage ausführen
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));
}
}
}
Eine SQL Transaktion ausführen
Sie können eine SQL Transaktion starten, eine oder mehrere SQL Anweisungen ausführen und dann die Änderungen mit einer Java-Anwendung festschreiben.
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 Data Definition Language (DDL) -Anweisung ausführen, empfehlen wir, die Anweisung nach einem Timeout des Aufrufs weiter auszuführen. Wenn eine DDL Anweisung beendet wird, bevor ihre Ausführung abgeschlossen ist, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um die Ausführung einer Anweisung fortzusetzen, nachdem ein Aufruf das RDS API Daten-Timeout-Intervall von 45 Sekunden überschritten hat, setzen Sie den continueAfterTimeout
Parameter auf. true
Eine SQL Batch-Operation wird ausgeführt
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 einer Reihe 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);
}
}
Steuern des Verhaltens beim API Daten-Timeout
Alle Aufrufe von Data API erfolgen synchron. Angenommen, Sie führen eine API Datenoperation durch, die eine SQL Anweisung wie INSERT
oder CREATE TABLE
ausführt. Wenn der API Datenaufruf erfolgreich zurückkehrt, ist die SQL Verarbeitung abgeschlossen, wenn der Aufruf zurückkehrt.
Standardmäßig API bricht Data einen Vorgang ab und gibt einen Timeout-Fehler zurück, wenn die Verarbeitung nicht innerhalb von 45 Sekunden abgeschlossen wird. In diesem Fall werden die Daten nicht eingefügt, die Tabelle nicht erstellt usw.
Sie können Data verwendenAPI, um lang andauernde Operationen auszuführen, die nicht innerhalb von 45 Sekunden abgeschlossen werden können. Wenn Sie davon ausgehen, dass ein Vorgang, z. B. ein Massenvorgang INSERT
oder ein DDL Vorgang an einer großen Tabelle, länger als 45 Sekunden dauert, können Sie den continueAfterTimeout
Parameter für den ExecuteStatement
Vorgang angeben. Ihre Anwendung erhält immer noch den Timeout-Fehler. Der Vorgang wird jedoch weiterhin ausgeführt und nicht abgebrochen. Ein Beispiel finden Sie unter Eine SQL Transaktion ausführen.
Wenn AWS SDK für Ihre Programmiersprache ein eigenes Timeout für API Anrufe oder HTTP Socket-Verbindungen gilt, stellen Sie sicher, dass alle diese Timeout-Perioden mehr als 45 Sekunden betragen. In einigen SDKs Fällen beträgt der Timeout-Zeitraum standardmäßig weniger als 45 Sekunden. Wir empfehlen, alle SDK spezifischen oder kundenspezifischen Timeout-Zeiträume auf mindestens eine Minute festzulegen. Dadurch wird die Möglichkeit vermieden, dass Ihre Anwendung einen Timeout-Fehler erhält, während der API Datenvorgang dennoch erfolgreich abgeschlossen wird. Auf diese Weise können Sie sicher sein, ob Sie den Vorgang wiederholen möchten oder nicht.
Nehmen wir zum Beispiel an, dass der einen Timeout-Fehler an Ihre Anwendung SDK zurückgibt, der API Datenvorgang aber trotzdem innerhalb des API Daten-Timeout-Intervalls abgeschlossen wird. In diesem Fall könnte ein erneuter Versuch des Vorgangs doppelte Daten einfügen oder auf andere Weise zu falschen Ergebnissen führen. Der Vorgang wird SDK möglicherweise automatisch wiederholt, wodurch falsche Daten entstehen, ohne dass Ihre Anwendung etwas dagegen unternommen hat.
Das Timeout-Intervall ist besonders wichtig für Java 2. SDK Dabei betragen das SDK API Aufruf-Timeout und das HTTP Socket-Timeout standardmäßig beide 30 Sekunden. Hier ist ein Beispiel dafür, wie diese Timeouts auf einen höheren Wert gesetzt werden:
public RdsDataClient createRdsDataClient() { return RdsDataClient.builder() .region(Region.US_EAST_1) // Change this to your desired Region .overrideConfiguration(createOverrideConfiguration()) .httpClientBuilder(createHttpClientBuilder()) .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider .build(); } private static ClientOverrideConfiguration createOverrideConfiguration() { return ClientOverrideConfiguration.builder() .apiCallTimeout(Duration.ofSeconds(60)) .build(); } private HttpClientBuilder createHttpClientBuilder() { return ApacheHttpClient.builder() // Change this to your desired HttpClient .socketTimeout(Duration.ofSeconds(60)); }
Hier ist ein äquivalentes Beispiel für die Verwendung des asynchronen Datenclients:
public static RdsDataAsyncClient createRdsDataAsyncClient() { return RdsDataAsyncClient.builder() .region(Region.US_EAST_1) // Change this to your desired Region .overrideConfiguration(createOverrideConfiguration()) .credentialsProvider(defaultCredentialsProvider()) // Change this to your desired credentials provider .build(); } private static ClientOverrideConfiguration createOverrideConfiguration() { return ClientOverrideConfiguration.builder() .apiCallAttemptTimeout(Duration.ofSeconds(60)) .build(); } private HttpClientBuilder createHttpClientBuilder() { return NettyNioAsyncHttpClient.builder() // Change this to your desired AsyncHttpClient .readTimeout(Duration.ofSeconds(60)); }
Verwendung der Java-Clientbibliothek für Daten RDS API
Sie können eine Java-Clientbibliothek für RDS Data API (DataAPI) herunterladen und verwenden. Diese Java-Clientbibliothek bietet eine alternative Möglichkeit, Data zu verwendenAPI. Mithilfe dieser Bibliothek können Sie Ihre clientseitigen Klassen API Datenanfragen und -antworten zuordnen. Dieser Mapping-Support kann die Integration mit einigen bestimmten Java-Typen wie etwa Date
, Time
und BigDecimal
erleichtern.
Die Java-Clientbibliothek für Data wird heruntergeladen API
Die Data API Java-Clientbibliothek ist GitHub am folgenden Speicherort als Open Source verfügbar:
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 Ihrer Maven-Datei die folgende Abhängigkeit hinzu. POM
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
Im Folgenden finden Sie einige gängige Beispiele für die Verwendung der Data API Java-Clientbibliothek. Diese Beispiele gehen davon aus, dass Sie eine Tabelle accounts
mit zwei Spalten haben: accountId
und name
. Sie haben auch das folgende Datenübertragungsobjekt (DTO).
public class Account {
int accountId;
String name;
// getters and setters omitted
}
In der Client-Bibliothek können Sie Parameter DTOs als Eingabeparameter übergeben. Das folgende Beispiel zeigt, wie Kunden Eingabeparametersätzen zugeordnet DTOs 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 eine automatische Zuordnung zu dem DTOs Zeitpunkt, zu dem ein Ergebnis zurückgegeben wird. Die folgenden Beispiele zeigen, wie das Ergebnis Ihrem 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 Client-Bibliothek Folgendes: API
int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
.execute()
.singleValue(Integer.class);
Anmerkung
Die mapToList
Funktion konvertiert eine SQL Ergebnismenge 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 RDS API Datenabfrageergebnissen im Format JSON.
Verarbeitung von RDS API Datenabfrageergebnissen im Format JSON
Wenn Sie den ExecuteStatement
Vorgang aufrufen, können Sie festlegen, dass die Abfrageergebnisse als Zeichenfolge im JSON Format zurückgegeben werden. Auf diese Weise können Sie die JSON Analysefunktionen 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.
Um die Ergebnismenge im JSON Format anzufordern, übergeben Sie den optionalen formatRecordsAs
Parameter mit dem Wert. JSON
Die mit JSON -formatierte Ergebnismenge wird im formattedRecords
Feld der ExecuteStatementResponse
Struktur zurückgegeben.
Die BatchExecuteStatement
-Aktion gibt keine Ergebnismenge zurück. Daher gilt die JSON Option nicht für diese Aktion.
Um die Schlüssel in der JSON Hash-Struktur anzupassen, definieren Sie Spaltenaliase in der Ergebnismenge. Sie können dies tun, indem Sie die AS
Klausel in der Spaltenliste Ihrer SQL Abfrage verwenden.
Sie könnten diese JSON Funktion nutzen, um die Lesbarkeit der Ergebnismenge zu verbessern und ihren Inhalt sprachspezifischen Frameworks zuzuordnen. Da das Volumen der ASCII -kodierten Ergebnismenge größer ist als die Standarddarstellung, können Sie die Standarddarstellung für Abfragen wählen, die eine große Anzahl von Zeilen oder großen Spaltenwerten zurückgeben, die mehr Speicher verbrauchen, als für Ihre Anwendung verfügbar ist.
Abfrageergebnisse werden im Format abgerufen JSON
Um die Ergebnismenge als JSON Zeichenfolge zu erhalten, fügen Sie sie .withFormatRecordsAs(RecordsFormatType.JSON)
in den ExecuteStatement
Aufruf ein. Der Rückgabewert wird als JSON Zeichenfolge im formattedRecords
Feld zurückgegeben. 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 Zeichenketten bleiben in der JSON Antwort nicht erhalten.
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 einer kleineren Gruppe von JSON Typen zugeordnet. Die Werte werden in Form JSON von Zeichenfolgen, Zahlen und einigen speziellen Konstanten wie true
false
, und dargestellt. null
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.
JDBCDatentyp |
JSONDatentyp |
---|---|
|
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 KlauselnLIMIT
undOFFSET
senden.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 in der Ergebnismenge wiederholt. Daher könnte ein Abfrageergebnis mit langen Spaltennamen und vielen Zeilen die Größenbeschränkung überschreiten. Verwenden Sie insbesondere Spaltenaliase für komplizierte Ausdrücke, um zu vermeiden, dass der gesamte Ausdruck in der JSON Zeichenfolge wiederholt wird.
-
SQLSie können zwar Spaltenaliase verwenden, um eine Ergebnismenge mit mehr als einer Spalte mit demselben Namen zu erzeugen, doppelte Schlüsselnamen sind jedoch nicht zulässig. JSON The RDS Data 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 die Antwort als Zeichenfolge im JSON -Format aufgerufen ExecuteStatement
und anschließend die Ergebnismenge interpretiert wird. Ersetzen Sie die entsprechenden Werte für databaseName
, secretStoreArn
, und clusterArn
Parameter.
Das folgende Java-Beispiel veranschaulicht eine Abfrage, die einen numerischen Dezimalwert in der Ergebnismenge zurückgibt. Die assertThat
Aufrufe testen, ob die Felder der Antwort die erwarteten Eigenschaften haben, die auf den Regeln für JSON Ergebnismengen basieren.
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 ColumnMetadata
Felder Records
und 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, nur die Zeichenfolge im JSON -Format zurückzugeben und die anderen Antwortfelder, die leer oder null sind, zu ignorieren. 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, welche Art von Code erforderlich ist, um eine Datenstruktur zu erstellen, 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 weitergegeben.
[{"count(*)":5,"max(id)":4,"4+7":11}]
Durch das Hinzufügen von AS
Spalten mit beschreibenden Bezeichnungen sind die Schlüssel in der JSON Ergebnismenge einfacher zu interpretieren.
select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;
Bei der überarbeiteten SQL Abfrage werden die durch die AS
Klauseln definierten Spaltenbeschriftungen 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 Zeichenketten 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 Zeichenketten 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 Zeichenketten 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-codierter 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 eines BLOB Werts von hello world
und der Rückgabe der Ergebnismenge als Zeichenfolge. JSON
[{"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 wandelt die JSON Zeichenfolge in eine Datenstruktur um, indem er die json.loads
Funktion aufruft. 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 auf die Werte aus dem Ergebnis eines JavaScript executeStatement
Funktionsaufrufs zugegriffen wird. Die Ergebnismenge ist ein Zeichenfolgenwert im Feld response.formattedRecords
. Der Code wandelt die JSON Zeichenfolge in eine Datenstruktur um, indem er die JSON.parse
Funktion aufruft. 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>
Behebung RDS von API Datenproblemen
In den folgenden Abschnitten mit den häufigsten Fehlermeldungen finden Sie Informationen zur Behebung von Problemen, die Sie mit RDS Daten API (DatenAPI) haben.
Themen
Transaction <transaction_ID> Is Not Found (Transaktion nicht gefunden)
In diesem Fall wurde die in einem API Datenaufruf 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 RDSDaten aufrufen 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 API Datengrößenbeschränkung 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 API Datenlimit in der von der Datenbank zurückgegebenen Ergebnismenge beträgt 1 MiB.
Um dieses Problem zu lösen, stellen Sie sicher, dass Aufrufe von Data 1 MiB Daten oder weniger API 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 zu der LIMIT
Klausel finden Sie unter SELECTSyntax
HttpEndpointist nicht für Cluster aktiviert <cluster_ID>
Überprüfen Sie die folgenden möglichen Ursachen für dieses Problem:
-
Der Aurora-DB-Cluster unterstützt keine DatenAPI. Für Aurora My können Sie SQL beispielsweise nur Data API with verwendenAurora Serverless v1. Informationen zu den Typen von DB-Clustern, die RDS Data API unterstützt, finden Sie unterVerfügbarkeit von Regionen und Versionen.
-
Daten sind für den Aurora-DB-Cluster API nicht aktiviert. Um Data API mit einem Aurora-DB-Cluster zu verwenden, API müssen Data für den DB-Cluster aktiviert sein. Hinweise zur Aktivierung von Data API finden Sie unterRDSDaten aktivieren API.
-
Der DB-Cluster wurde umbenannt, nachdem Data dafür aktiviert API wurde. Schalten Sie in diesem Fall die Daten API für diesen Cluster aus und aktivieren Sie ihn dann erneut.
-
Der von ARN Ihnen angegebene Wert entspricht nicht genau dem ARN des Clusters. Stellen Sie sicher, dass die von einer anderen Quelle ARN zurückgegebene oder von der Programmlogik erstellte Datei exakt mit der ARN des Clusters übereinstimmt. Stellen Sie beispielsweise sicher, dass der von ARN Ihnen verwendete Buchstabe die richtige Groß- und Kleinschreibung für alle alphabetischen Zeichen hat.