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

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

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

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

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

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

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

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

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

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

Вы можете включить расширенные службы, отредактировав файл манифеста . Например, чтобы включить расширенную службу Google Диска, добавьте поле 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 (например, «Календарь»), затем щелкните имя, как только оно появится.
Нажмите Включить API .
Закройте консоль Google Cloud и вернитесь в редактор скриптов.

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

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

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

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

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

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

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

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

Пример: Календарь.События.вставка

Предположим, вы хотите создать событие в Календаре . В документации по API Календаря Google показана соответствующая структура 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 , вы фактически обращаетесь к Google API как к внешнему 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.