Эта страница переведена с помощью Cloud Translation API.

Создать карточное сообщение

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

Используйте карточные сообщения, чтобы сделать следующее:

Представить подробную информацию
Собирать информацию от пользователей
Помогите пользователям сделать следующий шаг

В этом руководстве описывается, как создавать сообщения-карточки синхронно (ответ в реальном времени на событие Google Chat, например получение сообщения от пользователя или добавление в пространство) и асинхронно (отправка сообщения из приложения в пространство или пользователю без подсказки). с помощью Google Chat API ).

Предпосылки

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

Node.js

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

Примечание. Примеры кода Node.js в этом руководстве написаны для работы в качестве Google Cloud Function .

питон

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

Примечание. Примеры кода Python в этом руководстве написаны для работы в качестве облачной функции Google с использованием Python 3.9.

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

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

Анатомия сообщения карты

Каждая карточка, будь то диалог или сообщение, представляет собой объект JSON в ресурсе spaces.messages в Google Chat API.

Объект карты JSON состоит из следующего:

Массив с cardsV2[] , который содержит один или несколько объектов CardWithId .
cardId , используемый для идентификации карты и ограниченный рамками данного сообщения. (Карты в разных сообщениях могут иметь одинаковый идентификатор.)
Объект card , который состоит из следующего:
- Объект header , который определяет такие вещи, как заголовок, подзаголовок и изображение в стиле аватара.
- Один или несколько объектов section , каждый из которых содержит хотя бы один виджет.
- Один или несколько объектов widget . Каждый виджет представляет собой составной объект, который может представлять текст, изображения, кнопки и другие типы объектов.

В качестве примера обратите внимание на объекты header , section и widget в следующем сообщении карты:

Приложение чата, выполняющее опрос в пространстве чата с использованием сообщения карты

Следующий код представляет JSON сообщения карты:

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Создать синхронное карточное сообщение

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

Приложение Chat отвечает карточкой с отображаемым именем отправителя и изображением аватара.

В следующих примерах кода приложения Node.js и Python размещены в Google Cloud Functions . Пример Apps Script размещен на Google Apps Script .

Полные инструкции по созданию и развертыванию приложения чата см. в разделе Создание приложения чата .

Node.js

узел/аватар-бот/index.js

Посмотреть на GitHub

/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

питон

python/аватар-бот/main.py

Посмотреть на GitHub

from typing import Any, Mapping

import flask
import functions_framework


# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request) -> Mapping[str, Any]:
  if req.method == "GET":
    return "Hello! This function must be called from Google Chat."

  request_json = req.get_json(silent=True)

  display_name = request_json["message"]["sender"]["displayName"]
  avatar = request_json["message"]["sender"]["avatarUrl"]

  response = create_message(name=display_name, image_url=avatar)

  return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
  avatar_image_widget = {"image": {"imageUrl": image_url}}
  avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
  avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

  header = {"title": f"Hello {name}!"}

  cards = {
      "cardsV2": [
          {
              "cardId": "avatarCard",
              "card": {
                  "name": "Avatar Card",
                  "header": header,
                  "sections": [avatar_section],
              },
          }
      ]
  }

  return cards

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

приложения-скрипт/аватар-бот/hello-chat.gs

Посмотреть на GitHub

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Создайте асинхронное карточное сообщение с помощью Chat API

Этот пример асинхронно создает сообщение с помощью Chat API и отправляет его в пространство, в которое добавлено приложение Chat:

Карточное сообщение, созданное с помощью Google Chat API. — **Рис. 1.** Карточное сообщение, созданное с помощью Chat API.

питон

В рабочем каталоге создайте файл с именем chat_create_card_message.py .

Включите следующий код в chat_create_card_message.py :

from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # The message to create.
    body=
    {
      'cardsV2': [{
        'cardId': 'createCardMessage',
        'card': {
          'header': {
            'title': 'A Card Message!',
            'subtitle': 'Created with Chat REST API',
            'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
            'imageType': 'CIRCLE'
          },
          'sections': [
            {
              'widgets': [
                {
                  'buttonList': {
                    'buttons': [
                      {
                        'text': 'Read the docs!',
                        'onClick': {
                          'openLink': {
                            'url': 'https://developers.google.com/chat'
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }]
    }

).execute()

print(result)

В коде замените SPACE именем пространства, которое можно получить с помощью spaces.list() в Chat API или из URL-адреса пространства.
В рабочем каталоге соберите и запустите пример:
```
python3 chat_create_card_message.py
```

Дополнительные сведения о работе с сообщениями в Chat API см. в следующих статьях:

Открыть диалог

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

Диалоги полезны для многих типов взаимодействия с пользователем, в том числе:

Сбор информации от пользователей
Аутентификация пользователей с помощью веб-сервисов
Настройка параметров приложения чата

В этом примере приложение Chat открывает диалоговое окно , помогающее пользователю создать новый контакт для своей адресной книги:

Диалог с множеством различных виджетов.

Чтобы реализовать диалоги, см. Открытие диалогов .

Форматирование карты

Существует несколько различных способов форматирования внешнего вида карточек.

Форматирование текста карты

Внутри карточек большинство текстовых полей поддерживают базовое форматирование текста с помощью небольшого подмножества тегов HTML.

Поддерживаемые теги и их назначение показаны в следующей таблице:

Формат	Пример	Визуализированный результат
Смелый	`"This is <b>bold</b>."`	Это смело .
Курсив	`"This is <i>italics</i>."`	Это курсив .
Подчеркнуть	`"This is <u>underline</u>."`	Это подчеркивание .
Зачеркнутый	`"This is <s>strikethrough</s>."`	Это ~~зачеркнуто~~ .
Цвет шрифта	`"This is <font color=\"#FF0000\">red font</text>."`	Это красный шрифт .
Гиперссылка	`"This is a <a href=\"https://www.google.com\">hyperlink</a>."`	Это гиперссылка .
Время	`"This is a time format: <time>2023-02-16 15:00</time>."`	Это формат времени: 2023-05-10 15:00 .
Новая линия	`"This is the first line. <br> This is a new line.` "	Это первая строка. Это новая линия.

Обратите внимание, что текст основного сообщения анализируется с использованием другого синтаксиса разметки, оптимизированного для пользователей-людей. Подробнее см. в разделе Создание текстового сообщения .

Встроенные значки

Виджеты DecoratedText и ButtonList поддерживают элемент icon , используемый для указания одного из встроенных значков, доступных в Google Chat:

{
  .
  .
  .
      "knownIcon": "TRAIN",
  .
  .
  .
}

В следующей таблице перечислены встроенные значки, доступные для карточных сообщений:

	САМОЛЕТ		ЗАКЛАДКА
	АВТОБУС		МАШИНА
	ЧАСЫ		CONFIRMATION_NUMBER_ICON
	ОПИСАНИЕ		ДОЛЛАР
	ЭЛЕКТРОННАЯ ПОЧТА		EVENT_SEAT
	FLIGHT_ARRIVAL		FLIGHT_DEPARTURE
	ГОСТИНИЦА		HOTEL_ROOM_TYPE
	ПРИГЛАШАТЬ		MAP_PIN
	ЧЛЕНСТВО		НЕСКОЛЬКО_ЧЕЛОВЕК
	ЧЕЛОВЕК		ТЕЛЕФОН
	РЕСТОРАН_ICON		КОРЗИНА
	ЗВЕЗДА		МАГАЗИН
	БИЛЕТ		ТРЕНИРОВАТЬСЯ
	ВИДЕОКАМЕРА		VIDEO_PLAY

Пользовательские значки

Виджеты DecoratedText и ButtonList позволяют использовать встроенные значки или определять собственные значки. Чтобы указать собственный значок, используйте элемент iconUrl , как показано здесь:

{ . . . "iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" . . . }