JDBC

يمكن لبرمجة التطبيقات الاتصال بقواعد البيانات الخارجية من خلال خدمة JDBC، وهي عبارة عن برنامج تضمين حول تقنية اتصال قاعدة بيانات 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 من "برمجة التطبيقات":

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

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

باستخدام Jdbc.getCloudSqlConnection(url) (مُستحسَن)

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

للاتصال بخادم Cloud SQL SQL، يُرجى الاطّلاع على Jdbc.getConnection(url).

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

لاستخدام هذه الطريقة، يجب عليك تفويض نطاقات عناوين IP محدّدة للتوجيه بين النطاقات بدون فئات (CIDR) حتى تتمكن خوادم "برمجة التطبيقات" من الاتصال بقاعدة بياناتك. قبل تشغيل النص البرمجي، أكمل الخطوات التالية:

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

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

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

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

لمزيد من المعلومات حول طرق JDBC، راجع وثائق Java لـ JDBC.

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

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