В этом руководстве описывается, как получать и читать информацию, которую пользователи вводят в карточные сообщения и диалоги . Пользователи могут вводить данные, которые приложения чата получают, считывают и на которые отвечают. Виджеты, которые позволяют пользователям вводить информацию, включают следующее:
-
TextInputдля ввода текста в произвольной форме, который также поддерживает предложения. -
SelectionInputдля элементов списка и меню, таких как флажки, переключатели и раскрывающиеся меню. -
DateTimePickerдля записей даты и времени.
Получение вводимых данных от пользователей позволяет приложениям чата выполнять следующие действия:
- Обновление обращений по обслуживанию клиентов.
- Создавайте рабочие задания.
- Аутентификация с помощью веб-сервисов.
Как работает получение данных
Приложение чата представляет информацию пользователю в виде диалогового окна или сообщения-карточки. В этом примере диалоговое окно просит пользователя ввести информацию о контакте с помощью виджетов TextInput и SelectionInput :
По завершении приложение Chat получает данные, введенные пользователями в диалоговом окне, в формате JSON и событие взаимодействия, где:
-
EventType—CARD_CLICKED. -
DialogEventType—SUBMIT_DIALOG(только для диалогов).
Чтобы получить данные о том, что ввели пользователи, используйте поле Event.common.formInputs в полезных данных события. Поле formInputs представляет собой карту, где ключи представляют собой строковые идентификаторы, назначенные каждому виджету, а значения представляют собой вводимые пользователем данные для каждого виджета. Разные объекты представляют разные типы входных данных. Например, Event.common.formInputs.stringInputs представляет строковые входные данные.
Ваше приложение может получить доступ к первому введенному пользователем значению в event.common.formInputs. NAME .stringInputs.value[0] , где NAME — это поле name виджета TextInput .
Получать данные с карт
Когда пользователь вводит данные в сообщение-карточку, ваше приложение Chat получает событие взаимодействия с приложением Chat, как показано в следующем примере:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
"common": {
// Represents user data entered in a card.
"formInputs": {
// Represents user data entered for a specific field in a card.
"NAME": {
// Represents string data entered in a card, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a card.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
Получать данные из диалогов
Когда пользователь отправляет данные в диалоговом окне, ваше приложение Chat получает другое событие взаимодействия с приложением Chat, как показано в следующем примере:
JSON
{
"type": enum (EventType),
"eventTime": string,
"threadKey": string,
"message": {
object (Message)
},
"user": {
object (User)
},
"space": {
object (Space)
},
"action": {
object (FormAction)
},
"configCompleteRedirectUrl": string,
// Indicates that this event is dialog-related.
"isDialogEvent": true,
// Indicates that a user clicked a button, and all data
// they entered in the dialog is included in Event.common.formInputs.
"dialogEventType": "SUBMIT_DIALOG",
"common": {
"userLocale": string,
"hostApp": enum (HostApp),
"platform": enum (Platform),
"timeZone": {
object (TimeZone)
},
// Represents user data entered in a dialog.
"formInputs": {
// Represents user data entered for a specific field in a dialog.
"NAME": {
// Represents string data entered in a dialog, like text input fields
// and check boxes.
"stringInputs": {
// An array of strings entered by the user in a dialog.
"value": [
string
]
}
}
},
"parameters": {
string: string,
...
},
"invokedFunction": string
}
}
Отвечайте на данные, собранные из карточного сообщения или диалога.
После получения данных из карточного сообщения или диалога приложение Chat отвечает либо подтверждением получения, либо возвратом ошибки, оба из которых выполняются путем возврата ActionResponse :
- Чтобы подтвердить успешное получение, ответьте параметром
ActionResponseсо значением"actionStatus": "OK". - Чтобы вернуть ошибку, ответьте параметром
ActionResponseсо значением"actionStatus": " ERROR MESSAGE ".
Пример
В следующем примере проверяется наличие значения name . Если его нет, приложение возвращает ошибку. Если они присутствуют, приложение подтверждает получение данных формы и закрывает диалоговое окно.
Node.js
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] == "") {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
});
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
res.json({
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
});
}
}
Скрипт приложений
/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function receiveDialog(event) {
// Checks to make sure the user entered a name
// in a dialog. If no name value detected, returns
// an error message.
if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] == "") {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "Don't forget to name your new contact!"
}
}
};
// Otherwise the app indicates that it received
// form data from the dialog. Any value other than "OK"
// gets returned as an error. "OK" is interpreted as
// code 200, and the dialog closes.
} else {
return {
"actionResponse": {
"type": "DIALOG",
"dialogAction": {
"actionStatus": "OK"
}
}
};
}
}
Питон
def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
"""Checks for a form input error, the absence of a "name" value, and returns
an error if absent. Otherwise, confirms successful receipt of a dialog.
Args:
event (Mapping[str, Any]): the event object from Chat API.
Returns:
Mapping[str, Any]: the response.
"""
if common := event.get('common'):
if form_inputs := common.get('formInputs'):
if contact_name := form_inputs.get('WIDGET_NAME'):
if string_inputs := contact_name.get('stringInputs'):
if name := string_inputs.get('value')[0]:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'OK'
}
}
}
else:
return {
'actionResponse': {
'type': 'DIALOG',
'dialogAction': {
'actionStatus': 'Don\'t forget to name your new contact!'
}
}
}
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .