Aufrufen der Amazon RDS-Daten-API mit dem 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 Amazon 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.

Anmerkung

Sie AWS CLI können 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

Innerhalb der Daten-API kommt es bei einer Transaktion zu einem Timeout, 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 sie von der Daten-API automatisch zurückgesetzt.

DDL-Anweisungen (MySQL Data Definition Language) innerhalb einer Transaktion führen zu einem impliziten Commit. Wir empfehlen, dass Sie jede MySQL-DDL-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.

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

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"
}

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, nachdem der Aufruf das Daten-API-Timeout-Intervall von 45 Sekunden überschritten hat. Der Standardwert ist --no-continue-after-timeout.

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

  • --format-records-as "JSON"|"NONE" – Ein optionaler Wert, der angibt, ob die Ergebnismenge als JSON-Zeichenfolge formatiert werden soll. Der Standardwert ist "NONE". Nutzungsinformationen über die Verarbeitung von JSON-Ergebnismengen finden Sie unter Verarbeitung der Abfrageergebnisse 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.

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 (Standard).

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"
            }
        ]
    ]
}

Der folgende CLI-Befehl führt eine einzelne SQL-Anweisung in einer Transaktion aus, indem die Option --transaction-id 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
}

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. Geben Sie die --continue-after-timeout Option an, um die Ausführung einer Anweisung fortzusetzen, nachdem ein Aufruf das RDS-Daten-API-Timeout-Intervall von 45 Sekunden überschritten hat.

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 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 über die Daten-API übermittelten HTTP-Anfrage beträgt jedoch 4 MiB. Wenn die Anfrage dieses Limit überschreitet, gibt die Daten-API einen Fehler zurück und verarbeitet die Anfrage nicht. Dieses 4-MiB-Limit umfasst die Größe der HTTP-Header und der JSON-Notation in der Anforderung. Die Anzahl der Parametersätze, die Sie einbinden können, hängt demnach von mehreren Faktoren ab, z. B. von der Größe der SQL-Anweisung und der Größe der individuellen Parametersätze.

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

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 Batch-SQL-Anweisung für ein Daten-Array mit einem Parametersatz aus.

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.

Ü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 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"
}

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.

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"
    }