JDBC

يتم إيقاف الإصدارَين 1.0 و1.1 من بروتوكول أمان طبقة النقل (TLS). لإنشاء اتصالات، استخدِم الإصدار 1.2 من بروتوكول أمان طبقة النقل (TLS) أو إصدار أحدث.

يمكن ربط برمجة تطبيقات Google بقواعد بيانات خارجية من خلال خدمة JDBC، وهي برنامج تضمين لتكنولوجيا Java Database Connectivity العادية. تتوافق خدمة JDBC مع قواعد بيانات Google Cloud SQL for MySQL وMySQL وMicrosoft SQL Server وOracle وPostgreSQL.

إذا كان جدول البيانات يزداد حجمًا أو كنت تواجه مشاكل في انتهاء المهلة مع العمليات الحسابية المعقّدة، يمكن أن يؤدي نقل بياناتك إلى قاعدة بيانات خارجية إلى تحسين الأداء والموثوقية بشكل كبير.

لتعديل قاعدة بيانات خارجية باستخدام 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 لقاعدة البيانات jdbc:google:mysql://subname، حيث يمثّل subname اسم اتصال المثيل في MySQL المُدرَج في صفحة نظرة عامة الخاصة بمثيل Cloud SQL في وحدة تحكّم Google Cloud.

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

استخدِم Jdbc.getConnection

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

  1. في مثيل Google Cloud SQL، عليك منح الإذن لنطاقات عناوين IP، واحدًا تلو الآخر من مصدر البيانات هذا.

  2. انسخ عنوان URL الذي تم تعيينه لقاعدة البيانات، ويجب أن يكون بالتنسيق jdbc:mysql:subname.

بعد منح الإذن لنطاقات عناوين IP هذه، أنشئ اتصالات بمثيل Google Cloud SQL باستخدام إحدى طرق Jdbc.getConnection وعنوان URL الذي نسخته سابقًا.

قواعد البيانات الأخرى

إذا كان لديك قاعدة بيانات MySQL أو Microsoft SQL Server أو Oracle أو PostgreSQL، يمكنك الربط بها من خلال خدمة JDBC في Apps Script.

إنشاء عمليات ربط بقواعد بيانات أخرى

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

لا يمكن لخدمة JDBC الاتصال إلا بالمنافذ 1025 أو المنافذ الأحدث. تأكَّد من أنّ قاعدة البيانات لا تستخدم منفذًا أصغر.

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

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

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

لمزيد من المعلومات عن طرق 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);
  }
}

/**
 * Write 500 rows of data to a table in a single batch.
 * Recommended for faster writes
 */
function writeManyRecordsUsingExecuteBatch() {
  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 (?, ?)",
    );
    const params = [];
    for (let i = 0; i < 500; i++) {
      params.push([`Name ${i}`, `Hello, world ${i}`]);
    }

    const batch = stmt.executeBatch(params);
    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);
  }
}

/**
 * Read up to 1000 rows of data from the table and log them.
 * Recommended for faster reads
 */
function readFromTableUsingGetRows() {
  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();
    const getRowArgs = [];
    for (let col = 0; col < numCols; col++) {
      getRowArgs.push(`getString(${col + 1})`);
    }
    const rows = results.getRows(getRowArgs.join(","));
    for (let i = 0; i < rows.length; i++) {
      console.log(rows[i].join("\t"));
    }

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