משחקי JDBC

Apps Script יכול להתחבר למסדי נתונים חיצוניים באמצעות שירות JDBC, רכיב מקיף של טכנולוגיית הקישוריות הרגילה של מסדי נתונים של 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 כדי לגשת למסד הנתונים.

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

במאמר Jdbc.getConnection(url) מוסבר איך להתחבר לשרת Cloud SQL.

באמצעות 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 או ב-Oracle, תוכלו להתחבר אליו דרך שירות JDBC ב-Apps Script.

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

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

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

קוד לדוגמה

הקוד לדוגמה שבהמשך מניח שאתם מתחברים למסד נתונים של Google Cloud SQL, ויוצרים חיבורים למסדי נתונים באמצעות method Jdbc.getCloudSqlConnection(url). במסדי נתונים אחרים צריך להשתמש ב-method 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. כל שמות החברות והמוצרים האחרים הם סימנים מסחריים של החברות שאליהן הם משויכים.