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 المدرَج في صفحة نظرة عامة الخاصة بمثيل Cloud SQL في وحدة تحكّم Google Cloud.

للاتصال بخادم SQL في Cloud SQL، راجِع Jdbc.getConnection(url).

استخدام Jdbc.getConnection(url)

لاستخدام هذه الطريقة، يجب منح الإذن لنطاقات عناوين IP معيّنة للتوجيه بين النطاقات بدون فئات (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 في "برمجة تطبيقات Google"، يجب أن تسمح بنطاقات عناوين IP من مصدر البيانات هذا في إعدادات قاعدة البيانات.

بعد إعداد قوائم السماح هذه، يمكنك إنشاء اتصال بقاعدة البيانات باستخدام إحدى طرق Jdbc.getConnection(url) وعنوان URL الخاص بقاعدة البيانات.

نموذج التعليمات البرمجية

يفترض نموذج الرمز البرمجي أدناه أنّك تتصل بقاعدة بيانات Google Cloud SQL، وينشئ اتصالات بقاعدة البيانات باستخدام الطريقة Jdbc.getCloudSqlConnection(url). بالنسبة إلى قواعد البيانات الأخرى، يجب استخدام طريقة Jdbc.getConnection(url) لإنشاء عمليات ربط بقواعد البيانات.

لمزيد من المعلومات عن طرق JDBC، راجِع مستندات Java الخاصة بـ JDBC.

إنشاء قاعدة بيانات ومستخدم وجدول

يستخدم معظم المطوّرين أداة سطر الأوامر MySQL لإنشاء قواعد البيانات والمستخدمين والجداول. ومع ذلك، يمكن إجراء ذلك في "برمجة تطبيقات Google"، كما هو موضّح أدناه. من المستحسن إنشاء مستخدم واحد على الأقل ليستطيع النص البرمجي الاتصال بقاعدة البيانات دائمًا بصفتك 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، عليك استخدام عبارات تتضمّن مَعلمات لتجنُّب جميع البيانات التي يقدّمها المستخدم.

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. وجميع أسماء الشركات والمنتجات الأخرى هي علامات تجارية تملكها الشركات ذات الصلة بها.​