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

If you've built and published a Google Chat app that uses Google Chat API interaction events, like one based on the Google Chat app quickstart , this page shows how to convert it to a Google Workspace add-on that extends Google Chat.

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

Ограничения

Before starting the conversion, review the Limitations of Google Workspace add-ons that extend Google Chat to ensure your Google Chat app can be converted without losing essential functionality.

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

The conversion process requires code changes. To avoid affecting your live Google Chat app, create and work on a copy of your code.

Apps Script

  1. Open your existing Google Chat app Google Apps Script project.
  2. Слева нажмите «Обзорная .
  3. Справа нажмите «Создать копию содержимого .
  4. В левой части экрана нажмите проекта» .
  5. Under Google Cloud project , click Change project .
  6. Enter the same project number associated with your existing Google Chat app project.
  7. Нажмите «Установить проект» .

HTTP

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

If your app is deployed on Google Cloud and relies on features tied to the Google Cloud project (for example, the default App Engine identity), the new code should be deployed on a service associated with the existing Google Chat app project.

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

Google Workspace add-ons that extend Google Chat use different request and response structures compared to Google Chat apps built with Chat API interaction events. You need to update your code to use the Google Workspace add-on EventObject instead of the Google Chat API's Event for requests and responses. Use the Code conversion guide to modify your code.

Step 3: Enable the Google Workspace add-on configuration for test users

Use the Google Cloud console to configure the Google Workspace add-on settings for your Google Chat app:

  1. Go to the Google Chat API configuration page in the Google Cloud console.

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

  2. Under Interactive Features , turn on Enable Interactive features .

  3. Under Convert to Google Workspace add-on , click Convert to add-on .

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

  5. In the Visibility section, add the email addresses of your test users.

  6. If necessary, update Connection Settings with the deployment endpoint URL or Apps Script deployment ID of your copied and modified Google Chat app code from Step 2.

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

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

Test the Google Workspace add-on functionality thoroughly using the test user accounts configured in Step 3. Verify all features and interactions.

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

After you've verified that the converted Google Workspace add-on works correctly, you can make it available to all users.

  1. Go to the Google Chat API configuration page in the Google Cloud console.

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

  2. Under Interactive Features , click Convert to add-on . A side panel opens.

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

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

Your Google Chat app is now a Google Workspace add-on that extends Google Chat.

Optional: Clean up or free unused Google Cloud resources

Optionally, after converting your Google Chat app to an Google Workspace add-on, to avoid incurring charges to your Google Cloud account for the resources used by the Google Chat app that are no longer in use, consider turning them off.

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

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

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

The following table shows how fields in the Google Chat API Event map to the corresponding fields in the Google Workspace add-on EventObject .

Поле 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
 Available in different payloads depending on the event type.
dialogEventType
  • chat.appCommandPayload.dialogEventType
  • chat.buttonClickedPayload.dialogEventType
 Available in different payloads depending on the event type.
eventTime chat.eventTime
isDialogEvent
  • chat.appCommandPayload.isDialogEvent
  • chat.buttonClickedPayload.isDialogEvent
 Доступны различные варианты полезной нагрузки в зависимости от типа мероприятия.
message
  • chat.messagePayload.message
  • chat.buttonClickedPayload.message
  • chat.appCommandPayload.message
 Available in different payloads depending on the event type.
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
 Available in different payloads depending on the event type.
threadKey
  • chat.messagePayload.message.thread.threadKey
  • chat.buttonClickedPayload.message.thread.threadKey
  • chat.appCommandPayload.message.threadKey
 Доступны различные варианты полезной нагрузки в зависимости от типа мероприятия.
token Н/Д Verification is handled differently, see Request Verification for HTTP Apps .
type Н/Д Тип события можно определить по триггеру .
user chat.user

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

The following table shows the differences in request payloads for common use cases between Google Chat apps built with Chat API interaction events and Google Workspace add-ons that extend 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 add-ons that extend Google Chat return actions instead of a Message object. The following table maps Google Chat API Message response types to their Google Workspace add-on action equivalents.

Вариант использования Ответ 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» .

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

When you convert an HTTP Google Chat app to a Google Workspace add-on, card interactions on messages created before the conversion require special handling. add-ons use a full HTTP URL for a card's action.function , while Chat apps built with Google Chat API interaction events use a function name. The following table summarizes these differences.

Приложение Google Chat, созданное с использованием событий взаимодействия Google Chat API. Дополнение Google Workspace, расширяющее возможности Google Chat.
Конфигурация You configure a single endpoint for all events in the Google Cloud console. When implementing card interactions, a card's action only contains the name of the function to execute. The common HTTP endpoint is invoked for card click events.

Для получения дополнительной информации см. раздел «Открыть диалог (Чат)» . 



{
  "onClick": {
    "action": {
      "function": "submit"
    }
  }
}
 You can optionally configure per-event endpoints in the Google Cloud console, but this doesn't include card click events. When implementing card interactions, a card's action must contain the full URL of the HTTP endpoint to invoke. You can set a unique HTTP endpoint per button, or use a common endpoint and pass the action as a parameter in action.parameters .

Для получения дополнительной информации см. раздел «Открыть диалоговое окно (дополнения)» . 



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

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

This URL is only used for interactions on messages created before you converted your app. When a user interacts with one of these messages, the original action.function value is passed as a parameter called __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-конечная точка Адрес электронной почты для учетной записи сервиса по каждому проекту

The unique service account email for your Google Workspace add-on can be found in the Convert to Google Workspace add-ons section on the Google Chat API configuration page in the Google Cloud console.

Для проверки запросов в обновленном дополнении Google Workspace:

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