JDBC

يمكن أن يتصل Apps Script بقواعد بيانات خارجية من خلال خدمة JDBC، وهي حزمة برمجية حول تكنولوجيا Java Database Connectivity العادية. تتوافق خدمة JDBC مع Google Cloud SQL لـ MySQL وMySQL وMicrosoft SQL وقواعد بيانات الخادم وOracle.

لتعديل قاعدة بيانات خارجية باستخدام JDBC، يجب أن يفتح النص البرمجي اتصالًا بقاعدة البيانات ثم يُجري تغييرات من خلال إرسال عبارات SQL.

قواعد بيانات Google Cloud SQL

تتيح لك خدمة Google Cloud SQL إنشاء قواعد بيانات ارتباطية مباشرة في سحابة Google. يُرجى ملاحظة أنّ Cloud SQL إلى فرض رسوم بناءً على استخدامك.

يمكنك إنشاء مثيل Google Cloud SQL باتّباع الخطوات المذكورة في البدء السريع لخدمة Cloud SQL:

إنشاء اتصالات Google Cloud SQL

هناك طريقتان لإنشاء اتصال بخدمة Google Cloud SQL. باستخدام خدمة JDBC في "برمجة تطبيقات Google":

• (موصى به) الاتصال باستخدام 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

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

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

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

1. في مثيل Google Cloud SQL، امنح الإذن لنطاقات IP، واحدة تلو الأخرى من هذا مصدر البيانات.

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

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

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

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

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

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

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

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

يفترض الرمز النموذجي أدناه أنك تتصل بقاعدة بيانات Google Cloud SQL، وتنشئ اتصالات قاعدة البيانات باستخدام Jdbc.getCloudSqlConnection(url) . بالنسبة لقواعد البيانات الأخرى، يجب عليك استخدام دالة sort_values 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. وجميع أسماء الشركات والمنتجات الأخرى هي علامات تجارية تملكها الشركات ذات الصلة بها.​