JDBC

يمكن أن يتصل Apps Script بقواعد بيانات خارجية من خلال خدمة JDBC، وهي حزمة برمجية حول تكنولوجيا Java Database Connectivity العادية. تتوافق خدمة 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:

• (إجراء يُنصح به) الاتصال باستخدام Jdbc.getCloudSqlConnection(url)
• الاتصال باستخدام Jdbc.getConnection(url)

نوضّح هذه الطرق أدناه. كلا الطريقتَين صالحتان، ولكن الطريقة الثانية تتطلّب منك تفويض مجموعة من نطاقات عناوين IP للوصول إلى قاعدة بياناتك.

استخدام Jdbc.getCloudSqlConnection(url) (إجراء مُقترَح)

تنشئ هذه الطريقة اتصالاً بمثيل MySQL في Google Cloud SQL باستخدام الطريقة Jdbc.getCloudSqlConnection(url). يكون عنوان URL لقاعدة البيانات على شكل jdbc:google:mysql://subname، حيث يكون subname هو اسم اتصال مثيل MySQL المدرَج في صفحة نظرة عامة على مثيل Cloud SQL في Google Cloud Console.

للاتصال بخادم 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 في Apps Script، يجب منح الإذن لنطاقات عناوين IP من مصدر البيانات هذا في إعدادات قاعدة البيانات.

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

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

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

لمزيد من المعلومات عن طرق JDBC، اطّلِع على مستندات Java حول JDBC.

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

يستخدم معظم المطوّرين أداة سطر أوامر MySQL ل إنشاء قواعد البيانات والمستخدمين والجداول. ومع ذلك، من الممكن تنفيذ الإجراء نفسه في Apps Script كما هو موضّح أدناه. من المستحسن إنشاء مستخدم آخر على الأقل لكي لا يضطر النص البرمجي إلى الاتصال دائمًا بقاعدة البيانات باسم root.

/**
 * 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، يجب استخدام عبارات مُعلَمة لتشفير جميع البيانات المقدَّمة من المستخدِم.

/**
 * 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);
  }
}

القراءة من قاعدة البيانات

يوضِّح هذا المثال كيفية قراءة عدد كبير من السجلّات من قاعدة بيانات، مع تكرار مجموعة النتائج حسب الضرورة.

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