Создание дополнений для Google Workspace

На этой странице представлен обзор процесса проектирования, создания и публикации дополнений для Google Workspace. В обзоре описаны следующие шаги:

1. Определите приложения Google Workspace, в которых вы хотите, чтобы ваше дополнение было доступно пользователям.
2. Настройте проекты вашего дополнения, выберите владельца и соавторов.
3. Разработайте и настройте внешний вид и поведение вашего дополнения.
4. Создайте дополнение.
5. Проверьте области действия OAuth вашего дополнения.
6. Протестируйте дополнение в одном или нескольких приложениях Google Workspace.
7. Опубликуйте дополнение.

Вы можете создать дополнение с помощью Apps Script или HTTP. Для сравнения посмотрите видео "Apps Script против HTTP-конечных точек: что выбрать? 🤔".

Выберите приложения для размещения в Google Workspace.

Вы можете настроить отображение надстроек Google Workspace в следующих приложениях Google Workspace:

• Гмайл
• Календарь Google
• Google Чат
• Google Документы
• Google Диск
• Google Meet
• Google Таблицы
• Google Слайды

Чтобы узнать, как создавать приложения для Google Workspace, см. раздел «Расширение пользовательского интерфейса Google Workspace» .

Настройте проекты вашего дополнения, выберите владельца и соавторов.

Если вы разрабатываете дополнение на Apps Script, вам нужно создать как проект Apps Script, так и проект Google Cloud. Если же вы разрабатываете дополнение на языке, отличном от Apps Script, вам достаточно создать только проект Google Cloud.

Перед началом разработки дополнений выберите одну учетную запись пользователя, которая будет владеть проектами, и определите, какие другие учетные записи будут участвовать в разработке. Владелец проектов создает и управляет файлами проекта и связанными с ними настройками, а участники разработки могут помогать с кодированием и тестированием.

Внимание: Если вы не добавляете соавторов в свои проекты дополнений, крайне важно передать права собственности на них до того, как учетная запись владельца будет закрыта или удалена. В противном случае вы можете полностью потерять доступ к коду и настройкам дополнения.

Проекты Apps Script

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

Вы можете разместить файлы проекта Apps Script для своего дополнения на общем диске , чтобы ни одна учетная запись не имела единоличного владения. Размещение файла скрипта дополнения на общем диске гарантирует, что несколько соавторов будут иметь доступ к проекту скрипта.

При публикации дополнения в качестве издателя выступает одна учетная запись пользователя. У этой учетной записи должны быть права на редактирование проекта скрипта, но она не обязательно должна быть его владельцем.

Чтобы создать проект Apps Script, см. раздел «Проекты Script» .

Проекты Google Cloud

Мы рекомендуем добавить соавторов в облачный проект дополнения . Это поможет гарантировать, что кто-то из вашей команды всегда сможет получить доступ к облачным настройкам дополнения.

Чтобы создать проект Google Cloud, см. раздел «Создание проекта Google Cloud» .

Разработайте и настройте внешний вид и поведение вашего дополнения.

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

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

Для получения рекомендаций по разработке пользовательского интерфейса вашего дополнения обратитесь к руководству по стилю для дополнений Google Workspace .

Настройте манифест дополнения.

После разработки дополнения вы можете приступить к его реализации в манифесте дополнения. В манифесте вы настраиваете большую часть внешнего вида и поведения дополнения, включая хост-приложения Google Workspace, которые расширяет это дополнение.

Подробности см. в разделе «Манифесты для дополнения Google Workspace» .

По мере добавления кода и функций в ваше дополнение, редактируйте манифест по мере необходимости, чтобы получить требуемый внешний вид и поведение дополнения.

Настройка внешнего вида и поведения приложения Google Chat.

Если вы разработали дополнение, расширяющее функциональность Google Chat, вам необходимо использовать API Google Chat для настройки внешнего вида и поведения приложения Chat. Инструкции см. в разделе «Настройка приложения Google Chat» .

Создайте дополнение

Для дополнения необходимо реализовать интерфейс на основе карточек. Используйте службу Card из Apps Script или, если вы пишете на другом языке программирования, возвращайте правильно отформатированный JSON, чтобы интерфейс отображался в виде карточек.

Также необходимо реализовать все функции-триггеры, указанные в манифесте дополнения. Если ваше дополнение подключается к стороннему сервису, не принадлежащему Google, с использованием OAuth, необходимо также настроить OAuth для этого сервиса .

Карты конструирования

Пользовательский интерфейс дополнения определяется путем создания объектов Card и заполнения их виджетами . Функции-триггеры, указанные в вашем манифесте, должны возвращать либо один объект Card , либо массив объектов Card , представляющих различные «страницы» интерфейса дополнения. Ваше дополнение также может создавать и отображать новые карточки в ответ на действия пользователя.

В Apps Script карточки создаются с помощью класса CardBuilder . Каждая карточка требует наличия CardHeader и одного или нескольких CardSections . Каждый раздел карточки следует заполнить отдельными виджетами, составляющими интерфейс дополнения. Виджеты взаимодействия обычно связаны с действиями для определения их поведения при взаимодействии.

После того, как вы добавили все разделы и виджеты на свою карточку с помощью CardBuilder , необходимо вызвать CardBuilder.build() для создания соответствующего объекта Card .

Примечание: Невызов метода build() после использования классов-конструкторов в службе Card приводит к ошибкам типов. Например, функции-триггеры должны возвращать объекты Card . Возврат объектов CardBuilder вместо этого приводит к ошибке.

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

Если вашему дополнению требуется доступ к API, не относящимся к Google, и использующим OAuth, необходимо настроить и подключиться к соответствующей службе — подробности см. в руководстве «Подключение к сервисам, не относящимся к Google» .

Заказ на строительство

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

1. Создайте виджет.
2. Добавьте виджет в раздел карточек.
3. Повторяйте эти действия, пока в разделе карточек не появятся все необходимые виджеты.
4. Добавьте раздел с карточкой к самой карточке.

Это необходимо, потому что при добавлении виджета в карточку или раздел карточки вы фактически добавляете копию этого виджета. Любые изменения, внесенные в объект виджета после его добавления, не будут отражены в итоговой карточке.

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

Универсальные действия

Для обеспечения контекстно-независимой функциональности можно использовать универсальные действия . Универсальные действия — это пункты меню, доступные в пользовательском интерфейсе дополнения независимо от того, какая карточка отображается. Все определенные универсальные действия всегда отображаются в карточном меню дополнения.

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

Проверьте области действия OAuth для дополнения.

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

В проектах дополнений явно задавайте области видимости (scopes) , чтобы гарантировать использование дополнения минимально допустимого набора областей видимости. Какие области видимости использует ваше дополнение, вы определяете в манифесте дополнения.

Более подробную информацию см. в разделе «Области применения» .

Протестируйте дополнение.

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

Чтобы начать тестирование дополнения, ознакомьтесь со следующими руководствами:

• Тестирование и отладка надстроек Google Workspace на Apps Script
• Тестирование и отладка HTTP-дополнений Google Workspace
• Протестируйте интерактивные функции приложений Google Chat.

Опубликуйте дополнение

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

Дополнения для Google Workspace публикуются в Google Workspace Marketplace . Общедоступные дополнения должны пройти проверку приложения перед публикацией.

Дополнительные сведения см. в описании дополнения «Публикация в Google Workspace» .