Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

使用 Cloud SQL Data API 執行 SQL 陳述式

MySQL | PostgreSQL | SQL Server

本頁說明如何使用 Data API，對 Cloud SQL 執行個體上的資料庫執行 SQL 陳述式。使用 Data API 時，您可以使用 Cloud SQL Admin API 和 gcloud CLI，在已啟用 Data API 存取的任何執行個體上執行 SQL 陳述式。

您可以在使用公開 IP 位址、私人服務存取或 Private Service Connect 的執行個體上使用 Data API。Data API 支援所有類型的 SQL 陳述式，包括資料操縱語言 (DML)、資料定義語言 (DDL) 和資料查詢語言 (DQL)。Data API 適合執行小型且快速的管理陳述式，例如建立資料庫角色或使用者，以及進行小型結構定義更新。

事前準備

您必須先完成下列步驟，才能在執行個體上執行 SQL 陳述式。

設定資料庫使用者

Data API 必須以資料庫使用者的身分通過驗證，才能執行 SQL 陳述式。您可以透過內建使用者、IAM 使用者、IAM 服務帳戶或 IAM 群組進行驗證。

如要使用 IAM 進行驗證，請按照下列步驟操作：

為 IAM 資料庫驗證設定執行個體。
將 IAM 使用者、服務帳戶或群組新增至執行個體。
授予帳戶執行 SQL 陳述式所需的角色或權限。您可以在建立帳戶或更新帳戶時指派資料庫角色。如果您已建立具備最低權限的自訂資料庫角色，請將這些角色指派給帳戶。否則，請將預先定義的 cloudsqlsuperuser 角色指派給帳戶，使用 Data API 建立權限較低的自訂資料庫角色，然後將新角色授予帳戶，取代 cloudsqlsuperuser。

如要使用密碼以內建使用者身分進行驗證，請執行下列操作：

建立使用者。請注意，Data API 無法以預設 root 使用者身分進行驗證。
使用 Secret Manager 建立區域性密鑰來儲存密碼。為確保安全，Data API 會在 API 要求中要求提供密碼的資源名稱，而不是密碼本身。區域密鑰應與 Cloud SQL 執行個體儲存在相同區域。即使是儲存在相同區域，也不支援使用 Secret Manager 全域端點建立的密鑰。
定義選用的 IAM 條件，允許使用者存取特定密鑰，但無法存取專案中的其他密鑰。

必要角色或權限

根據預設，具備下列任一角色的使用者或服務帳戶，有權在 Cloud SQL 執行個體上執行 SQL 陳述式 (cloudsql.instances.executesql)：

Cloud SQL Admin (roles/cloudsql.admin)
Cloud SQL Instance User (roles/cloudsql.instanceUser)
Cloud SQL Studio User (roles/cloudsql.studioUser)

您也可以為使用者或服務帳戶定義 IAM 自訂角色，其中包含 cloudsql.instances.executesql 權限。這項權限支援身分與存取權管理 (IAM) 自訂角色。

啟用或停用 Data API

如要使用 Data API，必須為每個執行個體啟用這項功能。您隨時可以停用 Data API。

控制台

前往 Google Cloud 控制台的「Cloud SQL Instances」頁面。

前往 Cloud SQL 執行個體
如要開啟執行個體的「總覽」頁面，請按一下執行個體名稱。
在 SQL 導覽選單中，選取「連線」。
按一下 [網路] 分頁標籤。
勾選「允許 Data API」核取方塊。
按一下 [儲存]。

gcloud

如要在執行個體上啟用 Google Data API 存取權，請使用 gcloud sql instances patch 指令並加上 --data-api-access=ALLOW_DATA_API 標記：

gcloud sql instances patch INSTANCE_NAME --data-api-access=ALLOW_DATA_API

如要停用 Google Data API 存取權，請使用 --data-api-access=DISALLOW_DATA_API 標記：

gcloud sql instances patch INSTANCE_NAME --data-api-access=DISALLOW_DATA_API

將 INSTANCE_NAME 替換為要啟用或停用 Data API 的執行個體名稱。

執行 SQL 陳述式

您可以使用 gcloud CLI 或 REST API，對 Cloud SQL 執行個體上的資料庫執行 SQL 陳述式。

gcloud

如要使用 gcloud CLI 對執行個體上的資料庫執行 SQL 陳述式，請使用 gcloud sql instances execute-sql 指令。

如要使用 IAM 連線，請按照下列步驟操作：

gcloud sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--partial-result-mode=PARTIAL_RESULT_MODE

請將下列項目改為對應的值：

INSTANCE_NAME：執行個體的名稱。
DATABASE_NAME：執行個體中的資料庫名稱。
SQL_STATEMENT：要執行的 SQL 陳述式。如果陳述式含有空格或殼層特殊字元，就必須加上引號。
PARTIAL_RESULT_MODE：選用。控管結果不完整時的回應方式。可以是 ALLOW_PARTIAL_RESULT、FAIL_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。請參閱「修改截斷行為」。

如有需要，您也可以加入 --project=PROJECT_ID 旗標。

如要使用密碼以內建使用者身分連線，請按照下列步驟操作：

gcloud sql instances execute-sql INSTANCE_NAME \
--database=DATABASE_NAME \
--sql=SQL_STATEMENT \
--user=USER \
--password-secret-version=PASSWORD_SECRET_VERSION \
--partial-result-mode=PARTIAL_RESULT_MODE

請將下列項目改為對應的值：

USER：要驗證身分的資料庫使用者。省略 @ 和主機名稱。
PASSWORD_SECRET_VERSION：Secret Manager Secret 的資源名稱，其中包含資料庫使用者的密碼。密鑰應為區域密鑰，並儲存在與 Cloud SQL 執行個體相同的區域。預期的資源名稱格式為 projects/{project}/locations/{location}/secrets/{secret}/versions/{secret_version}。

Terraform

您可以在 Terraform 上使用 Data API，佈建資料庫內資源，例如資料庫、表格、擴充功能、使用者和權限授予，不必手動連線至執行個體。如要在 Terraform 上執行 SQL 指令碼，請使用 google_sql_provision_script Terraform 資源。

resource "google_sql_database_instance" "instance" {
  name             = "my-instance"
  database_version = "MYSQL_8_4"

  settings {
    tier            = "db-perf-optimized-N-2"
    data_api_access = "ALLOW_DATA_API"  # This allows the use of Data API.
    database_flags {
      name  = "cloudsql_iam_authentication"
      value = "on"
    }
  }
}

/*
 * Create a database user for your account and grant roles so it has privilege
 * to access the database. Set the type to CLOUD_IAM_USER for huamn
 * account or CLOUD_IAM_SERVICE_ACCOUNT for service account.
 */
resource "google_sql_user" "iam_user" {
  name     = "account-used-to-apply-this-config@example.com"
  instance = google_sql_database_instance.instance.name
  type     = "CLOUD_IAM_USER"

  # Roles granted to the user. To follow the principle of least privilege, you
  can first use `google_sql_provision_script` to create custom database role(s)
  with lesser privileges and then assign them to this user in place of
  `cloudsqlsuperuser`.
  # This field doesn't support MySQL 5.6 and 5.7.
  database_roles = ["cloudsqlsuperuser"]
}

resource "google_sql_provision_script" "script" {
  # You can inline the script or import from a file like script  = file("${path.module}/script.sql")
  # When modified, the whole script will be executed again. It's recommended to
  # make the script idempotent with patterns like create if not exists ... or
  # if not exists (select ...) then ... end if.
  script = "CREATE DATABASE pets;"
  instance = google_sql_database_instance.instance.name

  # Some of your queries may require a database. You can create and use a
  # database in the script or explicitly create and reference a database
  # like database = google_sql_database.database.name.

  description = "sql script to create DBs"

  # The identity account used to apply your Terraform config must exist as an
  # IAM user or IAM service account in the instance. Terraform connects to the
  # instance via IAM database authentication to execute the script.
  depends_on = [google_sql_user.iam_user]
}

套用變更

如要在 Google Cloud 專案中套用 Terraform 設定，請完成下列各節的步驟。

準備 Cloud Shell

啟動 Cloud Shell。
設定要套用 Terraform 設定的預設 Google Cloud 專案。

每項專案只需要執行一次這個指令，且可以在任何目錄中執行。
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
如果您在 Terraform 設定檔中設定明確值，環境變數就會遭到覆寫。

準備目錄

每個 Terraform 設定檔都必須有自己的目錄 (也稱為根模組)。

在 Cloud Shell 中建立目錄，並在該目錄中建立新檔案。檔案名稱的副檔名必須是 .tf，例如 main.tf。在本教學課程中，這個檔案稱為 main.tf。
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
如果您正在學習教學課程，可以複製每個章節或步驟中的程式碼範例。

將範例程式碼複製到新建立的 main.tf 中。

視需要從 GitHub 複製程式碼。如果 Terraform 程式碼片段是端對端解決方案的一部分，建議您使用這種做法。
查看並修改範例參數，套用至您的環境。
儲存變更。
初始化 Terraform。每個目錄只需執行一次這項操作。
```
terraform init
```
如要使用最新版 Google 供應商，請加入 -upgrade 選項：
```
terraform init -upgrade
```

套用變更

查看設定，確認 Terraform 即將建立或更新的資源符合您的預期：
```
terraform plan
```
視需要修正設定。
執行下列指令並在提示中輸入 yes，套用 Terraform 設定：
```
terraform apply
```
等待 Terraform 顯示「Apply complete!」訊息。
開啟 Google Cloud 專案即可查看結果。在 Google Cloud 控制台中，前往 UI 中的資源，確認 Terraform 已建立或更新這些資源。

刪除變更

刪除 google_sql_provision_script 資源不會刪除該資源建立的資料庫內資源。如要刪除這些變數，您可以在指令碼中明確新增 drop ... if exists 等陳述式，然後套用變更。

REST

如要使用 REST API 對執行個體上的資料庫執行 SQL 陳述式，請將 POST 要求傳送至 executeSql 端點：

POST https://sqladmin.googleapis.com/sql/v1beta4/projects/PROJECT_ID/instances/INSTANCE_NAME/executeSql

要求主體應包含資料庫名稱和 SQL 陳述式：

{
  "database": "DATABASE_NAME",
  "sqlStatement": "SQL_STATEMENT",
  "partialResultMode": "PARTIAL_RESULT_MODE"
  "autoIamAuthn": true
}

請將下列項目改為對應的值：

PROJECT_ID：您的專案 ID。
INSTANCE_NAME：執行個體的名稱。
DATABASE_NAME：執行個體中的資料庫名稱。
SQL_STATEMENT：要執行的 SQL 陳述式。
PARTIAL_RESULT_MODE：選用。控管結果超過 10 MB 時，API 的回應方式。可以是 FAIL_PARTIAL_RESULT、ALLOW_PARTIAL_RESULT 或 PARTIAL_RESULT_MODE_UNSPECIFIED。請參閱「修改截斷行為」。

修改截斷行為

執行 SQL 時，您可以透過在要求中加入 "partialResultMode" 欄位，控管結果大小的處理方式。這個欄位接受下列值：

FAIL_PARTIAL_RESULT：預設值。如果結果超過 10 MB，或只能擷取部分結果，請擲回錯誤。請勿傳回結果。
ALLOW_PARTIAL_RESULT：如果結果超過 10 MB，或因發生錯誤而只能擷取部分結果，請傳回截斷的結果，並將 partial_result 設為 true。請勿擲回錯誤。
PARTIAL_RESULT_MODE_UNSPECIFIED：未指定模式，與 FAIL_PARTIAL_RESULT 相同。

限制

回應大小上限為 10 MB。如果 partialResultMode 設為 ALLOW_PARTIAL_RESULT，超過這個大小的結果就會遭到截斷，否則系統會擲回錯誤。
要求大小上限為 0.5 MB。
您只能為正在執行的 MySQL 適用的 Cloud SQL 執行個體執行 SQL 陳述式。
如果執行個體已設定為外部伺服器複製，Cloud SQL 就不支援搭配使用 Data API。
如果要求處理時間超過 30 秒，系統就會取消要求。系統不支援使用 SET SESSION MAX_EXECUTION_TIME 設定較高的陳述式逾時。如果 MySQL 適用的 Cloud SQL 5.6 和 5.7 的長時間執行 DDL 陳述式逾時，可能會導致孤立檔案或資料表無法安全地復原。在大型資料表中使用 ALTER TABLE 等陳述式時，請務必謹慎。
Cloud SQL 會限制每位使用者對每個執行個體發出的並行 executeSql 要求數量，上限為 10 個。如果達到這個上限，後續要求就會失敗，並顯示「At most 10 concurrent queries may be run on this instance. 請稍後再試。」或「已達並行讀取作業上限 (10 個)。」
每個回應最多可包含 10 則資料庫訊息或警告。
如果陳述式語法或執行階段發生錯誤，系統就不會傳回任何結果。
如果是 MySQL 適用的 Cloud SQL，通知和警告只會顯示多重陳述式執行的最後一個陳述式。
如果陳述式耗用大量記憶體，可能會導致記憶體不足錯誤。如要進一步瞭解如何避免這些錯誤，請參閱「管理記憶體用量的最佳做法」。如果資料庫執行個體的記憶體用量偏高，通常會導致效能問題、停滯，甚至資料庫停機。
在執行個體上進行特定維護作業時，為確保資料完整性，資料 API 可能會暫時遭到封鎖。如果發生這種情況，請稍後再試。
SQL 指令碼及其執行回應可能會在用戶端與目標執行個體位置之間的中間位置傳輸。因此，對於特定 Assured Workloads 專案，以及constraints/sql.restrictNoncompliantResourceCreation手動強制執行的專案，要求會因「not supported for instances in certain Assured Workloads control packages folders」(特定 Assured Workloads 控制套件資料夾中的執行個體不支援) 錯誤而失敗。

使用 Cloud SQL Data API 執行 SQL 陳述式 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

設定資料庫使用者

必要角色或權限

啟用或停用 Data API

控制台

gcloud

執行 SQL 陳述式

gcloud

Terraform

套用變更

準備 Cloud Shell

準備目錄

套用變更

刪除變更

REST

修改截斷行為

限制

使用 Cloud SQL Data API 執行 SQL 陳述式