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

Verwenden der RDS-Daten-API

Mithilfe der RDS Data API (Data API) können Sie mit einer Webservice-Schnittstelle zu Ihrem Aurora-DB-Cluster arbeiten. Die Daten-API erfordert keine persistente Verbindung zum DB-Cluster. Stattdessen bietet sie einen sicheren HTTP-Endpunkt und eine Integration mit AWS SDKs. Über den Endpunkt können Sie SQL-Anweisungen ausführen, ohne Verbindungen zu verwalten.

Benutzer müssen bei Aufrufen an die Daten-API keine Anmeldeinformationen weitergeben, da die Daten-API Datenbankanmeldeinformationen 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 API gewährt werden. Weitere Informationen zum Autorisieren von Benutzern finden Sie unter Autorisieren des Zugriffs auf die RDS-Daten-API.

Sie können die Daten-API auch verwenden, um Amazon Aurora in andere AWS Anwendungen wie AWS Lambda AWS AppSync, und zu integrieren AWS Cloud9. Die Daten-API bietet eine sicherere Art der Verwendung AWS Lambda. Sie können damit auf Ihr DB-Cluster zugreifen, ohne eine Lambda-Funktion für den Zugriff auf Ressourcen in einer Virtual Private Cloud (VPC) konfigurieren zu müssen. Weitere Informationen finden Sie unter AWS Lambda, AWS AppSync und AWS Cloud9.

Sie können die Daten-API aktivieren, wenn Sie den Aurora-DB-Cluster erstellen. Sie können die Konfiguration später auch ändern. Weitere Informationen finden Sie unter RDS-Daten-API aktivieren.

Nachdem Sie die Daten-API aktiviert haben, können Sie den Abfrage-Editor auch verwenden, um Ad-hoc-Abfragen auszuführen, ohne ein Abfragetool für den Zugriff auf Aurora in einer VPC zu konfigurieren. Weitere Informationen finden Sie unter Verwenden des Aurora-Abfrage-Editors.

Verfügbarkeit von Regionen und Versionen

Informationen zu den Regionen und Engine-Versionen, die für die Daten-API verfügbar sind, finden Sie in den folgenden Abschnitten.

Wenn Sie beim Zugriff auf die Daten-API über eine Befehlszeilenschnittstelle oder eine API kryptografische Module benötigen, die nach FIPS 140-2 validiert wurden, verwenden Sie einen FIPS-Endpunkt. Weitere Informationen über verfügbare FIPS-Endpunkte finden Sie unter Federal Information Processing Standard (FIPS) 140-2.

Einschränkungen bei der RDS-Daten-API

Die RDS-Daten-API hat die folgenden Einschränkungen:

Vergleich der RDS-Daten-API mit Serverless v2 und der bereitgestellten Version und Aurora Serverless v1

Die neuesten Verbesserungen der RDS Data API machen sie für Cluster verfügbar, die aktuelle Versionen der PostgreSQL- oder MySQL-Engines verwenden. Diese Cluster könnten für die Verwendung konfiguriert werden Aurora Serverless v2, oder bereitgestellte Instanzklassen wie db.r6g oderdb.r6i.

In der folgenden Tabelle werden die Unterschiede zwischen der RDS-Daten-API (Daten-API) und Aurora Serverless v2 und bereitgestellte DB-Cluster und Aurora Serverless v1 DB-Cluster. Aurora Serverless v1 DB-Cluster verwenden den serverless Engine-Modus. Bereitgestellte DB-Cluster verwenden den provisioned Engine-Modus. Importieren in &S3; Aurora Serverless v2 Der DB-Cluster verwendet auch den provisioned Engine-Modus und enthält einen oder mehrere Aurora Serverless v2 DB-Instances mit der db.serverless Instance-Klasse.

Autorisieren des Zugriffs auf die RDS-Daten-API

Benutzer können RDS-Daten-API-Operationen (Daten-API) nur aufrufen, wenn sie dazu autorisiert sind. Sie können einem Benutzer die Erlaubnis zur Verwendung der Daten-API erteilen, indem Sie eine AWS Identity and Access Management (IAM-) Richtlinie anhängen, die seine Rechte definiert. Sie können die Richtlinie auch einer Rolle anfügen, wenn Sie IAM-Rollen verwenden. Eine AWS verwaltete Richtlinie umfasst Berechtigungen für die Daten-API. AmazonRDSDataFullAccess

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 der Daten-API verwenden können. Die Verwendung von Geheimnissen bedeutet, dass Benutzer bei ihren Aufrufen der Daten-API keine Datenbankanmeldeinformationen für die Ressourcen angeben müssen, auf die sie abzielen. Die Daten-API ruft Secrets Manager transparent auf, wodurch die Anfrage des Benutzers nach dem Secret zugelassen (oder abgelehnt) wird. Hinweise zum Einrichten von Geheimnissen für die Verwendung mit der Daten-API finden Sie unter. Speichern von Datenbankanmeldedaten in AWS Secrets Manager

Die AmazonRDSDataFullAccess Richtlinie bietet vollständigen Zugriff (über die Daten-API) auf Ressourcen. Sie können den Geltungsbereich einschränken, indem Sie eigene Richtlinien definieren, die den Amazon-Ressourcennamen (ARN) einer Ressource angeben.

Die folgende Richtlinie zeigt beispielsweise ein Beispiel für die Mindestberechtigungen, die ein Benutzer für den Zugriff auf die Daten-API für den durch seinen ARN identifizierten DB-Cluster benötigt. Die Richtlinie enthält die nötigen Berechtigungen, um auf Secrets Manager zuzugreifen und die Autorisierung für die DB-Instance für den Benutzer zu erhalten.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                "secretsmanager:GetSecretValue"
            ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*"
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                "rds-data:BatchExecuteStatement",
                "rds-data:BeginTransaction",
                "rds-data:CommitTransaction",
                "rds-data:ExecuteStatement",
                "rds-data:RollbackTransaction"
            ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:prod"
        }
    ]
}

Sie sollten für das Element „Ressourcen“ in Ihren Richtlinienanweisungen (wie im Beispiel gezeigt) einen spezifischen ARN anstelle eines Platzhalters (*) verwenden.

Arbeiten mit der Tag-basierten Autorisierung

RDS Data API (Data API) und Secrets Manager unterstützen beide die Tag-basierte Autorisierung. Tags sind Schlüssel-Wert-Paare, die eine Ressource, z. B. einen RDS-Cluster, mit einem zusätzlichen Zeichenfolgenwert kennzeichnen, z. B.

Sie können auf Ihre Ressourcen Tags zum Zweck der Kostenzuweisung, der Ausführungsunterstützung, der Zugriffskontrolle und zu vielen weiteren Zwecken anwenden. (Wenn Sie noch keine Tags für Ihre Ressourcen anwenden und Tags anwenden möchten, finden Sie weitere Informationen unter Markieren von Amazon RDS-Ressourcen.) Sie können die Tags in Ihren Richtlinienanweisungen verwenden, um den Zugriff auf die RDS-Cluster einzuschränken, die mit diesen Tags gekennzeichnet sind. Ein Aurora-DB-Cluster könnte beispielsweise Tags besitzen, die die Umgebung als Produktions- oder Entwicklungsumgebung kennzeichnen.

Das folgende Beispiel zeigt, wie Sie in Ihren Richtlinienanweisungen Tags verwenden können. Diese Anweisung erfordert, dass sowohl der Cluster als auch der in der Daten-API-Anforderung übergebene Schlüssel das Tag environment:production enthalten.

Die Richtlinie wird wie folgt angewendet: Wenn ein Benutzer mithilfe der Daten-API einen Anruf tätigt, wird die Anfrage an den Dienst gesendet. Die Daten-API überprüft zunächst, ob der in der Anfrage übergebene Cluster-ARN mit environment:production gekennzeichnet 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 die Daten-API den abgerufenen Wert für das DB-Passwort des Benutzers. Wenn dieser ebenfalls korrekt ist, wird die Daten-API-Anforderung für den Benutzer erfolgreich aufgerufen.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SecretsManagerDbCredentialsAccess",
            "Effect": "Allow",
            "Action": [
                 "secretsmanager:GetSecretValue"
               ],
            "Resource": "arn:aws:secretsmanager:*:*:secret:rds-db-credentials/*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
        },
        {
            "Sid": "RDSDataServiceAccess",
            "Effect": "Allow",
            "Action": [
                  "rds-data:*"
               ],
            "Resource": "arn:aws:rds:us-east-2:111122223333:cluster:*",
            "Condition": {
                    "StringEquals": {
                        "aws:ResourceTag/environment": [
                                         "production"
                                        ]
                     }
             }
         }
     ]
}

Das Beispiel zeigt separate Aktionen für rds-data und secretsmanager für Data API und Secrets Manager. Sie können jedoch Aktionen kombinieren und Tag-Bedingungen auf viele verschiedene Arten definieren, um Ihre spezifischen Anwendungsfälle zu unterstützen. Weitere Informationen finden Sie unter Verwenden identitätsbasierter Richtlinien (IAM-Richtlinien) für Secrets Manager.

Im Element „Bedingung“ der Richtlinie können Sie Tag-Schlüssel aus den folgenden Optionen auswählen:

Weitere Informationen zu Ressourcen-Tags und deren Verwendung aws:TagKeys finden Sie unter Steuern des Zugriffs auf AWS Ressourcen mithilfe von Resource-Tags.

Speichern von Datenbankanmeldedaten in AWS Secrets Manager

Wenn Sie die RDS Data API (Data API) aufrufen, übergeben Sie Anmeldeinformationen für den Aurora-DB-Cluster mithilfe eines Secrets in Secrets Manager. Zum Übermitteln der Anmeldeinformationen auf diese Weise geben Sie den Namen des Secrets oder den Amazon-Ressourcennamen (ARN) des Secrets an.

Weitere Informationen zur Verwendung von Secrets Manager finden Sie im AWS Secrets-Manager-Benutzerhandbuch.

Informationen dazu, wie Amazon Aurora die Identitäts- und Zugriffsverwaltung steuert, finden Sie unter So funktioniert Amazon Aurora mit IAM.

Informationen zum Erstellen einer IAM-Richtlinie finden Sie unter Erstellen von IAM-Richtlinien im IAM-Benutzerhandbuch. Informationen zum Hinzufügen einer IAM-Richtlinie zu einem Benutzer finden Sie im Abschnitt Hinzufügen und Entfernen von IAM-Identitätsberechtigungen im IAM-Benutzerhandbuch.

RDS-Daten-API aktivieren

Um die RDS-Daten-API (Daten-API) zu verwenden, aktivieren Sie sie für Ihren Aurora-DB-Cluster. Sie können die Daten-API aktivieren, wenn Sie den DB-Cluster erstellen oder ändern.

Aktivieren der RDS-Daten-API beim Erstellen einer Datenbank

Während Sie eine Datenbank erstellen, die die RDS-Daten-API (Daten-API) 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, oder die RDS-API verwenden.

RDS-Daten-API für eine bestehende Datenbank aktivieren

Sie können einen DB-Cluster ändern, der die RDS-Daten-API (Daten-API) unterstützt, um diese Funktion zu aktivieren oder zu deaktivieren.

Daten-API aktivieren oder deaktivieren (Aurora Serverless v2 und bereitgestellt)

Gehen Sie wie folgt vor, um die Daten-API auf zu aktivieren oder zu deaktivieren Aurora Serverless v2 und bereitgestellte Datenbanken. Um die Daten-API zu aktivieren oder zu deaktivieren Aurora Serverless v1 Datenbanken, verwenden Sie die Verfahren inDaten-API aktivieren oder deaktivieren (Aurora Serverless v1 nur).

Daten-API aktivieren oder deaktivieren (Aurora Serverless v1 nur)

Verwenden Sie die folgenden Verfahren, um die Daten-API auf bestehenden zu aktivieren oder zu deaktivieren Aurora Serverless v1 Datenbanken. Um die Daten-API zu aktivieren oder zu deaktivieren Aurora Serverless v2 und bereitgestellte Datenbanken, verwenden Sie die Verfahren unterDaten-API aktivieren oder deaktivieren (Aurora Serverless v2 und bereitgestellt).

Erstellen eines Amazon VPC-Endpunkts für RDS Data API ()AWS PrivateLink

Amazon VPC ermöglicht es Ihnen, AWS Ressourcen wie Aurora-DB-Cluster und -Anwendungen in einer Virtual Private Cloud (VPC) zu starten. AWS PrivateLink bietet private Konnektivität zwischen VPCs und AWS Diensten mit hoher Sicherheit im Amazon-Netzwerk. Mithilfe AWS PrivateLink können Sie Amazon VPC-Endpunkte erstellen, mit denen Sie Verbindungen zu Diensten herstellen können, die über verschiedene Konten hinweg und auf Amazon VPC VPCs basieren. Weitere Informationen über AWS PrivateLink finden Sie unter VPC-Endpunktservices (AWS PrivateLink) im Amazon-Virtual-Private-Cloud-Benutzerhandbuch.

Sie können die RDS-Daten-API (Daten-API) mit Amazon VPC-Endpunkten aufrufen. Durch die Verwendung eines Amazon VPC-Endpunkts wird der Datenverkehr zwischen Anwendungen in Ihrer Amazon VPC und der Daten-API im AWS Netzwerk aufrechterhalten, ohne öffentliche IP-Adressen zu verwenden. Amazon-VPC-Endpunkte können Ihnen dabei helfen, Compliance- und behördliche Anforderungen im Zusammenhang mit der Einschränkung der öffentlichen Internetkonnektivität zu erfüllen. Wenn Sie beispielsweise einen Amazon VPC-Endpunkt verwenden, können Sie den Datenverkehr zwischen einer Anwendung, die auf einer EC2 Amazon-Instance ausgeführt wird, und der Daten-API in der VPCs , die sie enthalten, aufrechterhalten.

Nachdem Sie den Amazon VPC-Endpunkt erstellt haben, können Sie ihn verwenden, ohne Code- oder Konfigurationsänderungen in der Anwendung vorzunehmen.

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

Auf der Registerkarte Details des Endpunkts werden die DNS-Hostnamen angezeigt, die beim Erstellen des Amazon VPC-Endpunkts generiert wurden.

Sie können den Standardendpunkt (rds-data.region.amazonaws.com) oder einen der VPC-spezifischen Endpunkte verwenden, um die Daten-API innerhalb der Amazon VPC aufzurufen. Der standardmäßige Daten-API-Endpunkt leitet automatisch an den Amazon VPC-Endpunkt weiter. Dieses Routing tritt auf, weil der private DNS-Hostname beim Erstellen des Amazon VPC-Endpunkts aktiviert wurde.

Wenn Sie einen Amazon VPC-Endpunkt in einem Daten-API-Aufruf verwenden, verbleibt der gesamte Datenverkehr zwischen Ihrer Anwendung und der Daten-API in dem Amazon VPCs , der sie enthält. Sie können einen Amazon VPC-Endpunkt für jeden Typ von Daten-API-Aufruf verwenden. Informationen zum Aufrufen der Daten-API finden Sie unterRDS-Daten-API aufrufen.

RDS-Daten-API aufrufen

Wenn die RDS-Daten-API (Daten-API) auf Ihrem Aurora-DB-Cluster aktiviert ist, können Sie SQL-Anweisungen auf dem Aurora-DB-Cluster ausführen, indem Sie die Daten-API oder die AWS CLI. Die Daten-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 Daten-API-Vorgängen

Die Daten-API bietet die folgenden Operationen zur Ausführung von SQL-Anweisungen.

Sie können beide Vorgänge verwenden, um einzelne SQL-Anweisungen oder Transaktionen auszuführen. Für Transaktionen bietet die Daten-API die folgenden Operationen.

Die Operationen zur Ausführung von SQL-Anweisungen und zur Unterstützung von Transaktionen haben die folgenden gemeinsamen Daten-API-Parameter und AWS CLI -Optionen. Einige Operationen unterstützen andere Parameter oder Optionen.

Die RDS Data API unterstützt die folgenden Datentypen für Aurora MySQL:

Die RDS Data API unterstützt die folgenden Aurora PostgreSQL-Skalartypen:

Die RDS Data API unterstützt die folgenden Aurora PostgreSQL-Arraytypen:

Sie können Parameter in Daten-API-Aufrufen an ExecuteStatement und und verwendenBatchExecuteStatement, wenn Sie die AWS CLI Befehle execute-statement und ausführen. batch-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 sind den Datentypen, die Sie in Daten-API-Aufrufen angeben, JDBC-Datentypen (Java Database Connectivity) zugeordnet.

Für bestimmte Typen, wie z. B. DECIMAL undTIME, ist ein Hinweis erforderlich, damit die Daten-API String Werte als den richtigen Typ an die Datenbank 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:

Aufrufen der RDS-Daten-API mit dem AWS CLI

Sie können die RDS-Daten-API (Daten-API) mit dem aufrufen AWS CLI.

In den folgenden Beispielen wird die AWS CLI for Data API verwendet. Weitere Informationen finden Sie in der AWS CLI -Referenz für die Daten-API.

Ersetzen Sie in jedem Beispiel den Amazon Resource Name (ARN) für den DB-Cluster durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.

Starten einer SQL-Transaktion

Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data begin-transaction starten. Der Aufruf gibt eine Transaktions-ID zurück.

Geben Sie zusätzlich zu den allgemeinen Optionen die Option --database an, die den Namen der Datenbank enthält.

Der folgende CLI-Befehl beispielsweise startet eine SQL-Transaktion.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Windows:

aws rds-data begin-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret"

Im Folgenden sehen Sie ein Beispiel für die Antwort.

{
    "transactionId": "ABC1234567890xyz"
}

Ausführen einer SQL-Anweisung

Sie können mittels des CLI-Befehls aws rds-data execute-statement eine SQL-Anweisung ausführen.

Sie können die SQL-Anweisung in einer Transaktion ausführen, indem Sie die Transaktions-ID mit der Option --transaction-id angeben. Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data begin-transaction starten. Sie können eine Transaktion beenden und übergeben, indem Sie den CLI-Befehl aws rds-data commit-transaction verwenden.

Geben Sie zusätzlich zu den allgemeinen Optionen die folgenden Optionen an:

Das DB-Cluster gibt für den Aufruf eine Antwort zurück.

Der folgende CLI-Befehl führt beispielsweise eine einzelne SQL-Anweisung aus und lässt die Metadaten in den Ergebnissen weg (Standard).

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "select * from mytable"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Windows:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--sql "select * from mytable"

Im Folgenden sehen Sie ein Beispiel für die Antwort.

{
    "numberOfRecordsUpdated": 0,
    "records": [
        [
            {
                "longValue": 1
            },
            {
                "stringValue": "ValueOne"
            }
        ],
        [
            {
                "longValue": 2
            },
            {
                "stringValue": "ValueTwo"
            }
        ],
        [
            {
                "longValue": 3
            },
            {
                "stringValue": "ValueThree"
            }
        ]
    ]
}

Der folgende CLI-Befehl führt eine einzelne SQL-Anweisung in einer Transaktion aus, indem die Option --transaction-id angegeben wird.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "update mytable set quantity=5 where id=201" --transaction-id "ABC1234567890xyz"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. 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.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert into mytable values (:id, :val)" --parameters "[{\"name\": \"id\", \"value\": {\"longValue\": 1}},{\"name\": \"val\", \"value\": {\"stringValue\": \"value1\"}}]"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. 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
}

Der folgende CLI-Befehl führt eine Data Definition Language (DDL)-SQL-Anweisung aus. Die DDL-Anweisung benennt die Spalte job in die Spalte role um.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "alter table mytable change column job role varchar(100)" --continue-after-timeout

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. 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
}

Ausführen einer Stapel-SQL-Anweisung über ein Daten-Array

Sie können eine Batch-SQL-Anweisung über ein Daten-Array ausführen, indem Sie den CLI-Befehl aws rds-data batch-execute-statement verwenden. Sie können dieses Befehl verwenden, um einen Massenimport oder eine Update-Operation auszuführen.

Sie können die SQL-Anweisung in einer Transaktion ausführen, indem Sie die Transaktions-ID mit der Option --transaction-id angeben. Sie können eine SQL-Transaktion mit dem CLI-Befehl aws rds-data begin-transaction starten. Sie können eine Transaktion mit dem CLI-Befehl aws rds-data commit-transaction beenden und übergeben.

Geben Sie zusätzlich zu den allgemeinen Optionen die folgenden Optionen an:

Das DB-Cluster gibt für den Aufruf eine Antwort zurück.

Der folgende CLI-Befehl führt beispielsweise eine Batch-SQL-Anweisung für ein Daten-Array mit einem Parametersatz aus.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data batch-execute-statement --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--database "mydb" --secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--sql "insert 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\"}}]]"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. 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\"}}]]"

Übergeben einer SQL-Transaktion

Mit dem CLI-Befehl aws rds-data commit-transaction können Sie eine SQL-Transaktion beenden, die mit aws rds-data begin-transaction gestartet wurde, und die Änderungen übergeben.

Geben Sie zusätzlich zu den allgemeinen Optionen die folgende Option an:

Der folgende CLI-Befehl beendet beispielsweise eine SQL-Transaktion und übergibt die Änderungen.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Windows:

aws rds-data commit-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

Im Folgenden sehen Sie ein Beispiel für die Antwort.

{
    "transactionStatus": "Transaction Committed"
}

Rollback einer SQL-Transaktion

Mit dem CLI-Befehl aws rds-data rollback-transaction können Sie einen Rollback für eine SQL-Transaktion ausführen, die mit aws rds-data begin-transaction gestartet wurde. Durch das Rollback einer Transaktion werden für sie ausgeführte Änderungen rückgängig gemacht.

Geben Sie zusätzlich zu den allgemeinen Optionen die folgende Option an:

Mit dem folgenden AWS CLI Befehl wird beispielsweise eine SQL-Transaktion rückgängig gemacht.

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Linux, macOS, oder Unix:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" \
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" \
--transaction-id "ABC1234567890xyz"

Wählen Sie in der &Snowconsole; Ihren Auftrag aus der Tabelle. Windows:

aws rds-data rollback-transaction --resource-arn "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster" ^
--secret-arn "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret" ^
--transaction-id "ABC1234567890xyz"

Im Folgenden sehen Sie ein Beispiel für die Antwort.

{
    "transactionStatus": "Rollback Complete"
    }

Aufrufen der RDS-Daten-API aus einer Python-Anwendung

Sie können die RDS-Daten-API (Daten-API) von einer Python-Anwendung aus aufrufen.

Die folgenden Beispiele verwenden das AWS SDK für Python (Boto). Weitere Informationen zu Boto finden Sie in der AWS SDK for Python (Boto 3)-Dokumentation.

Ersetzen Sie in jedem Beispiel den Amazon Resource Name (ARN) des DB-Clusters durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.

Ausführen einer SQL-Abfrage

Sie können eine SELECT-Anweisung ausführen und die Ergebnisse mit einer Python-Anwendung abrufen.

Im folgenden Beispiel wird eine SQL-Abfrage ausgeführt.

import boto3

rdsData = boto3.client('rds-data')

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

response1 = rdsData.execute_statement(
            resourceArn = cluster_arn,
            secretArn = secret_arn,
            database = 'mydb',
            sql = 'select * from employees limit 3')

print (response1['records'])
[
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'ROSALEZ'
        },
        {
            'stringValue': 'ALEJANDRO'
        },
        {
            'stringValue': '2016-02-15 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'DOE'
        },
        {
            'stringValue': 'JANE'
        },
        {
            'stringValue': '2014-05-09 04:34:33.0'
        }
    ],
    [
        {
            'longValue': 1
        },
        {
            'stringValue': 'STILES'
        },
        {
            'stringValue': 'JOHN'
        },
        {
            'stringValue': '2017-09-20 04:34:33.0'
        }
    ]
]

Ausführen einer DML SQL-Anweisung

Sie können eine Data Manipulation Language (DML)-Anweisung ausführen, um in Ihrer Datenbank Daten einzufügen, zu aktualisieren oder zu löschen. Sie können in DML-Anweisungen auch Parameter verwenden.

Im folgenden Beispiel werden eine SQL Insert-Anweisung ausgeführt und Parameter verwendet.

import boto3

cluster_arn = 'arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster'
secret_arn = 'arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret'

rdsData = boto3.client('rds-data')


param1 = {'name':'firstname', 'value':{'stringValue': 'JACKSON'}}
param2 = {'name':'lastname', 'value':{'stringValue': 'MATEO'}}
paramSet = [param1, param2]

response2 = rdsData.execute_statement(resourceArn=cluster_arn,
                                      secretArn=secret_arn,
                                      database='mydb',
                                      sql='insert into employees(first_name, last_name) VALUES(:firstname, :lastname)',
                                      parameters = paramSet)

print (response2["numberOfRecordsUpdated"])

Ausführen einer SQL-Transaktion

Sie können eine SQL-Transaktion starten, eine oder mehrere SQL-Anweisungen ausführen und anschließend die Änderungen mit einer Python-Anwendung übergeben.

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

RDS-Daten-API von einer Java-Anwendung aus aufrufen

Sie können die RDS-Daten-API (Daten-API) von einer Java-Anwendung aus aufrufen.

Die folgenden Beispiele verwenden das AWS SDK for Java. Weitere Informationen finden Sie im AWS SDK for Java -Entwicklerhandbuch.

Ersetzen Sie in jedem Beispiel den Amazon Resource Name (ARN) des DB-Clusters durch den ARN für Ihren Aurora-DB-Cluster. Ersetzen Sie außerdem den geheimen ARN durch den ARN des geheimen Schlüssels in Secrets Manager, der den Zugriff auf den DB-Cluster ermöglicht.

Ausführen einer SQL-Abfrage

Sie können eine SELECT-Anweisung ausführen und die Ergebnisse mit einer Java-Anwendung abrufen.

Im folgenden Beispiel wird eine SQL-Abfrage ausgeführt.

package com.amazonaws.rdsdata.examples;

import com.amazonaws.services.rdsdata.AWSRDSData;
import com.amazonaws.services.rdsdata.AWSRDSDataClient;
import com.amazonaws.services.rdsdata.model.ExecuteStatementRequest;
import com.amazonaws.services.rdsdata.model.ExecuteStatementResult;
import com.amazonaws.services.rdsdata.model.Field;

import java.util.List;

public class FetchResultsExample {
  public static final String RESOURCE_ARN = "arn:aws:rds:us-east-1:123456789012:cluster:mydbcluster";
  public static final String SECRET_ARN = "arn:aws:secretsmanager:us-east-1:123456789012:secret:mysecret";

  public static void main(String[] args) {
    AWSRDSData rdsData = AWSRDSDataClient.builder().build();

    ExecuteStatementRequest request = new ExecuteStatementRequest()
            .withResourceArn(RESOURCE_ARN)
            .withSecretArn(SECRET_ARN)
            .withDatabase("mydb")
            .withSql("select * from mytable");

    ExecuteStatementResult result = rdsData.executeStatement(request);

    for (List<Field> fields: result.getRecords()) {
      String stringValue = fields.get(0).getStringValue();
      long numberValue = fields.get(1).getLongValue();

      System.out.println(String.format("Fetched row: string = %s, number = %d", stringValue, numberValue));
    }
  }
}

Ausführen einer SQL-Transaktion

Sie können eine SQL-Transaktion starten, eine oder mehrere SQL-Anweisungen ausführen und anschließend die Änderungen mit einer Java-Anwendung übergeben.

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);
  }
}

Ausführen einer Stapel-SQL-Operation

Sie können mit einer Java-Anwendung Operationen für Masseneinfügungen und -aktualisierungen für ein Daten-Array ausführen. Sie können eine DML-Anweisung mit einem Array von Parametersätzen ausführen.

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 Timeout-Verhaltens der Daten-API

Alle Aufrufe der Daten-API erfolgen synchron. Angenommen, Sie führen eine Daten-API-Operation durch, die eine SQL-Anweisung wie INSERT oder CREATE TABLE ausführt. Wenn der Daten-API-Aufruf erfolgreich zurückkehrt, ist die SQL-Verarbeitung abgeschlossen, wenn der Aufruf zurückkehrt.

Standardmäßig bricht die Daten-API 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 die Daten-API verwenden, 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 Bulk INSERT - oder 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 Ausführen einer SQL-Transaktion.

Wenn das AWS SDK für Ihre Programmiersprache einen eigenen Timeout-Zeitraum für API-Aufrufe oder HTTP-Socket-Verbindungen hat, 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, SDK-spezifische oder kundenspezifische 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 Daten-API-Vorgang weiterhin erfolgreich abgeschlossen wird. Auf diese Weise können Sie sicher sein, ob Sie den Vorgang wiederholen möchten oder nicht.

Nehmen wir beispielsweise an, dass das SDK einen Timeout-Fehler an Ihre Anwendung zurückgibt, der Daten-API-Vorgang aber trotzdem innerhalb des Daten-API-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. Das SDK wiederholt den Vorgang möglicherweise automatisch, wodurch falsche Daten entstehen, ohne dass Ihre Anwendung etwas dagegen unternommen hat.

Das Timeout-Intervall ist besonders wichtig für das Java 2 SDK. In diesem SDK betragen das API-Aufruf-Timeout und das HTTP-Socket-Timeout standardmäßig beide 30 Sekunden. Hier ist ein Beispiel für das Setzen dieser Timeouts auf einen höheren Wert:

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 die RDS-Daten-API

Sie können eine Java-Clientbibliothek für die RDS Data API (Data API) herunterladen und verwenden. Diese Java-Clientbibliothek bietet eine alternative Möglichkeit zur Verwendung der Daten-API. Mithilfe dieser Bibliothek können Sie Ihre clientseitigen Klassen Daten-API-Anfragen und -Antworten zuordnen. Dieser Mapping-Support kann die Integration mit einigen bestimmten Java-Typen wie etwa Date, Time und BigDecimal erleichtern.

Herunterladen der Java Client-Bibliothek für die Daten-API

Die 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 die folgende Abhängigkeit zu Ihrer Maven-POM-Datei hinzu.

Verwenden Sie für Version 2.x, die mit AWS SDK 2.x kompatibel ist, Folgendes:

<dependency>
   <groupId>software.amazon.rdsdata</groupId>
   <artifactId>rds-data-api-client-library-java</artifactId>
   <version>2.0.0</version>
</dependency>

Verwenden Sie für Version 1.x, die mit AWS SDK 1.x kompatibel ist, Folgendes:

<dependency>
    <groupId>software.amazon.rdsdata</groupId>
    <artifactId>rds-data-api-client-library-java</artifactId>
    <version>1.0.8</version>
</dependency>

Java Client-Bibliothek-Beispiele

Nachfolgend finden Sie einige typische Beispiele für die Verwendung der Daten-API-Java-Client-Bibliothek. Diese Beispiele gehen davon aus, dass Sie eine Tabelle accounts mit zwei Spalten haben: accountId und name. Weiterhin haben Sie das folgende Datentransferobjekt (DTO):

public class Account {
    int accountId;
    String name;
    // getters and setters omitted
}

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 ermöglicht 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 Kundenbibliothek die folgende API an:

int numberOfAccounts = client.forSql("SELECT COUNT(*) FROM accounts")
          .execute()
          .singleValue(Integer.class);

Verarbeitung der Ergebnisse der RDS-Daten-API-Abfrage im JSON-Format

Wenn Sie die ExecuteStatement-Operation aufrufen, können Sie auswählen, ob die Abfrageergebnisse als Zeichenfolge im JSON-Format zurückgegeben werden sollen. Auf diese Weise können Sie die JSON-Parsing-Funktionen Ihrer Programmiersprache verwenden, um die Ergebnismenge zu interpretieren und neu zu formatieren. Dies kann dazu beitragen, zu vermeiden, zusätzlichen Code zu schreiben, um die Ergebnismenge zu durchlaufen und jeden Spaltenwert zu interpretieren.

Zum Anfordern der Ergebnismenge im JSON-Format übergeben Sie den optionalen formatRecordsAs-Parameter mit dem Wert JSON. Die JSON-formatierte Ergebnismenge wird im Feld formattedRecords der ExecuteStatementResponse-Struktur zurückgegeben.

Die BatchExecuteStatement-Aktion gibt keine Ergebnismenge zurück. Daher gilt die JSON-Option nicht für diese Aktion.

Wenn Sie die Schlüssel in der JSON-Hash-Struktur anpassen möchten, definieren Sie Spaltenaliasnamen in der Ergebnismenge. Verwenden Sie dazu die AS-Klausel in der Spaltenliste Ihrer SQL-Abfrage.

Sie können die JSON-Funktion verwenden, um die Ergebnismenge besser lesbar zu machen und den Inhalt sprachspezifischen Frameworks zuzuordnen. Da das Volume der ASCII-kodierten Ergebnismenge größer als die Standarddarstellung ist, können Sie die Standarddarstellung für Abfragen auswählen, die eine große Anzahl von Zeilen oder große Spaltenwerte zurückgeben, die mehr Speicher belegen, als für Ihre Anwendung verfügbar ist.

Abrufen von Abfrageergebnissen im JSON-Format

Um die Ergebnismenge als JSON-Zeichenfolge zu erhalten, fügen Sie sie .withFormatRecordsAs(RecordsFormatType.JSON) in den ExecuteStatement Aufruf ein. Der Rückgabewert wird im Feld formattedRecords als JSON-Zeichenfolge angezeigt. In diesem Fall hat columnMetadata den Wert null. Die Spaltenbeschriftungen sind die Schlüssel des Objekts, das jede Zeile darstellt. Diese Spaltennamen werden für jede Zeile in der Ergebnismenge wiederholt. Die Spaltenwerte sind in Anführungszeichen gesetzte Zeichenfolgen, numerische Werte oder Sonderwerte, die true, false oder null darstellen. Spaltenmetadaten wie Längenbeschränkungen und der genaue Typ für Zahlen und Zeichenfolgen werden in der JSON-Antwort nicht beibehalten.

Wenn Sie den .withFormatRecordsAs()-Aufruf weglassen oder einen Parameter NONE angeben, wird die Ergebnismenge im Binärformat unter Verwendung der Felder Records und columnMetadata zurückgegeben.

Datentypenzuordnung

Die SQL-Werte in der Ergebnismenge werden einem kleineren Satz von JSON-Typen zugeordnet. Die Werte werden in JSON als Zeichenfolgen, Zahlen und einige spezielle Konstanten wie true, false und null dargestellt. Sie können diese Werte in Variablen in Ihrer Anwendung umwandeln, indem Sie eine starke oder schwache Eingabe verwenden, die für Ihre Programmiersprache geeignet ist.

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:

Beispiele

Die folgenden Java-Beispiele zeigen, wie Sie ExecuteStatement mit der Antwort als JSON-formatierte Zeichenfolge aufrufen und dann die Ergebnismenge interpretieren. Ersetzen Sie die clusterArn Parameter databaseNamesecretStoreArn, und durch die entsprechenden Werte.

Das folgende Java-Beispiel veranschaulicht eine Abfrage, die einen numerischen Dezimalwert in der Ergebnismenge zurückgibt. assertThat-Aufrufe testen anhand der Regeln für JSON-Ergebnismengen, ob die Felder der Antwort die erwarteten Eigenschaften haben.

Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:

create table test_simplified_json (a float);
insert into test_simplified_json values(10.0);

public void JSON_result_set_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request);
}

Der Wert des Felds formattedRecords aus dem vorhergehenden Programm lautet:

[{"a":10.0}]

Die Felder Records und ColumnMetadata in der Antwort sind aufgrund des Vorhandenseins der JSON-Ergebnismenge beide null.

Das folgende Java-Beispiel veranschaulicht eine Abfrage, die einen numerischen Ganzzahlwert in der Ergebnismenge zurückgibt. Das Beispiel ruft getFormattedRecords auf, um nur die JSON-formatierte Zeichenfolge zurückzugeben und die anderen Antwortfelder zu ignorieren, die leer oder null sind. Im Beispiel wird das Ergebnis in eine Struktur deserialisiert, die eine Liste von Datensätzen darstellt. Jeder Datensatz enthält Felder, deren Namen den Spaltenaliasnamen aus der Ergebnismenge entsprechen. Diese Methode vereinfacht den Code, der die Ergebnismenge analysiert. Ihre Anwendung muss nicht die Zeilen und Spalten der Ergebnismenge durchlaufen und jeden Wert in den entsprechenden Typ konvertieren.

Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:

create table test_simplified_json (a int);
insert into test_simplified_json values(17);

public void JSON_deserialization_demo() {
    var sql = "select * from test_simplified_json";
    var request = new ExecuteStatementRequest()
      .withDatabase(databaseName)
      .withSecretArn(secretStoreArn)
      .withResourceArn(clusterArn)
      .withSql(sql)
      .withFormatRecordsAs(RecordsFormatType.JSON);
    var result = rdsdataClient.executeStatement(request)
      .getFormattedRecords();

/* Turn the result set into a Java object, a list of records.
   Each record has a field 'a' corresponding to the column
   labelled 'a' in the result set. */
    private static class Record { public int a; }
    var recordsList = new ObjectMapper().readValue(
        response, new TypeReference<List<Record>>() {
        });
}

Der Wert des Felds formattedRecords aus dem vorhergehenden Programm lautet:

[{"a":17}]

Zum Abrufen der Spalte a der Ergebniszeile 0 würde sich die Anwendung auf recordsList.get(0).a beziehen.

Im Gegensatz dazu zeigt das folgende Java-Beispiel die Art von Code, der zum Erstellen einer Datenstruktur erforderlich ist, die die Ergebnismenge enthält, wenn Sie das JSON-Format nicht verwenden. In diesem Fall enthält jede Zeile der Ergebnismenge Felder mit Informationen über einen einzelnen Benutzer. Das Erstellen einer Datenstruktur zur Darstellung der Ergebnismenge erfordert das Durchlaufen der Zeilen. Für jede Zeile ruft der Code den Wert jedes Felds ab, führt eine entsprechende Typkonvertierung durch und weist das Ergebnis dem entsprechenden Feld im Objekt zu, das die Zeile darstellt. Dann fügt der Code das Objekt, das jeden Benutzer repräsentiert, der Datenstruktur hinzu, die die gesamte Ergebnismenge darstellt. Wenn die Abfrage geändert wurde, um Felder in der Ergebnismenge neu anzuordnen, hinzuzufügen oder zu entfernen, müsste sich der Anwendungscode ebenfalls ändern.

/* Verbose result-parsing code that doesn't use the JSON result set format */
for (var row: response.getRecords()) {
    var user = User.builder()
      .userId(row.get(0).getLongValue())
      .firstName(row.get(1).getStringValue())
      .lastName(row.get(2).getStringValue())
      .dob(Instant.parse(row.get(3).getStringValue()))
      .build();
    result.add(user);
  } 

Die folgenden Beispielwerte zeigen die Werte des Felds formattedRecords für Ergebnismengen mit unterschiedlicher Anzahl von Spalten, Spaltenaliasnamen und Spaltendatentypen.

Wenn die Ergebnismenge mehrere Zeilen enthält, wird jede Zeile als Objekt dargestellt, das ein Array-Element ist. Jede Spalte in der Ergebnismenge wird zu einem Schlüssel im Objekt. Die Schlüssel werden für jede Zeile in der Ergebnismenge wiederholt. Daher müssen Sie für Ergebnismengen, die aus vielen Zeilen und Spalten bestehen, möglicherweise kurze Spaltenaliasnamen definieren, um zu vermeiden, dass das Längenlimit für die gesamte Antwort überschritten wird.

Dieses Beispiel funktioniert mit dem folgenden Schema und den folgenden Beispieldaten:

create table sample_names (id int, name varchar(128));
insert into sample_names values (0, "Jane"), (1, "Mohan"), (2, "Maria"), (3, "Bruce"), (4, "Jasmine");

[{"id":0,"name":"Jane"},{"id":1,"name":"Mohan"},
{"id":2,"name":"Maria"},{"id":3,"name":"Bruce"},{"id":4,"name":"Jasmine"}]

Wenn eine Spalte in der Ergebnismenge als Ausdruck definiert ist, wird der Text des Ausdrucks zum JSON-Schlüssel. Daher ist es normalerweise praktisch, einen beschreibenden Spaltenalias für jeden Ausdruck in der Auswahlliste der Abfrage zu definieren. Die folgende Abfrage enthält beispielsweise Ausdrücke wie Funktionsaufrufe und arithmetische Operationen in ihrer Auswahlliste.

select count(*), max(id), 4+7 from sample_names;

Diese Ausdrücke werden als Schlüssel an die JSON-Ergebnismenge übergeben.

[{"count(*)":5,"max(id)":4,"4+7":11}]

Wenn Sie AS-Spalten mit beschreibenden Beschriftungen hinzufügen, können die Schlüssel in der JSON-Ergebnismenge einfacher interpretiert werden.

select count(*) as rows, max(id) as largest_id, 4+7 as addition_result from sample_names;

Bei der überarbeiteten SQL-Abfrage werden die Spaltenbeschriftungen, die durch die AS-Klauseln definiert werden, als Schlüsselnamen verwendet.

[{"rows":5,"largest_id":4,"addition_result":11}]

Der Wert für jedes Schlüssel-Wert-Paar in der JSON-Zeichenfolge kann eine Zeichenfolge in Anführungszeichen sein. Die Zeichenfolge enthält möglicherweise Unicode-Zeichen. Wenn die Zeichenfolge Escape-Sequenzen oder die Zeichen " oder \ enthält, wird diesen Zeichen ein Escape-Zeichen mit umgekehrtem Schrägstrich vorangestellt. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten. Das Ergebnis string_with_escape_sequences enthält z. B. die Sonderzeichen Rücktaste, Zeilenumbruch, Wagenrücklauf, Tabulator, Seitenvorschub und \.

[{"quoted_string":"hello"}]
[{"unicode_string":"邓不利多"}]
[{"string_with_escape_sequences":"\b \n \r \t \f \\ '"}] 

Der Wert für jedes Schlüssel-Wert-Paar in der JSON-Zeichenfolge kann auch eine Zahl darstellen. Die Zahl kann eine Ganzzahl, ein Gleitkommawert, ein negativer Wert oder ein Wert sein, der in Exponentialschreibweise dargestellt wird. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten.

[{"integer_value":17}]
[{"float_value":10.0}]
[{"negative_value":-9223372036854775808,"positive_value":9223372036854775807}]
[{"very_small_floating_point_value":4.9E-324,"very_large_floating_point_value":1.7976931348623157E308}] 

Boolesche und Nullwerte werden mit den Sonderschlüsselwörtern true, false und null ohne Anführungszeichen dargestellt. Die folgenden Beispiele für JSON-Zeichenfolgen veranschaulichen diese Möglichkeiten.

[{"boolean_value_1":true,"boolean_value_2":false}]
[{"unknown_value":null}] 

Wenn Sie einen Wert eines BLOB-Typs auswählen, wird das Ergebnis in der JSON-Zeichenfolge als Base64-kodierter Wert dargestellt. Wenn Sie den Wert wieder in seine ursprüngliche Darstellung umwandeln möchten, können Sie die entsprechende Dekodierungsfunktion in der Sprache Ihrer Anwendung verwenden. In Java rufen Sie beispielsweise die Funktion Base64.getDecoder().decode() auf. Die folgende Beispielausgabe zeigt das Ergebnis der Auswahl des BLOB-Werts hello world und gibt die Ergebnismenge als JSON-Zeichenfolge zurück.

[{"blob_column":"aGVsbG8gd29ybGQ="}]

Das folgende Python-Beispiel zeigt, wie Sie auf die Werte aus dem Ergebnis eines Aufrufs der Python-Funktion execute_statement zugreifen. Die Ergebnismenge ist ein Zeichenfolgenwert im Feld response['formattedRecords']. Der Code verwandelt die JSON-Zeichenfolge durch Aufrufen der Funktion json.loads in eine Datenstruktur. Dann ist jede Zeile der Ergebnismenge ein Listenelement innerhalb der Datenstruktur und innerhalb jeder Zeile können Sie auf jedes Feld der Ergebnismenge nach Namen verweisen.

import json

result = json.loads(response['formattedRecords'])
print (result[0]["id"])

Das folgende JavaScript Beispiel zeigt, wie Sie auf die Werte aus dem Ergebnis eines JavaScript executeStatement Funktionsaufrufs zugreifen können. Die Ergebnismenge ist ein Zeichenfolgenwert im Feld response.formattedRecords. Der Code verwandelt die JSON-Zeichenfolge durch Aufrufen der Funktion JSON.parse in eine Datenstruktur. Dann ist jede Zeile der Ergebnismenge ein Array-Element innerhalb der Datenstruktur und innerhalb jeder Zeile können Sie auf jedes Feld der Ergebnismenge nach Namen verweisen.

<script>
    const result = JSON.parse(response.formattedRecords);
    document.getElementById("display").innerHTML = result[0].id;
</script> 

Behebung von Problemen mit der RDS-Daten-API

Verwenden Sie die folgenden Abschnitte mit den häufigsten Fehlermeldungen, um Probleme zu beheben, die Sie mit der RDS Data API (Daten-API) haben.

Transaction <transaction_ID> Is Not Found (Transaktion nicht gefunden)

In diesem Fall wurde die in einem Data-API-Aufruf angegebene Transaktions-ID nicht gefunden. Die Ursache für dieses Problem wird an die Fehlermeldung angehängt und ist eine der folgenden:

Informationen zum Ausführen von Transaktionen finden Sie unter RDS-Daten-API aufrufen.

Packet for Query Is Too Large (Paket für Abfrage zu groß)

In diesem Fall war die zurückgegebene Ergebnismenge für eine Zeile zu groß. Die Größenbegrenzung der Data-API beträgt 64 KB pro Zeile in der von der Datenbank zurückgegebenen Ergebnismenge.

Um dieses Problem zu beheben, stellen Sie sicher, dass jede Zeile in einem Ergebnissatz höchstens 64 KB groß ist.

Database Response Exceeded Size Limit Datenbankantwort überschreitet Größenlimit)

In diesem Fall war die Größe der von der Datenbank zurückgegebenen Ergebnismenge zu groß. Das Data-API-Limit beträgt 1 MiB für die von der Datenbank zurückgegebene Ergebnismenge.

Um dieses Problem zu lösen, stellen Sie sicher, dass Aufrufe der Daten-API 1 MiB Daten oder weniger zurückgeben. Wenn Sie mehr als 1 MiB zurückgeben müssen, können Sie mit der LIMIT-Klausel in Ihrer Abfrage mehrere ExecuteStatement-Aufrufe verwenden.

Weitere Informationen über die LIMIT-Klausel finden Sie unter SELECT-Syntax in der MySQL-Dokumentation.

HttpEndpointist nicht für Cluster aktiviert <cluster_ID>

Überprüfen Sie die folgenden möglichen Ursachen für dieses Problem:

DatabaseErrorException: Transaction führt immer noch eine Abfrage aus

Wenn Ihre Anwendung eine Anfrage mit einer Transaktions-ID sendet und diese Transaktion gerade eine weitere Anfrage verarbeitet, gibt die Daten-API diesen Fehler sofort an Ihre Anwendung zurück. Dieser Zustand kann auftreten, wenn Ihre Anwendung asynchrone Anfragen stellt und dabei einen Mechanismus wie „Promises“ in Javascript verwendet.

Um dieses Problem zu lösen, warten Sie, bis die vorherige Anfrage abgeschlossen ist, und versuchen Sie es dann erneut. Sie können es so lange wiederholen, bis der Fehler nicht mehr auftritt oder die Anwendung eine andere Art von Fehler erhält.

Dieser Zustand kann bei der Daten-API für auftreten Aurora Serverless v2 und bereitgestellte Instanzen. In der Daten-API für Aurora Serverless v1, bei nachfolgenden Anfragen für dieselbe Transaktions-ID wird automatisch darauf gewartet, dass die vorherige Anfrage abgeschlossen ist. Bei diesem älteren Verhalten kann es jedoch möglicherweise zu Timeouts kommen, da die vorherige Anfrage zu lange gedauert hat. Wenn Sie eine ältere Daten-API-Anwendung portieren, die gleichzeitige Anfragen stellt, ändern Sie Ihre Ausnahmebehandlungslogik, um diese neue Art von Fehler zu berücksichtigen.