JDBC

系統會停用 TLS 安全性通訊協定的 1.0 和 1.1 版。如要建立連線，請使用 TLS 1.2 以上版本。

Google Apps Script 可透過 JDBC 服務 (標準 Java 資料庫連線技術的包裝函式) 連線至外部資料庫。JDBC 服務支援 MySQL、Microsoft SQL Server、Oracle 和 PostgreSQL 資料庫適用的 Google Cloud SQL。

如果試算表越來越大，或是複雜的計算作業發生逾時問題，將資料移至外部資料庫可大幅提升效能和穩定性。

如要使用 JDBC 更新外部資料庫，指令碼必須開啟資料庫連線，然後傳送 SQL 陳述式來進行變更。

Google Cloud SQL 資料庫

Google Cloud SQL 可讓您建立位於 Google 雲端的關聯資料庫。Cloud SQL 可能會根據您的用量產生費用。

按照 Cloud SQL 快速入門導覽課程列出的步驟，建立 Google Cloud SQL 執行個體。

建立 Google Cloud SQL 連線

您可以使用 Apps Script 的 JDBC 服務，透過下列兩種方式建立與 Google Cloud SQL 資料庫的連線：

(建議) 使用 Jdbc.getCloudSqlConnection 連線
使用 Jdbc.getConnection 建立連線

這兩種方法都有效，但第二種方法需要您授權一組 IP 範圍，才能存取資料庫。

使用 Jdbc.getCloudSqlConnection (建議)

這個方法會使用 Jdbc.getCloudSqlConnection 方法，建立與 Google Cloud SQL MySQL 執行個體的連線。資料庫網址的格式為 jdbc:google:mysql://subname，其中 subname 是 Google Cloud 控制台中，Cloud SQL 執行個體「總覽」頁面列出的 MySQL 執行個體連線名稱。

如要連線至 Cloud SQL SQL Server，請參閱 Jdbc.getConnection。

使用 Jdbc.getConnection

如要使用這個方法，您必須授權特定「無類別跨網域路由 (CIDR)」IP 位址範圍，Apps Script 伺服器才能連線至資料庫。執行指令碼前，請先完成下列步驟：

在 Google Cloud SQL 執行個體中，授權 IP 範圍，一次一個，來自這個資料來源。
複製指派給資料庫的網址，網址應採用 jdbc:mysql:subname 格式。

授權這些 IP 範圍後，請使用其中一種 Jdbc.getConnection 方法和您稍早複製的網址，建立與 Google Cloud SQL 執行個體的連線。

其他資料庫

如果您已有自己的 MySQL、Microsoft SQL Server、Oracle 或 PostgreSQL 資料庫，可以透過 Apps Script 的 JDBC 服務連線。

建立其他資料庫連線

如要使用 Apps Script JDBC 服務建立資料庫連線，您必須在資料庫設定中授權這個資料來源的 IP 範圍。

JDBC 服務只能連線至通訊埠 1025 以上。確認資料庫並未透過較低的通訊埠提供服務。

設定這些允許清單後，請使用 Jdbc.getConnection 方法和資料庫的網址，建立與資料庫的連線。

程式碼範例

下列程式碼範例假設您要連線至 Google Cloud SQL 資料庫，並使用 Jdbc.getCloudSqlConnection 方法建立資料庫連線。如要連線至其他資料庫，請使用 Jdbc.getConnection 方法建立資料庫連線。

如要進一步瞭解 JDBC 方法，請參閱 JDBC 的 Java 說明文件。

建立資料庫、使用者和資料表

大多數開發人員會使用 MySQL 指令列工具建立資料庫、使用者和資料表。不過，您可以在 Apps Script 中執行相同操作，如下列範例所示。建立至少一位其他使用者，這樣指令碼就不必一律以 root 身分連線至資料庫。

service/jdbc.gs

前往 GitHub 查看

/**
 * Create a new database within a Cloud SQL instance.
 */
function createDatabase() {
  try {
    const conn = Jdbc.getCloudSqlConnection(instanceUrl, root, rootPwd);
    conn.createStatement().execute(`CREATE DATABASE ${db}`);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

/**
 * Create a new user for your database with full privileges.
 */
function createUser() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, root, rootPwd);

    const stmt = conn.prepareStatement("CREATE USER ? IDENTIFIED BY ?");
    stmt.setString(1, user);
    stmt.setString(2, userPwd);
    stmt.execute();

    conn.createStatement().execute(`GRANT ALL ON \`%\`.* TO ${user}`);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

/**
 * Create a new table in the database.
 */
function createTable() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);
    conn
      .createStatement()
      .execute(
        "CREATE TABLE entries " +
          "(guestName VARCHAR(255), content VARCHAR(255), " +
          "entryID INT NOT NULL AUTO_INCREMENT, PRIMARY KEY(entryID));",
      );
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

寫入資料庫

下列範例示範如何將單一記錄寫入資料庫，以及如何寫入 500 筆記錄的批次。批次處理對於大量作業至關重要。

系統會使用參數化陳述式，其中變數以 ? 表示。為防止 SQL 植入攻擊，請使用參數化陳述式逸出所有使用者提供的資料。

service/jdbc.gs

前往 GitHub 查看

/**
 * Write one row of data to a table.
 */
function writeOneRecord() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);

    const stmt = conn.prepareStatement(
      "INSERT INTO entries " + "(guestName, content) values (?, ?)",
    );
    stmt.setString(1, "First Guest");
    stmt.setString(2, "Hello, world");
    stmt.execute();
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

/**
 * Write 500 rows of data to a table in a single batch.
 */
function writeManyRecords() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);
    conn.setAutoCommit(false);

    const start = new Date();
    const stmt = conn.prepareStatement(
      "INSERT INTO entries " + "(guestName, content) values (?, ?)",
    );
    for (let i = 0; i < 500; i++) {
      stmt.setString(1, `Name ${i}`);
      stmt.setString(2, `Hello, world ${i}`);
      stmt.addBatch();
    }

    const batch = stmt.executeBatch();
    conn.commit();
    conn.close();

    const end = new Date();
    console.log("Time elapsed: %sms for %s rows.", end - start, batch.length);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

/**
 * Write 500 rows of data to a table in a single batch.
 * Recommended for faster writes
 */
function writeManyRecordsUsingExecuteBatch() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);
    conn.setAutoCommit(false);

    const start = new Date();
    const stmt = conn.prepareStatement(
      "INSERT INTO entries " + "(guestName, content) values (?, ?)",
    );
    const params = [];
    for (let i = 0; i < 500; i++) {
      params.push([`Name ${i}`, `Hello, world ${i}`]);
    }

    const batch = stmt.executeBatch(params);
    conn.commit();
    conn.close();

    const end = new Date();
    console.log("Time elapsed: %sms for %s rows.", end - start, batch.length);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

從資料庫讀取

這個範例示範如何從資料庫讀取大量記錄，並視需要對結果集進行迴圈。

service/jdbc.gs

前往 GitHub 查看

/**
 * Read up to 1000 rows of data from the table and log them.
 */
function readFromTable() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);
    const start = new Date();
    const stmt = conn.createStatement();
    stmt.setMaxRows(1000);
    const results = stmt.executeQuery("SELECT * FROM entries");
    const numCols = results.getMetaData().getColumnCount();

    while (results.next()) {
      let rowString = "";
      for (let col = 0; col < numCols; col++) {
        rowString += `${results.getString(col + 1)}\t`;
      }
      console.log(rowString);
    }

    results.close();
    stmt.close();

    const end = new Date();
    console.log("Time elapsed: %sms", end - start);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

/**
 * Read up to 1000 rows of data from the table and log them.
 * Recommended for faster reads
 */
function readFromTableUsingGetRows() {
  try {
    const conn = Jdbc.getCloudSqlConnection(dbUrl, user, userPwd);
    const start = new Date();
    const stmt = conn.createStatement();
    stmt.setMaxRows(1000);
    const results = stmt.executeQuery("SELECT * FROM entries");
    const numCols = results.getMetaData().getColumnCount();
    const getRowArgs = [];
    for (let col = 0; col < numCols; col++) {
      getRowArgs.push(`getString(${col + 1})`);
    }
    const rows = results.getRows(getRowArgs.join(","));
    for (let i = 0; i < rows.length; i++) {
      console.log(rows[i].join("\t"));
    }

    results.close();
    stmt.close();

    const end = new Date();
    console.log("Time elapsed: %sms", end - start);
  } catch (err) {
    // TODO(developer) - Handle exception from the API
    console.log("Failed with an error %s", err.message);
  }
}

關閉連線

指令碼執行完畢後，JDBC 連線會自動關閉。(即使發出呼叫的 HTML 服務頁面保持開啟狀態，單一 google.script.run 呼叫仍會計為一次完整執行。)

不過，如果您知道在指令碼結束前，連線、陳述式或結果集已完成，請呼叫 JdbcConnection.close、JdbcStatement.close 或 JdbcResultSet.close 手動關閉。

顯示警告或提示對話方塊也會終止所有開啟的 JDBC 連線。不過，其他顯示的 UI 元素 (例如自訂選單或對話方塊，以及含有自訂內容的側欄) 則不會。

Google、Google Workspace 和其他相關符號及標誌均為 Google LLC 的商標，所有其他公司和產品名稱則是與個別公司關聯的商標。

JDBC 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

Google Cloud SQL 資料庫

建立 Google Cloud SQL 連線

使用 Jdbc.getCloudSqlConnection (建議)

使用 Jdbc.getConnection

其他資料庫

建立其他資料庫連線

程式碼範例

建立資料庫、使用者和資料表

寫入資料庫

從資料庫讀取

關閉連線

JDBC