Как преобразовать приложение Google Chat в дополнение Google Workspace

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

После преобразования приложение Google Chat сможет использовать фреймворк дополнений Google Workspace, что откроет новые возможности для интеграции и функций в Google Chat и других сервисах Google Workspace. Например, вы можете распространять одно дополнение Google Workspace через Google Workspace Marketplace, которое расширяет приложения Chat вместе с другими размещаемыми приложениями Google Workspace, такими как Gmail, Календарь и Документы.

Ограничения

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

Шаг 1. Скопируйте код существующего приложения Google Chat

Для преобразования требуется изменить код. Чтобы не повлиять на работу приложения Google Chat, создайте копию кода и работайте с ней.

Apps Script

  1. Откройте существующий проект скрипта Google Apps для приложения Google Chat.
  2. Слева нажмите Обзор .
  3. Справа нажмите Создать копию .
  4. В левой части экрана нажмите Настройки проекта .
  5. В разделе Проект Google Cloud нажмите Изменить проект.
  6. Введите тот же номер проекта, который связан с существующим проектом приложения Google Chat.
  7. Нажмите Настроить проект.

HTTP

Создайте ответвление или копию существующей базы кода и разверните ее как новый сервис, отдельный от вашего действующего приложения Google Chat.

Если ваше приложение развернуто в Google Cloud и использует функции, связанные с проектом Google Cloud (например, идентификатор App Engine по умолчанию), новый код следует развернуть в сервисе, связанном с существующим проектом приложения Google Chat.

Шаг 2. Измените скопированный код

Дополнения Google Workspace, расширяющие возможности Google Chat, используют структуры запросов и ответов, отличные от структур приложений Chat, которые не являются дополнениями. Вам нужно обновить код, чтобы использовать объекты событий дополнений Google Workspace (EventObject) вместо событий взаимодействия Google Chat API (Event) для запросов и ответов. Чтобы изменить код, следуйте инструкциям из руководства по преобразованию кода.

Шаг 3. Включите конфигурацию дополнения Google Workspace для тестовых пользователей

Чтобы настроить дополнение Google Workspace для приложения Google Chat, используйте консоль Google Cloud:

  1. Откройте страницу конфигурации Google Chat API в консоли Google Cloud.

    Перейти на страницу конфигурации Google Chat API

  2. В разделе Интерактивные функции включите параметр Включить интерактивные функции.

  3. В разделе Преобразовать в дополнение Google Workspace нажмите Преобразовать в дополнение.

  4. Включите параметр Включить настройки конфигурации дополнений.

  5. В разделе Видимость добавьте адреса электронной почты тестовых пользователей.

  6. При необходимости обновите настройки подключения, указав URL конечной точки развертывания или идентификатор развертывания Apps Script скопированного и измененного кода приложения Google Chat из шага 2.

  7. Нажмите Сохранить и протестировать.

Шаг 4. Протестируйте преобразованное приложение

Тщательно протестируйте дополнение Google Workspace, используя тестовые аккаунты, настроенные на шаге 3. Проверьте все функции и взаимодействия.

Шаг 5. Завершите преобразование для всех пользователей

Убедившись, что преобразованное дополнение Google Workspace работает правильно, вы можете сделать его доступным для всех пользователей.

  1. Откройте страницу конфигурации Google Chat API в консоли Google Cloud.

    Перейти на страницу конфигурации Google Chat API

  2. В разделе Интерактивные функции нажмите Преобразовать в дополнение. Откроется боковая панель.

  3. На боковой панели нажмите Преобразовать в дополнение.

  4. Введите идентификатор проекта и нажмите Преобразовать.

Ваше приложение Google Chat теперь является дополнением Google Workspace, которое расширяет возможности Google Chat.

Необязательно: удалите или освободите неиспользуемые ресурсы Google Cloud

Если вы преобразовали приложение Google Chat в дополнение Google Workspace, чтобы избежать расходов на ресурсы Google Cloud, которые использовались приложением Google Chat и больше не нужны, вы можете отключить их.

Руководство по преобразованию кода

В этом разделе описано, как формат взаимодействия с Google Chat API Event сопоставляется с форматом дополнения Google Workspace EventObject.

Запрос на сопоставление

В таблице ниже показано, как поля в Google Chat API Event для приложения Chat, которое не является дополнением, сопоставляются с соответствующими полями в дополнении Google Workspace EventObject.

Приложение Chat, которое не является дополнением (поле Event) Поле EventObject дополнения Google Workspace Примечания
action.actionMethodName Н/Д Для взаимодействия с картой название метода можно передать в качестве параметра в commonEventObject.parameters. Подробнее о том, как открыть диалоговое окно…
action.parameters commonEventObject.parameters
appCommandMetadata chat.appCommandPayload.appCommandMetadata
common commonEventObject
configCompleteRedirectUrl
  • chat.appCommandPayload.configCompleteRedirectUri
  • chat.addedToSpacePayload.configCompleteRedirectUri
  • chat.messagePayload.configCompleteRedirectUri
 Доступно в разных полезных нагрузках в зависимости от типа события.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Доступно в разных полезных нагрузках в зависимости от типа события.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Доступно в разных полезных нагрузках в зависимости от типа события.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Доступно в разных полезных нагрузках в зависимости от типа события.
space
  • chat.messagePayload.space
  • chat.addedToSpacePayload.space
  • chat.removedFromSpacePayload.space
  • chat.buttonClickedPayload.space
  • chat.widgetUpdatedPayload.space
  • chat.appCommandPayload.space
thread
  • chat.messagePayload.message.thread
  • chat.buttonClickedPayload.message.thread
  • chat.appCommandPayload.message.thread
 Доступно в разных полезных нагрузках в зависимости от типа события.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Доступно в разных полезных нагрузках в зависимости от типа события.
token Н/Д Проверка выполняется иначе. Подробнее о запросе на проверку для приложений HTTP…
type Н/Д Тип события можно определить по триггеру.
user chat.user

Запрос сопоставления по варианту использования

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

История успеха Приложение Chat, которое не является дополнением (Event Payload) Полезная нагрузка дополнения Google Workspace EventObject
Приложение добавлено в чат-группу 
{
  "type": "ADDED_TO_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... }
    }
  }
}
Удалить приложение из чат-группы 
{
  "type": "REMOVED_FROM_SPACE",
  "space": { ... }
}
 
{
  "chat": {
    "removedFromSpacePayload": {
      "space": { ... }
    }
  }
}
Пользователь @упоминает приложение 
{
  "type": "MESSAGE",
  "message": { ... },
  "space": { ... },
  "configCompleteRedirectUrl": "..."
}
 
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... },
      "configCompleteRedirectUri": "..."
    }
  }
}
Пользователь упоминает приложение через символ @, чтобы добавить его в чат-группу. Вам нужно обработать один запрос от Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { ... }
}
 Вам нужно обработать два запроса от Google Chat.

Первый запрос:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Второй запрос:
{
  "chat": {
    "messagePayload": {
      "message": { ... },
      "space": { ... }
    }
  }
}
Слеш-команда 
{
  "type": "MESSAGE",
  "message": { "slashCommand": { ... } },
  "space": { ... }
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Слеш-команда для добавления приложения в чат-группу Вам нужно обработать один запрос от Google Chat:
{
  "type": "ADDED_TO_SPACE",
  "space": { ... },
  "message": { "slashCommand": { ... } }
}
 Вам нужно обработать два запроса от Google Chat.

Первый запрос:
{
  "chat": {
    "addedToSpacePayload": {
      "space": { ... },
      "interactionAdd": true
    }
  }
}

Второй запрос:
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Пользователь нажимает кнопку на карточке или в диалоговом окне. 
{
  "type": "CARD_CLICKED",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}

Для событий диалогового окна common.formInputs содержит значения виджета. Пример Google Apps Script:

{
  "type": "CARD_CLICKED",
  "common": {
   "formInputs": {
    "contactName": {
      "": { "stringInputs": { "value": ["Kai 0"] }}
    }
  }
  },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": true,
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "..."
    }
  }
}

Для событий диалогового окна commonEventObject.formInputs содержит значения виджета. Пример Google Apps Script:

{
  "commonEventObject": {
     "formInputs": {
      "contactName": {
        "stringInputs": {
          "value": ["Kai 0"]
        }
      }
    }
  },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "true",
      "dialogEventType": "..."
    }
  }
}
Пользователь отправляет информацию с карточки приложения на главном экране 
{
  "type": "SUBMIT_FORM",
  "common": { ... },
  "space": { ... },
  "message": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "buttonClickedPayload": {
      "message": { ... },
      "space": { ... },
      "isDialogEvent": "...",
      "dialogEventType": "SUBMIT_DIALOG"
    }
  }
}
Пользователь вызывает команду приложения с помощью быстрой команды 
{
  "type": "APP_COMMAND",
  "space": { ... },
  "isDialogEvent": "...",
  "dialogEventType": "..."
}
 
{
  "chat": {
    "appCommandPayload": {
      "message": { ... },
      "space": { ... },
      "appCommandMetadata": { ... }
    }
  }
}
Предпросмотр ссылки 
{
  "type": "MESSAGE",
  "message": {
    "matchedUrl": "..."
  },
  "space": { ... }
}
 
{
  "chat": {
    "messagePayload": {
      "message": {
        "matchedUrl": "..."
      },
      "space": { ... }
    }
  }
}
Пользователь обновляет виджет в карточке сообщения или диалоговом окне 
{
  "type": "WIDGET_UPDATED",
  "space": { ... },
  "common": { ... }
}
 
{
  "commonEventObject": { ... },
  "chat": {
    "widgetUpdatedPayload": {
      "space": { ... }
    }
  }
}

Сопоставление ответов по вариантам использования

Дополнения Google Workspace, расширяющие возможности Google Chat, возвращают действия вместо объекта Message. В таблице ниже приведены типы ответов API Google Chat Message для приложения Chat, которое не является дополнением, и их эквиваленты в действиях дополнения Google Workspace.

История успеха Приложение Chat, которое не является дополнением (Message Response) Ответ действия Chat дополнения Google Workspace
Создание сообщения в вызванной чат-группе 
{
  "actionResponse": {
    "type": "NEW_MESSAGE"
  },
  "text": "..."
}

actionResponse указывать необязательно. Подробнее о том, как отвечать на слеш-команды…

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Подробнее о том, как ответить на сообщение…
Как изменить сообщение 
{
 "actionResponse": {
  "type": "UPDATE_MESSAGE"
  },
 "text": "..."
}

Подробнее о том, как изменить сообщение…

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": {
          "text": "..."
         }
       }
    }
  }
}

Подробнее о том, как изменить сообщение…
Предпросмотр ссылки 
{
  "actionResponse": {
    "type": "UPDATE_USER_MESSAGE_CARDS"
  },
  "cardsV2": [{ ... }]
}

Подробнее о предварительном просмотре ссылок…

 
{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateInlinePreviewAction": {
        "cardsV2": [{ ... }]
      }
    }
  }
}

Подробнее о предварительном просмотре ссылок…
Как открыть диалоговое окно 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "dialog": {
        "body": { /* Card object */ }
      }
    }
  }
}

Подробнее о том, как открыть интерактивные диалоговые окна…

 
{
  "action": {
    "navigations": [{
      "pushCard": { /* Card object */ }
     }]
   }
}
Карточка, которую вы добавляете, может содержать виджеты с действиями onClick. Для дополнений Google Workspace, использующих HTTP, настройте следующие действия для вызова конечной точки функции: 
{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "clickedButton",
        "value": "submit"
      }]
    }
  }
}

Подробнее о том, как открыть интерактивные диалоговые окна…
Как закрыть диалоговое окно 
{
  "actionResponse": {
    "type": "DIALOG",
    "dialogAction": {
      "actionStatus": {
        "userFacingMessage": "..."
      }
    }
  }
}

Подробнее о том, как закрыть диалоговое окно…

 
{
  "action": {
    "navigations": [{
      "endNavigation": "CLOSE_DIALOG"
    }],
    "notification": { "text": "..."}
  }
}

Подробнее о том, как закрыть диалоговое окно…
Как подключиться к внешней системе (запрос конфигурации) 
{
  "actionResponse": {
    "type": "REQUEST_CONFIG",
    "url": "..."
  }
}

Подробнее о том, как подключиться к внешней системе (приложения Chat, не являющиеся дополнениями)…

 
{
  "basic_authorization_prompt": {
    "authorization_url": "...",
    "resource": "..."
  }
}

Подробнее о том, как подключить приложение Chat к другим сервисам и инструментам…
Автозаполнение элементов в интерактивных виджетах 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

Подробнее о том, как добавить меню с возможностью выбора нескольких вариантов…

 
{
  "action": {
    "modifyOperations": [{
      "updateWidget": {
        "widgetId": "widget_id",
        "selectionInputWidgetSuggestions": {
          "suggestions": ["..."]
        }
      }
    }]
  }
}

Подробнее о том, как читать данные, введенные пользователями в формы на карточках…

Обрабатывать взаимодействия с карточками в сообщениях, созданных до конверсии

При преобразовании приложения Chat, работающего по протоколу HTTP и не являющегося дополнением, в дополнение Google Workspace для обработки взаимодействий с карточками в сообщениях, созданных до преобразования, требуется специальный подход. В дополнениях используется полный URL с протоколом HTTP для action.function карточки, а в приложениях Chat, не являющихся дополнениями, – название функции. В таблице ниже приведены основные различия между этими двумя типами данных.

Приложение Chat, которое не является дополнением Дополнение Google Workspace, расширяющее возможности Google Chat
Настройка Вы настраиваете одну конечную точку для всех событий в консоли Google Cloud. При реализации взаимодействий с подсказками в action подсказки указывается только название функции, которую нужно выполнить. Общая конечная точка HTTP вызывается для событий клика по карточке.

Подробнее о том, как открыть интерактивные диалоговые окна…



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 Вы можете настроить конечные точки для каждого события в консоли Google Cloud, но это не относится к событиям кликов по карточкам. При реализации взаимодействия с карточками поле action должно содержать полный URL конечной точки HTTP, которую нужно вызвать. Вы можете задать уникальную конечную точку HTTP для каждой кнопки или использовать общую конечную точку и передавать действие в качестве параметра в action.parameters.

Подробнее о том, как открыть интерактивные диалоговые окна…



{
  "onClick": {
    "action": {
      "function": "https://...",
      "parameters": [{
        "key": "method",
        "value": "submit"
      }]
    }
  }
}

Чтобы карточки в сообщениях, созданных до конверсии, работали корректно, настройте URL взаимодействия с карточкой на странице конфигурации Google Chat API.

Этот URL используется только для взаимодействий с сообщениями, созданными до того, как вы преобразовали приложение. Когда пользователь взаимодействует с одним из таких сообщений, исходное значение action.function передается как параметр __action_method_name__.

Пример: клик по подсказке

Если вы настроили URL взаимодействия с карточкой как https://.../card-interaction-handler и пользователь нажимает на карточку в письме с историей, выполняя следующее действие:

{
  "onClick": {
    "action": {
     "function": "submit"
    }
  }
}

Событие отправляется на настроенный URL взаимодействия с карточкой в следующем формате:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "submit"
    }
  },
  "chat": {
    "buttonClickedPayload": { ... }
  }
}

Пример: меню с возможностью выбора нескольких вариантов

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

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "externalDataSource": {
      "function": "getContacts"
    }
  }
}

Событие отправляется на настроенный URL взаимодействия с карточкой в следующем формате:

{
  "commonEventObject": {
    "parameters": {
      "__action_method_name__": "getContacts",
    }
  },
  "chat": {
    "widgetUpdatedPayload": { ... }
  }
}

Если вы включите параметр Использовать общий URL конечной точки HTTP для всех триггеров для триггеров HTTP, общий URL также будет использоваться для событий Нажатие кнопки.

Как проверять запросы для дополнений Google Workspace на основе HTTP, которые расширяют возможности Chat

Для приложений Google Chat на основе HTTP логику проверки того, что запросы поступают от Google, необходимо обновить при преобразовании в дополнение Google Workspace.

Основные различия в проверке запросов:

Категория приложения Поддерживаемые аудитории Адрес электронной почты сервисного аккаунта
Приложение Chat, которое не является дополнением Номер проекта chat@system.gserviceaccount.com
Дополнение Google Workspace, расширяющее возможности Google Chat Только конечная точка HTTP Адрес электронной почты сервисного аккаунта для проекта

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

Чтобы подтвердить запросы в обновленном дополнении Google Workspace:

  1. Если вы используете функции Cloud Run, предоставьте сервисному аккаунту дополнения роль roles/cloudfunctions.invoker. Подробнее об авторизации доступа с помощью IAM…
  2. Обновите код подтверждения токена, чтобы использовать адрес электронной почты сервисного аккаунта дополнения Google Workspace для проверки подписи токена на предъявителя. Подробнее о том, как проверить запросы от Google…