RDSDaten verwenden API - Amazon Aurora

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, AWS AppSync und AWS Cloud9.

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.

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

Daten API mit Aurora Postgre SQL Serverless v1

Aurora My SQL Serverless v1

Daten API mit 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 () 140-2. FIPS

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
  • RDSAPI— Verwenden Sie die DisableHttpEndpoint Operationen EnableHttpEndpoint und.

  • AWS CLI — Verwenden Sie die disable-http-endpoint Operationen enable-http-endpoint und.

  • RDSAPI— Verwenden Sie die ModifyDBCluster Operation und geben Sie false gegebenenfalls true oder für den EnableHttpEndpoint Parameter an.

  • AWS CLI — Verwenden Sie die modify-db-cluster Operation gegebenenfalls mit der --no-enable-http-endpoint Option --enable-http-endpoint oder.

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

ExecuteStatementunterstützt das Abrufen mehrdimensionaler Array-Spalten nicht. In diesem Fall wirft Data. API UnsupportedResultException

Data unterstützt einige Datentypen API nicht, z. B. geometrische und monetäre Typen. In diesem Fall API wirft UnsupportedResultException: The result contains the unsupported data type data_type Data.

Nur die folgenden Typen werden unterstützt:

  • BOOL

  • BYTEA

  • DATE

  • CIDR

  • DECIMAL, NUMERIC

  • ENUM

  • FLOAT8, DOUBLE PRECISION

  • INET

  • INT, INT4, SERIAL

  • INT2, SMALLINT, SMALLSERIAL

  • INT8, BIGINT, BIGSERIAL

  • JSONB, JSON

  • REAL, FLOAT

  • TEXT, CHAR(N), VARCHAR, NAME

  • TIME

  • TIMESTAMP

  • UUID

  • VECTOR

Nur die folgenden Array-Typen werden unterstützt:

  • BOOL[], BIT[]

  • DATE[]

  • DECIMAL[], NUMERIC[]

  • FLOAT8[], DOUBLE PRECISION[]

  • INT[], INT4[]

  • INT2[]

  • INT8[], BIGINT[]

  • JSON[]

  • REAL[], FLOAT[]

  • TEXT[], CHAR(N)[], VARCHAR[], NAME[]

  • TIME[]

  • TIMESTAMP[]

  • UUID[]

ExecuteStatementunterstü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
  1. 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.

  2. 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.

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.

Der Abschnitt Konnektivität auf der Seite „Datenbank erstellen“, wobei das API Kontrollkästchen „RDSDaten aktivieren“ ausgewählt ist.

Anweisungen zum Erstellen eines Aurora-DB-Clusters, der die RDS Daten verwenden kannAPI, finden Sie im Folgenden:

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.

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.

Der API Bereich RDS Daten auf der Registerkarte Konnektivität und Sicherheit der Detailseite für einen DB-Cluster. Der Status von Daten API wird als deaktiviert angezeigt, und die API Schaltfläche „RDSDaten aktivieren“ ist vorhanden.

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.

Im Bereich Konnektivität auf der Seite DB-Cluster modifizieren ist API das Kontrollkästchen Daten ausgewählt.

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
  1. Melden Sie sich bei der an AWS Management Console und öffnen Sie die VPC Amazon-Konsole unter https://console.aws.amazon.com/vpc/.

  2. Wählen Sie Endpunkte und dann Endpunkt erstellen aus.

  3. 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.

    Erstellen Sie einen VPC Amazon-Endpunkt für Daten API
  4. 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.

  5. 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.

    Wählen Sie Subnetze für den Amazon-Endpunkt VPC

    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.

  6. Wählen Sie als DNSNamen aktivieren die Option Für diesen Endpunkt aktivieren aus.

    DNSNamen für den VPC Amazon-Endpunkt aktivieren

    Private DNS löst den standardmäßigen API DNS Daten-Hostnamen (https://rds-data.region.amazonaws.com) 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. URL

  7. 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.

  8. 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.

  9. Wählen Sie Endpunkt erstellen aus.

Nachdem der Endpunkt erstellt wurde, wählen Sie den Link in, AWS Management Console um die Endpunktdetails anzuzeigen.

Link zu den VPC Amazon-Endpunktdetails

Auf der Registerkarte Endpunktdetails werden die DNS Hostnamen angezeigt, die bei der Erstellung des VPC Amazon-Endpunkts generiert wurden.

Link zu den VPC Amazon-Endpunktdetails

Sie können den Standardendpunkt (rds-data.region.amazonaws.com) 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.

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.

Referenz zu API Datenoperationen

Data API bietet die folgenden Operationen zum Ausführen von SQL Anweisungen.

APIBetrieb von Daten

AWS CLI Befehl

Beschreibung

ExecuteStatement

aws rds-data execute-statement

Führt eine SQL Anweisung in einer Datenbank aus.

BatchExecuteStatement

aws rds-data batch-execute-statement

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

BeginTransaction

aws rds-data begin-transaction

Startet eine SQL Transaktion.

CommitTransaction

aws rds-data commit-transaction

Beendet eine SQL Transaktion und schreibt die Änderungen fest.

RollbackTransaction

aws rds-data rollback-transaction

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

resourceArn

--resource-arn

Ja

Der Amazon-Ressourcenname (ARN) des Aurora-DB-Clusters.

secretArn

--secret-arn

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

INTEGER, TINYINT, SMALLINT, BIGINT

LONG (oder STRING)

FLOAT, REAL, DOUBLE

DOUBLE

DECIMAL

STRING

BOOLEAN, BIT

BOOLEAN

BLOB, BINARY, LONGVARBINARY, VARBINARY

BLOB

CLOB

STRING

Andere Typen (einschließlich datums- und zeitbezogener Typen)

STRING

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 entsprechende String-Parameter wird als Objekt des Typs DATE an die Datenbank gesendet. Das akzeptierte Format ist YYYY-MM-DD.

  • DECIMAL – Der entsprechende String-Parameter wird als Objekt des Typs DECIMAL an die Datenbank gesendet.

  • JSON – Der entsprechende String-Parameter wird als Objekt des Typs JSON an die Datenbank gesendet.

  • TIME – Der entsprechende String-Parameter wird als Objekt des Typs TIME an die Datenbank gesendet. Das akzeptierte Format ist HH:MM:SS[.FFF].

  • TIMESTAMP – Der entsprechende String-Parameter wird als Objekt des Typs TIMESTAMP an die Datenbank gesendet. Das akzeptierte Format ist YYYY-MM-DD HH:MM:SS[.FFF].

  • UUID – Der entsprechende String-Parameter wird als Objekt des Typs UUID 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.

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 dem begin-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 database_name;" in der vorherigen Anforderung ausgeführt haben. Es wird empfohlen, die --database-Option zu verwenden statt --sql "use database_name;"-Anweisungen auszuführen.

  • --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 into mytable 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 into mytable 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. SQL

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 into mytable 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 into mytable 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 dem begin-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 dem begin-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.

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 truefalse, 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

INTEGER, TINYINT, SMALLINT, BIGINT

Die Standardeinstellung ist Zahl. Zeichenfolge, wenn die Option LongReturnType auf STRING eingestellt ist.

FLOAT, REAL, DOUBLE

Zahl

DECIMAL

Die Standardeinstellung ist Zeichenfolge. Zahl, wenn die Option DecimalReturnType auf DOUBLE_OR_LONG eingestellt ist.

STRING

String

BOOLEAN, BIT

Boolesch

BLOB, BINARY, VARBINARY, LONGVARBINARY

Zeichenfolge in Base64-Kodierung.

CLOB

String

ARRAY

Array

NULL

null

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 Klauseln LIMIT und OFFSET 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.

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- oder RollbackTransaction-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 in der SQL Dokumentation „Meine“.

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.