Расширенные сервисы 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 и Google API .

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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