Microsoft Teams 应用疑难解答

项目
10/28/2024

排查选项卡问题

访问开发工具

可以在 Teams 客户端中打开开发工具，获得与在 Windows) 上按 F12 (或 MacOS 上的 Command-Option-I (类似的体验) 。

空白选项卡屏幕

如果未在选项卡视图中看到内容，则可能是：

内容不能显示在中 <iframe>。
内容域不在清单中的 validDomains 列表中。

注意

当给定的选项卡 URL 重定向到登录屏幕时，将显示一个空白选项卡。登录页不会在 iFrame 中呈现，以防范点击劫持。身份验证逻辑必须使用重定向以外的方法。

对我的 Web 应用的更改不会反映在其 Teams 选项卡中

如果在 Teams 选项卡中托管 Web 应用时遇到一致或间歇性缓存问题，请检查服务器缓存设置并使用Cache-Control标头来确保所需的客户端缓存行为。

设置对话框中未启用“保存”按钮

确保在用户输入或选择设置页上的所有必需数据后调用 microsoftTeams.settings.setValidityState(true) ，以启用“保存”按钮。

选择“保存”时无法保存选项卡设置

添加选项卡时，如果选择“ 保存” ，但收到一条指示无法保存设置的错误消息，则问题可能是以下两类问题之一：

从未收到保存成功消息：如果使用注册保存 microsoftTeams.settings.registerOnSaveHandler(handler)处理程序，则回调必须调用 saveEvent.notifySuccess()。
- 如果回调未在 30 秒内调用 saveEvent.notifySuccess() ，或改为调用 saveEvent.notifyFailure(reason) ，则显示此错误。
- 如果未注册保存处理程序，当用户选择“保存”saveEvent.notifySuccess()时，将自动调用。
提供的设置无效：无法保存设置的另一个原因是，对提供的设置对象无效的调用 microsoftTeams.setSettings(settings) ，或者根本不进行调用。请参阅下一部分：设置对象的常见问题。

设置对象的常见问题

settings.entityId 缺少。此字段属于必填字段。
settings.contentUrl 缺少。此字段属于必填字段。
settings.contentUrl 或可选的 settings.removeUrl、或 settings.websiteUrl 都提供，但无效。 URL 必须使用 HTTPS，并且必须与设置页的域相同，或者在清单 validDomains 列表中指定。

无法对用户进行身份验证或在选项卡中显示身份验证提供程序

除非你正在执行无提示身份验证，否则必须遵循 Microsoft Teams JavaScript 客户端库提供的身份验证过程。

注意

我们要求所有身份验证流在域上开始和结束，必须在清单中的对象中 validDomains 列出。

有关身份验证的详细信息，请参阅如何对用户进行身份验证。

静态选项卡未显示

有一个已知问题，即使用新的或更新的静态选项卡更新现有机器人应用不会在从个人聊天对话访问应用时显示该选项卡更改。若要查看更改，应在新用户或测试实例上进行测试，或者从“应用”浮出控件访问机器人。

对机器人进行故障排除

无法添加机器人

应用必须由 Microsoft 365 租户管理员启用，最终用户才能加载应用。在某些情况下，Microsoft 365 租户可能有多个关联的 SKU，并且机器人若要在任何 SKU 中工作，必须在所有 SKU 中启用它们。有关详细信息，请参阅准备 Microsoft 365 租户。

无法将机器人添加为团队成员

必须先在团队中上传机器人，然后才能在该团队的任何频道中访问机器人。有关此过程的详细信息，请参阅如何在团队中上传应用。

我的机器人无法在频道中获取我的消息

通道中的机器人仅在显式 @mentioned接收消息时接收消息，即使你正在回复以前的机器人消息也是如此。在消息中可能不会看到机器人名称的唯一例外是，如果机器人收到由于它最初发送的 CardAction 而执行的操作 imBack 。

在通道中时，机器人无法理解我的命令

由于通道中的机器人仅在为时 @mentioned接收消息，因此机器人在通道中接收的所有消息都包含 @mention 在文本字段中的消息。最佳做法是在传递到分析逻辑之前，将机器人名称本身从所有传入的文本消息中去除。查看提及，获取有关如何处理此情况的提示。

打包和上传问题

读取manifest.json时出错

大多数清单错误都会提示缺少或无效的特定字段。但是，如果 JSON 文件根本无法读取为 JSON，则会使用此通用错误消息。

清单读取错误的常见原因：

无效的 JSON。使用自动验证 JSON 语法的 IDE（如 Visual Studio Code 或 Visual Studio）。
编码问题。对 manifest.json 文件使用 UTF-8。其他编码（特别是使用 BOM）可能不可读。
.zip 包格式不正确。 manifest.json文件必须位于 .zip 文件的顶层。请注意，默认 Mac 文件压缩可能会将 manifest.json 放在子目录中，而子目录中不会正确加载Microsoft Teams。

存在具有相同 ID 的另一个扩展

如果尝试再次上传具有相同 ID 的更新包，请选择选项卡表行末尾的 “替换 ”图标，而不是“ 上传 ”按钮。

如果不重新上传更新的包，请确保 ID 是唯一的。

在 Teams 中上传应用时出错

如果在将应用上传到团队时收到 清单分析失败 错误消息，请使用 Teams 应用验证程序验证应用包，包括应用清单和 OpenAPI 规范文件。查看应用清单和 OpenAPI 说明 (OAD) 解决错误或警告的要求，并尝试上传应用。
如果在 Teams 中运行应用时遇到任何问题，请使用以下故障排除步骤来识别并解决问题：
- 网络：选择开发人员工具中的“网络”选项卡以检查网络活动
  1. 打开 Teams Web 客户端。
  2. 使用 Microsoft 365 凭据登录。
  3. 转到聊天，并运行消息扩展应用。
  4. 在右上角，选择“设置和更多 (...) ”。转到“更多工具>开发人员工具。
  5. 选择“网络”。选择 筛选器 选项，并在搜索字段中输入 invoke 。
  6. 从列表中选择错误。
  7. 在右窗格中，选择“ 响应 ”选项卡。
  8. 将显示表示来自服务或 API 的错误响应的 JSON 对象。它包含具有 standardizedErrorerrorCode、 errorSubCode和 errorDescription的对象，这些对象具有有关错误的更多详细信息。
  常见 HTTP 错误响应：
  - 如果请求参数缺失或格式不正确，则可能会出现 400 错误请求错误。
  - “401 未授权”或“403 禁止访问”错误表示 API 密钥存在问题，例如缺少或未经授权。
  - 500 内部服务器错误指示由于服务器端问题，服务不知道如何响应。
使用工具进行故障排除：如果网络跟踪中的信息不足，可以按照 OpenAPI 说明文档构造请求，并在必要时使用 Swagger 编辑器或 Postman 等工具来测试请求，包括 API 密钥的授权标头。

如果无法解决这些错误，我们建议联系 Microsoft Teams 产品支持部门，以获取进一步的帮助。

通过