O Google Apps Script oferece mais de 30 serviços integrados para interagir com dados do usuário, outros sistemas do Google e sistemas externos. Esses serviços são fornecidos como objetos globais semelhantes ao objeto Math padrão do JavaScript. Por exemplo, assim como Math oferece métodos como random() e constantes como PI, o serviço de planilhas do Apps Script oferece métodos como openById(id), classes (objetos filhos) como Range e enums como DataValidationCriteria.
A documentação de referência para serviços que controlam produtos do Google Workspace está na seção "Serviços do Google Workspace", no cabeçalho "Referência" da barra lateral deste site. Os serviços de utilidade (para coisas como criar interfaces de usuário, analisar XML ou gravar dados de registro) são coletados na seção "Serviços de script".
Recursos modernos do JavaScript
O Apps Script é compatível com dois ambientes de execução do JavaScript: o ambiente moderno V8 e um mais antigo com tecnologia do interpretador JavaScript Rhino da Mozilla.
O tempo de execução do V8 é compatível com a sintaxe e os recursos modernos do ECMAScript. O ambiente de execução do Rhino é baseado no padrão mais antigo do JavaScript 1.6, além de alguns recursos das versões 1.7 e 1.8. Escolha qual ambiente de execução usar com seu script. No entanto, o ambiente de execução do V8 é altamente recomendado.
Cada ambiente de execução oferece suporte a classes e objetos JavaScript disponíveis para seu
script, além dos
serviços avançados do Google. Seus
scripts podem usar objetos comuns como
Array,
Date,
RegExp,
e assim por diante,
além dos objetos globais
Math e
Object.
Como o código do Apps Script é executado nos servidores do Google (com exceção das páginas do serviço HTML), os recursos JavaScript baseados em navegador, como manipulação do DOM ou a API Window, não estão disponíveis no Apps Script.
Preenchimento automático
O editor de script oferece um recurso de "assistência de conteúdo", mais conhecido como "preenchimento automático", que revela os objetos globais, além de métodos e enumerações válidos no contexto atual do script. As sugestões de preenchimento automático aparecem automaticamente sempre que você digita um ponto após um objeto global, uma enumeração ou uma chamada de método que retorna uma classe do Apps Script. Exemplo:
- Se você digitar o nome completo de um objeto global ou selecionar um no preenchimento automático e digitar
.(um ponto), todos os métodos e enums dessa classe vão aparecer. - Se você digitar alguns caracteres, verá todas as sugestões válidas que começam com eles.
Objetos globais
Cada serviço fornece pelo menos um objeto global (de nível superior). Por exemplo, o serviço do Gmail é acessado apenas pelo objeto GmailApp. Alguns serviços
fornecem vários objetos globais. Por exemplo, o
serviço de base inclui quatro objetos globais:
Browser,
Logger,
MimeType e
Session.
Métodos
Os objetos globais de quase todos os serviços avançados ou integrados incluem métodos que retornam dados ou uma classe do Apps Script. Os scripts fazem chamadas de método neste formato:
GlobalObjectName.methodName(argument1, argument2, ..., argumentN);
Por exemplo, um script pode enviar um e-mail chamando o método
sendEmail(recipient, subject, body)
do serviço Gmail da seguinte maneira:
GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');
Se um método retornar outra classe do Apps Script, encadeie as chamadas de método
em uma linha. Os tipos de retorno são mostrados no preenchimento automático e na documentação de referência de um método. Por exemplo, o método
DocumentApp.create()
retorna um Document. Portanto, as
duas seções de código a seguir são equivalentes:
var doc = DocumentApp.create('New document');
var body = doc.getTab('t.0').asDocumentTab().getBody();
body.appendParagraph('New paragraph.');
// Same result as above.
DocumentApp.create('New document').getTab('t.0').asDocumentTab().getBody()
.appendParagraph('New paragraph.');
Classes filhas
Cada serviço inclui uma ou mais classes filhas que não podem ser acessadas
do nível superior como um objeto global. Também não é possível usar a palavra-chave new para
construir essas classes, como faria com classes JavaScript padrão, como
Date.
Para acessar uma classe filha, chame um método que a retorne. Se você não souber como acessar uma determinada classe, acesse a página raiz da documentação de referência do serviço. Ela lista as classes do serviço e os métodos que as retornam.
Interfaces
Alguns serviços incluem classes rotuladas como "interfaces" na documentação de referência. São classes genéricas usadas como tipos de retorno para métodos que não podem determinar o tipo preciso com antecedência. Por exemplo, o método
Document service
Body.getChild(childIndex)
retorna um objeto Element genérico.
A interface Element representa alguma outra classe, possivelmente um
Paragraph ou
Table. Objetos de interface raramente são úteis por si só. Em vez disso, chame um método como Element.asParagraph() para converter o objeto de volta a uma classe específica.
Tipos enumerados
A maioria dos serviços inclui enums (tipos enumerados) de valores nomeados. Por exemplo, o serviço do Google Drive usa as enumerações Access e Permission para determinar quais usuários têm acesso a um arquivo ou pasta. Na maioria dos casos, você acessa esses enums do
objeto global, conforme mostrado no exemplo a seguir:
// Creates a folder that anyone on the Internet can read from and write to.
// (Domain administrators can prohibit this setting for Google Workspace users.)
var folder = DriveApp.createFolder('Shared Folder');
folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);