此页面由 Cloud Translation API 翻译。

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

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

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

聊天应用会请求用户提供信息，以便在包括以下方式：

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

前提条件

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

使用卡片构建表单

为了收集信息，Chat 扩展应用会设计表单及其输入，并将它们制作成卡片如需向用户显示卡片，Chat 应用可以使用以下 Chat 界面：

包含一个或多个卡片的消息。
首页，这是 Chat 应用私信中的首页标签页中显示的卡片。
对话框：即从消息和首页在新窗口中打开的卡片。

Chat 应用可以使用以下微件构建卡片：

用于请求用户信息的表单输入微件。您还可以选择添加验证形成输入微件，以确保用户输入和格式化信息正确。聊天应用可以使用以下表单输入微件：
- 文本输入 (textInput) 适用于自由格式文本或建议文本。
- 选择输入 (selectionInput) 是可选择的界面元素，例如复选框、单选按钮和下拉菜单。选择输入 widget 还可以从静态或动态数据源填充项。例如，用户可以从他们所属的 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，该表会显示 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 对象。

以下示例说明了如何传递包含 user 将数据输入函数，该函数会打开下一张卡片：

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 应用或卡片返回错误时，Chat 界面会显示“出了点问题”消息。或“无法处理您的请求”。有时，Chat 界面不会显示任何错误消息，但 Chat 应用或卡片会产生意外结果；例如，卡片消息可能不会显示。

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

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

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

前提条件

使用卡片构建表单

接收来自互动 widget 的数据

处理互动事件

HTTP

Apps 脚本

将数据转移到其他卡

Node.js

Python

Apps 脚本

回复表单提交

Apps 脚本

问题排查

相关主题