Как настроить Google Chat API

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

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

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

Требования

Выберите отображаемое название, аватар и описание для приложения Chat.

При включении Chat API вы настраиваете сведения о приложении Chat, которые будут видны пользователям в Chat, в том числе отображаемое название, аватар и описание. Эти сведения видны только в Chat. Чтобы опубликовать приложение Chat в Marketplace, необходимо также указать сведения, которые будут показываться на странице приложения в Marketplace.

Прежде чем настраивать приложение Chat, подготовьте следующую информацию:

Поле Описание Формат
Название приложения Отображаемое название приложения Chat. До 25 букв и цифр.
URL аватара Изображение, которое будет использоваться в качестве аватара приложения Chat. URL по HTTPS, указывающий на квадратное изображение в формате PNG или JPEG. Рекомендуемый размер – 256 x 256 пикселей или больше.
Описание Краткое описание приложения Chat, которое показывается, когда пользователи ищут приложения в Chat. До 40 букв и цифр.
Подробное описание Необязательное поле. Описание возможностей приложения Chat, которое показывается, когда пользователи начинают чат с приложением Chat или открывают главную страницу сеансов для агента. В настоящее время поддерживается только при обновлении конфигурации приложения с помощью консоли Google Cloud и не поддерживается через Google Workspace Add-ons API. Не более 250 символов.

Название, аватар и описание приложения Chat показываются пользователям в интерфейсе Chat. Для некоторых запросов на запись Chat API использует эту информацию, чтобы атрибутировать действия, которые приложение для Chat выполняет в Chat.

Например, если вы вызываете метод spaces.create(), Chat включает название приложения Chat в описание того, кто создал чат-группу, как показано на следующем изображении:

Приложение Google Chat создает чат-группу для пользователя.
Рисунок 1. Сообщение об авторстве, которое Chat показывает, когда для создания чат-группы от имени пользователя используется метод spaces.create().

При взаимодействии с приложениями Chat пользователи также видят или используют эту информацию следующим образом:

  • Чтобы добавить приложение Chat в чат-группу или отправить ему сообщение, упомяните его с помощью символа @.
  • Найдите приложение Chat и начните с ним прямую переписку. В меню Приложения для прямых переписок показывается название и аватар приложения Chat.
  • В поле чата пользователи могут просматривать приложения Chat, их названия, аватары и описания.

Как настроить приложение Chat в консоли Google Cloud

Когда у вас будут сведения о приложении Chat, откройте облачный проект и настройте Chat API:

  1. В консоли Google Cloud перейдите на страницу Chat API и нажмите Configuration (Конфигурация).

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

  2. В разделе Сведения о приложении заполните поля Название приложения, URL аватара и Описание.

  3. При необходимости заполните поле Подробное описание.

  4. Необязательно. В меню Синтаксис разметки выберите синтаксис разметки по умолчанию (Markdown или Chat) для сообщений приложения Chat. Подробнее о форматировании текста и о том, как Chat определяет синтаксис разметки для запросов к API…

  5. В разделе Интерактивные функции укажите, должно ли приложение Chat реагировать на действия пользователей:

    Чтобы создать интерактивное приложение Chat, включите параметр Включить интерактивные функции и выполните следующие действия:

    1. В разделе Функциональность:
      • При необходимости выберите Поддерживать главную страницу приложения, чтобы показывать карточку главной страницы на вкладке Главная в прямой переписке с приложением Chat.
      • Выберите Присоединяться к чат-группам и групповым чатам, чтобы приложение Chat можно было установить и использовать. По умолчанию пользователи могут устанавливать приложения Chat и обмениваться с ними сообщениями в чат-группе, созданной для пользователя и приложения. Пользователи также могут добавлять приложения Chat в чат-группы с несколькими участниками и взаимодействовать с ними.
    2. В разделе Настройки подключения выберите архитектуру, которую вы хотите использовать для получения объектов событий из Chat:

      • Чтобы использовать HTTP-сервис, выберите URL конечной точки HTTP и укажите URL.
      • Чтобы использовать проект Google Apps Script, выберите Apps Script и укажите идентификатор развертывания для проекта.
      • Чтобы использовать агент Dialogflow, выберите Dialogflow, а затем Dialogflow CX или Dialogflow ES и укажите название ресурса агента.
      • Чтобы использовать Pub/Sub, выберите Cloud Pub/Sub и введите название темы.
    3. Чтобы направлять объекты событий в определенные конечные точки или функции, перейдите в раздел Настройки подключения > Триггеры и укажите или обновите конечные точки или функции обратного вызова для следующих триггеров Chat:

      • Главная страница приложения (если включен параметр Поддержка главной страницы приложения). Пользователь открывает вкладку Главная в прямой переписке с приложением Chat.
      • Добавлено в чат-группу. Пользователь добавляет приложение Chat в групповой чат или чат-группу или устанавливает приложение Chat для прямой переписки.
      • Сообщение. Пользователь отправляет сообщение приложению Chat. Например, пользователь отправляет прямое сообщение приложению Chat или упоминает его через @в чат-группе с несколькими участниками.
      • Удалено из чат-группы. Пользователь удаляет приложение Chat из чат-группы.
      • Команда приложения. Пользователь вызывает быструю команду, слеш-команду или действие с сообщением из приложения Chat.
    4. При необходимости добавьте другие интерактивные функции, например сеансы, варианты запросов, команды (быстрые команды, слеш-команды и действия с сообщениями) или предварительный просмотр ссылок.

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

      • Чтобы установить и протестировать приложение самостоятельно, укажите свой адрес электронной почты.
      • Чтобы предоставить доступ к внутреннему приложению для Chat команде или всей организации, не публикуя его в Marketplace, укажите одну или несколько групп Google. В группах нет ограничений на количество участников. Если ваше приложение запрашивает chat.app.* области действия, вам все равно нужно опубликовать приложение, чтобы получить одобрение администратора.
      • Если администратор разрешает устанавливать из Marketplace только приложения из белого списка, в консоли Google Cloud в этом поле можно указать не более пяти адресов электронной почты пользователей для разработки. Видимость для группы применяется только после того, как администратор добавит приложение в белый список.
  6. При необходимости в разделе Журналы установите флажок Записывать ошибки в журнал, чтобы использовать Google Cloud Logging. Подробнее о запросах к журналам ошибок в приложениях для Chat…

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

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

Как настроить приложение Chat с помощью Google Cloud CLI

Вместо консоли Google Cloud вы можете просматривать и обновлять конфигурацию приложения Chat из командной строки с помощью Google Cloud CLI (gcloud CLI). Например, вы можете настроить приложение Chat из скрипта или хранить его конфигурацию в файле, который вы храните вместе со своим кодом.

Группа команд gcloud beta workspace-add-ons chat-app-config содержит следующие команды:

  • describe – показывает конфигурацию.
  • update – настраивает приложение Chat в первый раз или изменяет его конфигурацию.

В командах используется ресурс chatAppConfig в Google Workspace Add-ons API.

Подготовка

  1. Установите gcloud CLI. Если вы установили gcloud CLI ранее, убедитесь, что у вас последняя версия, выполнив команду gcloud components update.
  2. Войдите в gcloud CLI, используя свой аккаунт пользователя. Команды не поддерживают сервисные аккаунты.

    gcloud auth login
  3. Установите облачный проект приложения Chat в качестве проекта по умолчанию для gcloud CLI. Используйте идентификатор проекта, так как команды не принимают номер проекта.

    gcloud config set project PROJECT_ID

    или добавляйте флаг --project к каждой команде.

  4. Включите Google Workspace Add-ons API в облачном проекте:

    gcloud services enable gsuiteaddons.googleapis.com
  5. Убедитесь, что у вас есть следующие роли Identity and Access Management (IAM) в облачном проекте:

    • Разработчик дополнений Google Workspace (roles/gsuiteaddons.developer), чтобы просматривать и обновлять конфигурацию, или Читатель дополнений Google Workspace (roles/gsuiteaddons.reader), чтобы только просматривать ее. Эти роли включают разрешения, перечисленные в разделе Предварительные требования и аутентификация.
    • Пользователь Service Usage (roles/serviceusage.serviceUsageConsumer). gcloud CLI использует облачный проект в качестве проекта квоты для своих запросов, для чего требуется разрешение serviceusage.services.use.

    У владельца и редактора есть все эти разрешения. Ролей Владелец приложений Chat и Читатель приложений Chat, которые дают доступ к странице конфигурации в консоли Google Cloud, недостаточно.

Как посмотреть конфигурацию

Чтобы посмотреть конфигурацию приложения Chat, выполните команду describe:

gcloud beta workspace-add-ons chat-app-config describe

Выходные данные будут выглядеть примерно так:

avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
description: Helps manage tasks and schedules
displayName: Cymbal Assistant
errorLoggingEnabled: true
interactiveFeatureConfig:
  allowlistedTestingPrincipals:
  - user@example.com
  appCommands:
  - command: /help
    commandId: 1
    commandType: SLASH_COMMAND
    description: Show available commands
  connectionConfig:
    httpEndpointConfig:
      commonUrl: https://example.com/chat
  supportsMultiuserSpaces: true
  urlPatterns:
  - hostPattern: example.com
    pathPrefix: tasks/
name: projects/123456789012/chatAppConfig
state: ACTIVE

Если в облачном проекте ещё нет приложения Chat, команда выполняется успешно и выводит только поле name конфигурации:

name: projects/123456789012/chatAppConfig

Чтобы изменить выходные данные, добавьте один из следующих флагов:

  • --format=json – выводит конфигурацию в формате JSON.
  • --view=basic – не включает настройки интерактивных функций (interactiveFeatureConfig).
  • --format="value(displayName)" – выводит только отображаемое название или пустую строку, если в облачном проекте ещё нет приложения Chat. У настроенного приложения Chat всегда есть отображаемое название, поэтому вы можете использовать этот флаг в скрипте, чтобы проверить, существует ли приложение Chat.

Обновите конфигурацию

Чтобы настроить приложение Chat в первый раз или изменить его конфигурацию, выполните команду update. Укажите настройки с помощью флагов или в файле конфигурации. Их нельзя объединить в одной команде.

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

Как использовать пометки

В примере ниже настраивается приложение Chat, которое получает события в конечной точке HTTP:

gcloud beta workspace-add-ons chat-app-config update \
    --display-name="Quickstart App" \
    --description="Quickstart app" \
    --avatar-uri=https://developers.google.com/workspace/chat/images/quickstart-app-avatar.png \
    --http-endpoint-url=HTTP_ENDPOINT_URL \
    --supports-multiuser-spaces \
    --add-allowlisted-testing-principals=USER_EMAIL \
    --error-logging-enabled

Замените следующее:

  • HTTP_ENDPOINT_URL – URL по HTTPS, который получает объекты событий из Chat.
  • USER_EMAIL – адрес электронной почты пользователя или группы в организации Google Workspace, у которых есть разрешение на установку и тестирование приложения Chat, например ваш собственный адрес электронной почты.

Команда выводит обновленную конфигурацию.

В таблице ниже перечислены флаги для настроек на странице Configuration (Конфигурация) Chat API в консоли Google Cloud. Подробную информацию о каждом флаге можно найти в справочнике по командам update.

Настройка в консоли Google Cloud Флаги
Название приложения --display-name
URL аватара --avatar-uri с URL по HTTPS изображения, которое соответствует требованиям к аватару, или --clear-avatar-uri, чтобы использовать аватар по умолчанию.
Описание --description
Статус приложения --state=active или --state=disabled
Синтаксис разметки --markup-syntax=markdown или --markup-syntax=chat
присоединяться к чат-группам и групповым чатам; --supports-multiuser-spaces или --no-supports-multiuser-spaces
Настройки подключения Возможны следующие варианты:
  • URL конечной точки HTTP: --http-endpoint-url
  • Apps Script: --apps-script-deployment-id
  • Cloud Pub/Sub: --pubsub-topic с темой в том же облачном проекте Cloud в формате projects/PROJECT_ID/topics/TOPIC_ID.
  • Dialogflow: --dialogflow-edition=es или --dialogflow-edition=cx, где --dialogflow-agent – название ресурса агента или среды, например projects/PROJECT_ID/locations/LOCATION/agents/AGENT_ID.
Доступ --add-allowlisted-testing-principals, --remove-allowlisted-testing-principals и --clear-allowlisted-testing-principals
Регистрировать ошибки в Logging --error-logging-enabled или --no-error-logging-enabled

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

Например, чтобы отключить приложение Chat, не меняя другие его настройки, выполните следующую команду: Чтобы включить его снова, используйте --state=active.

gcloud beta workspace-add-ons chat-app-config update --state=disabled

Использование файла конфигурации

Чтобы сохранить конфигурацию в файле или задать настройки, у которых нет флагов, передайте файл YAML или JSON команде update. В файле используются поля ресурса chatAppConfig, которые также выводятся командой describe.

  1. Создайте файл, содержащий настройки, которые нужно обновить. Например, создайте файл chat_app_config.yaml со следующим содержимым:

    displayName: Cymbal Assistant
    description: Helps manage tasks and schedules
    avatarUri: https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png
    state: ACTIVE
    errorLoggingEnabled: true
    interactiveFeatureConfig:
      supportsMultiuserSpaces: true
      connectionConfig:
        httpEndpointConfig:
          commonUrl: https://example.com/chat
      appCommands:
      - commandId: 1
        commandType: SLASH_COMMAND
        command: /help
        description: Show available commands
      urlPatterns:
      - hostPattern: example.com
        pathPrefix: tasks/
      allowlistedTestingPrincipals:
      - USER_EMAIL
    

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

  2. Выполните команду update с флагом --config-file:

    gcloud beta workspace-add-ons chat-app-config update \
        --config-file=chat_app_config.yaml

Чтобы начать с текущей конфигурации приложения Chat, сохраните выходные данные команды describe в файл:

gcloud beta workspace-add-ons chat-app-config describe > chat_app_config.yaml

Затем отредактируйте файл, удалите поля, которые не нужно менять, и передайте файл команде update. Если в файле есть настройка, которую команда не может обновить, команда не выполняется. Подробнее об ограничениях…

Команда update игнорирует поле name в файле. Он всегда обновляет облачный проект, заданный в gcloud CLI, поэтому вы можете использовать один и тот же файл для настройки приложения Chat в другом облачном проекте.

Как команда применяет изменения

  • Изменятся только указанные вами настройки. Если вы используете флаги, команда изменяет настройки для переданных флагов. При использовании файла конфигурации изменяются поля, которые находятся в файле, поэтому файл не должен содержать всю конфигурацию. Исключение составляют настройки подключения: заданный тип подключения заменяет текущий, а заданная версия Dialogflow заменяет всю конфигурацию Dialogflow.
  • Списки заменяются целиком. Если в файле есть поле appCommands, urlPatterns или allowlistedTestingPrincipals, список из файла заменит текущий список. Чтобы добавить или удалить отдельных тестировщиков, используйте флаги --add-allowlisted-testing-principals и --remove-allowlisted-testing-principals.
  • Пустое значение очищает настройку. Например, файл, содержащий urlPatterns: [] в разделе interactiveFeatureConfig, удаляет все шаблоны URL для предварительного просмотра ссылок.
  • Если команда не выполняется, ничего не меняется. Если значение недопустимо, команда выводит ошибку и оставляет конфигурацию без изменений.
  • Частота запросов ограничена. API ограничивает количество запросов на чтение и обновление в минуту для каждого облачного проекта и для каждой организации. Каждая команда update отправляет один запрос на обновление. Если вы добавляете или удаляете тестировщиков с помощью флагов, команда также отправляет запрос на чтение. Чтобы изменить несколько настроек, передайте их в одной команде или одном файле, а не выполняйте команду для каждой настройки.

Ограничения

  • Команды поддерживают только приложения Chat, созданные как дополнения Google Workspace.
  • Команды не поддерживают сервисные аккаунты и олицетворение сервисных аккаунтов. Вам нужно войти в gcloud CLI, используя аккаунт пользователя.
  • У облачного проекта есть одна конфигурация приложения Chat, и команды не могут ее удалить. Чтобы запретить пользователям использовать приложение Chat, отключите его или удалите облачный проект.
  • Обновление применяется к активному приложению Chat. У команд нет режима черновика или пробного запуска.
  • Если приложение Chat опубликовано или находится на проверке в Google Workspace Marketplace, команды не могут изменить его отображаемое название, аватар, описание, команды или шаблоны URL для предпросмотра ссылок.
  • Команды поддерживают настройки в ресурсе chatAppConfig. Чтобы настроить параметр, который не включен в ресурс, используйте консоль Google Cloud.

Устранение неполадок

Если команда не выполняется, найдите текст сообщения об ошибке в таблице ниже. Если сообщение начинается со статуса, например INVALID_ARGUMENT, значит Google Workspace Add-ons API отклонил запрос, а текст после статуса описывает проблему.

Сообщение об ошибке содержит Причина Решение
Invalid choice: 'chat-app-config' или Invalid choice: 'workspace-add-ons' Команда не содержит beta или в вашей версии gcloud CLI нет нужных команд. Начните команду с gcloud beta workspace-add-ons chat-app-config. Если ошибка не исчезнет, обновите gcloud CLI до последней версии.
PROJECT ID Проект задается номером проекта. Укажите идентификатор проекта.
Failed to parse value(s) in protobuf Файл конфигурации содержит поле, которое не распознается gcloud CLI. В сообщении об ошибке указывается название поля, с которым связана проблема. Сравните название поля с выходными данными команды describe. Если поле новое, обновите gcloud CLI до последней версии.
does not have permission to access projects instance API отклонил запрос. Причина указывается в тексте после этого сообщения. Например:
  • У вашего аккаунта нет необходимых ролей IAM. Если текст содержит Caller does not have required permission to use project, роль Service Usage Consumer отсутствует.
  • В облачном проекте не включен Google Workspace Add-ons API.
  • Вы вошли в сервисный аккаунт.
Ознакомьтесь с требованиями в разделе Подготовка.
INVALID_ARGUMENT Недопустимое значение. Например, отображаемое название должно содержать от 3 до 25 символов, а описание – от 1 до 40. Если в сообщении есть not found or deleted, значит идентификатор проекта указан неправильно. Исправьте значение, указанное в сообщении об ошибке, и запустите команду снова.
FAILED_PRECONDITION Приложение Chat не разрешает запрос. Например, оно не создано как дополнение Google Workspace или опубликовано в Google Workspace Marketplace и настройку нельзя изменить. Следуйте инструкциям в сообщении об ошибке. Чтобы настроить приложение Chat, которое не является дополнением Google Workspace, используйте консоль Google Cloud или преобразуйте его.
RESOURCE_EXHAUSTED или 429 API получил слишком много запросов для облачного проекта или организации за короткий промежуток времени. Подождите минуту и запустите команду снова.

Как настроить приложение Chat с помощью Google Workspace Add-ons API

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

chatAppConfig – это ресурс-одиночка, который всегда существует для каждого облачного проекта. До первого сохранения конфигурации ресурс содержит пустую конфигурацию (которую также возвращает метод GetChatAppConfig, если вы прочитаете ресурс до первого сохранения). Поскольку ресурс уже существует, вам не нужно создавать его отдельно. Используйте UpdateChatAppConfig, чтобы сохранить исходную конфигурацию и обновить существующую.

Предварительные требования и аутентификация

Прежде чем вызывать GetChatAppConfig или UpdateChatAppConfig, выполните следующие предварительные требования:

  1. Включите Google Workspace Add-ons API (gsuiteaddons.googleapis.com) в своем облачном проекте. При необходимости вы можете включить Google Chat API (chat.googleapis.com), чтобы просматривать или обновлять конфигурацию приложения Chat в консоли Google Cloud или вызывать Chat API.
  2. Выполните аутентификацию как пользователь с учетными данными OAuth 2.0, которые включают область действия https://www.googleapis.com/auth/cloud-platform. Аутентификация сервисного аккаунта не поддерживается для методов chatAppConfig.
  3. Убедитесь, что у аутентифицированного пользователя есть необходимые разрешения Identity and Access Management (IAM) в целевом облачном проекте:
    • gsuiteaddons.chatAppConfigs.get и chat.bots.get для чтения конфигурации (GetChatAppConfig).
    • gsuiteaddons.chatAppConfigs.update, chat.bots.update и chat.bots.get, чтобы обновить конфигурацию (UpdateChatAppConfig).
  4. Если вы используете клиентскую библиотеку, установите последнюю версию клиентской библиотеки Google Workspace Add-ons API для вашего языка. Список клиентских библиотек можно найти в справочнике по Google Workspace Add-ons API.

Как обновить конфигурацию приложения Chat

Чтобы настроить приложение Chat в первый раз или обновить существующую конфигурацию, отправьте запрос PATCH (UpdateChatAppConfig) к ресурсу-одиночке chatAppConfig для вашего облачного проекта.

  • При первом сохранении облачного проекта с пустым полем chatAppConfig необходимо указать displayName (от 3 до 25 символов) и description (от 1 до 40 символов). Если вы не укажете interactiveFeatureConfig при первом сохранении, приложение Chat будет настроено как неинтерактивное.
  • Для последующих обновлений используйте необязательный параметр запроса updateMask, чтобы указать разделенные запятыми поля для обновления (или опустите updateMask, чтобы обновить все предоставленные поля). При обновлении повторяющегося поля (appCommands, urlPatterns или allowlistedTestingPrincipals) заменяется весь список.
PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

Замените в URL, заголовке и теле запроса следующие значения:

  • PROJECT_NUMBER – числовой номер облачного проекта, в котором размещено ваше приложение Chat.
  • ACCESS_TOKEN – токен доступа OAuth 2.0 пользователя, авторизованный с областью действия https://www.googleapis.com/auth/cloud-platform.
  • USER_EMAIL – адрес электронной почты или группа Google из вашей организации Google Workspace, которую нужно добавить в белый список для тестирования приложения Chat (например, ваш собственный адрес электронной почты).
  • Примеры полей конфигурации в теле запроса (такие как displayName, description, avatarUri и interactiveFeatureConfig, включая конфигурацию конечной точки, команды, шаблоны URL для предварительного просмотра ссылок и тестирования субъектов) со значениями для вашего приложения Chat. Подробные сведения обо всех поддерживаемых полях и параметрах конечных точек см. в справочнике по REST для projects.chatAppConfig и projects.chatAppConfig.patch.

Как получить конфигурацию приложения Chat

Чтобы прочитать текущую конфигурацию приложения Chat для облачного проекта, вызовите GetChatAppConfig. Вы можете передать необязательный параметр запроса view (ChatAppConfigView):

  • BASIC (по умолчанию) – возвращает основные метаданные без interactiveFeatureConfig.
  • FULL – возвращает все поля конфигурации, включая interactiveFeatureConfig.

Если конфигурация приложения Chat ещё не сохранена для облачного проекта, метод возвращает пустой объект ChatAppConfig.

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

Лимиты на использование

Для методов chatAppConfig действуют квоты на проект. Если вы превысите квоту, запрос не будет выполнен и вы получите код статуса HTTP 429: Too many requests. Подробнее о лимитах на использование Google Workspace Add-ons API…

Устранение ошибок

Если запрос chatAppConfig не выполнен, проверьте код статуса HTTP и поле message в ответе об ошибке. В таблице ниже перечислены распространенные ошибки, их причины и способы устранения.

Код статуса HTTP Основные причины Разрешение
400: Bad Request (INVALID_ARGUMENT)
  • Объект updateMask содержит поле, которое не существует или не может быть обновлено.
  • Значение поля отсутствует или недействительно. Например, в interactiveFeatureConfig нет connectionConfig.
Проверьте поле message на наличие недопустимого поля и исправьте запрос. Поддерживаемые поля и значения перечислены в справочнике по projects.chatAppConfig.
400: Bad Request (FAILED_PRECONDITION)
  • Приложение Chat не создано как дополнение Google Workspace.
  • Поле нельзя изменить, потому что приложение Chat опубликовано в Google Workspace Marketplace.
  • Новое значение несовместимо с существующей конфигурацией приложения Chat.
  • Преобразуйте приложение Chat в дополнение Google Workspace или настройте его в консоли Google Cloud.
  • Следуйте инструкциям в поле message, чтобы обновить опубликованную страницу приложения.
  • Проверьте поле message на наличие конфликтующих настроек и обновите обе настройки в одном запросе или сначала измените существующую настройку.
403: Forbidden (PERMISSION_DENIED)
  • У аутентифицированного пользователя нет необходимых разрешений IAM в облачном проекте.
  • Запрос аутентифицируется с помощью сервисного аккаунта, а не аккаунта пользователя.
404: Not Found (NOT_FOUND) Проект Google Cloud в названии ресурса не существует или недоступен для аутентифицированного пользователя. Убедитесь, что в названии ресурса указан правильный номер проекта в формате projects/PROJECT_NUMBER/chatAppConfig и что у пользователя есть доступ к облачному проекту.
429: Too Many Requests (RESOURCE_EXHAUSTED) Превышена квота на проект. Подождите и повторите запрос позже. Подробнее о лимитах на использование…

Что нужно учитывать при работе с существующими дополнениями Google Workspace

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

  • Устанавливать дополнение из Marketplace должны иметь возможность как отдельные пользователи, так и администраторы Google Workspace. Эти настройки установки задаются в Marketplace SDK.
  • Приложения Chat не используют название и логотип, которые вы настраиваете для других приложений Google Workspace в объекте addons.common манифеста.
  • Для дополнений, опубликованных в Google Workspace Marketplace, нельзя сохранить черновик изменений в настройках конфигурации Google Chat API. После того как вы обновите и сохраните настройки конфигурации Chat API, обновленное приложение Chat сразу станет доступно всем существующим пользователям. Чтобы обновить страницу приложения в Marketplace, вы можете создать черновик, прежде чем отправлять изменения.
  • Если вы создали дополнение с помощью Apps Script:
  • Если вы создали дополнение с помощью HTTP-сервиса, не указывайте сведения о конфигурации приложения Chat в манифесте projects.deployments, который вы создаете с помощью Google Workspace Add-ons API. Развертывания HTTP, которые вы указываете в Google Workspace Marketplace SDK, используются только для других приложений Google Workspace. Вместо этого настройте приложение Chat в консоли Google Cloud, с помощью gcloud CLI или ресурса chatAppConfig в Google Workspace add-ons API.

Как предоставить другим пользователям разрешение на настройку Chat API

Вы можете предоставить определенным пользователям доступ к странице конфигурации приложения Chat, назначив им роль Google Cloud Identity Access Management (IAM) Владелец приложений Chat или Наблюдатель приложений Chat. Пользователи с этими ролями не могут перейти на страницу конфигурации приложений Chat с помощью панели управления API и сервисы, но могут получить доступ к странице конфигурации, перейдя в консоль Google Cloud для хост-облачного проекта приложения Chat следующим образом:

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

где PROJECT_ID – идентификатор проекта Google Cloud, в котором размещено приложение Chat.

Приложения для Chat, которые не являются дополнениями: настройте Google Chat API

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

  1. В консоли Google Cloud перейдите на страницу Configuration (Конфигурация) Chat API.

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

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

  3. Снимите флажок Создать это приложение Chat как дополнение Google Workspace. Появится диалоговое окно с запросом на подтверждение. В диалоговом окне нажмите Отключить.

  4. В разделе Функциональность выберите Поддержка главного экрана приложения или Присоединение к чат-группам и групповым чатам.

  5. В разделе Connection settings (Настройки подключения) укажите одну конечную точку для приложения Chat (HTTP endpoint URL (URL конечной точки HTTP), идентификатор развертывания Apps Script, Cloud Pub/Sub topic name (Название темы Cloud Pub/Sub) или Dialogflow).

  6. Настройте необязательные параметры: Команды, Варианты запросов, Предварительный просмотр ссылок, Видимость и Журналы, а затем нажмите Сохранить.

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