Расширенные службы 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
только в том случае, если расширенная служба не обеспечивает необходимую вам функциональность.
Требования
Прежде чем вы сможете использовать расширенную услугу, вы должны удовлетворить следующие требования:
- Вам необходимо включить расширенную службу в проекте сценария.
Вы должны убедиться, что API, соответствующий расширенному сервису, включен в проекте Cloud Platform (GCP), который использует ваш скрипт.
Если в вашем проекте скрипта используется проект GCP по умолчанию, созданный 8 апреля 2019 года или после этой даты, API включается автоматически после включения расширенной службы и сохранения проекта скрипта. Если вы еще этого не сделали, вас также могут попросить принять Условия использования Google Cloud и Google API .
Если ваш проект скрипта использует стандартный проект GCP или более старый проект GCP по умолчанию, вам необходимо вручную включить соответствующий API расширенной службы в проекте GCP. Чтобы внести это изменение, у вас должен быть доступ к редактированию проекта GCP.
Дополнительную информацию см. в разделе «Проекты облачной платформы» .
Включить расширенные услуги
Чтобы использовать расширенный сервис Google, следуйте этим инструкциям:
- Откройте проект Apps Script.
- Слева нажмите редактора» .
- Слева рядом с пунктом «Услуги» нажмите услугу» .
- Выберите расширенную службу Google и нажмите «Добавить» .
После включения расширенной службы она станет доступна в режиме автозаполнения.
Как определяются сигнатуры методов
Расширенные службы обычно используют те же объекты, имена методов и параметры, что и соответствующие общедоступные API, хотя сигнатуры методов транслируются для использования в Apps Script. Функция автозаполнения редактора скриптов обычно предоставляет достаточно информации для начала работы, но приведенные ниже правила объясняют, как Apps Script генерирует сигнатуру метода из общедоступного API Google.
Запросы к API Google могут принимать различные типы данных, включая параметры пути, параметры запроса, тело запроса и/или вложение для загрузки мультимедиа. Некоторые расширенные службы также могут принимать определенные заголовки HTTP-запросов (например, расширенная служба «Календарь» ).
Соответствующая сигнатура метода в Google Apps Script имеет следующие аргументы:
- Тело запроса (обычно ресурс) в виде объекта JavaScript.
- Путь или обязательные параметры в качестве отдельных аргументов.
- Вложение для загрузки мультимедиа в качестве аргумента
Blob
. - Необязательные параметры в виде объектов JavaScript, сопоставляющих имена параметров со значениями.
- Заголовки HTTP-запросов в виде объектов JavaScript, сопоставляющих имена заголовков со значениями заголовков.
Если метод не содержит элементов в данной категории, эта часть подписи опускается.
Есть некоторые особые исключения, о которых следует знать:
- Для методов, которые принимают загрузку мультимедиа, параметр
uploadType
устанавливается автоматически. - Методы, называемые
delete
в Google API, называютсяremove
в Apps Script, посколькуdelete
— это зарезервированное слово в JavaScript. - Если расширенная служба настроена на прием заголовков HTTP-запросов и вы установили объект JavaScript заголовков запросов, вам также необходимо установить объект JavaScript необязательных параметров (пустой объект, если вы не используете необязательные параметры).
Поддержка расширенных услуг
Расширенные сервисы — это всего лишь тонкие оболочки, позволяющие использовать API Google в Apps Script. Таким образом, любая проблема, возникающая при их использовании, обычно связана с базовым API, а не с самим скриптом приложений.
Если вы столкнулись с проблемой при использовании расширенной службы, о ней следует сообщить, используя инструкции поддержки для базового API. Ссылки на эти инструкции по поддержке приведены в каждом расширенном руководстве по обслуживанию в разделе « Справочник по сценариям приложений».