| list_instances |
Alle Cloud SQL-Instanzen im Projekt auflisten.
|
| get_instance |
Details zu einer Cloud SQL-Instanz abrufen.
|
| create_instance |
Leitet die Erstellung einer Cloud SQL-Instanz ein.
Sofern nicht anders angegeben, verwendet eine neu erstellte Instanz die Standardkonfiguration einer Entwicklungsumgebung. Im Folgenden sehen Sie die Standardkonfiguration für eine Instanz in einer Entwicklungsumgebung:
{
"tier": "db-perf-optimized-N-2",
"data_disk_size_gb": 100,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "ZONAL",
"tags": [{"environment": "dev"}]
}
Die folgende Konfiguration wird für eine Instanz in einer Produktionsumgebung empfohlen:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "POSTGRES_18",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
Die folgende Instanzkonfiguration wird für SQL Server empfohlen:
{
"tier": "db-perf-optimized-N-8",
"data_disk_size_gb": 250,
"region": "us-central1",
"database_version": "SQLSERVER_2022_STANDARD",
"edition": "ENTERPRISE_PLUS",
"availability_type": "REGIONAL",
"tags": [{"environment": "prod"}]
}
|
| execute_sql |
Führen Sie beliebige gültige SQL-Anweisung für eine Cloud SQL-Instanz aus, einschließlich Anweisungen der Datendefinitionssprache (DDL), der Datenkontrollsprache (DCL), der Datenabfragesprache (DQL) oder der Datenbearbeitungssprache (DML). Damit das execute_sql-Tool unterstützt wird, muss eine Cloud SQL-Instanz die folgenden Anforderungen erfüllen:
- Der Wert von
data_api_access muss auf ALLOW_DATA_API festgelegt werden.
- Bei einer MySQL-Instanz muss das Datenbank-Flag
cloudsql_iam_authentication auf on gesetzt sein. Für eine PostgreSQL-Instanz muss das Datenbank-Flag cloudsql.iam_authentication auf on gesetzt sein.
- Für den Aufruf des
execute_sql-Tools ist ein IAM-Nutzerkonto oder ein IAM-Dienstkonto (CLOUD_IAM_USER oder CLOUD_IAM_SERVICE_ACCOUNT) erforderlich. Das Tool führt die SQL-Anweisungen mit den Berechtigungen des Datenbanknutzers aus, der mit der IAM-Datenbankauthentifizierung angemeldet ist.
Nachdem Sie mit dem Tool create_instance eine Instanz erstellt haben, können Sie mit dem Tool create_user ein IAM-Nutzerkonto für den Nutzer erstellen, der derzeit im Projekt angemeldet ist. Für das execute_sql-Tool gelten die folgenden Einschränkungen:
- Wenn eine SQL-Anweisung eine Antwort zurückgibt, die größer als 10 MB ist, wird die Antwort abgeschnitten.
- Das Tool
execute_sql hat ein Standardzeitlimit von 30 Sekunden. Wenn eine Abfrage länger als 30 Sekunden dauert, gibt das Tool einen DEADLINE_EXCEEDED-Fehler zurück.
- Das Tool
execute_sql wird für SQL Server nicht unterstützt.
Wenn Sie Fehler wie „IAM-Authentifizierung ist für die Instanz nicht aktiviert“ erhalten, können Sie mit dem Tool get_instance den Wert des Flags für die IAM-Datenbankauthentifizierung für die Instanz prüfen. Wenn Sie Fehler wie „Die Instanz erlaubt keinen Zugriff auf diese Instanz über executeSql“ erhalten, können Sie mit dem Tool get_instance die Einstellung data_api_access prüfen. Wenn Sie Authentifizierungsfehler erhalten:
- Prüfen Sie mit dem Tool
list_users, ob das aktuell angemeldete Nutzerkonto als IAM-Nutzer in der Instanz vorhanden ist.
- Wenn das IAM-Nutzerkonto nicht vorhanden ist, erstellen Sie es mit dem
create_user-Tool für den angemeldeten Nutzer.
- Wenn der aktuell angemeldete Nutzer nicht die richtigen Datenbanknutzerrollen hat, können Sie ihm mit dem Tool
update_user Datenbankrollen zuweisen. Mit der Rolle cloudsqlsuperuser kann einem IAM-Nutzer beispielsweise eine Vielzahl der erforderlichen Berechtigungen gewährt werden.
Prüfen Sie, ob dem aktuell angemeldeten Nutzer die richtigen IAM-Berechtigungen für das Projekt zugewiesen sind. Mit dem Befehl gcloud projects get-iam-policy [PROJECT_ID] können Sie prüfen, ob dem Nutzer die richtigen IAM-Rollen oder -Berechtigungen für das Projekt zugewiesen sind.
- Der Nutzer muss die Berechtigung
cloudsql.instance.login haben, um die automatische IAM-Datenbankauthentifizierung durchzuführen.
- Der Nutzer muss die Berechtigung
cloudsql.instances.executeSql haben, um SQL-Anweisungen mit dem Tool execute_sql oder der API executeSql auszuführen.
- Häufig verwendete IAM-Rollen, die die erforderlichen Berechtigungen enthalten: Cloud SQL-Instanznutzer (
roles/cloudsql.instanceUser) oder Cloud SQL-Administrator (roles/cloudsql.admin)
Wenn Sie eine ExecuteSqlResponse erhalten, prüfen Sie immer die Felder message und status im Antworttext. Ein erfolgreicher HTTP-Statuscode bedeutet nicht, dass alle SQL-Anweisungen vollständig ausgeführt wurden. Die Felder message und status geben an, ob während der Ausführung der SQL-Anweisung teilweise Fehler oder Warnungen aufgetreten sind.
|
| get_operation |
Den Status eines lang andauernden Vorgangs abrufen. Ein lang andauernder Vorgang kann einige Minuten dauern. Wenn ein Vorgang längere Zeit in Anspruch nimmt, verwenden Sie ein Befehlszeilentool, um 30 Sekunden zu warten, bevor Sie den Status des Vorgangs noch einmal prüfen.
|
| create_user |
Erstellen Sie einen Datenbanknutzer für eine Cloud SQL-Instanz.
- Dieses Tool gibt einen Vorgang mit langer Ausführungszeit zurück. Verwenden Sie das Tool
get_operation, um den Status abzufragen, bis der Vorgang abgeschlossen ist.
- Wenn Sie das Tool
create_user verwenden, geben Sie den Nutzertyp an: CLOUD_IAM_USER oder CLOUD_IAM_SERVICE_ACCOUNT.
- Standardmäßig wird dem neu erstellten Nutzer die Rolle
cloudsqlsuperuser zugewiesen, sofern Sie im Antrag nicht explizit andere Datenbankrollen angeben.
- Sie können einen neu erstellten Nutzer mit dem
execute_sql-Tool verwenden, wenn der Nutzer ein aktuell angemeldeter IAM-Nutzer ist. Das Tool execute_sql führt die SQL-Anweisungen mit den Berechtigungen des Datenbanknutzers aus, der sich mit der IAM-Datenbankauthentifizierung angemeldet hat.
Für das create_user-Tool gelten die folgenden Einschränkungen:
- Sie können keinen integrierten Nutzer mit einem Passwort erstellen.
- Mit dem Tool
create_user kann kein Nutzer für SQL Server erstellt werden.
So erstellen Sie einen IAM-Nutzer in PostgreSQL:
- Der Datenbank-Nutzername muss die E-Mail-Adresse des IAM-Nutzers sein und darf nur Kleinbuchstaben enthalten. Wenn Sie beispielsweise einen Nutzer für den PostgreSQL IAM-Nutzer
example-user@example.com erstellen möchten, können Sie die folgende Anfrage verwenden:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance":"test-instance",
"project": "test-project"
}
Der erstellte Datenbank-Nutzername für den IAM-Nutzer ist example-user@example.com. So erstellen Sie ein IAM-Dienstkonto in PostgreSQL:
- Der Datenbank-Nutzername muss ohne das Suffix
.gserviceaccount.com erstellt werden, obwohl die vollständige E-Mail-Adresse für das Konto service-account-name@project-id.iam.gserviceaccount.com lautet. Wenn Sie beispielsweise ein IAM-Dienstkonto für PostgreSQL erstellen möchten, können Sie das folgende Anfrageformat verwenden:
{
"name": "test@test-project.iam",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Der erstellte Datenbanknutzername für das IAM-Dienstkonto ist test@test-project.iam. So erstellen Sie einen IAM-Nutzer oder ein IAM-Dienstkonto in MySQL:
- Wenn Cloud SQL for MySQL einen Nutzernamen speichert, werden das @ und der Domainname von der E-Mail-Adresse des Nutzers oder Dienstkontos abgeschnitten. Aus
example-user@example.com wird beispielsweise example-user.
- Aus diesem Grund können Sie einer Cloud SQL-Instanz nicht zwei IAM-Nutzer oder Dienstkonten mit demselben Nutzernamen, aber unterschiedlichen Domainnamen hinzufügen.
- Wenn Sie beispielsweise einen Nutzer für den MySQL IAM-Nutzer
example-user@example.com erstellen möchten, verwenden Sie die folgende Anfrage:
{
"name": "example-user@example.com",
"type": "CLOUD_IAM_USER",
"instance": "test-instance",
"project": "test-project"
}
Der erstellte Datenbank-Nutzername für den IAM-Nutzer ist example-user.
- Verwenden Sie beispielsweise die folgende Anfrage, um das MySQL-IAM-Dienstkonto
service-account-name@project-id.iam.gserviceaccount.com zu erstellen:
{
"name": "service-account-name@project-id.iam.gserviceaccount.com",
"type": "CLOUD_IAM_SERVICE_ACCOUNT",
"instance": "test-instance",
"project": "test-project"
}
Der erstellte Datenbanknutzername für das IAM-Dienstkonto ist service-account-name.
|
| update_user |
Aktualisieren eines Datenbanknutzers für eine Cloud SQL-Instanz. Ein häufiger Anwendungsfall für die update_user ist, einem Nutzer die Rolle cloudsqlsuperuser zuzuweisen, die viele erforderliche Berechtigungen umfasst. Mit diesem Tool können nur Nutzer aktualisiert werden, um Datenbankrollen zuzuweisen.
- Dieses Tool gibt einen Vorgang mit langer Ausführungszeit zurück. Verwenden Sie das Tool
get_operation, um den Status abzufragen, bis der Vorgang abgeschlossen ist.
- Bevor Sie das
update_user-Tool aufrufen, prüfen Sie immer die vorhandene Konfiguration des Nutzers, z. B. den Nutzertyp, mit dem list_users-Tool.
- Als Sonderfall für MySQL gilt: Wenn das Tool
list_users eine vollständige E‑Mail-Adresse für das Feld iamEmail zurückgibt, z. B. {name=test-account,
iamEmail=test-account@project-id.iam.gserviceaccount.com}, verwenden Sie in Ihrem update_user-Antrag die vollständige E‑Mail-Adresse im Feld iamEmail im Feld name Ihres Tool-Antrags. Zum Beispiel name=test-account@project-id.iam.gserviceaccount.com.
Wichtige Parameter zum Aktualisieren von Nutzerrollen:
database_roles: Eine Liste der Datenbankrollen, die dem Nutzer zugewiesen werden sollen.revokeExistingRoles: Ein boolesches Feld (Standardwert: „false“), das steuert, wie vorhandene Rollen behandelt werden. So funktionieren Rollenaktualisierungen:
Wenn revokeExistingRoles zutrifft:
- Alle vorhandenen Rollen, die dem Nutzer zugewiesen sind, aber NICHT in der bereitgestellten
database_roles-Liste enthalten sind, werden ENTZOGEN.
- Der Widerruf gilt nur für Nicht-Systemrollen. Systemrollen wie
cloudsqliamuser werden nicht widerrufen.
- Alle Rollen in der Liste
database_roles, die der Nutzer noch NICHT hat, werden GEWÄHRT.
- Wenn
database_roles leer ist, werden ALLE vorhandenen Nicht-Systemrollen widerrufen.
Wenn revokeExistingRoles „false“ ist (Standard):
- Alle Rollen in der Liste
database_roles, die der Nutzer noch NICHT hat, werden GEWÄHRT.
- Vorhandene Rollen, die NICHT in der Liste
database_roles enthalten sind, werden BEIBEHALTEN.
- Wenn
database_roles leer ist, werden die Rollen des Nutzers nicht geändert.
Beispiele:
|
| clone_instance |
Cloud SQL-Instanz als Klon einer Quellinstanz erstellen
- Dieses Tool gibt einen Vorgang mit langer Ausführungszeit zurück. Verwenden Sie das Tool
get_operation, um den Status abzufragen, bis der Vorgang abgeschlossen ist.
- Das Klonen kann mehrere Minuten dauern. Verwenden Sie ein Befehlszeilentool, um 30 Sekunden zu warten, bevor Sie den Status noch einmal prüfen.
|
| update_instance |
Aktualisiert teilweise die Konfigurationseinstellungen einer Cloud SQL-Instanz.
- Dieses Tool gibt einen Vorgang mit langer Ausführungszeit zurück. Verwenden Sie das Tool
get_operation, um den Status abzufragen, bis der Vorgang abgeschlossen ist.
|
| list_users |
Alle Datenbanknutzer für eine Cloud SQL-Instanz auflisten.
|
| import_data |
Daten in eine Cloud SQL-Instanz importieren Wenn die Datei nicht mit gs:// beginnt, wird davon ausgegangen, dass sie lokal gespeichert ist. Wenn die Datei lokal ist, muss sie in Cloud Storage hochgeladen werden, bevor Sie den eigentlichen import_data-Aufruf ausführen können. Verwenden Sie zum Hochladen der Datei in Cloud Storage die Befehle gcloud oder gsutil. Bevor Sie die Datei in Cloud Storage hochladen, sollten Sie überlegen, ob Sie einen vorhandenen Bucket verwenden oder einen neuen Bucket im bereitgestellten Projekt erstellen möchten. Nachdem die Datei in Cloud Storage hochgeladen wurde, muss das Dienstkonto der Instanz ausreichende Berechtigungen haben, um die hochgeladene Datei aus dem Cloud Storage-Bucket zu lesen. So gehts:
- Verwenden Sie das Tool
get_instance, um die E‑Mail-Adresse des Dienstkontos der Instanz abzurufen. Rufen Sie aus der Ausgabe des Tools den Wert des Felds serviceAccountEmailAddress ab.
- Weisen Sie dem Dienstkonto der Instanz die Rolle
storage.objectAdmin für den bereitgestellten Cloud Storage-Bucket zu. Verwenden Sie einen Befehl wie gcloud storage buckets
add-iam-policy-binding oder eine Anfrage an die Cloud Storage API. Es kann zwei bis sieben Minuten oder länger dauern, bis die Rolle gewährt und die Berechtigungen an das Dienstkonto in Cloud Storage weitergegeben werden. Wenn nach dem Aktualisieren der IAM-Richtlinie ein Berechtigungsfehler auftritt, warten Sie einige Minuten und versuchen Sie es dann noch einmal.
Nachdem die Berechtigungen erteilt wurden, können Sie die Daten importieren. Wir empfehlen, optionale Parameter leer zu lassen und die Systemstandardeinstellungen zu verwenden. Der Dateityp kann in der Regel anhand der Dateiendung ermittelt werden. Wenn die Datei beispielsweise eine SQL-Datei ist, .sql oder .csv für eine CSV-Datei. Im Folgenden sehen Sie ein Beispiel für eine SQL-importContext für MySQL.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL"
}
Für MySQL ist kein database-Parameter vorhanden, da der Datenbankname in der SQL-Datei erwartet wird. Geben Sie nur einen URI an. Außer importContext sind keine weiteren Felder erforderlich. Für PostgreSQL ist das Feld database erforderlich. Im Folgenden finden Sie ein Beispiel für eine PostgreSQL-importContext mit dem angegebenen Feld database.
{
"uri": "gs://sample-gcs-bucket/sample-file.sql",
"kind": "sql#importContext",
"fileType": "SQL",
"database": "sample-db"
}
Das import_data-Tool gibt einen Vorgang mit langer Ausführungszeit zurück. Verwenden Sie das Tool get_operation, um den Status abzufragen, bis der Vorgang abgeschlossen ist.
|
