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

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

Чтобы узнать, какие API Google доступны в качестве расширенных сервисов, найдите раздел «Расширенные сервисы Google» в справочнике . Если вы хотите использовать API Google, недоступный в качестве расширенного сервиса, просто подключитесь к нему, как к любому другому внешнему API .

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

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

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

Используя метод UrlFetch для прямого доступа к API , вы фактически обращаетесь к API Google как к внешнему API . Этот метод позволяет использовать все функции API. Однако он требует от вас самостоятельной авторизации API. Также необходимо создать все необходимые заголовки и проанализировать ответы API.

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

Требования

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

  1. Вам необходимо включить расширенную службу в вашем проекте скрипта.

  2. Необходимо убедиться, что API, соответствующий расширенной услуге, включен в проекте Cloud Platform (GCP), который использует ваш скрипт.

    Если ваш проект скрипта использует проект GCP по умолчанию, созданный 8 апреля 2019 года или позднее, API будет включен автоматически после включения расширенного сервиса и сохранения проекта скрипта. Если вы ещё этого не сделали, вам также может быть предложено принять Условия использования Google Cloud и API Google .

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

Более подробную информацию см. в разделе «Проекты облачной платформы» .

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

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

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

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

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

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

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

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

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

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

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

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

Поддержка расширенных услуг

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

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