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

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

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

Ограничения

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

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

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

Скрипт приложений

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

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

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

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

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

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

  3. Enable Turn on add-on configuration settings .

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

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

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

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

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

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

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

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

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

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

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

  4. Введите идентификатор вашего проекта и нажмите «Конвертировать» .

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

Дополнительно: очистите или освободите неиспользуемые ресурсы Google Cloud.

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

Руководство по перекодировке кодов

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

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

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

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

{
  "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: 

{
  "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 Google Chat API сопоставляются с их эквивалентами действий в дополнениях 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"
    }
  }
}

To learn more, see Add a multiselect menu . 

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

Более подробную информацию см. в статье Сбор и обработка информации от пользователей Google Chat .

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

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

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

Этот 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, необходимо обновить при преобразовании в дополнение Google Workspace.

Ключевые отличия в проверке запросов:

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

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

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

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