JDBC

نسخه‌های ۱.۰ و ۱.۱ پروتکل امنیتی TLS غیرفعال هستند. برای برقراری اتصال، از TLS 1.2 یا بالاتر استفاده کنید.

اسکریپت Google Apps می‌تواند از طریق سرویس JDBC ، که پوششی پیرامون فناوری استاندارد اتصال پایگاه داده جاوا است، به پایگاه‌های داده خارجی متصل شود. سرویس JDBC از Google Cloud SQL برای پایگاه‌های داده MySQL، MySQL، Microsoft SQL Server، Oracle و PostgreSQL پشتیبانی می‌کند.

اگر صفحه گسترده شما بیش از حد بزرگ می‌شود یا با مشکلات اتمام زمان در محاسبات پیچیده مواجه هستید، انتقال داده‌های شما به یک پایگاه داده خارجی می‌تواند عملکرد و قابلیت اطمینان را به میزان قابل توجهی بهبود بخشد.

برای به‌روزرسانی یک پایگاه داده خارجی با JDBC، اسکریپت شما باید یک اتصال به پایگاه داده باز کند و سپس با ارسال دستورات SQL تغییرات را اعمال کند.

پایگاه‌های داده SQL ابری گوگل

Google Cloud SQL به شما امکان می‌دهد پایگاه‌های داده رابطه‌ای ایجاد کنید که در فضای ابری گوگل قرار دارند. Cloud SQL ممکن است بسته به میزان استفاده شما، هزینه‌هایی را متحمل شود.

با دنبال کردن مراحل ذکر شده در راهنمای سریع Cloud SQL، یک نمونه Google Cloud SQL ایجاد کنید.

ایجاد اتصالات Google Cloud SQL

دو روش برای برقراری ارتباط با پایگاه داده Google Cloud SQL با استفاده از سرویس JDBC مربوط به Apps Script وجود دارد:

هر دو معتبر هستند، اما روش دوم مستلزم آن است که شما مجموعه‌ای از محدوده‌های IP را برای دسترسی به پایگاه داده خود مجاز کنید.

این روش با استفاده از روش Jdbc.getCloudSqlConnection ، اتصالی به یک نمونه‌ی Google Cloud SQL MySQL ایجاد می‌کند. آدرس اینترنتی (URL) پایگاه داده به شکل jdbc:google:mysql://subname است، که در آن subname نام اتصال نمونه‌ی MySQL است که در صفحه‌ی نمای کلی نمونه‌ی Cloud SQL در کنسول Google Cloud ذکر شده است.

برای اتصال به Cloud SQL SQL Server، به Jdbc.getConnection مراجعه کنید.

از Jdbc.getConnection استفاده کنید

برای استفاده از این روش، باید محدوده‌های آدرس IP خاصی از نوع مسیریابی بین دامنه‌ای بدون کلاس (CIDR) را مجاز کنید تا سرورهای Apps Script بتوانند به پایگاه داده شما متصل شوند. قبل از اجرای اسکریپت، مراحل زیر را انجام دهید:

  1. در نمونه‌ی Google Cloud SQL خود، محدوده‌های IP را یکی‌یکی از این منبع داده مجاز کنید.

  2. آدرس اینترنتی (URL) اختصاص داده شده به پایگاه داده خود را کپی کنید؛ باید به شکل jdbc:mysql:subname باشد.

پس از تأیید این محدوده‌های IP، با استفاده از یکی از متدهای Jdbc.getConnection و URL که قبلاً کپی کرده‌اید، به نمونه Google Cloud SQL خود متصل شوید.

سایر پایگاه‌های داده

اگر از قبل پایگاه داده MySQL، Microsoft SQL Server، Oracle یا PostgreSQL خود را دارید، از طریق سرویس JDBC مربوط به Apps Script به آن متصل شوید.

ایجاد سایر اتصالات پایگاه داده

برای ایجاد اتصال به پایگاه داده با استفاده از سرویس Apps Script JDBC ، در تنظیمات پایگاه داده خود باید محدوده‌های IP را از این منبع داده مجاز کنید.

سرویس JDBC فقط می‌تواند به پورت‌های ۱۰۲۵ یا بالاتر متصل شود. مطمئن شوید که پایگاه داده شما از پورت پایین‌تری سرویس نمی‌دهد.

پس از ایجاد این لیست‌های مجاز، با استفاده از یکی از متدهای Jdbc.getConnection و URL پایگاه داده خود، یک اتصال به پایگاه داده ایجاد کنید.

کد نمونه

کد نمونه زیر فرض می‌کند که شما به یک پایگاه داده Google Cloud SQL متصل می‌شوید و اتصالات پایگاه داده را با استفاده از متد Jdbc.getCloudSqlConnection ایجاد می‌کند. برای سایر پایگاه‌های داده، باید از متد Jdbc.getConnection برای ایجاد اتصالات پایگاه داده استفاده کنید.

برای اطلاعات بیشتر در مورد متدهای JDBC، به مستندات جاوا برای JDBC مراجعه کنید.

ایجاد پایگاه داده، کاربر و جدول

اکثر توسعه‌دهندگان از ابزار خط فرمان MySQL برای ایجاد پایگاه‌های داده، کاربران و جداول استفاده می‌کنند. با این حال، همانطور که در مثال زیر نشان داده شده است، می‌توان همین کار را در Apps Script نیز انجام داد. حداقل یک کاربر دیگر ایجاد کنید تا اسکریپت شما همیشه مجبور نباشد به عنوان root به پایگاه داده متصل شود.

سرویس/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);
  }
}

نوشتن در پایگاه داده

مثال‌های زیر نحوه نوشتن یک رکورد واحد در پایگاه داده و همچنین نوشتن یک دسته ۵۰۰ تایی رکورد را نشان می‌دهند. دسته‌بندی برای عملیات انبوه حیاتی است.

از دستورات پارامتری استفاده می‌شود که در آن‌ها متغیرها با ? نشان داده می‌شوند. برای جلوگیری از حملات تزریق SQL ، از دستورات پارامتری برای escape کردن تمام داده‌های ارائه شده توسط کاربر استفاده کنید.

سرویس/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);
  }
}

خواندن از پایگاه داده

این مثال نحوه خواندن تعداد زیادی رکورد از پایگاه داده و اجرای حلقه روی مجموعه نتایج در صورت لزوم را نشان می‌دهد.

سرویس/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 باز را نیز خاتمه می‌دهد. با این حال، سایر عناصر رابط کاربری نمایش داده شده - مانند منوها یا دیالوگ‌های سفارشی و نوارهای کناری با محتوای سفارشی - این کار را نمی‌کنند.

گوگل، گوگل ورک‌اسپیس و علامت‌ها و لوگوهای مرتبط، علائم تجاری شرکت گوگل هستند. سایر نام‌های شرکت‌ها و محصولات، علائم تجاری شرکت‌هایی هستند که با آنها مرتبط هستند.