משחקי JDBC

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

כדי להתחבר אל Cloud 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.

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