משחקי JDBC

אפשר להתחבר למסדי נתונים חיצוניים ב-Apps Script באמצעות שירות JDBC, שהוא מעטפת של טכנולוגיית Java Database Connectivity הרגילה. שירות ה-JDBC תומך במסדי נתונים של Google Cloud SQL for MySQL,‏ MySQL,‏ Microsoft SQL Server ו-Oracle.

כדי לעדכן מסד נתונים חיצוני באמצעות JDBC, הסקריפט צריך לפתוח חיבור למסד הנתונים ואז לבצע שינויים על ידי שליחת משפטי SQL.

מסדי נתונים של Google Cloud SQL

Google Cloud SQL מאפשר ליצור מסדי נתונים רלציוניים שנמצאים בענן של Google. שימו לב שיכול להיות שתצברו חיובים על השימוש ב-Cloud SQL.

כדי ליצור מכונה של Google Cloud SQL, פועלים לפי השלבים שמפורטים במדריך למתחילים של Cloud SQL.

יצירת חיבורים ל-Google Cloud SQL

יש שתי דרכים ליצור חיבור עם מסד נתונים של Google Cloud SQL באמצעות שירות JDBC של Apps Script:

השיטות האלה מוסברות בהמשך. שתי השיטות תקינות, אבל בשיטה השנייה צריך להעניק הרשאה לקבוצה של טווחי IP כדי לגשת למסד הנתונים.

השיטה הזו יוצרת חיבור למכונה של MySQL ב-Google Cloud SQL באמצעות השיטה Jdbc.getCloudSqlConnection(url). כתובת ה-URL של מסד הנתונים היא jdbc:google:mysql://subname, כאשר subname הוא שם החיבור של המכונה ב-MySQL שמופיע בדף Overview של המכונה ב-Cloud SQL במסוף Google Cloud.

כדי להתחבר ל-Cloud SQL SQL Server, אפשר לעיין במאמר Jdbc.getConnection(url).

באמצעות Jdbc.getConnection(url)

כדי להשתמש בשיטה הזו, צריך לאשר טווחים מסוימים של כתובות IP מסוג Classless Inter-Domain Routing‏ (CIDR) כדי ששרתי Apps Script יוכלו להתחבר למסד הנתונים. לפני שמריצים את הסקריפט, צריך לבצע את השלבים הבאים:

  1. במכונה של Google Cloud SQL, נותנים הרשאה לטווחי ה-IP, אחד בכל פעם ממקור הנתונים הזה.

  2. מעתיקים את כתובת ה-URL שהוקצה למסד הנתונים. הפורמט שלה צריך להיות jdbc:mysql:subname.

אחרי שתאשרו את טווחי ה-IP האלה, תוכלו ליצור חיבורים למכונה של Google Cloud SQL באמצעות אחת מהשיטות Jdbc.getConnection(url) וכתובת ה-URL שהעתקתם למעלה.

מסדי נתונים אחרים

אם כבר יש לכם מסד נתונים משלכם של MySQL,‏ Microsoft SQL Server או Oracle, תוכלו להתחבר אליו דרך שירות ה-JDBC של Apps Script.

יצירת חיבורים אחרים למסדי נתונים

כדי ליצור חיבור למסד נתונים באמצעות שירות JDBC של Apps Script, צריך להעניק הרשאה לטווחי IP ממקור הנתונים הזה בהגדרות של מסד הנתונים.

אחרי שתגדירו את רשימות ההיתרים האלה, תוכלו ליצור חיבור למסד הנתונים באמצעות אחת מהשיטות Jdbc.getConnection(url) וכתובת ה-URL של מסד הנתונים.

קוד לדוגמה

בקוד לדוגמה שבהמשך אנו מתייחסים למסד נתונים של Google Cloud SQL, ויוצרים חיבורי מסד נתונים באמצעות השיטה Jdbc.getCloudSqlConnection(url). במסדי נתונים אחרים, צריך להשתמש ב-method‏ Jdbc.getConnection(url) כדי ליצור חיבורי מסדי נתונים.

מידע נוסף על ה-methods של JDBC זמין במאמרי העזרה של Java ל-JDBC.

יצירת מסד נתונים, משתמש וטבלה

רוב המפתחים משתמשים בכלי שורת הפקודה MySQL כדי ליצור מסדי נתונים, משתמשים וטבלאות. עם זאת, אפשר לעשות את אותו הדבר ב-Apps Script, כפי שמתואר בהמשך. מומלץ ליצור לפחות משתמש אחד נוסף כדי שהסקריפט לא יצטרך תמיד להתחבר למסד הנתונים בתור root.

שירות/jdbc.gs
/**
 * 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
/**
 * 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);
  }
}

קריאה מהמסד הנתונים

בדוגמה הזו מוסבר איך לקרוא מספר רב של רשומות מהמסד נתונים, ולעבור על קבוצת התוצאות לפי הצורך.

service/jdbc.gs
/**
 * 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);
  }
}

סגירת חיבורים

חיבורי JDBC נסגרים באופן אוטומטי כשהרצת הסקריפט מסתיימת. (חשוב לזכור שקריאה אחת ל-google.script.run נחשבת לביצוע מלא, גם אם דף השירות ב-HTML שבו בוצעה הקריאה נשאר פתוח).

עם זאת, אם אתם יודעים שאתם מסיימים להשתמש בחיבור, בהצהרה או בקבוצת תוצאות לפני סוף הסקריפט, מומלץ לסגור אותם באופן ידני באמצעות קריאה ל-JdbcConnection.close(), ל-JdbcStatement.close() או ל-JdbcResultSet.close().

הצגת תיבת דו-שיח של התראות או הנחיות סוגרת גם את כל חיבורי ה-JDBC הפתוחים. לעומת זאת, רכיבי ממשק משתמש אחרים שמוצגים – כמו תפריטים מותאמים אישית או תיבות דו-שיח וסרגלי צד עם תוכן מותאם אישית – לא נכללים במדיניות הזו.

Google, Google Workspace והסימנים וסמלי הלוגו הקשורים אליהם הם סימנים מסחריים של Google LLC. כל שמות החברות והמוצרים האחרים הם סימנים מסחריים של החברות שאליהן הם משויכים.