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](https://docs.aws.amazon.com/cli/latest/reference/rds-data/index.html).
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.
**Topics**
+ [Starten einer SQL-Transaktion](#data-api.calling.cli.begin-transaction)
+ [Ausführen einer SQL-Anweisung](#data-api.calling.cli.execute-statement)
+ [Ausführen einer Stapel-SQL-Anweisung über ein Daten-Array](#data-api.calling.cli.batch-execute-statement)
+ [Übergeben einer SQL-Transaktion](#data-api.calling.cli.commit-transaction)
+ [Rollback einer SQL-Transaktion](#data-api.calling.cli.rollback-transaction)
## 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](data-api-json.md).
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](https://www.postgresql.org/docs/10/dml-returning.html) 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"
}
```