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

Если вы хотите создать новое дополнение Google Workspace, следуйте следующей общей процедуре:

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

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

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

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

Проекты скриптов приложений

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

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

Чтобы создать проект Apps Script, см. раздел Проекты сценариев .

Google Cloud-проекты

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

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

Создайте внешний вид и поведение вашего дополнения.

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

Инструкции по созданию пользовательского интерфейса надстройки приведены в руководстве по стилю надстройки Google Workspace .

Настройка манифеста проекта надстройки

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

Подробную информацию о том, как настроить манифест надстройки в Apps Script, см. в разделе Манифесты .

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

Закодируйте дополнение

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

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

Создание карт

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

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

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

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

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

Порядок строительства

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

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

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

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

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

Дополнительные сведения см. в разделе Универсальные действия .

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

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

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

Дополнительные сведения см. в разделе Области действия .

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

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

Дополнительную информацию см. в разделе «Тестирование надстроек Google Workspace» .

Опубликовать дополнение

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

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

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

,

Если вы хотите создать новое дополнение Google Workspace, следуйте следующей общей процедуре:

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

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

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

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

Проекты скриптов приложений

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

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

Чтобы создать проект Apps Script, см. раздел Проекты сценариев .

Google Cloud-проекты

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

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

Создайте внешний вид и поведение вашего дополнения.

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

Инструкции по созданию пользовательского интерфейса надстройки приведены в руководстве по стилю надстройки Google Workspace .

Настройка манифеста проекта надстройки

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

Подробную информацию о том, как настроить манифест надстройки в Apps Script, см. в разделе Манифесты .

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

Закодируйте дополнение

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

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

Создание карт

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

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

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

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

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

Порядок строительства

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

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

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

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

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

Дополнительные сведения см. в разделе Универсальные действия .

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

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

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

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

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

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

Дополнительные сведения см. в разделе «Тестирование надстроек Google Workspace» .

Опубликовать дополнение

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

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

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