Microsoft Teams中Bot跳转至Tab的DeepLink开发问题咨询

提问背景 #

我正在开发一款面向Microsoft Teams的专用Bot，它的搜索功能最多会返回200-500条结果。虽然已经集成了筛选功能来缩小结果范围，但筛选后仍需要展示约50-100条记录。我不想在Bot里用轮播或者列表视图来展示这么多内容，所以打算把Bot和Tab集成，通过DeepLink跳转到Tab，让用户在jQuery DataTable里查看完整的搜索结果。目前我卡在两个问题上：

1. 如何从Bot生成正确的DeepLink，跳转到Teams Tab并传递搜索的筛选参数？
2. 如何在Tab的前端页面中接收这些参数，并用它们初始化jQuery DataTable加载对应的结果？

我的解决方案（亲测有效） #

针对问题1：生成带参数的DeepLink并在Bot中发送 #

Teams的DeepLink有固定格式，关键是要把你的搜索参数打包到上下文里，还要确保Tab的实体ID和应用ID正确。

1. 先找好Tab的实体ID和应用ID
   打开你的Teams应用Manifest文件，staticTabs或者configurableTabs里的entityId就是Tab的唯一标识（比如我用的是searchResultsTab）；而Manifest根节点的id就是你的应用ID，这个要记好。

2. 构造DeepLink URL
   格式是这样的：

   https://teams.microsoft.com/l/entity/{你的应用ID}/{Tab实体ID}?context={URL编码的JSON上下文}
   

   比如我要传递搜索关键词"客户项目"和状态"进行中"，先把参数放到JSON里：

   {
     "chatId": "{当前聊天ID}",
     "channelId": "{当前频道ID}",
     "searchParams": {
       "keyword": "客户项目",
       "status": "进行中"
     }
   }
   

   然后把这个JSON用encodeURIComponent()编码，拼到URL里就行。

3. 在Bot里发送带DeepLink的卡片
   用Hero Card加个按钮最直观，比如用Node.js的Bot Framework代码：

   const { HeroCard, CardFactory } = require('botbuilder');
   
   const heroCard = new HeroCard({
     title: '查看完整搜索结果',
     buttons: [
       {
         type: 'openUrl',
         title: '打开结果页面',
         value: deepLinkUrl // 刚才构造的DeepLink
       }
     ]
   });
   
   await turnContext.sendActivity({ attachments: [CardFactory.adaptiveCard(heroCard)] });
   

针对问题2：Tab接收参数并初始化DataTable #

这部分核心是用Teams JS SDK拿到上下文里的参数，再传给DataTable加载数据。

1. 加载Teams SDK并获取上下文
   先在Tab的HTML里引入SDK：

   <script src="https://statics.teams.cdn.office.net/sdk/v1.11.0/js/MicrosoftTeams.min.js"></script>
   

   然后初始化SDK并解析参数：

   microsoftTeams.initialize();
   microsoftTeams.getContext(context => {
     // 拿到我们传递的搜索参数
     const { keyword, status } = context.searchParams;
     // 初始化DataTable
     loadSearchResults(keyword, status);
   });
   

2. 用参数初始化jQuery DataTable
   写个函数调用后端API，把参数传过去，然后渲染表格：

   function loadSearchResults(keyword, status) {
     $('#searchResultsTable').DataTable({
       ajax: {
         url: '/api/teams/search',
         type: 'POST',
         data: { keyword, status },
         dataSrc: ''
       },
       columns: [
         { data: 'id', title: 'ID' },
         { data: 'title', title: '标题' },
         { data: 'status', title: '状态' },
         { data: 'createTime', title: '创建时间' }
       ],
       // 开启分页、排序这些实用功能
       paging: true,
       ordering: true,
       searching: false // 因为已经从Bot带了筛选参数，这里可以关掉自带搜索
     });
   }
   

一些要注意的小细节 #

• 传递参数的时候一定要URL编码，不然特殊字符会导致参数解析失败；
• 如果是在频道里用Bot，要确保channelId正确传递，Tab才能获取到频道上下文；
• 测试的时候可以直接把DeepLink复制到Teams聊天框里打开，先验证跳转和参数是否正确，再集成到Bot里。

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