JDBC

Le versioni 1.0 e 1.1 del protocollo di sicurezza TLS sono disattivate. Per stabilire le connessioni, utilizza TLS 1.2 o versioni successive.

Google Apps Script può connettersi a database esterni tramite il servizio JDBC, un wrapper intorno alla tecnologia Java Database Connectivity. Il servizio JDBC supporta i database Google Cloud SQL per MySQL, MySQL, Microsoft SQL Server, Oracle e PostgreSQL.

Se il foglio di lavoro sta diventando troppo grande o se si verificano problemi di timeout con calcoli complessi, il trasferimento dei dati in un database esterno può migliorare significativamente le prestazioni e l'affidabilità.

Per aggiornare un database esterno con JDBC, lo script deve aprire una connessione al database e apportare modifiche inviando istruzioni SQL.

Database Google Cloud SQL

Google Cloud SQL ti consente di creare database relazionali nel cloud di Google. Cloud SQL potrebbe comportare addebiti in base al tuo utilizzo.

Crea un'istanza Google Cloud SQL seguendo i passaggi descritti nella guida rapida di Cloud SQL.

Crea connessioni Google Cloud SQL

Esistono due modi per stabilire una connessione con un database Google Cloud SQL utilizzando il servizio JDBC di Apps Script:

Entrambi sono validi, ma il secondo metodo richiede l'autorizzazione di un insieme di intervalli IP per l'accesso al database.

Questo metodo crea una connessione a un'istanza Google Cloud SQL per MySQL utilizzando il metodo Jdbc.getCloudSqlConnection. L'URL del database ha il formato jdbc:google:mysql://subname, dove subname è il nome connessione istanza MySQL elencato nella pagina Panoramica dell'istanza Cloud SQL nella console Google Cloud.

Per connetterti a Cloud SQL SQL Server, consulta Jdbc.getConnection.

Utilizza Jdbc.getConnection

Per utilizzare questo metodo, devi autorizzare determinati intervalli di indirizzi IP Classless Inter-Domain Routing (CIDR) in modo che i server di Apps Script possano connettersi al tuo database. Prima di eseguire lo script, completa i seguenti passaggi:

  1. Nella tua istanza Google Cloud SQL, autorizza gli intervalli IP, uno alla volta da questa origine dati.

  2. Copia l'URL assegnato al tuo database. Dovrebbe avere il formato jdbc:mysql:subname.

Una volta autorizzati questi intervalli IP, crea connessioni all'istanza Google Cloud SQL utilizzando uno dei metodi Jdbc.getConnection e l'URL copiato in precedenza.

Altri database

Se hai già un tuo database MySQL, Microsoft SQL Server, Oracle o PostgreSQL, connettiti a questo tramite il servizio JDBC di Apps Script.

Creare altre connessioni al database

Per creare una connessione al database utilizzando il servizio JDBC di Apps Script, nelle impostazioni del database devi autorizzare gli intervalli IP di questa origine dati.

Il servizio JDBC può connettersi solo alle porte 1025 o successive. Assicurati che il tuo database non utilizzi una porta inferiore.

Una volta create queste liste consentite, crea una connessione al database utilizzando uno dei metodi Jdbc.getConnection e l'URL del database.

Codice di esempio

Il seguente codice di esempio presuppone che tu ti stia connettendo a un database Google Cloud SQL e crea connessioni al database utilizzando il metodo Jdbc.getCloudSqlConnection. Per gli altri database devi utilizzare il metodo Jdbc.getConnection per creare connessioni al database.

Per ulteriori informazioni sui metodi JDBC, consulta la documentazione Java per JDBC.

Crea un database, un utente e una tabella

La maggior parte degli sviluppatori utilizza lo strumento a riga di comando MySQL per creare database, utenti e tabelle. Tuttavia, è possibile fare la stessa cosa in Apps Script, come mostrato nell'esempio seguente. Crea almeno un altro utente in modo che lo script non debba sempre connettersi al database come 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);
  }
}

Scrivere nel database

Gli esempi seguenti mostrano come scrivere un singolo record nel database e un batch di 500 record. Il batching è fondamentale per le operazioni collettive.

Vengono utilizzate istruzioni con parametri, in cui le variabili sono indicate da ?. Per prevenire attacchi di SQL injection, utilizza istruzioni parametrizzate per eseguire l'escape di tutti i dati forniti dall'utente.

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

Leggere dal database

Questo esempio mostra come leggere un numero elevato di record dal database, eseguendo un ciclo sul set di risultati in base alle necessità.

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

Chiudere le connessioni

Le connessioni JDBC si chiudono automaticamente al termine dell'esecuzione di uno script. Le chiamate (singole google.script.run) vengono conteggiate come esecuzione completa, anche se la pagina del servizio HTML che ha effettuato la chiamata rimane aperta.

Tuttavia, se sai di aver terminato una connessione, un'istruzione o un insieme di risultati prima della fine dello script, chiudili manualmente chiamando JdbcConnection.close, JdbcStatement.close, o JdbcResultSet.close.

La visualizzazione di una finestra di avviso o prompt termina anche tutte le connessioni JDBC aperte. Tuttavia, altri elementi dell'interfaccia utente — come menu o finestre di dialogo personalizzati e barre laterali con contenuti personalizzati — non lo fanno.

Google, Google Workspace e i marchi e i loghi correlati sono marchi di Google LLC. Tutti gli altri nomi di società e prodotti sono marchi delle società a cui sono associati.