JDBC

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

برای به‌روزرسانی یک پایگاه داده خارجی با 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(url) یک اتصال به یک نمونه‌ی Google Cloud SQL MySQL ایجاد می‌کند. URL پایگاه داده به شکل jdbc:google:mysql://subname است، که در آن subname نام اتصال نمونه‌ی MySQL است که در صفحه‌ی نمای کلی نمونه‌ی Cloud SQL در کنسول Google Cloud ذکر شده است.

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

استفاده از Jdbc.getConnection(url)

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

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

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

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

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

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

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

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

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

کد نمونه

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

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

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

اکثر توسعه‌دهندگان از ابزار خط فرمان MySQL برای ایجاد پایگاه‌های داده، کاربران و جداول استفاده می‌کنند. با این حال، همانطور که در زیر نشان داده شده است، می‌توان همین کار را در Apps Script نیز انجام داد. ایده خوبی است که حداقل یک کاربر دیگر ایجاد کنید تا اسکریپت شما همیشه مجبور نباشد به عنوان 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);
  }
}

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

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

همچنین به استفاده از عبارات پارامتری که در آنها متغیرها با ? نشان داده می‌شوند، توجه کنید. برای جلوگیری از حملات تزریق 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);
  }
}

/**
 * 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);
  }
}

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

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

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

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