משחקי JDBC

אפשר להתחבר למסדי נתונים חיצוניים באמצעות שירות JDBC של Apps Script, שהוא עטיפה של טכנולוגיית Java Database Connectivity (קישוריות למסדי נתונים ב-Java) הרגילה. שירות JDBC תומך ב-Google Cloud SQL ל-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 Console.

כדי להתחבר ל-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). במסדי נתונים אחרים צריך להשתמש בשיטה Jdbc.getConnection(url) כדי ליצור חיבורים למסד הנתונים.

מידע נוסף על שיטות JDBC מופיע במסמכי התיעוד של Java בנושא JDBC.

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

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

service/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, צריך להשתמש בהצהרות עם פרמטרים כדי לבצע escape לכל הנתונים שהמשתמשים מספקים.

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. כל שמות החברות והמוצרים האחרים הם סימנים מסחריים של החברות שאליהן הם משויכים.​