O Google Apps Script fornece mais de 30 serviços integrados para interagir com os dados de usuários, 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 enumerações como
DataValidationCriteria.
A documentação de referência de serviços que controlam produtosGoogle Workspace é coletada na seção "Google Workspace Serviços", no cabeçalho "Referência", na barra lateral deste site. Os serviços utilitários (para criar interfaces de usuário, analisar XML ou gravar dados de registro) são coletados na seção "Script Services".
Recursos JavaScript modernos
O Apps Script é compatível com dois ambientes de execução do JavaScript: o moderno V8 e o mais antigo, com a tecnologia do intérprete JavaScript Rhino do Mozilla.
O V8 Runtime é compatível com a sintaxe e os recursos modernos do ECMAScript. O ambiente de execução do Rhino é baseado no padrão JavaScript 1.6 mais antigo, além de alguns recursos da 1.7 e 1.8. É possível escolher livremente qual ambiente de execução você quer usar com seu script, mas o tempo de execução V8 é altamente recomendado.
Cada ambiente de execução é compatível com classes e objetos JavaScript disponíveis para seu script, além dos serviços avançados e integrados do Google. Seus
scripts podem usar objetos comuns, como
Array,
Date,
RegExp,
e assim por diante,
bem como dos objetos
Math e
Object globais.
Usar o preenchimento automático
O editor de script fornece um recurso de "ajuda para conteúdo", mais conhecido como "preenchimento automático", que revela os objetos globais, bem como os 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 uma chamada de método, enumeração ou objeto global que retorna uma classe do Apps Script. Exemplo:
- Se você digitar o nome completo de um objeto global ou selecionar um objeto do preenchimento automático e depois digitar
.(um ponto), verá todos os métodos e tipos enumerados dessa classe. - Se você digitar alguns caracteres, verá todas as sugestões válidas que começam com esses caracteres.
Noções básicas sobre objetos globais
Cada serviço fornece pelo menos um objeto global (de nível superior). Por exemplo,
o serviço do Gmail é acessado exclusivamente 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 de chamada
Os objetos globais de quase todos os serviços integrados 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 do 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, será possível encadear 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. Assim, as
duas seções de código a seguir são equivalentes:
var doc = DocumentApp.create('New document');
var body = doc.getBody();
body.appendParagraph('New paragraph.');
// Same result as above.
DocumentApp.create('New document').getBody().appendParagraph('New paragraph.');
Como acessar 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. Não é possível usar a palavra-chave new para
criar essas classes, assim como é possível com classes JavaScript padrão, como
Date.
Você só pode acessar uma classe filha chamando 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 e procure um método que retorne a classe desejada.
Como lidar com interfaces
Alguns serviços incluem classes especiais rotuladas como "interfaces"
na documentação de referência. Essas são classes genéricas usadas como tipos de retorno
para métodos que não podem determinar o tipo exato com antecedência. Por exemplo,
o método Document service
Body.getChild(childIndex)
retorna um objeto genérico Element.
Element é uma interface que representa outra classe, possivelmente uma
Paragraph ou
Table. Os objetos de interface raramente são úteis
por conta própria. Em vez disso, convém chamar um método como
Element.asParagraph()
para transmitir o objeto de volta a uma classe precisa.
Como trabalhar com enumerações
A maioria dos serviços inclui algumas enumerações (tipos enumerados) de valores nomeados. Por
exemplo, o serviço do Drive usa as enumerações
Access e
Permission para determinar quais usuários
têm acesso a um arquivo ou uma pasta. Em quase todos os casos, você acessa essas enumerações
pelo objeto global. Por exemplo, uma chamada para o método
Folder.setSharing(accessType, permissionType)
tem esta aparência:
// 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);