Method: scripts.run

Запускает функцию в проекте Apps Script. Проект скрипта должен быть развёрнут для использования с API Apps Script, а вызывающее приложение должно использовать тот же проект 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/{deploymentId}:run

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

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

Параметры
deploymentId

string

Идентификатор развертывания исполняемого файла API. Найдите идентификатор развертывания в разделе «Развертывание» > «Управление развертываниями» в редакторе скриптов.

Текст запроса

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

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 Docs или Sheets, включённый в качестве дополнительных данных в намерение , запускающее надстройку. Когда надстройка Android запускается с состоянием сеанса, она получает привилегии связанного скрипта, то есть может получать доступ к такой информации, как текущее положение курсора пользователя (в Docs) или выбранная ячейка (в Sheets). Чтобы получить состояние, вызовите 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 выполнен успешно, но функция скрипта (или сам скрипт Apps) выдаёт исключение, это поле содержит объект 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" } .