此页面由 Cloud Translation API 翻译。

收集和处理 Google Chat 用户的信息

本指南介绍了 Google Chat 应用如何通过在基于卡片的界面中构建表单输入项来收集和处理用户信息。

一个显示各种不同微件的对话框。 — **图 1**：A 示例 Chat 应用会打开一个对话框以收集联系信息。

Chat 应用会向用户请求信息，以便在 Chat 中或之外执行操作，包括通过以下方式：

配置设置。例如，允许用户自定义通知设置或者配置 Chat 应用并将其添加到一个或多个空格。
在其他 Google Workspace 应用中创建或更新信息。例如，允许用户创建 Google 日历活动。
允许用户访问和更新其他应用或 Web 服务中的资源。对于例如，Chat 应用可以帮助用户更新支持服务工单的状态。

前提条件

一款已启用互动功能的 Google Chat 应用。要创建交互式 Chat 应用，请完成以下快速入门之一针对您要使用的应用架构：

使用卡片构建表单

为了收集信息，Chat 应用会设计表单及其输入内容，并将其构建为卡片。如需向用户显示卡片，Chat 应用可以使用以下 Chat 界面：

信息其中包含一张或多张卡片
首页、该卡片会直接显示在首页标签页中消息。
对话框：即从消息和首页在新窗口中打开的卡片。

聊天应用可以使用以下 widget 来构建卡片：

用于请求用户信息的表单输入微件。（可选）您可以向表单输入 widget 添加验证，以确保用户正确输入和设置信息格式。聊天应用可以使用以下表单输入 widget：
- 文本输入 (textInput) 适用于自由格式文本或建议文本。
- 选择输入 (selectionInput) 是可选择的界面元素，例如复选框、单选按钮和下拉菜单“选择输入”微件还可以用于填充来自静态或动态数据源的项。例如，用户可以从他们所属的 Chat 聊天室列表中进行选择。
- 用于日期和时间条目的日期时间选择器 (dateTimePicker)。
一个按钮 widget 以便用户提交他们在卡片中输入的值。用户点击该按钮后，Chat 应用即可处理收到的信息。

下面显示了一张卡片，该卡片包含三种不同类型的日期时间输入：

如需查看您可以用来收集请参阅设计互动式卡片或对话框。

接收来自互动 widget 的数据

无论何时用户点击按钮，聊天应用都会收到 CARD_CLICKED 互动事件其中包含有关该互动的信息 CARD_CLICKED 个互动事件包含 common.formInputs 对象具有用户输入的任何值。

您可以从对象 common.formInputs.WIDGET_NAME 检索值，其中 WIDGET_NAME 是您为该 widget 指定的 name 字段。这些值作为微件的特定数据类型返回（表示为 Inputs 对象）。在下例中，卡片会使用输入、日期时间选择器和选择输入 widget：

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

处理互动事件

当用户在卡片或对话框中输入数据时，您的 Chat 应用接收 Chat 应用 CARD_CLICKED 互动事件，其中包含用户输入的值。

下面显示了 CARD_CLICKED 互动事件的一部分，其中用户为每个 widget 输入值：

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps 脚本

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

如需接收数据，您的 Chat 应用需要处理互动事件，以获取用户输入到 widget 中的值。以下表显示了如何获取给定表单输入 widget 的值。对于每个微件该表显示了 widget 接受的数据类型，其中值的存储位置以及一个示例值。

表单输入微件	输入数据类型	互动事件中的输入值	示例值
`textInput`	`stringInputs`	`events.common.formInputs.contactName.stringInputs.value[0]`	`Kai O`
`selectionInput`	`stringInputs`	如需获取第一个或唯一值，请使用 `events.common.formInputs.contactType.stringInputs.value[0]`	`Personal`
仅接受日期的 `dateTimePicker`。	`dateInput`	`events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch`。	`1000425600000`

将数据转移到其他卡

用户提交卡片中的信息后，您可能需要返回执行以下任何操作：

创建不同的版块，帮助用户填写较长的表单。
让用户预览并确认初始卡片中的信息，以便他们在提交前检查自己的回答。
动态填充表单的其余部分。例如，为了提示用户创建预约，Chat 应用可以显示一个初始卡片来请求预约原因，然后填充另一张卡片，根据预约类型提供空闲时间。

如需从初始卡片传输数据输入，您可以使用包含微件 name 和用户输入的值的 actionParameters 构建 button 微件，如以下示例所示：

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

其中，WIDGET_NAME 是 widget 的 name，USER_INPUT_VALUE 是用户输入的内容。例如，对于一段用于收集人名的输入，微件名称为 contactName，示例值为 Kai O。

当用户点击该按钮时，您的 Chat 应用会收到 CARD_CLICKED 互动事件。要检索值，您可以使用 event.common.parameters 对象。

以下示例展示了如何将包含用户输入数据的参数传递给用于打开下一张卡片的函数：

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps 脚本

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

回复表单提交

从卡片消息或对话框收到数据后，聊天应用通过确认收到或返回错误。

在以下示例中，Chat 应用会将消息，确认已成功收到通过卡片消息。

Apps 脚本

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

要处理并关闭对话框，您需要返回一个 ActionResponse 用于指定是否要发送确认消息、更新原始消息或卡片，也可以直接关闭对话框。有关具体步骤，请参阅关闭对话框。

问题排查

当 Google Chat 应用或 card 会返回错误，聊天界面会显示一条内容为“出了点问题”的消息。或“无法处理您的请求”。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

虽然 Chat 界面中可能不会显示错误消息，提供描述性错误消息和日志数据，以帮助您修正错误启用 Chat 应用的错误日志记录时。如需观看方面的帮助，请参阅排查并修正 Google Chat 错误。

查看联系人管理器示例，这是一款会提示用户从卡片消息和对话框中创建联系表单。
打开互动式对话框

收集和处理 Google Chat 用户的信息

前提条件

使用卡片构建表单

接收来自互动 widget 的数据

处理互动事件

HTTP

Apps 脚本

将数据转移到其他卡

Node.js

Python

Apps 脚本

回复表单提交

Apps 脚本

问题排查

相关主题