Method: scripts.run

Запускает функцию в проекте Apps Script. Проект сценария должен быть развернут для использования с Apps Script API, а вызывающее приложение должно использовать тот же проект Cloud Platform.

Этот метод требует авторизации с помощью токена OAuth 2.0, который включает хотя бы одну из областей, перечисленных в разделе «Авторизация» ; проекты сценариев, не требующие авторизации, не могут быть выполнены через этот API. Чтобы найти правильные области для включения в токен аутентификации, откройте страницу обзора проекта скрипта и прокрутите вниз до «Области действия OAuth проекта».

Ошибка 403, PERMISSION_DENIED: The caller does not have permission указывает на то, что проект Cloud Platform, используемый для авторизации запроса, не совпадает с проектом, используемым сценарием.

HTTP-запрос

POST https://script.googleapis.com/v1/scripts/{scriptId}:run

URL-адрес использует синтаксис транскодирования gRPC .

Параметры пути

Параметры
scriptId

string

Идентификатор сценария, который будет выполнен. Найдите идентификатор сценария на странице настроек проекта в разделе «Идентификаторы».

Тело запроса

Тело запроса содержит данные следующей структуры:

JSON-представление 
{
  "function": string,
  "parameters": [
    value
  ],
  "sessionState": string,
  "devMode": boolean
}
Поля
function

string

Имя функции, которую нужно выполнить в данном скрипте. Имя не содержит скобок и параметров. Он может ссылаться на функцию во включенной библиотеке, например Library.libFunction1 .

parameters[]

value ( Value format)

Параметры, которые будут переданы в выполняемую функцию. Тип объекта для каждого параметра должен соответствовать ожидаемому типу в Apps Script. Параметры не могут быть типами объектов, специфичными для Apps Script (например, Document или Calendar ); они могут быть только примитивными типами, такими как string , number , array , object или boolean . Необязательный.

sessionState

string

Устарело . Только для использования с надстройками Android. Идентификатор, представляющий текущий сеанс пользователя в приложении Android для Документов или Таблиц Google, включенный в качестве дополнительных данных в намерение , запускающее надстройку. Когда надстройка Android запускается с состоянием сеанса, она получает привилегии привязанного сценария, то есть может получать доступ к такой информации, как текущая позиция курсора пользователя (в Документах) или выбранная ячейка (в Таблицах). Чтобы получить состояние, вызовите Intent.getStringExtra("com.google.android.apps.docs.addons.SessionState") . Необязательный.

devMode

boolean

Если true и пользователь является владельцем сценария, сценарий запускается в последней сохраненной версии, а не в версии, развернутой для использования с API Apps Script. Необязательный; по умолчанию — false .

Тело ответа

В случае успеха тело ответа содержит данные следующей структуры:

Представление выполнения функции Apps Script, начатой ​​с помощью run . Ответ на выполнение не приходит до тех пор, пока функция не завершит выполнение. Максимальное время выполнения указано в руководстве по квотам Apps Script .

После начала выполнения оно может иметь один из четырех результатов:

  • Если функция скрипта завершает работу успешно, поле response содержит объект ExecutionResponse с возвращаемым значением функции в поле result объекта.
  • Если функция скрипта (или сам скрипт Apps) выдает исключение, поле error содержит объект Status . Поле details объекта Status содержит массив с одним объектом ExecutionError , который предоставляет информацию о характере ошибки.
  • Если выполнение еще не завершено, поле done имеет false и поля response и поля error отсутствуют.
  • Если сам вызов run завершается неудачей (например, из-за неправильного запроса или ошибки авторизации), метод возвращает код ответа HTTP в диапазоне 4XX с другим форматом тела ответа. Клиентские библиотеки автоматически преобразуют ответ 4XX в класс исключения.

JSON-представление 
{
  "done": boolean,

  // Union field result can be only one of the following:
  "error": {
    object (Status)
  },
  "response": {
    "@type": string,
    field1: ...,
    ...
  }
  // End of list of possible types for union field result.
}
Поля
done

boolean

В этом поле указывается, завершено ли выполнение сценария. Завершенное выполнение имеет заполненное поле response , содержащее ExecutionResponse от выполненной функции.

result поля объединения. Результат операции, который может быть либо error , либо допустимым response . Если done == false , ни error , ни response не устанавливаются. Если done == true , может быть установлен ровно один из error или response . Некоторые службы могут не предоставить результат. result может быть только одним из следующих:
error

object ( Status )

Если вызов run завершается успешно, но функция скрипта (или сам скрипт приложения) выдает исключение, это поле содержит объект Status . Поле details объекта Status содержит массив с одним объектом ExecutionError , который предоставляет информацию о характере ошибки.

response

object

Если функция скрипта завершает работу успешно, это поле содержит объект ExecutionResponse с возвращаемым значением функции.

Объект, содержащий поля произвольного типа. Дополнительное поле "@type" содержит URI, идентифицирующий тип. Пример: { "id": 1234, "@type": "types.example.com/standard/id" } .

Области авторизации

Требуется одна из следующих областей OAuth:

  • https://apps-apis.google.com/a/feeds
  • https://apps-apis.google.com/a/feeds/alias/
  • https://apps-apis.google.com/a/feeds/groups/
  • https://mail.google.com/
  • https://sites.google.com/feeds
  • https://www.google.com/calendar/feeds
  • https://www.google.com/m8/feeds
  • https://www.googleapis.com/auth/admin.directory.group
  • https://www.googleapis.com/auth/admin.directory.user
  • https://www.googleapis.com/auth/documents
  • https://www.googleapis.com/auth/documents.currentonly
  • https://www.googleapis.com/auth/drive
  • https://www.googleapis.com/auth/dynamiccreatives
  • https://www.googleapis.com/auth/forms
  • https://www.googleapis.com/auth/forms.currentonly
  • https://www.googleapis.com/auth/groups
  • https://www.googleapis.com/auth/script.cpanel
  • https://www.googleapis.com/auth/script.external_request
  • https://www.googleapis.com/auth/script.scriptapp
  • https://www.googleapis.com/auth/script.send_mail
  • https://www.googleapis.com/auth/script.storage
  • https://www.googleapis.com/auth/script.webapp.deploy
  • https://www.googleapis.com/auth/spreadsheets
  • https://www.googleapis.com/auth/spreadsheets.currentonly
  • https://www.googleapis.com/auth/sqlservice
  • https://www.googleapis.com/auth/userinfo.email

Дополнительную информацию см. в обзоре OAuth 2.0 .

Статус

Если вызов run завершается успешно, но функция скрипта (или сам скрипт Apps) выдает исключение, поле error тела ответа содержит этот объект Status .

JSON-представление 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Поля
code

integer

Код состояния. Для этого API это значение либо:

  • 10, что указывает на ошибку SCRIPT_TIMEOUT ,
  • 3, что указывает на ошибку INVALID_ARGUMENT , или
  • 1, что указывает на CANCELLED выполнение.

message

string

Сообщение об ошибке для разработчика на английском языке. Любое сообщение об ошибке, обращенное к пользователю, локализуется и отправляется в поле details или локализуется клиентом.

details[]

object

Массив, содержащий один объект ExecutionError , предоставляющий информацию о характере ошибки.

Объект, содержащий поля произвольного типа. Дополнительное поле "@type" содержит URI, идентифицирующий тип. Пример: { "id": 1234, "@type": "types.example.com/standard/id" } .