Эта страница переведена с помощью Cloud Translation API.

Расширенные сервисы Google

Расширенные сервисы в Apps Script позволяют подключаться к некоторым общедоступным API Google с меньшими затратами на настройку, чем при использовании их HTTP-интерфейсов. Расширенные сервисы представляют собой тонкие оболочки вокруг этих API Google. Они работают во многом так же, как встроенные сервисы Apps Script — например, предлагают автозаполнение, а Apps Script автоматически обрабатывает процесс авторизации . Однако перед использованием расширенного сервиса в скрипте его необходимо включить .

Включить расширенные сервисы

Чтобы воспользоваться расширенными сервисами Google, следуйте этим инструкциям:

Шаг 1: Включите расширенные функции.

Включить расширенную службу можно с помощью редактора Apps Script или путем редактирования манифеста.

Метод А: Использование редактора

Откройте проект Apps Script.
Слева нажмите «Редактор .
Слева, рядом с пунктом «Услуги» , нажмите « услугу» .
Выберите расширенный сервис Google и нажмите «Добавить» .

Метод Б: Использование манифеста

Вы можете включить расширенные сервисы, отредактировав файл манифеста . Например, чтобы включить расширенный сервис Google Drive, добавьте поле enabledAdvancedServices в объект dependencies :

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

После включения расширенной услуги она становится доступна в функции автозаполнения.

Шаг 2: Включите API Google Cloud (только для стандартных проектов Google Cloud).

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

Если вы используете стандартный проект Google Cloud , вам также необходимо вручную включить API, соответствующий расширенной службе. Чтобы включить API вручную:

Откройте проект Cloud, связанный с вашим скриптом, в **консоли Google Cloud**.
В верхней части консоли щелкните в строке поиска и введите часть названия API (например, "Calendar"), затем щелкните по названию, как только оно появится.
Нажмите «Включить API» .
Закройте консоль Google Cloud и вернитесь в редактор скриптов.

Как определяются сигнатуры методов

Расширенные сервисы, как правило, используют те же объекты, имена методов и параметры, что и соответствующие общедоступные API, хотя сигнатуры методов переводятся для использования в Apps Script. Функция автозаполнения в редакторе скриптов обычно предоставляет достаточно информации для начала работы, но следующие правила объясняют, как Apps Script генерирует сигнатуру метода из общедоступного API Google.

Запросы к API Google могут принимать различные типы данных, включая параметры пути, параметры запроса, тело запроса или вложение для загрузки медиафайлов. Некоторые расширенные сервисы также могут принимать определенные заголовки HTTP-запросов (например, расширенный сервис «Календарь »).

Соответствующая сигнатура метода в Google Apps Script имеет следующие аргументы:

Тело запроса (обычно ресурс) в виде объекта JavaScript.
Путь или обязательные параметры, в виде отдельных аргументов. Если метод требует несколько параметров пути, они отображаются в том порядке, в котором они перечислены в URL-адресе конечной точки API.
Вложение медиафайла в виде аргумента типа Blob .
Необязательные параметры (обычно параметры запроса), представленные в виде объекта JavaScript, сопоставляющего имена параметров со значениями.
Заголовки HTTP-запросов, представленные в виде объекта JavaScript, сопоставляющего имена заголовков со значениями заголовков.

Если метод не содержит элементов в данной категории, эта часть сигнатуры опускается.

Следует учитывать некоторые особые исключения:

Для методов, принимающих загрузку медиафайлов, параметр uploadType устанавливается автоматически.
Методы, названные delete в Google API, в Apps Script называются remove , поскольку delete — зарезервированное слово в JavaScript.
Если расширенная служба настроена на прием заголовков HTTP-запросов, и вы задаете объект JavaScript для заголовков запроса, то вам также необходимо задать объект JavaScript для необязательных параметров (пустой объект, если вы не используете необязательные параметры).

Пример: Calendar.Events.insert

Предположим, вы хотите создать событие в календаре . В документации Google Calendar API показана соответствующая структура HTTP-запроса:

HTTP-метод : POST
URL запроса : https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
Тело запроса : ресурс события .
Параметры запроса : sendUpdates , supportsAttachments и т. д.

В Apps Script сигнатура метода определяется путем изменения порядка этих входных данных:

Тело события : Ресурс события (объект JavaScript).
Путь : Идентификатор calendarId (строка).
Необязательные параметры : Параметры запроса (объект JavaScript).

В результате вызов метода будет выглядеть следующим образом:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

Расширенные сервисы или HTTP?

Каждый из расширенных сервисов Google связан с общедоступным API Google. В Apps Script вы можете получить доступ к этим API, используя расширенные сервисы или выполняя запросы к API напрямую с помощью UrlFetch .

При использовании расширенного метода авторизации Apps Script обрабатывает процесс авторизации и поддерживает автозаполнение. Однако перед использованием расширенного метода необходимо его включить .

Если вы используете метод UrlFetch для прямого доступа к API , вы, по сути, рассматриваете API Google как внешний API . При этом методе можно использовать все возможности API. Однако это требует от вас обработки авторизации API.

В следующей таблице приведено сравнение двух методов:

Особенность	Расширенное обслуживание	UrlFetch (HTTP)
Авторизация	Обрабатывается автоматически	Требуется ручная погрузка/разгрузка.
Автозаполнение	Доступный	Нет в наличии
Область применения	Возможно, это подмножество API.	Полный доступ ко всем функциям API.
Сложность	Полегче	Более сложный вариант (требует формирования заголовков и анализа ответов).

Сравнение кода

Приведенные примеры кода демонстрируют разницу в сложности создания события календаря с использованием расширенного сервиса и с использованием UrlFetchApp .

Расширенное обслуживание:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

Мы рекомендуем по возможности использовать расширенный сервис и применять метод UrlFetch только в том случае, если расширенный сервис недоступен или не предоставляет необходимую вам функциональность.

Поддержка расширенных сервисов

Поскольку расширенные сервисы представляют собой лишь тонкие оболочки над API Google, любые проблемы, возникающие при их использовании, обычно связаны с самим API, а не с Apps Script.

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