通过

指向应用程序的深层链接

  • 项目

深层链接配置为执行各种操作，例如打开选项卡、启动应用安装对话框或在应用中浏览。 使用 机器人 和 连接器 消息中的深层链接通知用户选项卡或其项的更改。

可以为自定义应用创建深层链接。 但是，如果Microsoft Teams 应用商店中的应用与自定义应用 ID 共享相同的应用 ID，则深层链接将从 Teams 应用商店打开应用，而不是自定义应用。 在应用获得 Teams 移动平台批准后，还可以创建指向移动应用的深层链接。 若要在 Teams iOS 上使用深层链接，需要 Apple App Store Connect 团队 ID。 有关详细信息，请参阅 如何更新 Apple App Store Connect 团队 ID。

深层链接允许用户了解有关应用的详细信息，并将其安装在不同的范围内。 你还可以为应用用户创建深层链接，以转到应用中的特定页面。 本文介绍如何创建深层链接：

注意

本主题反映 2.0.x 版的 Microsoft Teams JavaScript 客户端库 (TeamsJS) 。 如果使用的是早期版本，请参阅 TeamsJS 库概述 ，获取有关最新 TeamsJS 与早期版本之间的差异的指导。

深层链接允许应用用户打开应用程序安装对话框，以了解有关应用的详细信息或将其安装在不同的上下文中。 可以通过以下方式创建指向应用程序的深层链接：

下面是使用应用 ID 从 Teams 客户端打开应用安装对话框所需的深层链接格式：

https://teams.microsoft.com/l/app/<your-app-id>?tenantId=<tenantId>

其中 <your-app-id> ，应用程序 ID (f46ad259-0fe5-4f12-872d-c737b174bcb4) 。

不同类型的应用的应用 ID

下表列出了不同类型的应用 ID，这些 ID 用于不同类型的应用，用于深层链接：

应用类型 应用 ID 的类型
在 Teams 中上传的自定义应用 清单 ID
提交到组织目录的应用 组织目录 ID
提交到 Teams 应用商店的应用 应用商店 ID

有关详细信息，请参阅 如何基于应用清单 ID 查找 ID。

应用程序可以使用 TeamsJS 库启动应用安装对话框，而无需手动生成深层链接。 下面是如何在应用程序中使用 TeamsJS 触发应用安装对话框的示例：

// Open an app install dialog from your tab
if(appInstallDialog.isSupported()) {
    const dialogPromise = appInstallDialog.openAppInstallDialog({ appId: "<appId>" });
    dialogPromise.
      then((result) => {/*Successful operation*/}).
      catch((error) => {/*Unsuccessful operation*/});
}
else { /* handle case where capability isn't supported */ }

有关模块 appInstallDialog 的详细信息，请参阅 appInstallDialog 模块。

应用用户可以使用 TeamsJS 从选项卡浏览 Teams 中的内容。 如果你的选项卡需要将用户与 Teams 中的其他内容（例如频道、消息、另一个选项卡）连接或打开计划对话框，则可以使用深层链接在应用中浏览。 在少数情况下，还可以使用 TeamsJS 完成导航，建议尽可能使用 TeamsJS 的类型化功能。

TeamsJS 使跨 Outlook 和 Microsoft 365 扩展的 Teams 应用能够检查主机是否支持你尝试使用的功能。 若要检查主机对功能的支持，可以使用与 API 命名空间关联的 isSupported() 函数。 TeamsJS 通过命名空间将 API 组织到功能中。 例如，在使用命名空间中的 pages API 之前，可以检查从 pages.isSupported() 中返回的布尔值，并在应用和应用 UI 的上下文中执行相应的操作。

有关 TeamsJS 中的功能和 API 的详细信息，请参阅 使用 TeamsJS 库生成选项卡和其他托管体验。

可以通过以下方式配置深层链接以在应用中浏览：

注意

在 Microsoft Windows 中，由于 Windows ShellExecuteExecuteEx API 中的限制，Teams 无法处理超过 2048 个字符的 INTERNET_MAX_URL_LENGTH 深层链接。 创建深层链接时，请确保 Teams 客户端和其他元数据的路径符合此限制。 如果深层链接包含大量数据，请在链接中包含一个唯一标识符，你的应用可以使用该标识符从后端服务中提取必要的数据。

对机器人、连接器或消息扩展卡中的深层链接使用以下格式：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?tenantId=<tenantId>&webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

  • 如果机器人发送包含 TextBlock 和深层链接的消息，则当用户选择链接时，将打开新的浏览器选项卡。 当 Chrome 和 Teams 桌面应用中在 Linux 上运行时，就会发生这种情况。

  • 如果机器人将相同的深层链接 URL 发送到 Action.OpenUrl，则当用户选择链接时，Teams 选项卡将在当前浏览器选项卡中打开。

查询参数为：

参数名称 说明 示例
appId  Microsoft Teams 管理中心的 ID。 fe4a8eba-2a31-4737-8e33-e5fae6fee194
entityId  选项卡的 ID，在 配置选项卡时提供。生成用于深层链接的 URL 时，请继续使用实体 ID 作为 URL 中的参数名称。 配置选项卡时，上下文对象将 引用 entityId 为 page.id。 任务列表 123
entityWebUrl 或 subEntityWebUrl  在客户端不支持呈现选项卡时要是用的具有回退 URL 的可选字段。 https://tasklist.example.com/123 或 https://tasklist.example.com/list123/task456
entityLabel 或 subEntityLabel  选项卡中项的标签，用于显示深层链接时使用。 任务列表 123 或任务 456
context.subEntityId  选项卡内项的 ID。生成用于深层链接的 URL 时，请继续在 subEntityId URL 中用作参数名称。 配置选项卡时，上下文对象将 引用 subEntityId 为 page.subPageId。 任务 456
context.channelId  选项卡 上下文 中提供的 Microsoft Teams 频道 ID。 此属性仅在具有 团队范围的可配置选项卡中可用。 它在具有 个人 范围的静态选项卡中不可用。 19:cbe3683f25094106b826c9cada3afbe0@thread.skype
context.chatId  可在选项卡 上下文 中用于群组和会议聊天的聊天 ID。 17:b42de192376346a7906a7dd5cb84b673@thread.v2
context.contextType  会议仅支持 contextType 聊天。 聊天
openInMeeting 使用 openInMeeting 控制目标选项卡与会议关联的用户体验。 如果用户在正在进行的会议体验中与深层链接交互，Teams 会在会议内侧面板中打开应用。 将此值设置为 ， false 无论会议状态如何，始终在会议聊天选项卡而不是侧面板中打开应用。 Teams 会忽略 除 之外 false的任何值。 false

注意

  • 个人选项卡具有 personal 作用域，而通道和组选项卡使用 team 或 group 作用域。 这两种选项卡类型的语法略有不同，因为只有可配置的选项卡具有与其上下文对象关联的 channel 属性。 有关选项卡范围的详细信息，请参阅 应用清单。
  • 仅当选项卡是使用库 v0.4 或更高版本配置的，因为它具有实体 ID 时，深层链接才能正常工作。 指向没有实体 ID 的选项卡的深层链接仍会转到选项卡，但无法向选项卡提供子实体 ID。

示例：

  • 链接到静态 (个人) 选项卡本身:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123

  • 链接到静态 (个人) 选项卡内的任务项目:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456"}

  • 链接到可配置选项卡本身：

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&label=Task List 123&context={"channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • 链接到可配置选项卡中的任务项：

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"subEntityId": "task456","channelId": "19:cbe3683f25094106b826c9cada3afbe0@thread.skype"}

  • 链接到添加到会议或群组聊天的选项卡应用:

    https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456?context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

重要

  • 确保所有查询参数和空格都正确编码了 URI。 下面是 URI 编码的查询参数的示例：

    var encodedWebUrl = encodeURIComponent('https://tasklist.example.com/123/456&label=Task 456');
var encodedContext = encodeURIComponent(JSON.stringify({"subEntityId": "task456"}));
var taskItemUrl = 'https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=' + encodedWebUrl + '&context=' + encodedContext;

  • Outlook 不支持指向具有编码 URI 的 Teams 应用程序的深层链接。

可以通过 TeamsJS 在应用中配置深层链接，以允许应用用户浏览应用中的不同页面。 以下代码演示如何导航到 Teams 应用中的特定实体：

可以使用 pages.navigateToApp() 函数从选项卡触发导航，如以下代码所示：

if (pages.isSupported()) {
  const navPromise = pages.navigateToApp({ appId: <appId>, pageId: <pageId>, webUrl: <webUrl>, subPageId: <subPageId>, channelId:<channelId>});
  navPromise.
     then((result) => {/*Successful navigation*/}).
     catch((error) => {/*Failed navigation*/});
}
else { /* handle case where capability isn't supported */ }

有关选项卡应用内导航的详细信息，请参阅 在选项卡应用中导航。 有关使用页面功能的详细信息，请参阅 pages.navigateToApp() 和其他导航选项的“页面”命名空间。 如果需要，请使用 app.openLink () 函数直接打开深层链接。

跨 Microsoft 365 Office 扩展的 Teams 应用的导航行为取决于两个因素：

  1. 深层链接指向的目标。
  2. 运行 Teams 应用的主机。

如果 Teams 应用在深层链接作为目标的主机中运行，则应用将直接在主机中打开。 但是，如果 Teams 应用在与深层链接目标不同的主机中运行，则首先在浏览器中打开该应用。

可以通过使用以下格式手动配置深层链接，允许应用用户浏览到与应用程序的个人聊天：

https://teams.microsoft.com/l/entity/<appId>/conversations?tenantId=<tenantId>，其中 appId 是应用程序 ID。 若要了解使用的不同应用 ID，请参阅 不同类型的应用的应用 ID。

可以在 Teams 应用中共享指向实体的深层链接，以导航到选项卡应用中的内容和信息。 例如，如果选项卡应用包含任务列表，则团队成员可以创建和共享指向单个任务的链接。 当应用用户选择链接时，它会导航到侧重于特定项目的选项卡。

以最适合你的 UI 的任何方式向每个项目添加 复制链接 操作。 当用户执行此操作时，调用 pages.shareDeepLink() 以显示一个对话框，其中包含用户可以复制到剪贴板的链接。 进行此呼叫时，请传递你的项目的 ID。 当链接被跟踪并重新加载选项卡时，可在 上下文 中将其返回。

pages.shareDeepLink({ subPageId: <subPageId>, subPageLabel: <subPageLabel>, subPageWebUrl: <subPageWebUrl> })

需要将以下参数替换为相应的信息：

  • subPageId：要向其进行深层链接的页面内项的唯一标识符。
  • subPageLabel：用于显示深层链接的项的标签。
  • subPageWebUrl：客户端无法呈现页面时使用的回退 URL。

有关详细信息，请参阅 pages.shareDeepLink () 。

注意

  • 此深层链接不同于 “复制到选项卡” 菜单项的链接，后者仅生成指向此选项卡的深层链接。
  • shareDeepLink 不适用于 Teams 移动平台。

可以在机器人、连接器或消息扩展卡中使用以下深层链接格式： https://teams.microsoft.com/l/entity/<appId>/<EntityId>?webUrl=<entityWebUrl>/<EntityName>。

注意

  • 当机器人发送 TextBlock 包含深层链接的消息时，当用户选择链接时，将打开一个新的浏览器选项卡。 这发生在 Linux 上运行的 Chrome 和 Microsoft Teams 桌面应用中。
  • 如果机器人在 中 Action.OpenUrl发送相同的深层链接 URL，则当用户选择链接时，Teams 选项卡将在当前浏览器中打开。 未打开新的浏览器选项卡。

查询参数为：

  • appID：清单 ID，例如 fe4a8eba-2a31-4737-8e33-e5fae6fee194。

  • entityID：在配置选项卡时提供的项 ID。例如 tasklist123。

  • entityWebUrl：具有回退 URL 的可选参数，在客户端不支持呈现选项卡时使用 - https://tasklist.example.com/123 或 https://tasklist.example.com/list123/task456。

  • entityName：选项卡中项的标签，用于显示深层链接时使用，例如 Task List 123 或 Task 456。

例如：https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123&TaskList

对话深层链接是对象的序列化 TaskInfo ，其中包含其他两个详细信息， APP_ID 以及 （可选） BOT_APP_ID：

  • https://teams.microsoft.com/l/task/APP_ID?url=<TaskInfo.url>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

  • https://teams.microsoft.com/l/task/APP_ID?card=<TaskInfo.card>&height=<TaskInfo.height>&width=<TaskInfo.width>&title=<TaskInfo.title>&completionBotId=BOT_APP_ID

有关 <TaskInfo.url>、<TaskInfo.card>、<TaskInfo.height>、<TaskInfo.width> 和 <TaskInfo.title> 的数据类型和允许的值，请参阅 TaskInfo 对象。

提示

使用 card 参数（例如 JavaScript encodeURI() 函数）时对深层链接 URL 进行编码。

下表提供了有关 APP_ID 和 BOT_APP_ID 的信息：

值 类型 必需 说明
APP_ID string 是 对于第三方应用，请使用清单中的应用 id 或 APP_ID Teams 管理中心中的应用，因为它们完全相同。 对于为组织构建的自定义应用或自定义应用， (LOB 应用) ，请使用 APP_ID Teams 管理中心中的 或使用 图形 API。 的 清单APP_ID中的 validDomains 数组必须包含 的域（url如果 url 存在于深层链接 URL 中）。 当从选项卡或机器人调用对话框时，应用 ID 已经是已知的，这就是为什么它未包含在 中 TaskInfo的原因。
BOT_APP_ID string 否 如果指定了 completionBotId 的值，则使用 task/submit invoke 消息将 result 对象发送到指定的机器人。 指定 BOT_APP_ID 必须在应用的清单中指定为机器人，无法将其发送到任何机器人。

注意

APP_ID 在许多情况下 BOT_APP_ID ，如果应用有一个建议的机器人用作应用的 ID，并且如果有机器人，则和 可以相同。

生成深层链接以将内容共享到会议阶段

还可以生成深层链接，以 共享应用以暂存 和开始或加入会议。

有关将内容共享到阶段的深层链接，请参阅 在会议中将内容共享到阶段的深层链接。

注意

  • 生成用于在会议中将内容共享到阶段的深层链接仅在 公共开发人员预览版中可用。
  • 仅在 Teams 桌面客户端中支持用于将内容共享到会议阶段的深层链接。

可以在会议中生成 指向会议侧面板 的深层链接。 使用以下格式进行到会议端面板的深层链接：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>.

示例：

https://teams.microsoft.com/l/entity/fe4a8eba-2a31-4737-8e33-e5fae6fee194/tasklist123?webUrl=https://tasklist.example.com/123/456&label=Task 456&context={"chatId": "17:b42de192376346a7906a7dd5cb84b673@thread.v2","contextType":"chat"}

默认情况下，深层链接在会议侧面板中打开。 若要直接在应用而不是会议端面板中打开深层链接，请添加 openInMeeting=false 深层链接格式：

https://teams.microsoft.com/l/entity/<appId>/<entityId>?webUrl=<entityWebUrl>&label=<entityLabel>&context=<context>&openInMeeting=false

有关详细信息，请参阅 指向选项卡的深层链接。

在以下情况下，深层链接不会在会议侧面板中打开：

  • 没有活动会议。
  • 应用未 sidePanel 在应用清单中声明上下文。
  • openInMeeting 在深层链接中设置为 false 。
  • 深层链接在会议窗口或组件之外选择。
  • 深层链接与当前会议不匹配，例如，如果深层链接是从另一个会议创建的。

可以通过在 API 中 app.openLink(url) 包装深层链接 URL，从选项卡中通过深层链接调用 Stageview。 也可以通过卡片中的 OpenURL 操作传递深层链接。 API openMode 中定义的 属性确定 Stageview 响应。 有关详细信息，请参阅 通过深层链接调用 Stageview。

代码示例

示例名称 Description .NET Node.js
使用子实体 ID 的深层链接 此示例演示如何使用从机器人聊天到使用子实体 ID 的选项卡的深层链接。 它还显示了以下项的深层链接：
- 导航到应用
- 导航到聊天
- 打开配置文件对话框
- 打开计划对话框		 View View