Встроенные сервисы Google

Google Apps Script предоставляет более 30 встроенных сервисов для взаимодействия с пользовательскими данными, другими системами Google и внешними системами. Эти службы предоставляются в виде глобальных объектов, аналогичных стандартному объекту Math в JavaScript. Например, точно так же, как Math предлагает такие методы, как random() и константы, такие как PI , служба электронных таблиц Apps Script предлагает такие методы, как openById(id) , классы (дочерние объекты), такие как Range , и перечисления, такие как DataValidationCriteria .

Справочная документация по службам, управляющим продуктамиGoogle Workspace , собрана в разделе «СлужбыGoogle Workspace » под заголовком «Справочник» на боковой панели этого сайта. Служебные службы (для создания пользовательских интерфейсов, анализа XML или записи данных журнала) собраны в разделе «Службы сценариев».

Современные возможности JavaScript

Apps Script поддерживает две среды выполнения JavaScript: современную среду выполнения V8 и более старую, основанную на интерпретаторе Mozilla Rhino JavaScript .

Среда выполнения V8 поддерживает современный синтаксис и функции ECMAScript . Среда выполнения Rhino основана на старом стандарте JavaScript 1.6 , а также на некоторых функциях версий 1.7 и 1.8 . Вы можете свободно выбирать, какую среду выполнения использовать со своим сценарием, но настоятельно рекомендуется использовать среду выполнения V8.

Каждая среда выполнения поддерживает классы и объекты JavaScript, доступные вашему сценарию в дополнение к встроенным и расширенным службам Google . Ваши сценарии могут использовать общие объекты, такие как Array , Date , RegExp и т. д. , а также глобальные объекты Math и Object .

Использование автозаполнения

Редактор сценариев предоставляет функцию «помощника по содержимому», чаще называемую «автозаполнением», которая показывает глобальные объекты, а также методы и перечисления, которые действительны в текущем контексте сценария. Предложения автозаполнения появляются автоматически всякий раз, когда вы вводите точку после глобального объекта, перечисления или вызова метода, который возвращает класс Apps Script. Например:

  • Если вы вводите полное имя глобального объекта или выбираете его из автозаполнения, введите . (точка), вы увидите все методы и перечисления для этого класса.
  • Если вы введете несколько символов, вы увидите все допустимые предложения, начинающиеся с этих символов.

Понимание глобальных объектов

Каждая служба предоставляет по крайней мере один глобальный объект (верхнего уровня); например, доступ к службе Gmail осуществляется исключительно из объекта GmailApp . Некоторые службы предоставляют несколько глобальных объектов; например, базовый сервис включает в себя четыре глобальных объекта: Browser , Logger , MimeType и Session .

Методы вызова

Глобальные объекты почти всех встроенных или расширенных служб включают методы, возвращающие данные, или класс Apps Script. Скрипты вызывают вызовы методов в следующем формате:

GlobalObjectName.methodName(argument1, argument2, ..., argumentN);

Например, сценарий может отправить электронное письмо, вызвав метод sendEmail(recipient, subject, body) службы Gmail следующим образом:

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

Если метод возвращает другой класс Apps Script, вы можете объединить вызовы метода в одну строку. (Типы возвращаемых значений показаны как при автозаполнении, так и в справочной документации метода.) Например, метод DocumentApp.create() возвращает Document ; таким образом, следующие два раздела кода эквивалентны:

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.');

Доступ к дочерним классам

Каждая служба включает в себя один или несколько дочерних классов, к которым нельзя получить доступ с верхнего уровня, как к глобальному объекту. Вы не можете использовать ключевое слово new для создания этих классов, как это можно сделать со стандартными классами JavaScript, такими как Date ; вы можете получить доступ к дочернему классу, только вызвав метод, который его возвращает. Если вы не уверены, как получить доступ к определенному классу, посетите корневую страницу справочной документации службы и найдите метод, который возвращает нужный вам класс.

Разбираемся с интерфейсами

Некоторые службы включают специальные классы, которые в справочной документации помечены как «интерфейсы». Это универсальные классы, используемые в качестве возвращаемых типов для методов, которые не могут заранее определить точный тип; например, метод службы документов Body.getChild(childIndex) возвращает универсальный объект Element . Element — это интерфейс, который представляет какой-то другой класс, возможно, Paragraph или Table . Объекты интерфейса редко бывают полезны сами по себе; вместо этого вы обычно хотите вызвать такой метод, как Element.asParagraph() , чтобы вернуть объект к точному классу.

Работа с перечислениями

Большинство сервисов включают в себя несколько перечислений (перечисляемых типов) именованных значений. Например, служба Диска использует перечисления Access и Permission , чтобы определить, какие пользователи имеют доступ к файлу или папке. Почти во всех случаях вы получаете доступ к этим перечислениям из глобального объекта. Например, вызов метода Folder.setSharing(accessType, permissionType) выглядит так:

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