Aufrufen der Daten-API von Amazon RDS über die AWS CLI - Amazon Aurora
Starten einer SQL-TransaktionAusführen einer SQL-AnweisungAusführen einer Stapel-SQL-Anweisung über ein Daten-ArrayÜbergeben einer SQL-TransaktionRollback einer SQL-Transaktion

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.

Aufrufen der Daten-API von Amazon RDS über die AWS CLI

Sie können die RDS-Daten-API (Daten-API) über die AWS CLI aufrufen.

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

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

Anmerkung

Die AWS CLI kann Antworten in JSON formatieren.

Starten einer SQL-Transaktion

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

Wichtig

Auf der Daten-API kommt es bei einer Transaktion 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, setzt die Daten-API die Transaktion automatisch zurück.

MySQL Data Definition Language (DDL)-Anweisungen innerhalb einer Transaktion führen zu einem impliziten Commit. Wir empfehlen Ihnen, die einzelnen MySQL-DDL-Anweisungen jeweils in einem separaten Befehl execute-statement mit der Option --continue-after-timeout auszuführen.

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

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

Für Linux, 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"

Für Windows:

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

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

{
    "transactionId": "ABC1234567890xyz"
}

Ausführen einer SQL-Anweisung

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

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

Wichtig

Wenn Sie die Option --transaction-id nicht angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.

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

  • --sql (erforderlich) – eine SQL-Anweisung, die auf dem DB-Cluster ausgeführt werden soll.

  • --transaction-id (optional) – die ID einer Transaktion, die über den CLI-Befehl begin-transaction gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL-Anweisung einfügen möchten.

  • --parameters (optional) – die Parameter für die SQL-Anweisung.

  • --include-result-metadata | --no-include-result-metadata (optional) – ein Wert, der angibt, ob Metadaten in die Ergebnisse eingefügt werden sollen. Der Standardwert ist --no-include-result-metadata.

  • --database (optional) – der Name der Datenbank.

    Die --database-Option funktioniert möglicherweise nicht, wenn Sie eine SQL-Anweisung ausführen, nachdem Sie bei der vorherige Anfrage --sql "use database_name;" 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, wenn der Aufruf das Daten-API-Zeitintervall von 45 Sekunden überschreitet. Der Standardwert ist --no-continue-after-timeout.

    Im Fall von Data Definition Language (DDL)-Anweisungen sollten Sie die Anweisung nach Ablauf des Aufrufs weiter ausführen, um Fehler und die Möglichkeit beschädigter Datenstrukturen zu vermeiden.

  • --format-records-as "JSON"|"NONE" – Ein optionaler Wert, der angibt, ob die Ergebnismenge als JSON-Zeichenfolge formatiert werden soll. Der Standardwert ist "NONE". Nutzungsinformationen über die Verarbeitung von JSON-Ergebnismengen finden Sie unter Verarbeiten von Abfrageergebnissen der Amazon-RDS-Data-API im JSON-Format.

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

Anmerkung

Das Limit für Antwortgrößen beträgt 1 MiB. Wenn der Aufruf mehr als 1 MiB an Antwortdaten zurückgibt, wird der Aufruf beendet.

Für Aurora Serverless v1 beträgt die maximale Anzahl der Anforderungen pro Sekunde 1 000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.

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

Für Linux, 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"

Für Windows:

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

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

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

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

Für Linux, 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"

Für Windows:

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

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

{
    "numberOfRecordsUpdated": 1
}

Der folgende CLI-Befehl führt eine einzelne SQL-Anweisung mit Parametern aus.

Für Linux, 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\"}}]"

Für 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.

Wichtig

Im Fall von DDL-Anweisungen sollten Sie die Anweisung auch nach Ablauf des Aufrufs weiter ausführen. Wenn eine DDL-Anweisung vor Ende der Ausführung beendet wird, kann dies zu Fehlern und möglicherweise beschädigten Datenstrukturen führen. Um eine Anweisung weiter auszuführen, nachdem ein Aufruf das für die RDS-Daten-API geltende Zeitintervall von 45 Sekunden überschritten hat, geben Sie die Option --continue-after-timeout an.

Für 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

Für Windows:

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

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

{
    "generatedFields": [],
    "numberOfRecordsUpdated": 0
}
Anmerkung

Die generatedFields-Daten werden von Aurora PostgreSQL nicht unterstützt. Zum Abrufen der Werte von generierten Feldern verwenden Sie die RETURNING-Klausel. Weitere Informationen finden Sie in unter Returning Data From Modified Rows in der PostgreSQL-Dokumentation.

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

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

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

Wichtig

Wenn Sie die Option --transaction-id nicht angeben, werden Änderungen, die sich durch den Aufruf ergeben, automatisch übergeben.

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

  • --sql (erforderlich) – eine SQL-Anweisung, die auf dem DB-Cluster ausgeführt werden soll.

    Tipp

    Fügen Sie bei MySQL-kompatiblen Anweisungen kein Semikolon am Ende des --sql-Parameters ein. Ein abschließendes Semikolon kann einen Syntaxfehler verursachen.

  • --transaction-id (optional) – die ID einer Transaktion, die über den CLI-Befehl begin-transaction gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, in die Sie die SQL-Anweisung einfügen möchten.

  • --parameter-set (optional) – die Parametersätze für die Batch-Operation.

  • --database (optional) – der Name der Datenbank.

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

Anmerkung

Es gibt keine feste Obergrenze für die Anzahl der Parametersätze. Die maximale Größe der HTTP-Anforderung, die über die Daten-API gesendet wird, beträgt jedoch 4 MiB. Wenn die Anforderung dieses Limit überschreitet, gibt die Daten-API einen Fehler zurück und die Anfrage wird nicht verarbeitet. Dieses 4-MiB-Limit umfasst die Größe der HTTP-Header und der JSON-Notation in der Anforderung. Die Anzahl der Parametersätze, die Sie einbinden können, hängt demnach von mehreren Faktoren ab, z. B. von der Größe der SQL-Anweisung und der Größe der individuellen Parametersätze.

Das Limit für Antwortgrößen beträgt 1 MiB. Wenn der Aufruf mehr als 1 MiB an Antwortdaten zurückgibt, wird der Aufruf beendet.

Für Aurora Serverless v1 beträgt die maximale Anzahl der Anforderungen pro Sekunde 1 000. Für alle anderen unterstützten Datenbanken gibt es kein Limit.

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

Für Linux, 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\"}}]]"

Für 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.

Übergeben einer SQL-Transaktion

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

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

  • --transaction-id (erforderlich) – die ID einer Transaktion, die über den CLI-Befehl begin-transaction gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, die Sie beenden und übergeben möchten.

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

Für Linux, 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"

Für Windows:

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

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

{
    "transactionStatus": "Transaction Committed"
}

Rollback einer SQL-Transaktion

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

Wichtig

Wenn die Transaktions-ID abgelaufen ist, wurde automatisch ein Rollback für die Transaktion ausgeführt. In diesem Fall gibt ein aws rds-data rollback-transaction-Befehl, der die abgelaufene Transaktions-ID angibt, einen Fehler zurück.

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

  • --transaction-id (erforderlich) – die ID einer Transaktion, die über den CLI-Befehl begin-transaction gestartet wurde. Geben Sie die Transaktions-ID der Transaktion an, für die Sie ein Rollback ausführen möchten.

Der folgende AWS CLI-Befehl führt beispielsweise einen Rollback für eine SQL-Transaktion aus.

Für Linux, 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"

Für 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"
    }