Ten przewodnik opisuje, jak otrzymywać i odczytywać informacje, które użytkownicy wpisują w wiadomościach na karcie i w oknach dialogowych. Użytkownicy mogą wprowadzać dane, które aplikacje do obsługi czatu otrzymują i odczytują oraz na które reaguje. Widżety umożliwiające użytkownikom wpisywanie informacji to między innymi:
TextInput
– możliwość swobodnego wpisywania tekstu, który obsługuje też sugestie.SelectionInput
w przypadku elementów list i menu, takich jak pola wyboru, przyciski i menu.DateTimePicker
w przypadku wpisów daty i godziny.
Za pomocą Kreatora kart możesz projektować karty JSON i wyświetlać ich podgląd na potrzeby aplikacji Google Chat:
Otwórz kreator kartOtrzymywanie danych wejściowych od użytkowników umożliwia aplikacjom Google Chat między innymi:
- Aktualizowanie zgłoszeń do działu obsługi klienta.
- tworzyć zamówienia,
- Uwierzytelniaj za pomocą usług internetowych.
Jak działa odbieranie danych
Aplikacja do obsługi czatu prezentuje informacje użytkownikowi w formie okna lub wiadomości na karcie. W tym przykładzie okno dialogowe z prośbą o podanie informacji o kontakcie za pomocą widżetów TextInput
i SelectionInput
:
Gdy skończysz, aplikacja Google Chat otrzyma dane wpisywane przez użytkowników w oknie w formacie JSON oraz zdarzenie interakcji, gdzie:
EventType
toCARD_CLICKED
.DialogEventType
ma wartośćSUBMIT_DIALOG
(tylko w przypadku okien).
Aby uzyskać dane o wpisach użytkowników, użyj pola Event.common.formInputs
w ładunku zdarzenia. Pole formInputs
to mapa, na której klucze to identyfikatory w postaci ciągów przypisane do każdego widżetu, a wartości reprezentują dane wejściowe użytkownika. Różne obiekty reprezentują różne typy danych wejściowych. Na przykład Event.common.formInputs.stringInputs
oznacza dane wejściowe w postaci ciągu znaków.
Aplikacja może uzyskać dostęp do pierwszej wartości wskazanej przez użytkownika w lokalizacji event.common.formInputs.NAME.stringInputs.value[0]
, gdzie NAME
to pole name
widżetu TextInput
.
Odbieranie danych z kart
Gdy użytkownik wpisze dane w wiadomości na karcie, aplikacja Google Chat otrzyma zdarzenie interakcji z Google Chat, takie jak:
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
}
}
Odbieranie danych z okien
Gdy użytkownik przesyła dane w oknie, aplikacja do obsługi czatu otrzyma inne zdarzenie interakcji z aplikacją Google Chat, takie jak:
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
}
}
Reaguj na dane zebrane z wiadomości karty lub okna dialogowego
Po otrzymaniu danych z komunikatu na karcie lub w oknie aplikacja Google Chat odpowiada, potwierdzając odbiór odbioru lub zwracając błąd. W obu tych przypadkach następuje zwrócenie ActionResponse
:
- Aby potwierdzić odbiór, wyślij odpowiedź z parametrem
ActionResponse
zawierającym"actionStatus": "OK"
. - Aby zwrócić błąd, w odpowiedzi użyj parametru
ActionResponse
zawierającego"actionStatus": "ERROR MESSAGE"
.
Przykład
W tym przykładzie sprawdzamy obecność wartości name
. Jeśli go nie ma, aplikacja zwraca błąd. Jeśli ta opcja jest dostępna, aplikacja potwierdza odbiór danych formularza i zamyka okno.
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"
}
}
});
}
}
Google Apps Script
Ten przykład wysyła wiadomość dotyczącą karty, zwracając kod card JSON. Możesz też użyć usługi kart Apps Script.
/**
* 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"
}
}
};
}
}
Python
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!'
}
}
}
Rozwiązywanie problemów
Gdy aplikacja lub karta Google Chat zwróci błąd, w interfejsie Google Chat pojawi się komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami w interfejsie Google Chat nie pojawia się żaden komunikat o błędzie, ale aplikacja lub karta Google Chat zwraca nieoczekiwany wynik, na przykład komunikat na karcie może się nie pojawić.
Mimo że komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, dostępne są opisowe komunikaty o błędach i dane dziennika, które pomogą Ci naprawić błędy występujące po włączeniu logowania błędów w aplikacjach Google Chat. Informacje o wyświetlaniu, debugowaniu i naprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat i ich naprawianie.