如何通过Deep Link向Teams静态标签页传递自定义查询参数

问题原因 #

你当前的Deep Link构造逻辑有误：webUrl参数仅用于指定在外部浏览器打开的地址，不会将参数传递给Teams内部加载的静态标签页页面。静态标签页的contentUrl是在应用清单中固定定义的，Teams不会自动把webUrl里的参数同步到标签页的加载URL中。

正确解决方案 #

方案1：通过Deep Link的context参数传递自定义参数 #

1. 修改Deep Link构造代码

将自定义参数序列化为JSON字符串并URL编码，附加到Deep Link的context查询参数中：

import urllib.parse
import json

# 定义自定义参数
custom_params = {"auth": "username"}
# 序列化并URL编码
encoded_context = urllib.parse.quote(json.dumps(custom_params))
# 构造正确的Deep Link
deeplink = f"https://teams.microsoft.com/l/entity/{APP_ID}/{entityId}?context={encoded_context}"

2. 前端页面获取参数

引入Teams JavaScript SDK，通过上下文API获取传递的参数：

// 初始化Teams SDK
microsoftTeams.initialize();

// 获取上下文并解析自定义参数
microsoftTeams.getContext((context) => {
  if (context.customContext) {
    const params = JSON.parse(context.customContext);
    console.log(params.auth); // 输出username
  }
});

方案2：直接修改实体Deep Link的查询参数（部分场景适用） #

如果静态标签页页面支持直接从URL查询参数获取值，可尝试将参数直接附加到实体Deep Link末尾，Teams会将这些参数传递到标签页的加载URL中：

deeplink = f"https://teams.microsoft.com/l/entity/{APP_ID}/{entityId}?auth=username"

此时前端原有的解析代码即可生效：

const search = new URLSearchParams(window.location.search);
const params = [];
search.forEach((value, name) => {
  console.log(`${name}: ${value}`);
  params.push({ name: name, value: value });
});

注意：该方式并非所有场景都支持，部分Teams版本或配置下可能无法生效，优先推荐方案1。

额外检查项 #

• 确认APP_ID和entityId与应用清单中的值完全一致，大小写敏感。
• 确保前端页面已正确加载Teams JavaScript SDK（可通过CDN引入：<script src="https://statics.teams.cdn.office.net/sdk/v1.11.0/js/MicrosoftTeams.min.js"></script>）。

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