Class ScriptApp

Приложение-скрипт

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

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

Свойство Тип Описание
Auth Mode Auth Mode Перечисление, определяющее, какие категории авторизованных служб Apps Script может выполнять с помощью триггерной функции.
Authorization Status Authorization Status Перечисление, обозначающее статус авторизации сценария.
Event Type Event Type Перечисление, обозначающее тип инициируемого события.
Installation Source Installation Source Перечисление, обозначающее, как скрипт был установлен пользователю в качестве дополнения.
Trigger Source Trigger Source Перечисление, обозначающее источник события, вызывающего срабатывание триггера.
Week Day Weekday Перечисление, представляющее дни недели.

Методы

Метод Тип возврата Краткое описание
delete Trigger(trigger) void Удаляет данный триггер, чтобы он больше не работал.
get Authorization Info(authMode) Authorization Info Получает объект, используемый для определения того, необходимо ли пользователю авторизовать этот сценарий для использования одной или нескольких служб, а также для предоставления URL-адреса для диалогового окна авторизации.
get Identity Token() String Получает токен удостоверения Open ID Connect для эффективного пользователя, если предоставлена ​​область openid .
get Installation Source() Installation Source Возвращает значение перечисления, указывающее, как скрипт был установлен в качестве надстройки для текущего пользователя (например, установил ли пользователь его лично через Интернет-магазин Chrome или администратор домена установил его для всех пользователей).
get OAuth Token() String Получает токен доступа OAuth 2.0 для эффективного пользователя.
get Project Triggers() Trigger[] Получает все устанавливаемые триггеры, связанные с текущим проектом и текущим пользователем.
get Script Id() String Получает уникальный идентификатор проекта сценария.
get Service() Service Получает объект, используемый для управления публикацией сценария в виде веб-приложения.
get User Triggers(document) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данном документе, только для этого скрипта или надстройки.
get User Triggers(form) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю, в заданной форме, только для этого скрипта или надстройки.
get User Triggers(spreadsheet) Trigger[] Получает все устанавливаемые триггеры, принадлежащие этому пользователю в данной электронной таблице, только для этого скрипта или надстройки.
invalidate Auth() void Делает недействительными полномочия эффективного пользователя для выполнения текущего сценария.
new State Token() State Token Builder Создает построитель для токена состояния, который можно использовать в API обратного вызова (например, в потоке OAuth).
new Trigger(functionName) Trigger Builder Начинает процесс создания устанавливаемого триггера, который при срабатывании вызывает заданную функцию.

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

delete Trigger(trigger)

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

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

Параметры

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

Авторизация

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

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

get Authorization Info(authMode)

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

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

Параметры

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

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

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


get Identity Token()

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

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

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);
Полный список возвращаемых полей (утверждений) см. в документации Open ID Connect .

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

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


get Installation Source()

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

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

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


get OAuth Token()

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

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

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

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


get Project Triggers()

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

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

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

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

Авторизация

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

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

get Script Id()

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

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

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


get Service()

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

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

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

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


get User Triggers(document)

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

const doc = DocumentApp.getActiveDocument();
const 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

get User Triggers(form)

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

const form = FormApp.getActiveForm();
const 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

get User Triggers(spreadsheet)

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

const ss = SpreadsheetApp.getActiveSpreadsheet();
const 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

invalidate Auth()

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

ScriptApp.invalidateAuth();

Броски

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


new State Token()

Создает построитель для токена состояния, который можно использовать в 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.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const 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 , который вызывает метод, указанный State Token Builder.withMethod(method) .

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

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


new Trigger(functionName)

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

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

Параметры

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

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

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

Авторизация

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

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

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