Gmail Workspace插件开发：SelectionInput.setExternalDataSource回调返回值疑问

当你使用setExternalDataSource()为SelectionInput绑定外部数据源时，对应的函数（比如getContacts()）不能直接返回普通对象数组，必须返回CardService.SelectionInputResponse类型的对象，该对象需要通过官方提供的构建器来创建。

核心要求 #

函数必须通过CardService.newSelectionInputResponseBuilder()构建响应，并用CardService.newSelectionItem()创建每个下拉选项，为每个选项分别设置显示文本（setText()）和对应的值（setValue()）。

完整代码示例 #

1. 创建绑定外部数据源的SelectionInput

function buildCard() {
  // 创建下拉选择组件
  const contactDropdown = CardService.newSelectionInput()
    .setType(CardService.SelectionInputType.DROPDOWN)
    .setTitle("选择联系人")
    .setFieldName("selectedContact")
    // 绑定外部数据源函数
    .setExternalDataSource(CardService.newAction().setFunctionName("getContacts"));

  // 将组件添加到卡片并返回
  const card = CardService.newCardBuilder().addSection(
    CardService.newCardSection().addWidget(contactDropdown)
  );
  return card.build();
}

2. 实现外部数据源函数getContacts()

function getContacts(event) {
  // 可选：获取用户输入的查询词（用于搜索过滤场景）
  const userQuery = event?.commonEventObject?.query || "";

  // 调用外部Web服务获取数据（替换为你的实际请求逻辑，比如UrlFetchApp.fetch）
  const externalContacts = fetchContactsFromExternalService(userQuery);

  // 构建下拉选项响应
  const responseBuilder = CardService.newSelectionInputResponseBuilder();
  externalContacts.forEach(contact => {
    const selectionItem = CardService.newSelectionItem()
      .setText(contact.displayName) // 下拉框显示的文本
      .setValue(contact.uniqueId); // 选中后传递的值
    responseBuilder.addItem(selectionItem);
  });

  // 返回构建完成的响应对象
  return responseBuilder.build();
}

// 模拟外部Web服务请求逻辑
function fetchContactsFromExternalService(query) {
  // 这里替换为实际的API调用，比如：
  // const response = UrlFetchApp.fetch("https://your-api.com/contacts?query=" + encodeURIComponent(query));
  // return JSON.parse(response.getContentText());
  
  // 模拟返回数据
  const mockData = [
    {displayName: "张三", uniqueId: "user_001"},
    {displayName: "李四", uniqueId: "user_002"},
    {displayName: "王五", uniqueId: "user_003"}
  ];
  
  // 根据查询词过滤（可选）
  return mockData.filter(item => item.displayName.includes(query));
}

关键注意点 #

• 必须使用CardService提供的构建器类，不能直接返回普通JSON或数组，否则插件无法识别
• 如果需要支持搜索过滤，可通过event.commonEventObject.query获取用户输入的关键词，在函数中对外部数据进行过滤后再构建选项
• 确保外部数据请求逻辑符合Google Apps Script的执行限制（比如请求超时、权限等）

内容的提问来源于stack exchange，提问作者mpk