Информация о процессе, введенная пользователями

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

  • TextInput для ввода текста в произвольной форме, который также поддерживает предложения.
  • SelectionInput для элементов списка и меню, таких как флажки, переключатели и раскрывающиеся меню.
  • DateTimePicker для записей даты и времени.


Используйте конструктор карточек для разработки и предварительного просмотра карточных сообщений JSON для приложений чата:

Откройте конструктор карточек

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

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

Как работает получение данных

Приложение чата представляет информацию пользователю в виде диалогового окна или сообщения-карточки. В этом примере диалоговое окно просит пользователя ввести информацию о контакте с помощью виджетов TextInput и SelectionInput :

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

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

Чтобы получить данные о том, что ввели пользователи, используйте поле 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"
        }
      }
    });
  }
}

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

В этом примере отправляется карточное сообщение, возвращая card JSON . Вы также можете использовать службу карточек 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"
        }
      }
    };
  }
}

Питон

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» .