משחקי JDBC

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

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

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

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

כדי להשתמש בשיטה הזו, עליך לתת הרשאות מסוימות Classless Inter-Domain Routing (CIDR) טווחים של כתובות IP כדי שהשרתים של 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.

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

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

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

קוד לדוגמה

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