JDBC

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

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

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

للاتصال بخادم SQL 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 في "برمجة التطبيقات".

إنشاء اتصالات أخرى بقاعدة البيانات

لإنشاء اتصال قاعدة بيانات باستخدام برمجة تطبيقات خدمة JDBC، عليك تفويض نطاقات IP من مصدر البيانات هذا في إعدادات قاعدة البيانات.

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

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

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

لمزيد من المعلومات عن طرق JDBC، يمكنك الاطّلاع على مستندات 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. وجميع أسماء الشركات والمنتجات الأخرى هي علامات تجارية تملكها الشركات ذات الصلة بها.