Google Apps Script API Quickstart

Built-in Google Services

Google Apps Script provides more than 30 built-in services for interacting with user data, other Google systems, and external systems. These services are provided as global objects akin to JavaScript’s standard Math object. For example, just as Math offers methods like random() and constants like PI , Apps Script’s Spreadsheet service offers methods like openById(id) , classes (child objects) like Range , and enums like DataValidationCriteria .

The reference documentation for services that control Google Workspace products are collected in the «Google Workspace Services» section under the «Reference» header in the sidebar of this site. Utility services (for things like creating user interfaces, parsing XML, or writing log data) are collected in the «Script Services» section.

Modern JavaScript features

Apps Script supports two JavaScript runtimes: the modern V8 runtime and an older one powered by Mozilla’s Rhino JavaScript interpreter.

The V8 runtime supports modern ECMAScript syntax and features. The Rhino runtime is based on the older JavaScript 1.6 standard, plus a few features from 1.7 and 1.8. You can freely choose which runtime to use with your script, but the V8 runtime is strongly recommended.

Each runtime supports JavaScript classes and objects that are available to your script in addition to the built-in and advanced Google services. Your scripts can use common objects like Array , Date , RegExp , and so forth, as well as the Math and Object global objects.

Note: Because Apps Script code runs on Google’s servers (with the exception of HTML-service pages), browser-based JavaScript features like DOM manipulation or the Window API are not available in Apps Script.

Using autocomplete

The script editor provides a «content assist» feature, more commonly called «autocomplete,» which reveals the global objects as well as methods and enums that are valid in the script’s current context. Autocomplete suggestions appear automatically whenever you type a period after a global object, enum, or method call that returns an Apps Script class. For example:

• If you type the full name of a global object or select one from autocomplete, then type . (a period), you will see all methods and enums for that class.
• If you type a few characters, you’ll see all valid suggestions that begin with those characters.

Understanding global objects

Each service provides at least one global (top-level) object; for example, the Gmail service is accessed solely from the GmailApp object. Some services provide multiple global objects; for example, the Base service includes four global objects: Browser , Logger , MimeType , and Session .

Calling methods

The global objects of nearly all built-in or advanced services include methods that return data or an Apps Script class. Scripts make method calls in this format:

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

For example, a script can send an email by calling the sendEmail(recipient, subject, body) method of the Gmail service like so:

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

If a method returns another Apps Script class, you can chain method calls on one line. (Return types are shown both in autocomplete and in a method’s reference documentation.) For example, the method DocumentApp.create() returns a Document ; thus, the following two sections of code are equivalent:

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

Accessing child classes

Every service includes one or more child classes that cannot be accessed from the top level as a global object can. You cannot use the new keyword to construct these classes, as you can with standard JavaScript classes like Date ; you can only access a child class by calling a method that returns it. If you’re not sure how to access a certain class, visit the root page for the service’s reference documentation and look for a method that returns the class you want.

Dealing with interfaces

A handful of services include special classes that are labeled as «interfaces» in the reference documentation. These are generic classes used as return types for methods that cannot determine the precise type in advance; for example, the Document service method Body.getChild(childIndex) returns a generic Element object. Element is an interface that represents some other class, possibly a Paragraph or Table . Interface objects are rarely useful on their own; instead, you usually want to call a method like Element.asParagraph() to cast the object back to a precise class.

Working with enums

Most services include a few enums (enumerated types) of named values. For example, the Drive service uses the enums Access and Permission to determine which users have access to a file or folder. In almost all cases, you access these enums from the global object. For example, a call to the method Folder.setSharing(accessType, permissionType) looks like this:

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

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2023-07-24 UTC.

Источник

Краткое руководство по JavaScript

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

В кратких руководствах объясняется, как настроить и запустить приложение, которое вызывает API Google Workspace.

В кратких руководствах по Google Workspace используются клиентские библиотеки API для обработки некоторых деталей процесса аутентификации и авторизации. Мы рекомендуем вам использовать клиентские библиотеки для ваших собственных приложений. В этом кратком руководстве используется упрощенный подход к проверке подлинности, подходящий для среды тестирования. Для рабочей среды мы рекомендуем изучить аутентификацию и авторизацию, прежде чем выбирать учетные данные для доступа , подходящие для вашего приложения.

Создайте веб-приложение JavaScript, которое отправляет запросы к Google Apps Script API.

Цели

Предпосылки

Настройте свою среду

Для завершения этого краткого руководства настройте свою среду.

Включить API

Настройка экрана согласия OAuth

Если вы используете новый проект Google Cloud для выполнения этого краткого руководства, настройте экран согласия OAuth и добавьте себя в качестве тестового пользователя. Если вы уже выполнили этот шаг для своего облачного проекта, перейдите к следующему разделу.

1. В консоли Google Cloud выберите menu >API и службы >Экран согласия OAuth . Перейти к экрану согласия OAuth
2. Выберите тип пользователя для своего приложения, затем нажмите «Создать» .
3. Заполните регистрационную форму приложения, затем нажмите «Сохранить и продолжить» .
4. На данный момент вы можете пропустить добавление областей и нажать «Сохранить и продолжить» . В будущем, когда вы будете создавать приложение для использования за пределами вашей организации Google Workspace, вы должны будете добавить и проверить области авторизации, необходимые вашему приложению.
5. Если вы выбрали Внешний для типа пользователя, добавьте тестовых пользователей:
   1. В разделе «Проверить пользователей» нажмите «Добавить пользователей» .
   2. Введите свой адрес электронной почты и любых других авторизованных тестовых пользователей, затем нажмите «Сохранить и продолжить» .

   Авторизация учетных данных для веб-приложения

   1. В консоли Google Cloud выберите menu >API и службы >Учетные данные . Перейти к учетным данным
   2. Нажмите «Создать учетные данные» >«Идентификатор клиента OAuth» .
   3. Щелкните Тип приложения >Веб-приложение .
   4. В поле Имя введите имя учетных данных. Это имя отображается только в консоли Google Cloud.
   5. Добавьте авторизованные URI, связанные с вашим приложением:
      • Клиентские приложения (JavaScript) — в разделе «Авторизованные источники JavaScript» нажмите «Добавить URI» . Затем введите URI, который будет использоваться для запросов браузера. Это определяет домены, из которых ваше приложение может отправлять запросы API на сервер OAuth 2.0.
      • Серверные приложения (Java, Python и т. д.) . В разделе Авторизованные URI перенаправления нажмите Добавить URI . Затем введите URI конечной точки, на которую сервер OAuth 2.0 может отправлять ответы.
   6. Щелкните Создать . Появится экран создания клиента OAuth, показывающий ваш новый идентификатор клиента и секрет клиента. Обратите внимание на идентификатор клиента. Секреты клиента не используются для веб-приложений.
   7. Нажмите ОК . Вновь созданные учетные данные отображаются в разделе Идентификаторы клиентов OAuth 2.0 .

   Запишите эти учетные данные, поскольку они понадобятся вам позже в этом кратком руководстве.

   Создать ключ API

   1. В консоли Google Cloud выберите menu >API и службы >Учетные данные . Перейти к учетным данным
   2. Щелкните Создать учетные данные >Ключ API .
   3. Отображается ваш новый ключ API.
      • Нажмите Копировать content_copy , чтобы скопировать ключ API для использования в коде вашего приложения. Ключ API также можно найти в разделе «Ключи API» учетных данных вашего проекта.
      • Нажмите Ограничить ключ , чтобы обновить дополнительные настройки и ограничить использование вашего ключа API. Дополнительные сведения см. в разделе Применение ограничений ключа API .

   Настроить образец

   1. В рабочем каталоге создайте файл с именем index.html .
   2. В файл index.html вставьте следующий пример кода:

        
   Google Apps Script API Quickstart
    Authorize Sign Out     

   • YOUR_CLIENT_ID : идентификатор клиента, созданный вами при авторизации учетных данных для веб-приложения .
   • YOUR_API_KEY : ключ API, который вы создали в качестве предварительного условия .

   Запустите образец

   1. Если вы еще не вошли в свою учетную запись Google, вам будет предложено выполнить вход. Если вы вошли в несколько учетных записей, выберите одну учетную запись для авторизации.
   2. Нажмите Принять .
   3. Скопируйте код из браузера, вставьте его в командную строку и нажмите Enter .

   Информация об авторизации хранится в файловой системе, поэтому при следующем запуске примера кода авторизация не запрашивается.

   Вы успешно создали свое первое приложение JavaScript, которое отправляет запросы к Google Apps Script API.

   Следующие шаги

   Если не указано иное, контент на этой странице предоставляется по лицензии Creative Commons «С указанием авторства 4.0», а примеры кода – по лицензии Apache 2.0. Подробнее об этом написано в правилах сайта. Java – это зарегистрированный товарный знак корпорации Oracle и ее аффилированных лиц.

   Последнее обновление: 2023-07-25 UTC.

   Источник