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