Class ScriptApp

ScriptApp

Доступ к публикации скриптов и триггерам и управление ими. Этот класс позволяет пользователям создавать триггеры сценариев и управлять публикацией сценария как службы.

Характеристики

Свойство Тип Описание
AuthMode AuthMode Перечисление, определяющее, какие категории авторизованных служб Apps Script может выполнять с помощью триггерной функции.
AuthorizationStatus AuthorizationStatus Перечисление, обозначающее статус авторизации сценария.
EventType EventType Перечисление, обозначающее тип инициируемого события.
InstallationSource InstallationSource Перечисление, обозначающее, как скрипт был установлен пользователю в качестве дополнения.
TriggerSource TriggerSource Перечисление, обозначающее источник события, вызывающего срабатывание триггера.
WeekDay Weekday Перечисление, представляющее дни недели.

Методы

Метод Тип возврата Краткое описание
deleteTrigger(trigger) void Удаляет данный триггер, чтобы он больше не работал.
getAuthorizationInfo(authMode) AuthorizationInfo Получает объект, используемый для определения того, необходимо ли пользователю авторизовать этот сценарий для использования одной или нескольких служб, а также для предоставления URL-адреса для диалогового окна авторизации.
getIdentityToken() String Получает токен удостоверения OpenID Connect для эффективного пользователя, если предоставлена ​​область openid .
getInstallationSource() InstallationSource Возвращает значение перечисления, указывающее, как скрипт был установлен в качестве дополнения для текущего пользователя (например, установил ли пользователь его лично через Интернет-магазин Chrome или администратор домена установил его для всех пользователей).
getOAuthToken() String Получает токен доступа OAuth 2.0 для эффективного пользователя.
getProjectTriggers() Trigger[] Получает все устанавливаемые триггеры, связанные с текущим проектом и текущим пользователем.
getScriptId() String Получает уникальный идентификатор проекта сценария.
getService() Service Получает объект, используемый для управления публикацией сценария в виде веб-приложения.
getUserTriggers(document) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данном документе, только для этого скрипта или надстройки.
getUserTriggers(form) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю, в заданной форме, только для этого скрипта или надстройки.
getUserTriggers(spreadsheet) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данной электронной таблице, только для этого скрипта или надстройки.
invalidateAuth() void Делает недействительными полномочия эффективного пользователя для выполнения текущего сценария.
newStateToken() StateTokenBuilder Создает построитель для токена состояния, который можно использовать в API обратного вызова (например, в потоке OAuth).
newTrigger(functionName) TriggerBuilder Начинает процесс создания устанавливаемого триггера, который при срабатывании вызывает заданную функцию.

Подробная документация

deleteTrigger(trigger)

Удаляет данный триггер, чтобы он больше не работал.

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

Параметры

Имя Тип Описание
trigger Trigger Триггер для удаления.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

Получает объект, используемый для определения того, необходимо ли пользователю авторизовать этот сценарий для использования одной или нескольких служб, а также для предоставления URL-адреса для диалогового окна авторизации. Если скрипт опубликован как надстройка , использующая устанавливаемые триггеры , эта информация может использоваться для контроля доступа к участкам кода, для которых у пользователя нет необходимой авторизации. Альтернативно, надстройка может попросить пользователя открыть URL-адрес диалогового окна авторизации, чтобы решить проблему.

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

Параметры

Имя Тип Описание
authMode AuthMode режим авторизации, для которого запрашивается информация авторизации; почти во всех случаях значение authMode должно быть ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL) , поскольку ни один другой режим авторизации не требует, чтобы пользователи предоставляли авторизацию.

Возвращаться

AuthorizationInfo — объект, который может предоставить информацию о статусе авторизации пользователя.

getIdentityToken()

Получает токен удостоверения OpenID Connect для эффективного пользователя, если предоставлена ​​область openid . Эта область не включена по умолчанию, и для ее запроса необходимо добавить ее как явную область в файл манифеста. Включите области https://www.googleapis.com/auth/userinfo.email или https://www.googleapis.com/auth/userinfo.profile , чтобы вернуть дополнительную информацию о пользователе в токене.

Возвращенный токен идентификатора представляет собой закодированный веб-токен JSON (JWT) , и его необходимо декодировать, чтобы извлечь из него информацию. В следующих примерах показано, как декодировать токен и извлечь эффективный идентификатор профиля Google пользователя.

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
Полный список возвращаемых полей (утверждений) см. в документации OpenID Connect .

Возвращаться

String — токен идентификации, если он доступен; в противном случае null .

getInstallationSource()

Возвращает значение перечисления, указывающее, как скрипт был установлен в качестве дополнения для текущего пользователя (например, установил ли пользователь его лично через Интернет-магазин Chrome или администратор домена установил его для всех пользователей).

Возвращаться

InstallationSource — источник установки.

getOAuthToken()

Получает токен доступа OAuth 2.0 для эффективного пользователя. Если области OAuth сценария достаточны для авторизации другого API Google, которому обычно требуется собственный поток OAuth (например, Google Picker ), сценарии могут обойти второй запрос авторизации, передав вместо этого этот токен. Срок действия токена истекает через некоторое время (минимум несколько минут); сценарии должны обрабатывать ошибки авторизации и вызывать этот метод для получения нового токена при необходимости.

Токен, возвращаемый этим методом, включает только те области, которые в данный момент необходимы сценарию. Области, которые были ранее авторизованы, но больше не используются сценарием, не включаются в возвращаемый токен. Если требуются дополнительные области OAuth помимо тех, которые требуются самому сценарию, их можно указать в файле манифеста сценария.

Возвращаться

String — строковое представление токена OAuth 2.0.

getProjectTriggers()

Получает все устанавливаемые триггеры, связанные с текущим проектом и текущим пользователем.

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

Возвращаться

Trigger[] — Массив триггеров текущего пользователя, связанных с этим проектом.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

Получает уникальный идентификатор проекта сценария. Это предпочтительный метод получения уникального идентификатора проекта скрипта, а не getProjectKey() . Этот идентификатор можно использовать везде, где ранее был указан ключ проекта.

Возвращаться

String — Идентификатор проекта скрипта.

getService()

Получает объект, используемый для управления публикацией сценария в виде веб-приложения.

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

Возвращаться

Service — объект, используемый для наблюдения и управления публикацией сценария в виде веб-приложения.

getUserTriggers(document)

Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данном документе, только для этого скрипта или надстройки. Этот метод нельзя использовать для просмотра триггеров, прикрепленных к другим сценариям.

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

Параметры

Имя Тип Описание
document Document Файл Google Docs, который может содержать устанавливаемые триггеры.

Возвращаться

Trigger[] — Массив триггеров, принадлежащих этому пользователю в данном документе.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

Получает все устанавливаемые триггеры, принадлежащие этому пользователю, в заданной форме, только для этого скрипта или надстройки. Этот метод нельзя использовать для просмотра триггеров, прикрепленных к другим сценариям.

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

Параметры

Имя Тип Описание
form Form Файл Google Forms, который может содержать устанавливаемые триггеры.

Возвращаться

Trigger[] — Массив триггеров, принадлежащих этому пользователю в заданной форме.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данной электронной таблице, только для этого скрипта или надстройки. Этот метод нельзя использовать для просмотра триггеров, прикрепленных к другим сценариям.

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

Параметры

Имя Тип Описание
spreadsheet Spreadsheet Файл Google Таблиц, который может содержать устанавливаемые триггеры.

Возвращаться

Trigger[] — Массив триггеров, принадлежащих этому пользователю в данной электронной таблице.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

Делает недействительными полномочия эффективного пользователя для выполнения текущего сценария. Используется для аннулирования любых разрешений для текущего сценария. Это особенно полезно для функций, помеченных как однократная авторизация. Поскольку функции однократной авторизации можно вызвать только при первом запуске после того, как сценарий получил авторизацию, если вы хотите выполнить какое-либо действие впоследствии, вы должны отозвать все авторизации, которые были у сценария, чтобы пользователь мог снова увидеть диалоговое окно авторизации.

ScriptApp.invalidateAuth();

Броски

Error — когда недействительность не удалась

newStateToken()

Создает построитель для токена состояния, который можно использовать в API обратного вызова (например, в потоке OAuth). 

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

В большинстве потоков OAuth2 токен state передается конечной точке авторизации напрямую (а не как часть URL-адреса обратного вызова), а конечная точка авторизации затем передает его как часть URL-адреса обратного вызова.

Например:

  • Скрипт перенаправляет пользователя на URL-адрес авторизации OAuth2: https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters .
  • Пользователь нажимает «Авторизовать», и страница авторизации OAuth2 перенаправляет пользователя обратно на https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants .
  • Приведенное выше перенаправление (обратно на http://script.google.com/... ) вызывает запрос браузера к /usercallback , который вызывает метод, указанный StateTokenBuilder.withMethod(method) .

Возвращаться

StateTokenBuilder — объект, используемый для продолжения процесса создания токена состояния.

newTrigger(functionName)

Начинает процесс создания устанавливаемого триггера, который при срабатывании вызывает заданную функцию. 

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

Параметры

Имя Тип Описание
functionName String Функция, вызываемая при срабатывании триггера. Вы можете использовать функции из включенных библиотек, например Library.libFunction1 .

Возвращаться

TriggerBuilder — объект, используемый для продолжения процесса создания триггера.

Авторизация

Скрипты, использующие этот метод, требуют авторизации с одной или несколькими из следующих областей :

  • https://www.googleapis.com/auth/script.scriptapp

Устаревшие методы