Serviço HTML: comunicar-se com as funções do servidor (original) (raw)

google.script.run é uma API JavaScript assíncrona do lado do cliente que permite que páginas de serviço HTML chamem funções do Apps Script do lado do servidor. O exemplo a seguir mostra a funcionalidade mais básica de google.script.run:chamando uma função no servidordo JavaScript do lado do cliente.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function doSomething() { Logger.log('I was called!'); }

Index.html

Se você implantar esse script como um app da Web e acessar o URL dele, não vai aparecer nada, mas, se você consultar os registros, vai notar que a função do servidordoSomething() foi chamada.

As chamadas do lado do cliente para funções do lado do servidor são assíncronas: depois que o navegador solicita que o servidor execute a função doSomething(), ele continua imediatamente para a próxima linha de código sem esperar por uma resposta. Isso significa que as chamadas de função do servidor podem não ser executadas na ordem esperada. Se você fizer duas chamadas de função ao mesmo tempo, não vai ser possível saber qual função será executada primeiro. O resultado pode ser diferente a cada vez que você carrega a página. Nessa situação,gerenciadores de sucesso e gerenciadores de falhaajudam a controlar o fluxo do código.

A API google.script.run permite 10 chamadas simultâneas para funções do servidor. Se você fizer uma 11ª chamada enquanto 10 ainda estiverem em execução, a função do servidor será adiada até que um dos 10 pontos seja liberado. Na prática, raramente você precisará pensar nessa restrição, especialmente porque a maioria dos navegadores já limita o número de solicitações simultâneas para o mesmo servidor a um número inferior a 10. No Firefox, por exemplo, o limite é 6. A maioria dos navegadores também atrasa o excesso de solicitações do servidor até que uma das solicitações atuais seja concluída.

Parâmetros e valores de retorno

É possível chamar uma função do servidor com parâmetros do cliente. Da mesma forma, uma função do servidor pode retornar um valor ao cliente como um parâmetro transmitido para umgerenciador de sucesso.

Parâmetros legais e valores de retorno são primitivos do JavaScript, como Number, Boolean, String ou null, além de objetos e matrizes do JavaScript que são compostos de primitivos, objetos e matrizes. Um elemento form na página também é válido como parâmetro, mas precisa ser o único parâmetro da função e não pode ser usado como valor de retorno. As solicitações falham se você tentar transmitir umDate, Function, elemento DOM além de um form ou outro tipo proibido, incluindo tipos proibidos em objetos ou matrizes. Objetos que criam referências circulares também falharão, e campos indefinidos em matrizes se tornarãonull.

Um objeto transmitido ao servidor se torna uma cópia do original. Se uma função do servidor receber um objeto e mudar as propriedades dele, as propriedades do cliente não serão afetadas.

Manipuladores de sucesso

Como o código do lado do cliente continua para a próxima linha sem esperar que uma chamada do servidor seja concluída,withSuccessHandler(function)permite que você especifique uma função de callback do lado do cliente para ser executada quando o servidor responder. Se a função do servidor retornar um valor, a API vai transmitir o valor para a nova função como um parâmetro.

O exemplo a seguir mostra um alerta do navegador quando o servidor responde. Observe que este exemplo de código exige autorização porque a função do lado do servidor está acessando sua conta do Gmail. A maneira mais simples de autorizar o script é executar a função getUnreadEmails() manualmente no editor de script uma vez antes de carregar a página. Como alternativa, aoimplantar o app da Web, você pode escolher executar como "usuário acessando o app da Web". Nesse caso, será necessário autorizar o carregamento do app.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function getUnreadEmails() { return GmailApp.getInboxUnreadCount(); }

Index.html

Formulários

Se você chamar uma função do servidor com um elemento form como parâmetro, o formulário se tornará um único objeto com nomes de campo como chaves e valores de campo como valores. Todos os valores são convertidos em strings, exceto o conteúdo dos campos de entrada de arquivo, que se tornam objetos Blob.

Este exemplo processa um formulário, incluindo um campo de entrada de arquivo, sem recarregar a página. Ele faz upload do arquivo no Google Drive e imprime o URL do arquivo na página do lado do cliente. No manipulador onsubmit, a palavra-chave thisse refere ao formulário. Ao carregar, todos os formulários na página têm a ação de envio padrão desativada por preventFormSubmit. Isso impede que a página redirecione para um URL incorreto em caso de exceção.

Code.gs

function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); }

function processForm(formObject) { var formBlob = formObject.myFile; var driveFile = DriveApp.createFile(formBlob); return driveFile.getUrl(); }

Index.html