Преобразуйте интерактивное приложение Google Chat в дополнение к Google Workspace

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

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

Ограничения

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

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

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

Apps Script

  1. Откройте существующий проект Google Apps Script для вашего приложения 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, используют иные структуры запросов и ответов по сравнению с приложениями Google Chat, созданными с использованием событий взаимодействия Chat API. Вам необходимо обновить свой код, чтобы использовать EventObject дополнения Google Workspace вместо Event API Google Chat для запросов и ответов. Воспользуйтесь руководством по преобразованию кода , чтобы изменить свой код.

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

Используйте консоль Google Cloud для настройки параметров надстройки Google Workspace для вашего приложения Google Chat:

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

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

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

  3. Включить параметры конфигурации дополнения .

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

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

  6. Нажмите «Сохранить и проверить» .

Шаг 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, которые больше не используются, рекомендуется отключить их.

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

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

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

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

Поле Event взаимодействия с Google Chat API Поле 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

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

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

Вариант использования Событие взаимодействия с API чата. Полезная нагрузка Event Дополнение Google Workspace EventObject Payload
Приложение добавлено в космос 
{
  "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 . В следующей таблице приведено соответствие типов ответов Message API Google Chat их эквивалентам в дополнениях Google Workspace.

Вариант использования Ответ Message API чата Google Дополнение 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 . Для HTTP-дополнений Google Workspace настройте эти действия для вызова конечной точки функции:
{
  "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": "..."
  }
}

Для получения более подробной информации см. раздел «Подключение к внешней системе» . 

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

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

Автозаполнение элементов в интерактивных виджетах 
{
  "actionResponse": {
    "type": "UPDATE_WIDGET",
    "updatedWidget": {
      "suggestions": {
        "items": ["..."]
      },
      "widget": "widget_id"
    }
  }
}

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

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

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

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

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

Приложение Google Chat, созданное с использованием событий взаимодействия Google Chat API. Дополнение 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-адрес будет также использоваться для событий нажатия кнопки .

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

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

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

Тип приложения Поддерживаемая аудитория Адрес электронной почты учетной записи службы поддержки
Приложение Google Chat, созданное с использованием событий взаимодействия Google Chat API. Номер проекта 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. Обновите код подтверждения токена, чтобы для проверки подписи токена Bearer использовался адрес электронной почты учетной записи службы надстройки Google Workspace. См. раздел «Проверка запросов от Google» .