Serviços integrados do Google

O Google Apps Script fornece mais de 30 serviços integrados para interagir com os 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 o Math oferece métodos como random() e constantes como PI, o serviço Planilhas do Apps Script oferece métodos como openById(id), classes (objetos filhos) como Range e tipos enumerados como DataValidationCriteria.

A documentação de referência dos serviços que controlam Google Workspace produtos estão disponíveis na seção Google Workspace Serviços, no cabeçalho "Referência" na barra lateral deste site. Os serviços utilitários, como criação de interfaces do usuário, análise de XML ou gravação de dados de registro, são coletados na seção "Serviços de script".

Recursos modernos do JavaScript

O Apps Script aceita dois ambientes de execução JavaScript: o moderno V8 e um mais antigo, com a tecnologia do intérprete Rhino JavaScript do Mozilla.

O ambiente 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 JavaScript 1.6 mais antigo, além de alguns recursos das versões 1.7 e 1.8. É possível escolher livremente qual ambiente de execução usar com seu script, mas o ambiente de execução do V8 é altamente recomendado.

Cada ambiente de execução é compatível com classes e objetos JavaScript disponíveis para o script, além dos serviços avançados do Google e integrados. Seus scripts podem usar objetos comuns, como Array, Date, RegExp e assim por diante, além dos objetos globais Math e Object.

Usar o 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 tipos enumerados 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 objeto global, tipo enumerado ou 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, depois, digitar . (um ponto final), 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 eles.

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 somente a partir do objeto GmailApp. Alguns serviços fornecem vários objetos globais. Por exemplo, o serviço Base inclui quatro objetos globais: Browser, Logger, MimeType e Session.

Métodos de chamada

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 do Gmail da seguinte forma:

GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');

Se um método retornar outra classe do Apps Script, você poderá 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. Portanto, 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.');

Acesso a classes filhas

Cada serviço inclui uma ou mais classes filhas que não podem ser acessadas do nível superior da mesma forma que um objeto global. Não é possível usar a palavra-chave new para criar essas classes, como é possível fazer com classes JavaScript padrão, como Date. Só é possível acessar uma classe filha chamando um método que a retorne. Se você não tiver certeza de como acessar uma determinada classe, visite 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. Elas 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 Body.getChild(childIndex) do serviço de documentos Body.getChild(childIndex) retorna um objeto Element genérico. Element é uma interface que representa outra classe, possivelmente uma Paragraph ou Table. Objetos de interface raramente são úteis por si só. Em vez disso, chame um método como Element.asParagraph() para transmitir o objeto de volta para uma classe precisa.

Como trabalhar com tipos enumerados

A maioria dos serviços inclui alguns tipos enumerados (tipos enumerados) de valores nomeados. Por exemplo, o serviço do Drive usa os tipos enumerados Access e Permission para determinar quais usuários têm acesso a um arquivo ou pasta. Em quase todos os casos, esses tipos enumerados podem ser acessados no 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);