教程

在本文中，详细了解如何构建 Teams 应用功能。下面是可用于 Teams 平台功能的分步指南列表。

#	功能	分步操作指南
1.	机器人	- 使用 Microsoft 365 智能体操场调试 AI 聊天机器人 - 发送主动消息
2.	消息扩展	- 生成基于 API 的消息扩展 - 构建基于操作的消息扩展 - 使用 JavaScript 构建你的第一个消息扩展应用
3.	点按	使用 C sharp 构建你的第一个标签页应用
4.	SSO	- 使用 SSO 身份验证生成机器人程序 - 将 SSO 添加到选项卡和消息扩展应用

构建首个机器人应用

使用你的第一个 Microsoft Teams 应用开始 Microsoft Teams 应用开发。可以使用 Javascript 与 Teams 一起创建机器人应用。

首个机器人

应用具有一项功能，该功能附带自己的 UI 和 UX：

图中显示此应用具有三个功能。

在本教程中，将学习：

如何使用 Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 设置新项目。
如何构建机器人程序应用。
如何部署应用。

先决条件

确保安装以下用于构建和部署应用的工具。

	安装	对于使用...
必选
	Microsoft 365 代理工具包	可为应用创建项目基架的 Microsoft Visual Studio Code 扩展。使用最新版本。
	Microsoft Teams	Microsoft Teams 通过聊天、会议和通话应用与与你协作的每个人。
	Node.js	后端 JavaScript 运行时环境。有关详细信息 Node.js 请参阅项目类型的版本兼容性表。
	Microsoft Edge (推荐的) 或 Google Chrome	具有开发人员工具的浏览器。
	Visual Studio Code	JavaScript、TypeScript 或 SharePoint 框架 (SPFx) 生成环境。使用最新版本。
可选
	适用于 Visual Studio Code 和 Azure CLI 的 Azure 工具	用于访问存储的数据或为 Azure 中的 Teams 应用部署基于云的后端的 Azure 工具。
	适用于 Chrome 的 React 开发人员工具或适用于 Microsoft Edge 的 React 开发人员工具	用于开源 React JavaScript 库的浏览器 DevTools 扩展。
	Microsoft Graph 资源管理器	Microsoft Graph 资源管理器，一个基于浏览器的工具，可让你从 Microsoft Graph 数据运行查询。
	Teams 开发者门户	基于 Web 的门户，用于配置、管理和发布 Teams 应用，包括到组织或 Microsoft Teams 应用商店。

提示

如果使用 Microsoft Graph 数据，则应了解 Microsoft Graph 资源管理器并为其添加书签。使用此基于浏览器的工具，可以在应用外部查询 Microsoft Graph。

创建先决条件

安装所需工具后，设置开发环境。

安装 Microsoft 365 代理工具包

Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 通过为应用预配和部署云资源并发布到 Teams 应用商店的工具来帮助简化开发过程。

可以将 Agents Toolkit 与 Visual Studio Code 或名为 Microsoft 365 Agents Toolkit CLI (以前称为 TeamsFx CLI) 的命令行界面一起使用。

Visual Studio Code
命令行

打开 Visual Studio Code，然后选择“扩展” (Ctrl+Shift+X 或“查看>扩展) ”。
在搜索框中输入 Microsoft 365 代理工具包。
选择“安装”。

Microsoft 365 Agents Toolkit 图标显示在 Visual Studio Code 活动栏中。

还可以从 Visual Studio Code Marketplace 安装 Agents Toolkit。

要安装 Agents Toolkit CLI，请使用包管理器并在 npm 命令提示符中输入以下命令：

npm install -g @microsoft/m365agentstoolkit-cli

根据配置，可能需要使用来 sudo 安装 CLI：

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

这种情况在 Linux 和 macOS 系统上更为常见。

确保将 npm 全局缓存添加到 PATH。此步骤通常作为 Node.js 安装程序的一部分完成。

可以将 CLI 与命令 atk 一起使用。运行验证atk -h命令是否正常工作。

警告

必须先为 PowerShell 启用 远程签名 执行策略，然后才能在 PowerShell 终端中运行 TeamsFx。

设置 Teams 开发租户

租户是组织在 Teams 中的空间或容器，可在其中聊天、共享文件和举行会议。此空间也是上传和测试应用的地方。让我们验证一下你是否准备好与租户一起开发。

检查“上传应用”选项

创建自定义应用后，必须使用“ 上传自定义应用” 选项将应用上传到 Teams。登录 Microsoft 365 帐户以检查此选项是否已启用。

以下步骤可帮助验证是否可以在 Teams 中上传应用：

在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果该选项可见，则可以上传自定义应用。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户

如果没有 Teams 开发人员帐户，请加入 Microsoft 365 开发人员计划。这是一个可选步骤。

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕：
使用刚刚设置的管理员帐户登录到 Teams。验证你是否在 Teams 中具有 “上传自定义应用” 选项。

获取免费的 Azure 帐户

如果想要在 Azure 中托管应用或访问资源，则必须具有 Azure 订阅。在开始之前创建一个免费帐户。

现在，你拥有了设置帐户的所有工具。接下来，让我们设置开发环境并开始构建！首先选择要创建的应用。

为机器人应用创建项目工作区

让我们创建你的第一个机器人应用。

Teams 应用的机器人功能可创建聊天机器人或对话机器人。您可以使用它来运行简单和自动化的任务，例如提供客户服务。机器人与 Web 服务通信并帮助你使用其产品/服务。您可以获取天气预报、进行预订或使用对话机器人提供的任何其他服务。

图中显示此应用具有三个功能。突出显示机器人。

由于已准备好创建这些应用，因此可以设置新的 Teams 项目来创建机器人应用。

本教程介绍：

如何使用 Agents Toolkit 设置新的机器人程序项目。
关于应用项目的目录结构。

重要

由世纪互联环境运营的政府社区云 (GCC) 、GCC High、国防部 (国防部) 和团队中均可使用机器人。

创建机器人程序项目工作区

如果先决条件到位，让我们开始吧！

注意

显示的 Visual Studio Code UI 来自 Mac。它可能因操作系统、Agents Toolkit 版本和环境而异。

Visual Studio Code
命令行

打开 Visual Studio Code。
选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
选择“新建代理/应用>”Teams 应用。
选择 机器人 程序以创建新的机器人程序项目。
确保选择基本 机器人 作为要在应用中生成的应用功能。
选择 JavaScript 作为编程语言。
选择 “默认文件夹 ”以将项目根文件夹存储在默认位置。

还可以通过以下步骤更改默认位置：
1. 选择“浏览”。
2. 选择项目工作区的位置。
3. 选择 “选择”文件夹。
为应用输入合适的名称，然后选择 Enter。

将出现一个对话框，您需要选择“是”或“否”才能信任此文件夹中文件的作者。

屏幕截图显示了信任与否信任此文件夹中文件的作者的对话框。

具有机器人功能的 Teams 应用将在几秒钟内创建。

屏幕截图显示创建的应用。

创建应用后，Agents Toolkit 将显示以下消息：

屏幕截图显示功能已成功创建的消息。

选择 “本地调试” 以预览项目。

创建 Teams 应用的快速回顾。

观看此有关创建 Teams 应用的简短回顾。

创建 Teams 应用

使用“atk”CLI 创建你的第一个项目。从要在其中创建项目文件夹的文件夹开始。

atk new

可以使用 CLI 创建新的 Teams 应用。 CLI 将引导你解决一系列问题。每个问题都包含回答说明。

例如，使用箭头键选择一个选项。做出选择后，选择 Enter 进行确认。

选择“ 创建新的 Teams 应用”。
选择 Bot 并取消选择 Tab。
选择 JavaScript 作为编程语言。
选择 Enter 以选择默认工作区文件夹。
输入适用于应用的名称，如 HelloBot。应用的名称必须仅包含字母数字字符。

回答所有问题后，创建项目。

了解机器人应用源代码

基架完成后，在 Visual Studio Code 的资源管理器中查看项目目录和文件。

屏幕截图显示了文件夹结构。

文件夹 / 文件	目录
`m365agents.yml`	主项目文件
`m365agents.local.yml`	这将覆盖 `m365agents.yml` 启用本地执行和调试的操作。
`.vscode/`	用于本地调试的 VSCode 文件。
`appPackage/`	Teams 应用程序清单的模板。
`adaptiveCards/`	机器人发回的自适应卡。
`infra/`	用于预配 Azure 资源的模板。
`index.js`	应用程序入口点和 `express` 处理程序。
`teamsBot.js`	Teams 活动处理程序。

提示

在将第一个机器人集成到 Teams 中之前，请先熟悉 Teams 外部的机器人。

生成并运行你的第一个机器人应用

使用 Agents Toolkit 设置项目工作区后，生成机器人程序项目。你需要登录到 Microsoft 365 帐户。

使用此帐户登录 Teams。如果使用的是 Microsoft 365 开发人员计划租户，则注册时设置的管理员帐户是 Microsoft 365 帐户。

Visual Studio Code
命令行

打开 Visual Studio Code。
选择边栏中的 Microsoft 365 Agents Toolkit 图标。
选择“使用凭据 登录到 M365 ”。

此时将打开默认 Web 浏览器，以登录该帐户。
出现提示时关闭浏览器并返回到 Visual Studio Code。
返回到 Visual Studio Code 中的代理工具包。

使用此帐户登录 Teams。如果使用的是 Microsoft 365 开发人员计划租户，则注册时设置的管理员帐户是 Microsoft 365 帐户。

现在已准备好生成应用并在本地运行它！

使用 Microsoft 365 Agents Toolkit CLI 登录 Microsoft 365 (以前称为 TeamsFx CLI) ：

atk account login m365

此时将打开默认 Web 浏览器，以登录该帐户。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

帐户登录名在 Visual Studio Code 和 Agents Toolkit CLI 之间共享。

现在，开发环境已配置完成，可以创建、生成和部署你的第一个 Teams 应用。

在本地生成并运行你的第一个机器人应用

若要在本地环境中生成并运行应用，请执行以下操作：

在 Visual Studio Code 中选择 F5 以在调试模式下运行应用。

注意

如果 Agents Toolkit 无法检查特定的先决条件，它会提示您进行检查。
了解在调试器中本地运行应用时会发生什么。

如果你想知道，按 F5 键时，代理工具包会：
1. 检查以下所有先决条件：
- 你已使用 Microsoft 365 帐户登录。
- 已为 Microsoft 365 帐户启用自定义应用上传。
- 已安装受支持 Node.js 版本。
- 机器人程序应用所需的端口可用。
1. 安装 npm 包。
2. 启动开发隧道以创建 HTTP 隧道。
3. 在 Microsoft Entra ID 中注册应用并配置应用。
4. 在 Bot Framework 中注册机器人程序应用并配置机器人程序应用。
5. 在 Teams 开发人员门户中注册应用并配置应用。
6. 启动机器人程序应用。
7. 在 Web 浏览器中启动 Teams 并上传自定义机器人应用。
注意

首次运行应用时，下载所有依赖项，并生成应用。生成完成后，浏览器窗口将自动打开。此过程可能需要 3 到 5 分钟才能完成。

Teams 在 Web 浏览器中运行应用。
如果出现提示，请使用 Microsoft 365 帐户登录。
选择“ 添加 ”，将自定义机器人应用上传到 Teams。
选择 “打开 ”以在个人范围内打开应用。

或者，可以搜索并选择所需的范围，或从列表中选择频道、聊天或会议，然后在对话框中移动以选择“ 转到”。

现在，机器人已在 Teams 上成功运行！加载应用后，将打开与机器人的聊天会话。

可以键入welcome以显示介绍卡，键入learn以转到自适应卡和机器人命令文档。

可以像处理任何其他 Web 应用程序一样执行正常的调试活动，例如设置断点。打开文件 bot/teamsBot.js 并找到方法 onMessage() 。在任何情况下设置断点。然后，键入一些文本。

了解如何在应用未在本地运行时进行故障排除。

若要在 Teams 中成功运行应用，请确保已在 Teams 帐户中启用自定义应用上传。可以在先决条件部分了解有关自定义应用上传的详细信息。

重要

自定义应用上传在政府社区云 (GCC) 中可用，在 21Vianet 运营的 GCC High、DoD 和 Teams 中不受支持。

提示

在上传自定义应用之前，请使用应用验证工具检查问题。该工具包含在工具包中。修复错误以上传应用。

部署你的第一个 Teams 应用

你已了解如何使用机器人功能创建、生成和运行 Teams 应用。最后一步是在 Azure 上部署应用。

让我们使用代理工具包在 Azure 上部署第一个具有机器人功能的应用。

使用此帐户访问 Microsoft Azure 门户并预配新的云资源以支持你的应用。

Visual Studio Code
命令行

打开 Visual Studio Code。
打开在其中创建机器人程序应用的项目文件夹。
选择边栏中的 Microsoft 365 Agents Toolkit 图标。
选择“使用凭据登录到 Azure”。

提示

如果已安装 AZURE 帐户扩展并使用同一帐户，则可以跳过此步骤。使用与其他扩展中使用的相同帐户。

此时将打开默认 Web 浏览器，以登录该帐户。
出现提示时关闭浏览器并返回到 Visual Studio Code。

边栏的 ACCOUNTS 部分分别显示两个帐户。它还列出了可用的可用 Azure 订阅数量。确保至少有一个可用的可用 Azure 订阅。如果没有，请注销并使用其他帐户。

恭喜，你已创建 Teams 应用！现在，让我们继续学习如何使用 Agents Toolkit 将其中一个应用部署到 Azure。

使用代理工具包 CLI 登录到 Microsoft 365：

atk account login m365

此时将打开默认 Web 浏览器，以登录该帐户。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

使用代理工具包 CLI 登录到 Azure：

atk account login azure

此时将打开默认 Web 浏览器，以登录该帐户。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

帐户登录名在 Visual Studio Code 和 Agents Toolkit CLI 之间共享。

恭喜，你已登录 Azure 帐户！现在，让我们继续学习如何使用 Agents Toolkit 将其中一个应用部署到 Azure。

在 Azure 上预配和部署应用

部署包括两个步骤。首先，Azure创建必要的云资源 (也称为预配) 。然后，Azure 将应用的代码复制到创建的云资源中。在本教程中，您将部署机器人程序应用。

预配和部署之间有何区别？

“预配”步骤在 Azure 和 Microsoft 365 中为应用创建资源，但不会将 HTML、CSS 或 JavaScript) (代码复制到资源。部署步骤会将应用的代码复制到预配步骤中创建的资源。多次部署而不预配新资源是很常见的。由于预配步骤可能需要一些时间才能完成，因此它与部署步骤是分开的。

Visual Studio Code
命令行

选择 Visual Studio Code 边栏中的 Microsoft 365 Agents Toolkit 图标。

选择 “预配”。
选择要用于 Azure 资源的订阅。

你的应用使用 Azure 资源托管。

对话框警告你在 Azure 中运行资源时可能会产生成本。
选择 “预配”。

预配过程在 Azure 云中创建资源。这可能需要一些时间。可以通过观看右下角的对话框来监视进度。几分钟后，你会看到以下通知：

如果需要，可以查看预配的资源。对于本教程，无需查看资源。

预配的资源将显示在 ENVIRONMENT 部分中。
预配完成后，从 LIFECYCLE 面板中选择“部署”。

与预配一样，部署需要一些时间。您可以通过观看右下角的对话框来监视该过程。几分钟后，你将看到完成通知。

现在，可以使用相同的过程将机器人和消息扩展应用部署到 Azure。

在终端窗口中：

运行 atk provision.
```
atk provision
```
出现提示时，请选择 Azure 订阅以使用 Azure 资源。

你的应用使用 Azure 资源托管。
运行 atk deploy.
```
atk deploy
```

运行部署的应用

预配和部署步骤完成后：

(Ctrl+Shift+D / ⌘⇧-D 打开调试面板，或>从 Visual Studio Code 查看运行) 。
从启动配置下拉列表中选择启动 远程 (Edge) 。
选择“ 开始调试 (F5) ”。系统会提示你将自定义机器人应用上传到 Teams。
选择“添加”。
选择 “打开 ”以在个人范围内打开应用。

或者，可以搜索并选择所需的范围，或从列表中选择频道、聊天或会议，然后在对话框中移动以选择“ 转到”。

已成功将机器人应用添加到 Teams 客户端。

了解将应用部署到 Azure 时会发生什么

在部署之前，应用程序已在本地运行：

后端使用 Azure Functions 核心工具运行。
应用程序 HTTP 终结点（Microsoft Teams 在其中加载应用程序）在本地运行。

部署过程分为两步。在活动 Azure 订阅上预配资源，然后将应用程序的后端和前端代码部署或上传到 Azure。

后端（如果配置）使用各种 Azure 服务，包括 Azure 应用服务和 Azure 存储。
前端应用程序部署到为静态 Web 托管配置的 Azure 存储帐户。

恭喜！

成功了！

你已创建了一个机器人应用。

现在您已经学会了创建基本应用，您可以继续创建更复杂的应用。你已完成使用 JavaScript 生成机器人的教程。

教程

使用 Microsoft 365 智能体操场调试 AI 聊天机器人

使用 Teams AI 聊天机器人应用开始 Microsoft Teams 应用开发，并使用 Microsoft 365 智能体操场 (以前称为 Teams 应用测试工具) 进行调试。 Agents Playground 使调试基于机器人的应用程序变得轻松。无需 Microsoft 365 开发人员帐户、隧道或 Teams 应用和机器人注册即可使用 Agents Playground。

教程：调试 AI 聊天机器人

先决条件

你可以与机器人聊天，并查看 Teams 中显示的消息和自适应卡片。您还可以使用活动触发器模拟 Agents Playground 中的活动。

注意

Agents Playground 仅在 Microsoft 365 Agents Toolkit 的 v5.4.0 中可用 (以前称为 Teams Toolkit) 。
Agents Playground 仅支持桌面和 Web 客户端。

本分步指南可帮助你使用 Agents Toolkit 构建 AI 聊天机器人，并使用测试工具进行调试。完成本指南后，你将看到以下输出，用户可以在其中访问和使用 AI 聊天机器人：

安装	对于使用...
Visual Studio Code 或 Visual Studio	JavaScript、TypeScript 或 C# 生成环境。使用最新版本。
Microsoft 365 代理工具包	可为应用创建项目基架的 Microsoft Visual Studio Code 扩展。使用 Agents Toolkit v5.4.0。有关详细信息，请参阅安装代理工具包。
Node.js	后端 JavaScript 运行时环境。有关详细信息 Node.js 请参阅项目类型的版本兼容性表。
OpenAI 或 Azure OpenAI	首先创建 OpenAI API 密钥以使用 OpenAI 的 GPT。若要托管应用或访问 Azure 中的资源，则必须创建 Azure OpenAI 服务。
Microsoft Edge (推荐的) 或 Google Chrome	具有开发人员工具的浏览器。

为 AI 聊天机器人应用创建项目工作区

Teams 应用的机器人功能可创建聊天机器人或对话机器人。它与 Web 服务通信，方便使用其服务。机器人可以执行简单的自动化任务，例如提供客户服务。您可以获取天气预报、进行预订或使用对话机器人提供的任何其他服务。

屏幕截图显示了具有三个功能的应用。突出显示机器人。

由于已准备好创建这些应用，因此可以设置新的 Teams 项目来创建 AI 聊天机器人应用。

创建机器人程序项目工作区

如果先决条件到位，让我们开始吧！

打开 Visual Studio Code。
选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
选择“ 创建新的代理/应用”。
选择 TeamsAzure>OpenAI> 的代理立即输入 Azure API 服务密钥
选择 Teams 的基本代理。如果机器人需要其他功能，请选择所需的选项。
选择编程语言作为 JavaScript。
选择 “默认文件夹”。

若要更改默认位置，请执行以下步骤：
1. 选择“浏览”。
2. 选择项目工作区的位置。
3. 选择 “选择文件夹”。
为应用输入合适的名称，然后选择 Enter 键。

将出现一个对话框，您需要在其中选择“是”或“否”才能信任此文件夹中文件的作者。

现在，你已成功创建 AI 聊天机器人项目工作区。

了解机器人应用源代码

完成基架后，浏览 Visual Studio Code 的“资源管理器”部分中的项目目录和文件。

屏幕截图显示了 Teams 工具包示例机器人文件夹结构。

文件夹或文件名	目录
`env/.env.playground`	包含可提交到 Git 的环境变量的配置文件。
`env/.env.playground.user`	包含环境变量（包括凭据）的配置文件，默认情况下不会提交到 Git。
`appPackage`	应用清单模板文件和应用图标 (color.png 和 outline.png) 。
`appPackage/manifest.json`	用于在本地和远程环境中运行应用的应用清单。
`src/app.js`	处理 AI 聊天机器人的业务逻辑。
`m365agents.yml`	这是主的 Agents Toolkit 项目文件。项目文件定义了两个主要内容：属性和配置以及阶段定义。
`m365agents.local.yml`	这将覆盖 `m365agents.yml` 启用本地执行和调试的操作。
`m365agents.playground.yml`	这将覆盖 `m365agents.yml` 在测试工具中启用本地执行和调试的操作。

构建并运行 AI 聊天机器人应用

为 AI 聊天机器人创建 OpenAI 密钥和终结点

转到 Azure 门户。
选择“创建资源”并搜索 Azure OpenAI。
选择“Azure OpenAI”，然后选择“创建”。
填写所需详细信息，然后选择“ 下一步”。
选择 “所有网络（包括 Internet）均可访问此资源” ，然后选择“ 下一步”。
填写所需详细信息，然后选择“ 下一步”。
选择“创建”。

你已成功为 AI 聊天机器人创建密钥和终结点。

屏幕截图显示了 Azure OpenAI 的部署。

注意

您还可以获取 OpenAI API 密钥来调试您的 AI 聊天机器人。

获取 Azure OpenAI 密钥和终结点

选择“ 转到资源”。
从左侧窗格中选择“ 密钥和终结点 ”，然后复制密钥和 终结点。可以复制 密钥 1 或 密钥 2。

保存密钥和 终结点 以供进一步使用。
从左窗格中选择“ 模型部署” ，然后选择“ 管理部署”。

将显示 Azure OpenAI Studio 窗口。
从左窗格中选择 “部署” ，然后选择“ + 创建新部署”。
选择以下详细信息：
1. 从“选择模型”下拉列表中选择 gpt-35-turbo。
  
  注意
  
  AI 聊天机器人仅支持 gpt-35-turbo 模型。
2. 从“模型版本”下拉列表中选择“0301 (默认) ”。
3. 输入 部署名称 并选择创建。
4. 复制并保存 部署名称 供进一步使用。

更新 Azure OpenAI 密钥和终结点

在 Visual Studio Code 中打开项目。
在资源管理器下，转到 env.env.playground.user > 文件。

输入 SECRET_AZURE_OPENAI_API_KEY 和 SECRET_AZURE_OPENAI_ENDPOINT。

...
SECRET_AZURE_OPENAI_API_KEY=<azure-openai-api-key>
SECRET_AZURE_OPENAI_ENDPOINT=<azure-openai-endpoint>

转到 src>app.js 文件。
注释 OpenAI 代码和取消注释 Azure OpenAI 代码。

在中azureDefaultDeployment输入你的 Azure OpenAI 部署名称。


// Use OpenAI
// apiKey: config.openAIKey,
// defaultModel: "gpt-3.5-turbo",

azureApiKey: config.azureOpenAIKey,
azureDefaultDeployment: "gpt-35-turbo",
azureEndpoint: config.azureOpenAIEndpoint,

调试并运行 AI 聊天机器人应用

在左侧窗格中，选择“ 运行并调试 ” (Ctrl+Shift+D) ，然后从下拉列表中选择“在 代理操场中调试 ”。
Agents Playground 将在网页中打开 AI 聊天机器人。

活动触发因素

有两种类型的活动触发器：

预定义的活动触发器

Agents Playground 提供预定义的活动触发器来测试机器人的功能。

类别	活动	处理程序
触发器安装更新活动	安装机器人程序卸载机器人程序	`onInstallationUpdate` `onInstallationUpdateAdded` `onInstallationUpdate` `onInstallationUpdateRemove`
触发对话更新活动	添加用户添加机器人添加频道	`onMembersAdded` `onTeamsMembersAddedEvent` `onMembersAdded` `onTeamsMembersAddedEvent` `onTeamsChannelCreatedEvent`
	删除用户删除机器人程序删除频道删除团队	`onMembersRemoved` `onTeamsMembersRemovedEvent` `onMembersRemoved` `onTeamsMembersRemovedEvent` `onTeamsChannelDeletedEvent` `onTeamsTeamDeletedEvent`
	重命名频道重命名团队	`onTeamsChannelRenamedEvent` `onTeamsTeamRenamedEvent`

注意

并非所有类型的活动都可用于所有范围。例如，无法在个人聊天或群组聊天中添加或删除频道。

预定义的活动触发器可在 Agents Playground 的模拟活动菜单中找到。

要模拟“ 添加用户” 活动，请执行以下步骤：

在 Agents Playground 中，转到 模拟活动添加>用户。

将出现一个对话框，用于预览活动处理程序。
选择 “发送活动”。

机器人程序发送以下响应：

自定义活动触发器

可以使用 自定义活动 来自定义活动触发器，例如， reactionsAdded 以满足机器人程序应用的要求。 Agents Playground 会自动填充活动的所需属性。还可以修改活动类型并添加更多属性。

选择“ 模拟活动>自定义”活动。

添加以 messageReaction 自定义属性下的 type 活动：

{
    "type": "messageReaction",
    "reactionsAdded": [
    {
        "type": "like"
    }
    ],
    "replyToId": "d60fd1cb-3e8f-44ef-849c-404806ba1b47"
}

选择 “发送活动”。

机器人程序在响应中发送 onReactionsAdded 处理程序。

完成挑战

是不是想出了这样的输出？

恭喜！你已成功创建 AI 聊天机器人应用。现在，你已经学会了在 Agents Playground 中调试 AI 聊天机器人应用。

Microsoft 365 智能体操场

返回页首

发送主动消息

主动消息是机器人为响应用户在聊天中发送的简单命令而发送的消息。

教程：发送主动消息

消息响应可以采用以下格式之一：

欢迎消息
计划消息
通知

本分步指南可帮助您从机器人发送主动消息。你将看到以下输出：

屏幕截图显示 Teams 聊天中主动的问候消息。

先决条件

确保安装以下用于生成和部署应用的工具。

	安装	对于使用
	Microsoft Visual Studio Code	JavaScript 或 TypeScript，生成环境。使用最新版本。
	Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit)	可为应用创建项目基架的 Visual Studio Code 扩展。使用最新版本。
	Node.js	后端 JavaScript 运行时环境。有关详细信息 Node.js 请参阅项目类型的版本兼容性表。
	Microsoft Teams	Teams 可通过聊天、会议、通话等所有位置应用与与你协作的每个人。
	Microsoft Edge (推荐的) 或 Google Chrome	具有开发人员工具的浏览器。
	Microsoft 365 开发人员帐户	有权访问 Teams 帐户，并具有安装应用的相应权限。

准备开发环境

安装所需工具后，设置开发环境。

安装 Microsoft 365 代理工具包

Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 通过为应用预配和部署云资源并发布到 Teams 应用商店的工具来帮助简化开发过程。

可以将 Agents Toolkit 与 Visual Studio Code 或名为 Microsoft 365 Agents Toolkit CLI (以前称为 TeamsFx CLI) 的命令行界面一起使用。

Visual Studio Code
命令行

打开 Visual Studio Code，然后选择“扩展” (Ctrl+Shift+X 或“查看>扩展) ”。
在搜索框中输入 Microsoft 365 代理工具包。
选择“安装”。

Microsoft 365 Agents Toolkit 图标显示在 Visual Studio Code 活动栏中。

还可以从 Visual Studio Code Marketplace 安装 Agents Toolkit。

要安装 Agents Toolkit CLI，请使用包管理器并在 npm 命令提示符中输入以下命令：

npm install -g @microsoft/m365agentstoolkit-cli

根据配置，可能需要使用来 sudo 安装 CLI：

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

这种情况在 Linux 和 macOS 系统上更为常见。

确保将 npm 全局缓存添加到 PATH。此步骤通常作为 Node.js 安装程序的一部分完成。

可以将 CLI 与命令 atk 一起使用。运行验证atk -h命令是否正常工作。

警告

必须先为 PowerShell 启用 远程签名 执行策略，然后才能在 PowerShell 终端中运行 TeamsFx。

设置 Teams 开发租户

检查“上传应用”选项

创建自定义应用后，必须使用“ 上传自定义应用” 选项将应用上传到 Teams。登录 Microsoft 365 帐户以检查此选项是否已启用。

以下步骤可帮助验证是否可以在 Teams 中上传应用：

在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果该选项可见，则可以上传自定义应用。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 开发人员帐户，请加入 Microsoft 365 开发人员计划。

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕：
使用刚刚设置的管理员帐户登录到 Teams。验证你是否在 Teams 中具有 “上传自定义应用” 选项。

构建主动消息机器人

若要使用 Visual Studio Code 构建主动消息机器人，请执行以下步骤：

打开 Visual Studio Code。
选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
在左窗格中，选择“ 查看示例”。
从示例列表中，选择“ 主动消息”。可供调试的预生成示例随即打开。
选择“创建”。
选择 “默认文件夹 ”以将项目根文件夹存储在默认位置。

如果要更改默认位置，请执行以下步骤：
1. 选择“浏览”。
2. 选择项目工作区的位置。
3. 选择 “选择文件夹”。
主动消息机器人将在几秒钟内创建，并在右下角显示主动消息机器人成功对话框，并提供调试选项：

屏幕:::
从左上角选择“ 运行和调试 ”图标。
从下拉列表中选择 “ (Edge) 调试 ”或“ (Chrome) 调试 ”。

调试成功后，系统会提示你将主动消息机器人上传到本地计算机上的 Teams。
选择“添加”。
搜索并选择所需的范围，或从列表中选择频道、聊天或会议，然后在对话框中移动以选择“ 转到”。

主动消息机器人应用会上传到 Teams 客户端，并显示以下消息作为对发送的消息的响应。
复制并粘贴 URL，或导航到浏览器中的 URL。主动的问候消息被触发并在聊天中共享。
转到 Teams。你将收到来自机器人的 主动问候 消息。

了解源代码

Agents Toolkit 提供用于生成应用的组件。创建项目后，您可以在 Visual Studio Code 的 EXPLORER 区域查看项目文件夹和文件。

屏幕截图显示结构选项卡。

新项目文件夹包含以下内容：

文件夹 / 文件	目录
`.vscode/`	用于调试的 Visual Studio Code 文件。
`appManifest/`	应用清单的模板 (以前称为 Teams 应用清单) 。
`env/`	名称/值对存储在环境文件中，并 `m365agents.yml` 用于自定义预配和部署规则。
`manifest.json`	用于通过 Teams 开发人员门户发布的应用清单存储在 `Properties/manifest.json`中。
`m365agents.yml`	主项目文件描述应用配置并定义要在每个生命周期阶段运行的操作集。
`m365agents.local.yml`	这将覆盖 `m365agents.yml` 启用本地执行和调试的操作。

部署主动消息机器人

你已了解如何使用主动消息机器人功能构建和运行 Teams 应用。让我们使用 Agents Toolkit 在 Azure 上部署第一个具有主动消息机器人功能的应用。

使用帐户访问 Microsoft Azure 门户并预配新的云资源以支持应用。

打开 Visual Studio Code。
打开在其中创建主动消息机器人应用的项目文件夹。
选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
选择“使用凭据登录到 Azure”。

提示

如果已安装 AZURE 帐户扩展并使用同一帐户，则可以跳过此步骤。

此时将打开默认 Web 浏览器，以登录该帐户。
出现提示时关闭浏览器并返回到 Visual Studio Code。

边栏的 ACCOUNTS 部分分别显示两个帐户。它还列出了可用的可用 Azure 订阅数量。确保至少有一个可用的可用 Azure 订阅。如果没有，请注销并使用其他帐户。

将应用部署到 Azure

部署包括两个步骤。首先，创建必要的云资源 (也称为预配) 。然后，应用的代码被复制到创建的云资源中。在本教程中，您将部署机器人程序应用。

预配和部署之间有何区别？

预配会在 Azure 和 Microsoft 365 中为应用创建资源，但不会将 HTML、CSS 和 JavaScript) (代码复制到资源中。
部署会将应用的代码复制到预配期间创建的资源。多次部署而不预配新资源是很常见的。由于预配可能需要一些时间才能完成，因此它与部署分开。

Visual Studio Code
命令行

选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
在“生命周期”下选择“预配”。
选择现有订阅之一。
选择现有资源组或新建资源组。有关详细信息，请参阅创建资源组。

注意

将弹出一个对话框，提及在 Azure 中运行资源时可能会产生成本。
选择 “预配”。

预配过程在 Azure 云中创建资源。可以在右下角显示的对话框中监视进度。几分钟后，将显示以下对话框：
在“生命周期”下选择“部署”。
选择 “部署”。

部署需要一些时间。可以在右下角显示的对话框中监视进度。几分钟后，将显示以下对话框。
(Ctrl+Shift+D / ⌘⇧-D 打开调试面板，或>从 Visual Studio Code 查看运行) 。
从启动配置下拉列表中选择启动 远程 (Edge) 。

调试成功后，系统会提示你将主动消息机器人应用上传到 Teams。
选择“添加”。
搜索并选择所需的范围，或从列表中选择频道、聊天或会议，然后在对话框中移动以选择“ 转到”。

主动消息机器人应用会上传到 Teams 客户端，并显示以下消息作为对发送的消息的响应。
复制并粘贴 URL，或导航到浏览器中的 URL。主动的问候消息被触发并在聊天中共享。
转到 Teams。你将收到来自机器人的 主动问候 消息。

在终端窗口中：

运行 atk new 以创建新项目。

atk new

运行 atk provision 以创建 Azure 资源。

atk provision

运行 atk deploy 以部署应用。

atk deploy

atk preview运行以运行应用。

atk preview

完成挑战

你是想出这样的东西吗？

屏幕截图显示主动问候消息。

你已完成此方案。

您可以每天发送通知或定期请求用户反馈。
可以处理限制以避免多个通知。

发送主动消息

返回页首

生成基于 API 的消息扩展

使用基于 API (API 生成的消息扩展) 允许 Teams 应用与外部服务交互，从而显著增强了它们的功能。基于 API 的消息扩展可以通过减少在不同应用程序之间切换的需要来帮助简化工作流程。

教程：生成基于 API 的消息扩展

注意

基于 API 的消息扩展仅支持搜索命令。

您可以使用基于 API 的消息扩展来集成业务工作流中常用的外部服务。例如，经常使用 CRM 系统进行客户管理的企业可以使用消息扩展直接从 Teams 获取和显示客户数据。该应用程序通过减少在不同应用程序之间切换的需要来帮助节省时间并提高效率。 Teams 可用的所有平台（包括桌面、Web 和移动设备）都支持此功能。

生成消息扩展的先决条件

下面是生成和部署应用所需的工具列表。

安装	对于使用...
Microsoft Teams	Microsoft Teams 可通过聊天、会议或通话应用与与你协作的所有人 - 全部集中在一个位置。
Microsoft Edge (推荐的) 或 Google Chrome	具有开发人员工具的浏览器。
Visual Studio Code	JavaScript、TypeScript 或 SharePoint 框架 (SPFx) 生成环境。使用版本 1.55 或更高版本。
Microsoft 365 开发人员帐户	有权访问 Teams 帐户，并具有安装应用的相应权限。
Azure 帐户	访问 Azure 资源。
OAD) 文档 (OpenAPI 说明	描述 API 功能的文档。有关详细信息，请参阅 OpenAPI 说明。

设置 Teams 开发租户

租户就像 Teams 中组织的空间或容器，可在其中聊天、共享文件和举行会议。此空间也是上传和测试自定义应用的地方。让我们验证一下你是否准备好与租户一起开发。

检查自定义应用上传选项

创建应用后，必须在 Teams 中加载应用而不分发应用。此过程称为自定义应用上传。登录 Microsoft 365 帐户以查看此选项。

注意

在 Teams 本地环境中预览和测试应用需要自定义应用上传。如果未启用，则无法在 Teams 本地环境中预览和测试应用。

是否已有租户，是否具有管理员访问权限？让我们检查一下你是否真的这样做！

验证是否可以在 Teams 中上传自定义应用：

在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果看到该选项，则表示已启用自定义应用上传。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 开发人员帐户，可以免费获取。加入 Microsoft 365 开发人员计划！

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕。
使用刚刚设置的管理员帐户登录到 Teams。验证你是否在 Teams 中具有 “上传自定义应用” 选项。

获取免费的 Azure 帐户

如果想要在 Azure 中托管应用或访问资源，则必须具有 Azure 订阅。在开始之前创建一个免费帐户。

你拥有设置帐户的所有工具。接下来，让我们设置开发环境并开始构建！选择要首先生成的应用。

创建 OpenAPI 说明文档

OpenAPI 说明 (OAD) 是行业标准规范，概述了 OpenAPI 文件的结构和概述。它是一种与语言无关、可读的格式，用于描述 API。人类和机器都可以轻松读取和写入。架构是机器可读的，并以 YAML 或 JSON 表示。

若要与 API 交互，需要 OpenAPI 说明文档。 OpenAPI 说明文档必须满足以下条件：

auth不得指定该属性。
JSON 和 YAML 是支持的格式。
支持 OpenAPI 版本 2.0 和 3.0.x。
Teams 不支持 oneOf、anyOf、allOf 和 (swagger.io) 构造。
不支持为请求构造数组，但支持 JSON 请求正文中的嵌套对象。
请求正文（如果存在）必须是应用程序/Json，以确保与各种 API 兼容。
定义属性的 servers.url HTTPS 协议服务器 URL。
仅支持单个参数搜索。
只允许一个没有默认值的必需参数。
仅支持 POST 和 GET HTTP 方法。
OpenAPI 说明文档必须具有 operationId.
如果没有默认值，操作不得要求 Header 或 Cookie 参数。
一个命令必须只有一个参数。
确保 OpenAPI 说明文档中没有远程引用。

具有默认值的必需参数被视为可选参数。

我们使用以下 OpenAPI 说明作为本教程的示例：

OpenAPI 说明

    openapi: 3.0.1
    info:
    title: OpenTools Plugin
    description: A plugin that allows the user to find the most appropriate AI tools for their use cases, with their pricing information.
    version: 'v1'
    servers:
        - url: https://gptplugin.opentools.ai
    paths:
    /tools:
    get:
    operationId: searchTools
    summary: Search for AI Tools
        parameters:
        - in: query
          name: search
          required: true
          schema:
          type: string
          description: Used to search for AI tools by their category based on the keywords. For example, a search for "tool to create music" provides a list of tools that can create music.
        responses:
        "200":
          description: OK
          content:
          application/json:
            schema:
            $ref: '#/components/schemas/searchToolsResponse'
        "400":
          description: Search Error
          content:
          application/json:
            schema:
            ref: '#/components/schemas/searchToolsError'
        components:
        schemas:
        searchToolsResponse:
        required:
        - search
        type: object
        properties:
        tools:
        type: array
        items:
        type: object
        properties:
        name:
        type: string
        description: The name of the tool.
        opentools_url:
        type: string
        description: The URL to access the tool.
        main_summary:
        type: string
        description: A summary of what the tool is.
        pricing_summary:
        type: string
        description: A summary of the pricing of the tool.
        categories:
        type: array
        items:
        type: string
        description: The categories assigned to the tool.
        platforms:
        type: array
        items:
        type: string
        description: The platforms that this tool is available on.
        description: The list of AI tools.
        searchToolsError:
        type: object
        properties:
        message:
        type: string
        description: Message of the error.

注意

确保该 required: true 属性仅可用于一个参数。如果有多个必需参数，您可以将其他参数的必需属性更新为 required: false 。

可以验证 OpenAPI 说明文档是否有效。要进行验证，请执行以下步骤：

转到 Swagger 或 OpenAPI 验证程序并验证 OpenAPI 说明文档。
保存 OpenAPI 说明文档。
转到 Swagger 编辑器。
在左窗格中，将 OpenAPI 说明粘贴到编辑器中。
在右窗格中，选择“ 获取”。
选择 “试用”。
将搜索参数的值输入为工具以 创建音乐。
选择 “执行”。 swagger 编辑器将显示一个包含产品列表的响应。
转到 服务器响应>响应正文。
在 products下，从列表中复制第一个产品并保存以供将来参考。

创建响应呈现模板

OpenAPI 说明文档需要应用响应呈现模板来响应 GET 或 POST 请求。响应呈现模板由自适应卡模板、预览卡模板和元数据组成。

自适应卡模板

若要创建自适应卡片模板，请执行以下步骤：

转到 ChatGPT ，在消息撰写区域提出以下查询：


Create an Adaptive Card Template that binds to the following response:
    "categories": [
        "Music Generation",
        "AI Detection"
    ],
    "chatbot_short_url": "https://goto.opentools.ai/c/ai-music-generator",
    "main_summary": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
    "name": "AI Music Generator",
    "opentools_url": "https://goto.opentools.ai/ai-music-generator",
    "platforms": [
        "Web",
        "App",
        "API"
    ]

选择 “发送消息”。

ChatGPT 使用绑定到示例数据的自适应卡片模板生成响应。保存自适应卡片模板以供将来参考。

下面是自适应卡片模板的示例：

自适应卡模板


{
"$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
"type": "AdaptiveCard",
"version": "1.4",
"body": [
    {
    "type": "TextBlock",
    "text": "AI Music Generator",
    "weight": "Bolder",
    "size": "Large"
    },
    {
    "type": "TextBlock",
    "text": "Categories",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
     "text": "Music Generation, AI Detection",
     "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Description",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. AI Music Generator is powered by advanced AI technology, and it makes music production accessible to everyone.",
    "wrap": true
    },
    {
    "type": "TextBlock",
    "text": "Platform",
    "size": "Medium"
    },
    {
    "type": "TextBlock",
    "text": "Web, App, API",
    "wrap": true
    }
],
"actions": [
    {
    "type": "Action.OpenUrl",
    "title": "Learn More",
    "url": "https://goto.opentools.ai/ai-music-generator"
    },
    {
    "type": "Action.OpenUrl",
    "title": "Try It",
    "url": "https://goto.opentools.ai/c/ai-music-generator"
    }
]
}

要验证生成的自适应卡是否绑定到示例数据，请执行以下步骤：
1. 转到 Adaptive Card Designer。
2. 转到 “选择主机应用”，然后从下拉列表中选择 Microsoft Teams 。
3. 转到 卡片有效负载编辑器 ，然后粘贴自适应卡模板代码。
4. 转到示例 数据编辑器 ，粘贴之前保存的 GET API 响应。
5. 选择 预览模式。自适应卡设计器将显示一个自适应卡，其中包含将响应绑定到模板的数据。

创建预览卡模板

预览卡模板可以包含 title、和subtitleimage属性。如果 API 响应没有图像，则可以删除图像属性。

下面是预览卡模板的示例：

预览卡模板

   "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    }

为 and titlesubtitle创建 if 条件，其中：

如果名称存在，机器人将使用该名称。
如果名称不存在，机器人将使用 NA。

例如， "title": "Name: ${if(name, name, 'N/A')}". 保存预览卡模板以供将来参考。

响应呈现模板

响应呈现模板必须符合托管 https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json在的架构。

要创建响应呈现模板，请执行以下步骤：

创建 JSON 文件并将以下代码添加到该文件中：

{ 
  "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json", 
  "version": "1.0", 
  "jsonPath": "", 
  "responseLayout": "", 
  "responseCardTemplate": { 
 },
 "previewCardTemplate": {
     }
 }

按如下所示更新响应呈现模板中的属性：

#	属性名称	值
1.	`"$schema"`	`"https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json"`
2.	`"version"`	`"1.0"` `version` 是要使用的呈现模板的版本。
3.	`"jsonPath"`	`"tools"` `jsonPath` 是响应 JSON 响应中一个或多个结果的路径。将添加到 `jsonPath` API 响应中产品列表中的相关数据/数组。在本例中， `jsonPath` 即工具。有关如何确定 JSON 路径的详细信息，请参阅使用 JSON 路径查询 JSON。
4.	`"responseLayout"`	`"list"` `responseLayout` 指定附件的布局。用于类型结果的响应。支持的类型为列表和网格。如果响应正文包含具有多个元素（如文本、标题和图像）的对象，则响应布局必须设置为 `list`。如果 API 响应仅包含图像或缩略图，则响应布局必须设置为 `grid`。
5.	`"responseCardTemplate"`	粘贴之前保存的自适应卡片模板代码。 `responseCardTemplate` 是一个自适应卡模板，用于将 JSON 响应映射到自适应卡。
6.	`"previewCardTemplate"`	粘贴您之前保存的预览卡模板代码。 `previewCardTemplate`是预览卡模板，用于在“邮件扩展”浮出控件中显示结果预览。

将响应呈现模板保存在保存 OpenAPI 说明文档的同一文件夹中。

以下代码是响应呈现模板的示例：

响应呈现模板


{
    "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.ResponseRenderingTemplate.schema.json",
    "version": "1.0",
    "jsonPath": "tools",
    "responseLayout": "list",
    "responseCardTemplate": {
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
            {
            "type": "TextBlock",
            "text": "AI Music Generator",
            "weight": "Bolder",
            "size": "Large"
            },
            {
            "type": "TextBlock",
            "text": "Categories",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Music Generation, AI Detection",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Description",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "AI Music Generator is an AI-powered music composing tool that allows users to create original and personalized music for various purposes. It can generate melodies, harmonies, and rhythms tailored to specific needs and preferences, with customization options such as genre, mood, length, and instrumentation. The tool is designed for creative individuals, from beginners to professionals, and can produce high-quality music in seconds. Every generated piece of music is royalty-free and can be used instantly, with no limitations on beat creation. With advanced AI technology, AI Music Generator makes music production accessible to everyone.",
            "wrap": true
            },
            {
            "type": "TextBlock",
            "text": "Platform",
            "size": "Medium"
            },
            {
            "type": "TextBlock",
            "text": "Web, App, API",
            "wrap": true
            }
        ],
        "actions": [
            {
            "type": "Action.OpenUrl",
            "title": "Learn More",
            "url": "https://goto.opentools.ai/ai-music-generator"
            },
            {
            "type": "Action.OpenUrl",
            "title": "Try It",
            "url": "https://goto.opentools.ai/c/ai-music-generator"
            }
        ]
    },
    "previewCardTemplate": {
        "title": "${if(name, name, 'N/A')}",
        "subtitle": "$${if(price, price, 'N/A')}"
    } 
}

创建应用清单

现在，你需要创建一个应用清单 (以前称为 Teams 应用清单) 。应用清单描述了应用如何集成到 Microsoft Teams 产品。

创建 Teams 应用清单

要创建清单，请执行以下步骤：

创建一个新的 JSON 文件。应用清单必须符合应用清单架构中定义的架构的 1.20 版本。

将以下代码添加到 JSON 文件中：

应用清单

{
 "$schema": "https://developer.microsoft.com/json-schemas/teams/v1.20/MicrosoftTeams.schema.json",
 "manifestVersion": "1.20",
 "version": "1.0.3",
 "id": "<<YOUR-MICROSOFT-APP-ID>>",
 "packageName": "com.microsoft.teams.extension",
 "developer": {
     "name": "Teams App, Inc.",
     "websiteUrl": "https://www.example.com",
     "privacyUrl": "https://www.example.com/termofuse",
     "termsOfUseUrl": "https://www.example.com/privacy"
 },
 "icons": {
     "color": "color.png",
     "outline": "outline.png"
 },
 "name": {
     "short": "Search ME API",
     "full": "Search ME API full"
 },
 "description": {
     "short": "product app for testing API Message Extensions",
     "full": "product app for testing API Message Extensions"
 },
 "accentColor": "#FFFFFF",
 "composeExtensions": [
     {
         "composeExtensionType": "",
         "apiSpecificationFile": "",
         "commands": [
             {
                 "context": [
                     "compose"
                 ],
                 "type": "query",
                 "title": "API for fetching Klarna.",
                 "id": "",
                 "parameters": [
                     {
                         "name": "",
                         "title": "",
                         "description": ""
                     }
                 ],
                 "description": "",
                 "apiResponseRenderingTemplateFile": ""
             }
         ]
     }
 ],
 "permissions": [
     "identity",
     "messageTeamMembers"
 ],
 "validDomains": []
}

更新应用清单属性，如下所示：
- 替换 <<YOUR-MICROSOFT-APP-ID>> 为机器人的 Microsoft 应用 ID。
- 将该值 composeExtensionType 更新为 apiBased.
- 将该 apiSpecificationFile 值更新为 OpenAPI 说明文件的路径。
- 将该值 commands.id 更新为 searchTools.
- 将该值 commands.title 更新为 Search for AI Tools.
- 将该值 commands.description 更新为 Search for AI Tools.
- 将该值 parameters.name 更新为 search. 如果没有参数，则值必须是查询参数，或者 properties.name 引用请求正文架构中的属性。
- 将更新 apiResponseRenderingTemplateFile 到响应呈现模板文件的路径。
- 将的 validDomains 值更新为 OpenAPI 说明文件中定义的 service URL 终结点。
将 Teams 应用清单保存在保存 OpenAPI 说明文档和响应呈现模板的同一文件夹中。
- 需要彩色图像和轮廓图像。这些图像应包含在文件夹中，并在 Teams 应用清单中引用。
- 压缩文件夹的内容。该 zip 文件必须包含以下文件：
  - OpenAPI 说明文档
  - 响应呈现模板
  - 应用清单
  - 颜色图标
  - “大纲”图标

将自定义应用上传到 Teams

登录到 Teams 测试环境，在 Teams 中测试你的应用。若要在 Teams 中上传自定义应用，请执行以下步骤：

转到 Microsoft Teams 并使用测试租户凭据登录。
转到“应用” “管理>应用>” “上传应用”。
选择 “上传自定义应用”。
选择创建的 zip 文件，然后选择“ 打开”。
选择“添加”。
选择“打开”。
转到聊天，然后从消息撰写区域中选择 + ，然后搜索应用。
选择应用并进行搜索查询。
应用在聊天窗口中使用自适应卡进行响应。
选择“发送”。

恭喜！你做到了！你已了解如何使用 OpenAPI 创建基于 API 的消息扩展说明文档。

创建基于 API 的消息扩展

返回页首

构建基于操作的消息扩展

基于 Teams 操作的消息扩展允许用户与 Microsoft Teams 客户端中的 Web 服务交互。消息扩展有助于从撰写消息区域、命令框或直接从消息在外部系统中启动操作。

教程：生成基于操作的消息扩展

基于操作的消息扩展的主要功能：

向用户呈现用于收集或显示信息的模式弹出窗口。
从撰写消息区域、命令框或消息触发操作命令。

本分步指南可帮助你构建 Teams 基于操作的消息扩展，以从撰写消息和消息区域启动操作。本教程结束时，可以实现以下输出：

成功完成分步指南后消息扩展输出的屏幕截图。

先决条件

确保安装以下工具并设置开发环境：

	安装	对于使用...
	Microsoft Teams	Microsoft Teams 通过聊天、会议和通话应用与与你协作的每个人。
	Visual Studio 2022	可以在 Visual Studio 2022 中安装企业版本，并安装 ASP.NET 和 Web 开发工作负载。使用最新版本。
	.NET Core SDK	本地调试和 Azure Functions 应用部署的自定义绑定。如果您尚未安装最新版本，请安装便携版本。
	开发隧道	Teams 应用功能 (对话机器人、消息扩展和传入 Webhook，) 需要入站连接。隧道将开发系统连接到 Teams。开发隧道是一个功能强大的工具，可以安全地将本地主机打开到 Internet 并控制谁具有访问权限。开发隧道在 Visual Studio 2022 版本 17.7.0 或更高版本中可用。或你还可以使用 ngrok 作为隧道来将开发系统连接到 Teams。仅包含选项卡的应用则不需要该设置。此包 (使用 npm `devDependencies`) 安装在项目目录中。

注意

下载 ngrok 后，注册并安装 authtoken。

设置本地环境

打开 Microsoft-Teams-Samples。
选择 “代码”。
在下拉菜单中，选择“ 使用 GitHub Desktop 打开”。
选择 “克隆”。

注册 Microsoft Entra 应用

以下步骤可帮助你在 Azure 门户中创建和注册机器人：

创建并注册 Azure 应用。
创建客户端密码以启用机器人的 SSO 身份验证。
添加 Teams 频道以部署机器人程序。
使用开发隧道 (推荐的) 或 ngrok 创建到 Web 服务器终结点的隧道。
将消息终结点添加到你创建的开发隧道。

添加应用注册

转到 Azure 门户。
选择“应用注册”。
选择 + 新建注册。
输入应用的名称。
选择“任何组织目录中的帐户” (“任何Microsoft Entra ID租户 - 多租户) ”。
选择 “注册”。

应用已在 Microsoft Entra ID 中注册。将显示应用概述页。

注意

将 应用程序 (客户端 中的应用 ID 保存) ID 和目录 (租户) ID 以供进一步使用。

创建隧道

按照以下两种方法之一创建隧道。

开发隧道
ngrok

打开 Visual Studio。
选择“ 创建新项目”。
在搜索框中，输入 ASP.NET。从搜索结果中，选择 ASP.NET Core Web 应用。
选择“下一步”。
输入 项目名称 并选择 “下一步”。
选择“创建”。

将显示概述窗口。
在调试下拉列表中，选择“ 开发隧道 (无活动隧道”) >“创建隧道...”。

将显示一个弹出窗口。
在弹出窗口中更新以下详细信息：
1. 帐户：输入 Microsoft 或 GitHub 帐户。
2. 名称：输入隧道的名称。
3. 隧道类型：从下拉列表中选择“ 临时”。
4. 访问：从下拉列表中，选择 “公共”。
选择“确定”。

将显示一个弹出窗口，显示已成功创建开发隧道。
选择“确定”。

可在调试下拉列表中找到创建的隧道，如下所示：
选择 F5 以在调试模式下运行应用程序。
如果出现 “安全警告” 对话框，请选择 “是”。

将显示一个弹出窗口。
选择“继续”。

将在新的浏览器窗口中打开开发隧道主页，并且开发隧道现在处于活动状态。
转到 Visual Studio，选择 “查看 > 输出”。
从 “输出 控制台”下拉菜单中，选择“ 开发隧道”。

输出控制台显示开发隧道 URL。

使用 ngrok 或命令提示符创建到本地运行的 Web 服务器的公开可用 HTTPS 终结点的隧道。在 ngrok 中运行以下命令：

ngrok http --host-header=localhost 3978

提示

如果遇到 ERR_NGROK_4018，请按照命令提示符中提供的步骤注册并对 ngrok 进行身份验证。然后运行该 ngrok http --host-header=localhost 3978 命令。

该窗口显示 HTTPS URL。

屏幕截图显示 ngrok HTTPS URL。

添加 Web 身份验证

在左窗格的 “管理”下，选择 “身份验证”。
选择 “添加平台>Web”。
通过追加 auth-end 到完全限定的域名来输入应用的重定向 URI。例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end.
在 “隐式授权和混合流”下，选中“ 访问令牌” 和“ ID 令牌” 复选框。
选择配置。
在 Web 下，选择 添加 URI。
Enter https://token.botframework.com/.auth/web/redirect.
选择“保存”。

创建客户端密码

注意

如果遇到“ 租户范围策略已阻止客户端密码”错误。有关详细信息，请与租户管理员联系，您可以改为创建证书。有关分步说明，请参阅创建应用注册证书。

在左窗格的 “管理”下，选择“ 证书 & 机密”。
在 “客户端密码”下，选择“ + 新建客户端密码”。

将显示 “添加客户端密码 ”窗口。
输入说明。
选择“添加”。
在 “值”下，选择“ 复制到剪贴板 ”以保存客户端机密值供进一步使用。

添加 API 权限

在左窗格中，选择 “API 权限”。
选择 “+ 添加权限”。
选择 Microsoft Graph。
选择“ 委托的权限”。
选择用户>User.Read。
选择 “添加权限”。
注意
- 如果未向应用授予 IT 管理员同意，则用户必须在首次使用应用时提供同意。
- 只有当 Microsoft Entra 应用在其他租户中注册时，用户才需要同意 API 权限。

添加应用程序 ID URI

在左窗格的 “管理”下，选择“ 公开 API”。
在 “应用程序 ID URI”旁边，选择 “添加”。
更新格式中的api://botid-{AppID}应用程序 ID URI，然后选择“保存”。

添加作用域

在左窗格的 “管理”下，选择“ 公开 API”。
选择 + 添加范围。
输入 access_as_user 作为 范围名称。
在“ 谁可以同意？”下，选择“ 管理员和用户”。
按如下所示更新其余字段的值：
- 输入 Teams 可以作为管理员同意显示名称访问用户的配置文件。
- Enter 允许 Teams 以当前用户身份调用应用的 Web API，作为管理员同意说明。
- 输入 Teams 可以访问用户配置文件，并代表用户发出请求 ，如 用户同意显示名称。
- 输入“允许 Teams 使用与用户同意描述相同的权限调用此应用的 API”。
确保 将“状态 ”设置为 “已启用”。
选择 “添加范围”。

下图显示了字段和值：

注意

作用域名称必须与应用程序 ID URI 匹配，并/access_as_user附加在末尾。

添加客户端应用程序

在左窗格的 “管理”下，选择“ 公开 API”。

在 授权的客户端应用程序下，确定要为应用的 Web 应用程序授权的应用程序。
选择 + 添加客户端应用程序。
添加 Teams 移动或桌面和 Teams Web 应用程序。
1. 对于 Teams 移动版或桌面版：将 客户端 ID 作为 1fec8e78-bce4-4aaf-ab1b-5451cc387264输入。
2. 对于 Teams Web：将 客户端 ID 输入 5e3ce6c0-2b1f-4285-8d4b-75ee78787346为 .
选中 “授权范围 ”复选框。
选择 “添加应用程序”。

下图显示 了客户端 ID：

创建机器人程序

创建 Azure 机器人资源

注意

如果已在 Teams 中测试机器人，请注销此应用和 Teams。若要查看此更改，请再次登录。

前往主页。
选择“ + 创建资源”。
在搜索框中输入“Azure 机器人”。
选择 Enter。
选择 Azure 机器人。
选择“创建”。
在 机器人句柄中输入机器人名称。
从下拉列表中选择你的订阅。
从下拉列表中选择 资源组 。

如果没有现有资源组，可以创建新的资源组。要创建新的资源组，请按照下列步骤操作：
1. 选择“ 新建”。
2. 输入资源名称，然后选择“ 确定”。
3. 从 “新建资源组位置” 下拉列表中选择一个位置。
在 “定价”下，选择 “更改计划”。
选择 F0 Free>选择。
在 Microsoft 应用 ID 下，选择 应用类型 为 多租户。
在 创建类型中，选择 使用现有应用注册。
输入 应用 ID。

注意

不能使用相同的 Microsoft 应用 ID 创建多个机器人。
选择 “审阅 + 创建”。
验证通过后，选择 “创建”。

机器人需要几分钟时间来预配。
选择“ 转到资源”。

你已成功创建 Azure 机器人。

添加 Teams 频道

在左窗格中，选择 “频道”。
在 可用频道下，选择 Microsoft Teams。
选中复选框以接受 服务条款。
选择 “同意”。
选择“应用”。

添加消息终结点

使用以下方法之一添加消息终结点：

开发隧道
ngrok

使用输出控制台中的开发隧道 URL 作为消息传递终结点。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-devtunnel-domain/api/messages更新消息终结点。
选择“应用”。

你已在 Azure 机器人服务中成功设置机器人。

注意

如果 Application Insights 检测密钥 显示错误，请使用 应用 ID 进行更新。

在 ngrok 中，复制 HTTPS URL。

注意

ngrok 中的 HTTPS URL 是一个完全限定的域名。是一个 WebAppDomain 完全限定的域名，不包含在 https:// 其中。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-ngrok-domain/api/messages更新消息终结点。
选择“应用”。

你已成功在 Azure 机器人服务中设置机器人。

注意

如果 Application Insights 检测密钥 显示应用程序 ID 的错误更新。

设置应用设置和清单文件

转到克隆的存储库中的 appsettings.json 文件。
打开 appsettings.json 文件并更新以下信息：
- 设置为 "MicrosoftAppId" 机器人的 Microsoft 应用 ID。
- 设置为 "MicrosoftAppPassword" 机器人的客户端密码 ID 值。
- 设置为 ConnectionName OAuth 连接名称。
- 设置为 "MicrosoftAppType"MultiTenant。
- 设置为 "MicrosoftAppTenantId"common。
转到克隆的存储库中的 manifest.json 文件。
打开 manifest.json 文件并更新以下更改：
- 将所有匹配 "{TODO: MicrosoftAppId}" 项替换为 Microsoft 应用 ID。
- 设置为 "<<domain-name>>" ngrok 或 dev tunnel 域。

生成并运行服务

若要生成和运行服务，请使用 Visual Studio 或命令行。

Visual Studio
命令行

打开 Visual Studio。
转到文件>>打开项目/解决方案.....
从 csharp 文件夹中，选择 TeamsMessagingExtensionsAction.csproj 文件。
按 F5 运行项目。
如果出现以下对话框，请选择“ 是 ”：

此时将出现一个网页，显示一条消息“ 你的机器人已准备就绪！”。

转到>命令提示符窗口中的示例msgext-action>csharp 并输入以下命令：

    dotnet run

命令提示符的屏幕截图 - 使用 dotnet run 命令的 dotnet run。

将行动消息扩展应用添加到 Teams

在克隆的存储库中，转到示例>msgext-action>csharp>TeamsAppManifest。
使用 Manifest 文件夹中的以下文件创建一个 .zip：
- manifest.json
- icon-outline.png
- icon-color.png
在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果看到该选项，则表示已启用自定义应用上传。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。
选择“ 打开 ”以上传在 TeamsAppManifest 文件夹中创建的 messaging.zip 文件。
选择“添加”。
选择 “打开 ”以在个人范围内打开应用。

或者，可以搜索并选择所需的范围，或从列表中选择频道、聊天或会议，然后在对话框中移动以选择“ 转到”。

与 Teams 中的应用交互

从撰写框命令列表中选择“ 创建卡片 ”命令。
在模式弹出窗口中输入你的信息。
选择“提交”。
从溢出菜单中选择“更多选项 (...) ”。
选择 “更多操作>”“共享邮件”。
如果要包含图像，请选中“ 在主图卡中包含图像 ”复选框，然后选择 “提交”。

完成挑战

你是想出这样的东西吗？

成功完成分步指南后消息扩展输出的屏幕截图。

你已完成开始使用 Action Message Extension 应用的教程！

操作命令

返回页首

使用 SSO 身份验证生成机器人程序

Microsoft Teams 中的对话机器人执行由用户启动的重复性自动化任务，例如客户服务。用户需要多次登录，而无需单一登录 (SSO) 身份验证。使用 SSO 身份验证方法，用户无需多次登录机器人程序。

教程：使用 SSO 身份验证生成机器人程序

机器人的行为因其参与的对话而异：

频道和群组聊天对话中的机器人需要机器人的用户 @mention 。
一对一对话中的机器人不需要 @mention. 用户发送的所有消息都路由到机器人程序。

本分步指南可帮助你使用 SSO 身份验证构建机器人程序。你将看到以下输出：

成功完成分步指南后，具有 SSO 身份验证输出的机器人程序的屏幕截图。

生成机器人程序的先决条件

确保安装以下工具并设置开发环境：

安装	对于使用...
Microsoft Teams	Microsoft Teams 通过在一个位置进行聊天、会议和通话应用，与与你一起工作的任何人进行协作。
Visual Studio 2022	可以在 Visual Studio 2022 中安装企业版本，并安装 ASP.NET 和 Web 开发工作负载。使用最新版本。
Microsoft 365 开发人员帐户	有权访问 Teams 帐户，并具有安装应用的相应权限。
开发隧道	Teams 应用功能 (对话机器人、消息扩展和传入 Webhook，) 需要入站连接。隧道将开发系统连接到 Teams。开发隧道是一个功能强大的工具，可以安全地将本地主机打开到 Internet 并控制谁具有访问权限。开发隧道在 Visual Studio 2022 版本 17.7.0 或更高版本中可用。或你还可以使用 ngrok 作为隧道来将开发系统连接到 Teams。仅包含选项卡的应用则不需要该设置。此包 (使用 npm `devDependencies`) 安装在项目目录中。

注意

下载 ngrok 后，注册并安装 authtoken。

设置 Teams 开发租户

租户就像一个空间或容器，你可以在其中聊天、共享文件以及在 Teams 中为组织举行会议。还可以上传和测试自定义应用。

检查自定义应用上传选项

创建应用后，必须在 Teams 中加载应用而不分发应用。此过程称为自定义应用上传。登录 Microsoft 365 帐户以查看此选项。

注意

在 Teams 本地环境中预览和测试应用需要自定义应用上传。启用应用上传以在本地 Teams 中预览和测试应用。

是否已有租户，是否具有管理员访问权限？让我们检查一下你是否真的这样做！

要在 Teams 中验证自定义上传应用，请执行以下操作：

在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”
查找“ 上传自定义应用”选项。如果看到该选项，则表示已启用自定义应用上传。

注意

如果没有上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户

如果没有 Teams 开发人员帐户，可以免费获取。加入 Microsoft 365 开发人员计划！

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕。
使用刚刚设置的新管理员帐户登录到 Teams。验证你是否在 Teams 中具有 “上传自定义应用” 选项。

设置本地环境

按照以下步骤克隆存储库：

打开 Microsoft-Teams-Samples。
选择 “代码”。
在下拉菜单中，选择“ 使用 GitHub Desktop 打开”。
选择 “克隆”。

注册 Microsoft Entra 应用

以下步骤可帮助你在 Azure 门户中创建和注册机器人：

创建并注册 Azure 应用。
创建客户端密码以启用机器人的 SSO 身份验证。
添加 Teams 频道以部署机器人程序。
使用开发隧道 (推荐的) 或 ngrok 创建到 Web 服务器终结点的隧道。
将消息终结点添加到你创建的开发隧道。

添加应用注册

转到 Azure 门户。
选择“应用注册”。
选择 + 新建注册。
输入应用的名称。
根据需要选择租户选项。
选择 “注册”。

应用已在 Microsoft Entra ID 中注册。将显示应用概述页。

注意

将 应用程序 (客户端 中的应用 ID 保存) ID 和目录 (租户) ID 以供进一步使用。

创建隧道

按照以下两种方法之一创建隧道。

开发隧道
ngrok

打开 Visual Studio。
选择“ 创建新项目”。
在搜索框中，输入 ASP.NET。从搜索结果中，选择 ASP.NET Core Web 应用。
选择“下一步”。
输入 项目名称 并选择 “下一步”。
选择“创建”。

将显示概述窗口。
在调试下拉列表中，选择“ 开发隧道 (无活动隧道”) >“创建隧道...”。

将显示一个弹出窗口。
在弹出窗口中更新以下详细信息：
1. 帐户：输入 Microsoft 或 GitHub 帐户。
2. 名称：输入隧道的名称。
3. 隧道类型：从下拉列表中选择“ 临时”。
4. 访问：从下拉列表中，选择 “公共”。
选择“确定”。

将显示一个弹出窗口，显示已成功创建开发隧道。
选择“确定”。

可在调试下拉列表中找到已创建的隧道，如下所示：
选择 F5 以在调试模式下运行应用程序。
如果出现 “安全警告” 对话框，请选择 “是”。

将显示一个弹出窗口。
选择“继续”。

将在新的浏览器窗口中打开开发隧道主页，并且开发隧道现在处于活动状态。
转到 Visual Studio，选择 “查看 > 输出”。
从 “输出 控制台”下拉菜单中，选择“ 开发隧道”。

输出控制台显示开发隧道 URL。

使用 ngrok 或命令提示符创建到本地运行的 Web 服务器的公开可用 HTTPS 终结点的隧道。在 ngrok 中运行以下命令：

ngrok http --host-header=localhost 3978

提示

如果遇到 ERR_NGROK_4018，请按照命令提示符中提供的步骤注册并对 ngrok 进行身份验证。然后运行该 ngrok http --host-header=localhost 3978 命令。

该窗口显示 HTTPS URL。

屏幕截图显示 ngrok HTTPS URL。

添加 Web 身份验证

在左窗格的 “管理”下，选择 “身份验证”。
选择 “添加平台>Web”。
通过追加 auth-end 到完全限定的域名来输入应用的重定向 URI。例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end.
在 “隐式授权和混合流”下，选中“ 访问令牌” 和“ ID 令牌” 复选框。
选择配置。
在 Web 下，选择 添加 URI。
Enter https://token.botframework.com/.auth/web/redirect.
选择“保存”。

创建客户端密码

注意

在左窗格的 “管理”下，选择“ 证书 & 机密”。
在 “客户端密码”下，选择“ + 新建客户端密码”。

将显示 “添加客户端密码 ”窗口。
输入说明。
选择“添加”。
在 “值”下，选择“ 复制到剪贴板 ”以保存客户端机密值供进一步使用。

添加 API 权限

在左窗格中，选择 “API 权限”。
选择 “+ 添加权限”。
选择 Microsoft Graph。
选择“ 委托的权限”。
选择用户>User.Read。
选择 “添加权限”。
注意
- 如果未向应用授予 IT 管理员同意，则用户必须在首次使用应用时提供同意。
- 只有当 Microsoft Entra 应用在其他租户中注册时，用户才需要同意 API 权限。

添加应用程序 ID URI

在左窗格的 “管理”下，选择“ 公开 API”。
在 “应用程序 ID URI”旁边，选择 “添加”。
更新格式中的api://botid-{AppID}应用程序 ID URI，然后选择“保存”。

添加作用域

在左窗格的 “管理”下，选择“ 公开 API”。
选择 + 添加范围。
输入 access_as_user 作为 范围名称。
在“ 谁可以同意？”下，选择“ 管理员和用户”。
按如下所示更新其余字段的值：
1. 输入 Teams 可以作为管理员同意显示名称访问用户的配置文件。
2. Enter 允许 Teams 以当前用户身份调用应用的 Web API，作为管理员同意说明。
3. 输入 Teams 可以访问用户配置文件，并代表用户发出请求 ，如 用户同意显示名称。
4. 输入“允许 Teams 使用与用户同意描述相同的权限调用此应用的 API”。
确保 将“状态 ”设置为 “已启用”。
选择 “添加范围”。

下图显示了字段和值：

注意

作用域名称必须与应用程序 ID URI 匹配，并/access_as_user附加在末尾。

添加客户端应用程序

在左窗格的 “管理”下，选择“ 公开 API”。

在 授权的客户端应用程序下，确定要为应用的 Web 应用程序授权的应用程序。
选择 + 添加客户端应用程序。
添加 Teams 移动或桌面和 Teams Web 应用程序。
1. 对于 Teams 移动版或桌面版：将 客户端 ID 作为 1fec8e78-bce4-4aaf-ab1b-5451cc387264输入。
2. 对于 Teams Web：将 客户端 ID 输入 5e3ce6c0-2b1f-4285-8d4b-75ee78787346为 .
选中 “授权范围 ”复选框。
选择 “添加应用程序”。

下图显示 了客户端 ID：

更新清单

在左窗格中，选择 “清单”。
设置“收件人2”的requestedAccessTokenVersion值，然后选择“保存”。

创建机器人程序

创建 Azure 机器人资源

注意

如果已在 Teams 中测试机器人，请注销此应用和 Teams。若要查看此更改，请再次登录。

前往主页。
选择“ + 创建资源”。
在搜索框中输入“Azure 机器人”。
选择 Enter。
选择 Azure 机器人。
选择“创建”。
在 机器人句柄中输入机器人名称。
从下拉列表中选择你的订阅。
从下拉列表中选择 资源组 。

如果没有现有资源组，可以创建新的资源组。要创建新的资源组，请按照下列步骤操作：
1. 选择“ 新建”。
2. 输入资源名称，然后选择“ 确定”。
3. 从 “新建资源组位置” 下拉列表中选择一个位置。
在 “定价”下，选择 “更改计划”。
选择 F0 Free>选择。
在 Microsoft 应用 ID 下，选择 应用类型 为 多租户。
在 创建类型中，选择 使用现有应用注册。
输入 应用 ID。

注意

不能使用相同的 Microsoft 应用 ID 创建多个机器人。
选择 “审阅 + 创建”。
验证通过后，选择 “创建”。

机器人需要几分钟时间来预配。
选择“ 转到资源”。

你已成功创建 Azure 机器人。

添加 Teams 频道

在左窗格中，选择 “频道”。
在 可用频道下，选择 Microsoft Teams。
选中复选框以接受 服务条款。
选择 “同意”。
选择“应用”。

添加消息终结点

使用以下方法之一添加消息终结点：

开发隧道
ngrok

使用输出控制台中的开发隧道 URL 作为消息传递终结点。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-devtunnel-domain/api/messages更新消息终结点。
选择“应用”。

你已在 Azure 机器人服务中成功设置机器人。

注意

如果 Application Insights 检测密钥 显示错误，请使用 应用 ID 进行更新。

在 ngrok 中，复制 HTTPS URL。

注意

ngrok 中的 HTTPS URL 是一个完全限定的域名。是一个 WebAppDomain 完全限定的域名，不包含在 https:// 其中。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-ngrok-domain/api/messages更新消息终结点。
选择“应用”。

你已成功在 Azure 机器人服务中设置机器人。

注意

如果 Application Insights 检测密钥 显示应用程序 ID 的错误更新。

添加 OAuth 连接设置

在左窗格中，选择“ 配置”。
选择 “添加 OAuth 连接设置”。
在 “新建连接设置”下，更新以下详细信息：
- 名称：输入新连接设置的名称。可以在机器人服务代码的设置中使用该名称。
- 服务提供商：从下拉列表中，选择 Azure Active Directory v2。
- 客户端 ID：更新 Microsoft 应用 ID。
- 客户端密码：更新客户端密码值。
- 令牌交换 URL：更新应用程序 ID URI。
- 租户 ID：输入常用。
- 作用域：输入 User.Read。
选择“保存”。

设置应用设置和清单文件

转到克隆的存储库中的 appsettings.json 文件。
打开 appsettings.json 文件并更新以下信息：
- 设置为 "MicrosoftAppId" 机器人的 Microsoft 应用 ID。
- 设置为 "MicrosoftAppPassword" 机器人的客户端密码 ID 值。
- 设置为 ConnectionName OAuth 连接名称。
- 设置为 "MicrosoftAppType"MultiTenant。
- 设置为 "MicrosoftAppTenantId"common。
转到克隆的存储库中的 manifest.json 文件。
打开 manifest.json 文件并更新以下更改：
- 将所有匹配 "{TODO: MicrosoftAppId}" 项替换为 Microsoft 应用 ID。
- 设置为 "<<domain-name>>" ngrok 或 dev tunnel 域。

生成并运行服务

打开 Visual Studio。
转到>文件打开>项目/解决方案....
从 bot-conversation-sso-quickstart>csharp_dotnetcore 文件夹中，然后选择 BotConversationSsoQuickstart.sln 文件。
选择 F5 运行项目。
如果出现 “安全警告” 对话框，请选择 “是”。

此时将打开一个网页，显示一条消息“ 机器人已准备就绪！”。

注意

仅当导航到 localhost URL 时才显示此页面。
疑难解答

如果遇到 “找不到包” 错误，请执行以下步骤：
1. 转到 工具、>NuGet 包管理器>、包管理器设置。
2. 在显示的 “选项” 窗口中，选择 NuGet 包管理器>包源。
3. 选择“添加”。
4. 在 “名称”中输入 nuget.org ，在 “源”中输入 https://api.nuget.org/v3/index.json。
5. 选择 “更新 ”和 “确定”。
6. 重新生成项目。

在 Teams 中上传机器人程序

在克隆的存储库中，转到 Microsoft-Teams-Samples>示例>bot-conversation-sso-quickstart>csharp_dotnetcore>TeamsApp>appPackage。
使用 appPackage 文件夹中的以下文件创建一个 .zip 文件：
- manifest.json
- outline.png
- color.png
转到 Microsoft Teams。
1. 在 Teams 客户端中，选择 “应用”。
2. 选择 “管理应用”。
3. 选择 “上传应用”。
4. 查找“ 上传自定义应用”选项。
选择“ 打开 ”上传在 清单文件夹中 创建的 .zip 文件。
选择“ 添加 ”以将机器人添加到聊天中。
选择“打开”。

可以通过向机器人发送消息来与机器人交互。机器人交换 SSO 令牌，并代表你调用图形 API。它会使你保持登录状态，除非你发送注销消息。
向机器人发送消息。对话机器人将首次请求同意。
对于桌面设备：选择 “继续” 以向 Teams 客户端授予访问机器人的权限。

注意

现在，你已经使用机器人应用配置了 SSO，这是你唯一需要同意的时候。
对于移动设备：选择 “接受”。

注意

现在，你已经在移动设备上使用机器人应用配置了 SSO，这是你唯一需要同意的时候。

你是想出这样的东西吗？

成功完成分步指南后输出的屏幕截图。

你已完成教程，开始使用 SSO 身份验证构建机器人。

为机器人启用 SSO

返回页首

使用 JavaScript 构建你的第一个消息扩展应用

使用 JavaScript 通过你的第一个 Microsoft Teams 应用开始 Microsoft Teams 应用开发。

在本教程中，将学习：

如何使用 Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 设置新项目。
如何构建消息扩展应用。
如何部署应用。

教程：使用 JavaScript 生成第一个邮件扩展应用

本分步指南可帮助你在 Visual Studio Code 中使用 Agents Toolkit 构建消息扩展 Teams 应用。完成本指南后，你将看到以下输出：

先决条件

确保安装以下用于构建和部署应用的工具。

	安装	对于使用...
必选
	Visual Studio Code	JavaScript 或 TypeScript 生成环境。使用最新版本。
	Microsoft 365 代理工具包	可为应用创建项目基架的 Microsoft Visual Studio Code 扩展。使用最新版本。
	Node.js	后端 JavaScript 运行时环境。有关详细信息，请参阅 Node.js 版本兼容性表。
	Microsoft Teams	通过一个位置的聊天、会议和通话应用与与你一起工作的人进行协作。
	Microsoft Edge (推荐的) 或 Google Chrome	具有调试和测试所必需的开发人员工具的浏览器。
	Microsoft 365 开发人员帐户	访问具有适当权限的 Teams 帐户，以安装自定义应用。
可选
	适用于 Visual Studio Code 和 Azure CLI 的 Azure 工具	用于访问存储的数据或为 Azure 中的 Teams 应用部署基于云的后端的 Azure 工具。
	适用于 Chrome 的 React 开发人员工具或适用于 Microsoft Edge 的 React 开发人员工具	用于开源 React JavaScript 库的浏览器 DevTools 扩展。

准备开发环境

安装所需工具后，设置开发环境。

安装 Microsoft 365 代理工具包

Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 通过为应用预配和部署云资源并发布到 Teams 应用商店的工具来帮助简化开发过程。

可以将 Agents Toolkit 与 Visual Studio Code 或名为 Microsoft 365 Agents Toolkit CLI (以前称为 TeamsFx CLI) 的命令行界面一起使用。

Visual Studio Code
命令行

打开 Visual Studio Code，然后选择“扩展” (Ctrl+Shift+X 或“查看>扩展) ”。
在搜索框中输入 Microsoft 365 代理工具包。
选择“安装”。

Microsoft 365 Agents Toolkit 图标显示在 Visual Studio Code 活动栏中。

还可以从 Visual Studio Code Marketplace 安装 Agents Toolkit。

要安装 Agents Toolkit CLI，请使用包管理器并在 npm 命令提示符中输入以下命令：

npm install -g @microsoft/m365agentstoolkit-cli

根据配置，可能需要使用来 sudo 安装 CLI：

sudo npm install -g --unsafe-perm @microsoft/m365agentstoolkit-cli

这种情况在 Linux 和 macOS 系统上更为常见。

确保将 npm 全局缓存添加到 PATH。此步骤通常作为 Node.js 安装程序的一部分完成。

可以将 CLI 与命令 atk 一起使用。运行验证atk -h命令是否正常工作。

警告

必须先为 PowerShell 启用 远程签名 执行策略，然后才能在 PowerShell 终端中运行 TeamsFx。

设置 Teams 开发租户

检查“上传应用”选项

创建自定义应用后，必须使用“ 上传自定义应用” 选项将应用上传到 Teams。登录 Microsoft 365 帐户以检查此选项是否已启用。

以下步骤可帮助验证是否可以在 Teams 中上传应用：

在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果该选项可见，则可以上传自定义应用。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 开发人员帐户，请加入 Microsoft 365 开发人员计划。

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕：
使用刚刚设置的管理员帐户登录到 Teams。验证你是否在 Teams 中具有 “上传自定义应用” 选项。

获取免费的 Azure 帐户

如果想要在 Azure 中托管应用或访问资源，则必须具有 Azure 订阅。在开始之前创建一个免费帐户。

为消息扩展应用创建项目工作区

现在，让我们创建你的第一个消息扩展应用。

消息扩展功能允许您通过按钮和表单与 Web 服务交互。直接在 Teams 客户端中使用消息撰写区域、命令框或消息搜索和启动外部系统中的操作。消息扩展依靠机器人在用户和代码之间提供对话。

图中显示了不同类型的应用功能，其中突出显示了消息扩展。

有两种类型的 Teams 消息扩展：

搜索命令：您可以搜索外部系统，并将结果以卡的形式插入到消息中。
操作命令：您可以向用户呈现一个模式弹出窗口以收集或显示信息。然后，可以处理他们的交互并将信息发送回 Teams。

让我们使用搜索命令创建一个消息扩展应用。首先，设置新的 Teams 项目以创建消息扩展应用。

在本教程中，将学习：

如何使用 Agents Toolkit 设置新的邮件扩展项目。
关于应用项目的目录结构。

创建邮件扩展项目工作区

如果先决条件到位，让我们开始吧！

注意

显示的 Visual Studio Code UI 可能因操作系统、工具包版本、主题和环境而异。

Visual Studio Code
命令行

打开 Visual Studio Code。
选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。
选择“新建代理/应用>”Teams 应用。
选择 消息扩展。
选择 “自定义搜索结果”。
选择“ 开始使用机器人”。
选择 JavaScript。
选择 “默认文件夹 ”以将项目根文件夹存储在默认位置。

还可以通过以下步骤更改默认位置：
1. 选择“浏览”。
2. 选择项目工作区的位置。
3. 选择 “选择文件夹”。
输入适用于应用的名称。选择 Enter。

Agents Toolkit 在几秒钟内创建应用。

创建应用后，Agents Toolkit 将显示以下消息：

使用“atk”CLI 创建你的第一个项目。

转到要在其中创建项目文件夹的文件夹，然后打开命令提示符。
输入以下命令以创建新的 Teams 应用：
```
atk new
```
CLI 提供了一系列可供选择的选项。使用箭头键选择一个选项。做出选择后，选择 Enter 进行确认。
1. 选择新项目的消息扩展。
2. 选择使用消息扩展的应用功能的自定义搜索结果。
3. 为基于搜索的消息扩展的体系结构选择“开始使用机器人”。
4. 为编程语言选择 JavaScript。
5. 选择 Enter 为应用选择默认工作区文件夹。
6. 输入适用于应用的名称。应用的名称必须仅包含字母数字字符。

CLI 将在你回答所有问题后创建项目。

了解消息扩展应用源代码

消息扩展使用 Bot Framework 通过对话与服务交互。搭建基架后，查看资源 管理器下的项目目录和文件。

屏幕截图显示消息扩展应用的文件。

文件夹 / 文件	目录
`m365agents.yml`	主项目文件描述应用程序配置，并定义要在每个生命周期阶段中运行的操作集。
`m365agents.local.yml`	使用启用本地 `m365agents.yml` 执行和调试的操作替代。
`.vscode/`	用于本地调试的 Visual Studio Code 文件。
`appPackage/`	Teams 应用程序清单的模板。
`infra/`	用于预配 Azure 资源的模板。
`index.js`	应用程序入口点和 `express` 处理程序。

提示

在将应用集成到 Teams 中之前，请先熟悉 Teams 外部的机器人和消息扩展。

构建并运行你的第一个消息扩展应用

使用 Agents Toolkit 设置项目工作区后，可以生成项目了。你需要登录到 Microsoft 365 帐户。

使用加入 Microsoft 365 开发人员计划时创建的管理员帐户登录。

Visual Studio Code
命令行

打开 Visual Studio Code。
在活动栏中选择 Microsoft 365 Agents Toolkit 图标。
选择“使用凭据 登录到 Microsoft 365 ”。默认 Web 浏览器将打开以允许登录。
使用凭据登录后关闭浏览器。
返回到 Visual Studio Code 中的代理工具包。

边栏的 “帐户 ”部分显示 Microsoft 365 帐户名称。如果为 Microsoft 365 帐户启用了自定义应用上传，则 Agents Toolkit 将显示已 启用自定义应用上传。

屏幕截图显示用户登录到 Microsoft 365 以及已启用上传的消息。

现在已准备好生成应用并在本地运行它！

转到消息扩展应用的项目文件夹，然后打开命令提示符。
使用 Microsoft 365 Agents Toolkit CLI 登录 Microsoft 365 (以前称为 TeamsFx CLI) 命令：
```
atk account login m365
```

默认 Web 浏览器将打开以允许登录。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

在本地环境中生成并运行应用

现在，可以在本地生成和调试第一个 Teams 消息扩展应用。

在本地生成并运行应用

在 Visual Studio Code 中选择 F5 键以在调试模式下运行应用程序。

注意

如果 Agents Toolkit 无法验证特定先决条件，它会提示您进行检查。
了解在调试器中本地运行应用时会发生什么。

选择 F5 时，Agents Toolkit 执行以下功能：
1. 检查以下先决条件：
  1. 你已使用 Microsoft 365 帐户登录。
  2. 已为 Microsoft 365 帐户启用自定义应用上传。
  3. 已安装受支持 Node.js 版本。
  4. 机器人程序应用所需的端口可用。
2. 安装 npm 包
3. 启动开发隧道以创建 HTTP 隧道。
4. 在 Microsoft Entra ID 中注册应用并配置应用。
5. 在 Bot Framework 中注册机器人程序应用并配置该应用。
6. 在 Teams 开发人员门户中注册应用并配置应用。
7. 启动本地托管的消息扩展应用。
8. 在 Web 浏览器中启动 Teams 并上传 Teams 应用。
首次调试应用时，Teams 会下载依赖项并生成应用。此过程可能需要 3 到 5 分钟才能完成。
生成完成后，Teams 将在浏览器窗口中打开。如果出现提示，请使用 Microsoft 365 帐户登录。
此时将打开一个对话框，允许将邮件扩展应用添加到 Teams。选择“添加”。

Teams 加载消息扩展应用。

由于消息扩展应用依赖机器人来实现用户与 Web 服务之间的通信，因此应用会加载到机器人的聊天功能中。
- 如果在创建消息扩展应用之前创建了机器人应用，则 Teams 会在创建的机器人应用中加载消息扩展。机器人应用以前的聊天消息可见。
- 如果首先创建了消息扩展，Teams 会在 Teams 上打开的最近聊天中加载应用。

测试应用

首次加载应用时，消息扩展应用将打开供你测试。通过此示例应用，可以从软件注册表搜索开源 npm 包。

在消息扩展的搜索框中输入开源 npm 包的名称，例如 cli。消息扩展显示匹配项的列表。
从列表中选择其中一项。应用会使用邮件撰写区域中的项目创建一个自适应卡，以便你可以在聊天或频道中发送它。
选择 Enter。消息扩展应用在聊天或频道中发送包含项目的自适应卡。

如何打开消息扩展应用

在上一步中测试了消息扩展应用的搜索功能。现在，了解打开消息扩展应用程序的不同方法。

从命令框打开应用

Enter / 后跟命令框中消息扩展应用的名称。

应用将在命令框中打开，可以使用它来运行查询。
注意
- 用于 / 从命令框打开消息扩展应用仅适用于新 Teams 客户端。
- 用于 @ 从经典 Teams 客户端中的命令框打开消息扩展应用。

从消息撰写区域打开应用

选择邮件撰写区域底部的三个点。
选择消息扩展应用。

消息扩展应用程序将加载运行搜索的选项。

从上传的自定义应用中打开应用

选择 “应用>”“管理你的应用”。
从应用列表中选择应用的下拉列表，然后选择“ 个人应用”。
将出现一个对话框，建议你试用应用。如果选择 “已找到”，对话框将消失。选择 “试用”。
消息扩展应用的列表显示在最近的 Teams 聊天中。从列表中选择消息扩展应用。

了解如何在应用无法在本地运行时进行故障排除

若要在 Teams 中运行应用，必须具有允许上传自定义应用的 Microsoft 365 开发帐户。可以在先决条件部分了解有关自定义应用上传的详细信息。

部署你的第一个 Teams 应用

让我们使用代理工具包在 Azure 上部署你的第一个邮件扩展应用。

登录到 Azure 帐户以访问 Microsoft Azure 门户并预配新的云资源以支持您的应用。

Visual Studio Code
命令行

打开 Visual Studio Code。
打开在其中创建邮件扩展应用的项目文件夹。
在活动栏中选择 Microsoft 365 Agents Toolkit 图标。
选择“使用凭据登录到 Azure”。默认 Web 浏览器将打开以允许登录。

提示

如果已安装 AZURE 帐户扩展并使用同一帐户，则可以跳过此步骤。
出现提示时关闭浏览器并返回到 Visual Studio Code。

边栏的“帐户”部分列出了可用的可用 Azure 订阅数量。确保至少有一个可用的可用 Azure 订阅。如果没有，请注销并使用其他帐户。

转到消息扩展应用的项目文件夹，然后打开命令提示符。
使用代理工具包登录 Azure CLI 命令：
```
atk account login azure
```
默认 Web 浏览器将打开以允许登录。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

现在，让我们了解如何使用 Agents Toolkit 将应用部署到 Azure。

将应用部署到 Azure

部署包括两个步骤。首先，创建必要的云资源 (也称为预配) 。然后，应用的代码被复制到创建的云资源中。在本教程中部署消息扩展应用。

预配和部署之间有何区别？

“预配”步骤会在 Azure 和 Microsoft 365 中为应用创建资源，但不会将 HTML、CSS 或 JavaScript) 等代码 (复制到资源中。部署步骤会将应用的代码复制到预配步骤中创建的资源。多次部署而不预配新资源是很常见的。由于预配步骤需要一些时间才能完成，因此它与部署步骤是分开的。

Visual Studio Code
命令行

选择 Visual Studio Code 活动栏中的 Microsoft 365 Agents Toolkit 图标。

选择 “预配”。
选择一个订阅。
选择资源组。

如果没有要选择的资源组，可以使用以下步骤新建资源组：
1. 选择 + 新建资源组。
2. 为资源组选择默认名称或输入合适的名称。
3. 选择资源组的位置。
对话框警告你在 Azure 中运行资源时可能会产生成本。选择 “预配”。

预配过程在 Azure 云中创建资源。这可能需要一些时间。几分钟后，你将看到以下消息：

如果需要，可以查看预配的资源。对于本教程，无需查看资源。

预配的资源将显示在 “环境”下。
在 “生命周期”下，选择 “部署”。
将出现一个对话框，询问您是否要在开发环境中部署资源。选择 “部署”。

与预配一样，部署需要一些时间。几分钟后，你将看到完成消息。

转到创建邮件扩展应用的文件夹，然后打开命令提示符。
运行 atk provision.
```
atk provision
```
出现提示时，请选择 Azure 订阅和资源组以使用 Azure 资源。你的应用使用 Azure 资源托管。
运行 atk deploy.
```
atk deploy
```
部署了消息扩展应用。

运行部署的应用

预配和部署步骤完成后，转到“ 运行和调试 ” (Ctrl+Shift+D 或在“代理工具包”中 查看 > “运行) ”。

选择“ 运行和调试 ”下拉菜单。
选择“ 在 Teams (Edge 中远程启动) ”。
选择 ▷ 按钮。
此时将打开一个对话框，用于将已部署的应用安装到 Teams。选择“添加”。

Teams 在最近的聊天中打开消息扩展应用。

了解将应用部署到 Azure 时会发生什么

在部署之前，应用在本地运行。

后端使用 Azure Functions 核心工具运行。
应用程序 HTTP 终结点（Microsoft Teams 在其中加载应用程序）在本地运行。

部署过程分为两步。在活动 Azure 订阅上预配资源，然后将应用的后端和前端代码部署或上传到 Azure。

后端（如果配置）使用各种 Azure 服务，包括 Azure 应用服务和 Azure 存储。
前端应用将部署到为静态 Web 托管配置的 Azure 存储帐户。

恭喜

你完成了使用 JavaScript 生成邮件扩展应用的教程！

你是想出这样的东西吗？

构建消息扩展应用

返回页首

使用 C sharp 构建你的第一个标签页应用

通过构建具有选项卡功能的第一个 Teams 应用，开始 Microsoft Teams 应用开发。

在本教程中，将学习：

如何设置新项目。
如何使用 C# 和 Microsoft Visual Studio 2022 生成具有选项卡功能的应用。

教程：使用 C 生成第一个选项卡应用#

本分步指南可帮助你使用 Microsoft 365 Agents Toolkit (以前称为 Teams Toolkit) 构建选项卡。完成本指南后，你将看到以下输出：

屏幕截图显示 Teams 选项卡应用的最终输出。

生成应用的先决条件

下面是生成和部署 Teams 应用所需安装的工具列表。

安装	对于使用...
Microsoft Teams	Microsoft Teams 通过聊天、会议和通话应用与与你协作的每个人。
Visual Studio 2022	可以在 Visual Studio 2022 中安装企业版本，并安装 ASP.NET 和 Web 开发工作负载。使用最新版本。
Microsoft 365 代理工具包	可为应用创建项目基架的 Visual Studio 扩展。使用最新版本。

安装代理工具包

Agents Toolkit 使用工具为应用创建项目基架，帮助简化开发过程。它为所有选定的功能创建必要的目录结构，并准备好生成项目所需的文件。

可以下载最新的 Visual Studio 安装程序。代理工具包作为 Visual Studio 中的扩展提供。

在弹出的工作负载窗口中打开 Visual Studio 安装程序后：

选择“ ASP.NET 和 Web 开发”。
在 安装详细信息>“可选”下，选择 Microsoft Teams 开发工具。
选择“安装”。
选择 “启动”。将显示 Visual Studio 2022 应用窗口。
转到 “扩展”“>管理扩展”。

将显示“管理扩展”窗口：
在左窗格中，选择 “已安装”。 Microsoft 365 Agents Toolkit 扩展现已推出。

设置 Teams 开发租户

租户就像是组织在 Teams 中的空间或容器，可在其中聊天、共享文件和举行会议。此空间也是上传和测试自定义应用的地方。让我们验证一下你是否准备好与租户一起开发。

检查自定义应用上传选项

创建应用后，必须在 Teams 中加载应用而不分发应用。此过程称为自定义应用上传。登录 Microsoft 365 帐户以查看此选项。

注意

在 Teams 本地环境中预览和测试应用需要自定义应用上传。如果未启用，则无法在 Teams 本地环境中预览和测试应用。

是否已有租户和管理员访问权限？让我们检查一下您是否这样做！

验证是否可以在 Teams 中上传自定义应用：

打开 Microsoft Teams，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用” 选项。如果看到该选项，则表示已启用自定义应用上传。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。

创建免费的 Teams 开发人员租户 (可选)

如果没有 Teams 帐户，可以免费获取。加入 Microsoft 365 开发人员计划！

转到 Microsoft 365 开发人员计划。
选择 “立即加入” 并按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。完成后，将显示以下屏幕：
使用设置的管理员帐户登录 Teams。验证你是否在 Teams 中具有“ 上传自定义应用” 选项。

获取免费的 Azure 帐户

如果要在 Azure 中托管应用或访问资源，则必须具有 Azure 订阅。在开始之前创建一个免费帐户。

现在，你拥有了设置帐户的所有工具。接下来，让我们设置开发环境并开始构建！首先选择要创建的应用。

使用 C sharp 为选项卡应用创建项目工作区

通过创建第一个应用开始 Microsoft Teams 应用开发。此应用使用选项卡功能。如果先决条件到位，让我们开始吧！

以下步骤可帮助你在 Visual Studio 中为选项卡应用创建项目工作区：

打开 Visual Studio。
选择 “新建项目”。
在搜索框中输入 “Teams”。
接下来，选择 Microsoft 365 智能体>。
输入以下详细信息以配置新项目。
在 “项目名称”中输入所需的项目名称。
选择保存项目文件和文件夹的所需位置。
选择“创建”。
选择 “选项卡>创建”。

Teams 选项卡应用将在几秒钟内创建。

使用 C sharp 生成并运行你的第一个标签页应用

使用 Agents Toolkit 设置项目工作区后，生成选项卡应用。

使用 Microsoft 365 帐户登录 Teams。如果使用的是 Microsoft 365 开发人员计划租户，则注册时设置的管理员帐户是 Microsoft 365 帐户。

在解决方案资源管理器的“解决方案 MyTeamsApp”下，右键单击“MyTeamsApp”。
选择 Microsoft 365 代理工具包>选择 Microsoft 365 帐户。
选择 Microsoft 365 帐户>继续。

在 Visual Studio 本地生成并运行应用

若要在本地生成并运行应用，请执行以下操作：

选择“调试>”、“开始调试”或选择 F5。

Visual Studio 启动调试过程并在浏览器中打开 Teams Web 客户端。如果出现提示，请使用 Microsoft 365 帐户登录。
选择“添加”。
选择 “打开 ”以在个人范围内打开应用。

或者，可以搜索并选择所需的范围，或从列表中选择频道或聊天，然后在对话框中移动以选择“ 转到”。

屏幕截图显示范围选择对话框，其中包含共享范围的列表。

恭喜，你的第一个选项卡应用正在 Teams 上运行！

屏幕截图显示 Teams 选项卡应用的最终输出。

了解如何在应用未在本地运行时进行故障排除。

若要在 Teams 中成功运行应用，请确保已在 Teams 帐户中启用自定义应用上传。可以在先决条件部分了解有关自定义应用上传的详细信息。

你已使用 C# 成功创建选项卡应用。 Agents Toolkit 已向应用的目录结构添加了必要的基架。本教程现在完成。

创建选项卡

使用 Microsoft 365 智能体工具包创建新的 Teams 项目

返回页首

将 SSO 添加到选项卡和消息扩展应用

Microsoft Entra单一登录 (SSO) 可在 Teams 中实现无缝用户身份验证。

Microsoft Entra SSO 的关键方面：

允许用户在首次登录后自动登录。
允许用户登录到其他设备，而无需再次输入凭据。
获取已登录用户的令牌。

教程：将 SSO 添加到选项卡和消息扩展应用

本分步指南可帮助你创建选项卡和消息扩展，以启用 Microsoft Entra SSO 身份验证。你将看到以下输出：

成功完成分步指南后，具有 SSO 身份验证输出的选项卡和消息扩展的屏幕截图。

将 SSO 添加到应用的先决条件

确保安装以下工具并设置开发环境：

#	安装	对于使用...
1.	Microsoft Teams	Microsoft Teams 通过在一个位置进行聊天、会议和通话应用，与与你一起工作的任何人进行协作。
2.	Microsoft 365 开发人员帐户	有权访问 Teams 帐户，并具有安装应用的相应权限。
3.	.NET Core SDK	本地调试和 Azure Functions 应用部署的自定义绑定。如果您尚未安装最新版本，请安装便携版本。
4.	Visual Studio 2022	可以在 Visual Studio 2022 中安装企业版本，并安装 ASP.NET 和 Web 开发工作负载。使用最新版本。
5.	开发隧道	Teams 应用功能 (对话机器人、消息扩展和传入 Webhook，) 需要入站连接。隧道将开发系统连接到 Teams。开发隧道是一个功能强大的工具，可以安全地将本地主机打开到 Internet 并控制谁具有访问权限。开发隧道在 Visual Studio 2022 版本 17.7.0 或更高版本中可用。或你还可以使用 ngrok 作为隧道来将开发系统连接到 Teams。仅包含选项卡的应用则不需要该设置。此包 (使用 npm `devDependencies`) 安装在项目目录中。

注意

下载 ngrok 后，注册并安装 authtoken。

设置本地环境

打开 Microsoft-Teams-Samples。
选择 “代码”。
在下拉菜单中，选择“ 使用 GitHub Desktop 打开”。
选择 “克隆”。

注册 Microsoft Entra 应用

以下步骤可帮助你在 Azure 门户中创建和注册机器人：

创建并注册 Azure 应用。
创建客户端密码以启用机器人的 SSO 身份验证。
添加 Teams 频道以部署机器人程序。
使用开发隧道 (推荐的) 或 ngrok 创建到 Web 服务器终结点的隧道。
将消息终结点添加到你创建的开发隧道。

添加应用注册

转到 Azure 门户。
选择“应用注册”。
选择 + 新建注册。
输入应用的名称。
选择“任何组织目录中的帐户” (“任何Microsoft Entra ID租户 - 多租户) ”。
选择 “注册”。

应用已在 Microsoft Entra ID 中注册。将显示应用概述页。

注意

将 应用程序 (客户端 中的应用 ID 保存) ID 和目录 (租户) ID 以供进一步使用。

创建隧道

选择以下方法之一来创建隧道：

开发隧道
ngrok

打开 Visual Studio。
选择“ 创建新项目”。
在搜索框中，输入 ASP.NET。从搜索结果中，选择 ASP.NET Core Web 应用。
选择“下一步”。
输入 项目名称 并选择 “下一步”。
选择“创建”。

将显示概述窗口。
在调试下拉列表中，选择“ 开发隧道 (无活动隧道”) >“创建隧道...”。

将显示一个弹出窗口。
在弹出窗口中更新以下详细信息：
1. 帐户：输入 Microsoft 或 GitHub 帐户。
2. 名称：输入隧道的名称。
3. 隧道类型：从下拉列表中选择“ 临时”。
4. 访问：从下拉列表中，选择 “公共”。
选择“确定”。

将显示一个弹出窗口，显示已成功创建开发隧道。
选择“确定”。

可在调试下拉列表中找到已创建的隧道，如下所示：
选择 F5 以在调试模式下运行应用程序。
如果出现 “安全警告” 对话框，请选择 “是”。

将显示一个弹出窗口。
选择“继续”。

将在新的浏览器窗口中打开开发隧道主页，并且开发隧道现在处于活动状态。
转到 Visual Studio，然后选择 “查看 > 输出”。
从 “输出 控制台”下拉菜单中，选择“ 开发隧道”。

输出控制台显示开发隧道 URL。

使用 ngrok 或命令提示符创建到本地运行的 Web 服务器的公开可用 HTTPS 终结点的隧道。在 ngrok 中运行以下命令：

ngrok http --host-header=localhost xxxx

提示

如果遇到 ERR_NGROK_4018，请按照命令提示符中提供的步骤注册并对 ngrok 进行身份验证。然后运行该 ngrok http --host-header=localhost xxxx 命令。

该窗口显示 HTTPS URL。

屏幕截图显示 ngrok HTTPS URL。

添加 Web 身份验证

在左窗格的 “管理”下，选择 “身份验证”。
选择 “添加平台>Web”。
通过追加 auth-end 到完全限定的域名来输入应用的重定向 URI。例如， https://your-devtunnel-domain/auth-end 或 https://your-ngrok-domain/auth-end.
在 “隐式授权和混合流”下，选中“ 访问令牌” 和“ ID 令牌” 复选框。
选择配置。
在 Web 下，选择 添加 URI。
Enter https://token.botframework.com/.auth/web/redirect.
选择“保存”。

创建客户端密码

注意

在左窗格的 “管理”下，选择“ 证书 & 机密”。
在 “客户端密码”下，选择“ + 新建客户端密码”。

将显示 “添加客户端密码 ”窗口。
输入说明。
选择“添加”。
在 “值”下，选择“ 复制到剪贴板 ”以保存客户端机密值供进一步使用。

添加 API 权限

在左窗格中，选择 “API 权限”。
选择 “+ 添加权限”。
选择 Microsoft Graph。
选择“ 委托的权限”。
选择用户>User.Read。
选择 “添加权限”。
注意
- 如果未向应用授予 IT 管理员同意，则用户必须在首次使用应用时提供同意。
- 只有当 Microsoft Entra 应用在其他租户中注册时，用户才需要同意 API 权限。

添加应用程序 ID URI

在左窗格的 “管理”下，选择“ 公开 API”。
在 “应用程序 ID URI”旁边，选择 “添加”。
以 or api://your-ngrok-domain/botid-{AppID} 格式更新应用程序 ID URIapi://your-devtunnel-domain/botid-{AppID}，然后选择“保存”。

下图显示域名：

添加作用域

在左窗格的 “管理”下，选择“ 公开 API”。
选择 + 添加范围。
输入 access_as_user 作为 范围名称。
在“ 谁可以同意？”下，选择“ 管理员和用户”。
按如下所示更新其余字段的值：
- 输入 Teams 可以作为管理员同意显示名称访问用户的配置文件。
- Enter 允许 Teams 以当前用户身份调用应用的 Web API，作为管理员同意说明。
- 输入 Teams 可以访问用户配置文件，并代表用户发出请求 ，如 用户同意显示名称。
- 输入“允许 Teams 使用与用户同意描述相同的权限调用此应用的 API”。
确保 将“状态 ”设置为 “已启用”。
选择 “添加范围”。

下图显示了字段和值：

注意

作用域名称必须与应用程序 ID URI 匹配，并/access_as_user附加在末尾。

添加客户端应用程序

在左窗格的 “管理”下，选择“ 公开 API”。

在 授权的客户端应用程序下，确定要为应用的 Web 应用程序授权的应用程序。
选择 + 添加客户端应用程序。
添加 Teams 移动或桌面和 Teams Web 应用程序。
1. 对于 Teams 移动版或桌面版：将 客户端 ID 作为 1fec8e78-bce4-4aaf-ab1b-5451cc387264输入。
2. 对于 Teams Web：将 客户端 ID 输入 5e3ce6c0-2b1f-4285-8d4b-75ee78787346为 .
选中 “授权范围 ”复选框。
选择 “添加应用程序”。

下图显示 了客户端 ID：

更新清单

在左窗格中，选择 “清单”。
设置“收件人2”的requestedAccessTokenVersion值，然后选择“保存”。

创建机器人程序

创建 Azure 机器人资源

注意

如果已在 Teams 中测试机器人，请注销此应用和 Teams。若要查看此更改，请再次登录。

前往主页。
选择“ + 创建资源”。
在搜索框中输入“Azure 机器人”。
选择 Enter。
选择 Azure 机器人。
选择“创建”。
在 机器人句柄中输入机器人名称。
从下拉列表中选择你的订阅。
从下拉列表中选择 资源组 。

如果没有现有资源组，可以创建新的资源组。要创建新的资源组，请按照下列步骤操作：
1. 选择“ 新建”。
2. 输入资源名称，然后选择“ 确定”。
3. 从 “新建资源组位置” 下拉列表中选择一个位置。
在 “定价”下，选择 “更改计划”。
选择 F0 Free>选择。
在 Microsoft 应用 ID 下，选择 应用类型 为 多租户。
在 创建类型中，选择 使用现有应用注册。
输入 应用 ID。

注意

不能使用相同的 Microsoft 应用 ID 创建多个机器人。
选择 “审阅 + 创建”。
验证通过后，选择 “创建”。

机器人需要几分钟时间来预配。
选择“ 转到资源”。

你已成功创建 Azure 机器人。

添加 Teams 频道

在左窗格中，选择 “频道”。
在 可用频道下，选择 Microsoft Teams。
选中复选框以接受 服务条款。
选择 “同意”。
选择“应用”。

添加消息终结点

开发隧道
ngrok

使用输出控制台中的开发隧道 URL 作为消息传递终结点。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-devtunnel-domain/api/messages更新消息终结点。
选择“应用”。

你已在 Azure 机器人服务中成功设置机器人。

注意

如果 Application Insights 检测密钥 显示错误，请使用 应用 ID 进行更新。

在 ngrok 中，复制 HTTPS URL。

注意

ngrok 中的 HTTPS URL 是一个完全限定的域名。是一个 WebAppDomain 完全限定的域名，不包含在 https:// 其中。
在左窗格的 “设置”下，选择 “配置”。
以格式https://your-ngrok-domain/api/messages更新消息终结点。
选择“应用”。

你已成功在 Azure 机器人服务中设置机器人。

注意

如果 Application Insights 检测密钥 显示应用程序 ID 的错误更新。

添加 OAuth 连接设置

在左窗格中，选择“ 配置”。
选择 “添加 OAuth 连接设置”。
在 “新建连接设置”下，更新以下详细信息：
- 名称：输入新连接设置的名称。可以在机器人服务代码的设置中使用该名称。
- 服务提供商：从下拉列表中，选择 Azure Active Directory v2。
- 客户端 ID：更新 Microsoft 应用 ID。
- 客户端密码：更新客户端密码值。
- 令牌交换 URL：更新应用程序 ID URI。
- 租户 ID：输入常用。
- 作用域：输入 User.Read。
选择“保存”。

设置应用设置

转到克隆的存储库中的 appsettings.json 文件。
在 Visual Studio 中打开 appsettings.json 文件。
更新以下信息：
- 替换 "MicrosoftAppId" 为机器人的 Microsoft 应用 ID。
- 替换 "MicrosoftAppPassword" 为机器人的客户端密码值。
- 替换 "SiteUrl" 为 ngrok URL。
- 替换 "ConnectionName" 为 OAuth 连接设置的名称。
- 替换 "TenantId" 为使用应用的租户的租户 ID。
- 替换 "ClientId" 为机器人的 Microsoft 应用 ID。
- 替换 "AppSecret" 为机器人的客户端密码值。
- 替换 "ApplicationIdURI" 为 api://*******.ngrok.io/botid-{AppID}.

设置清单文件

转到克隆的存储库中的 manifest.json 文件。
在 Visual Studio 中打开 manifest.json 文件并进行以下更改：
- 替换 DOMAIN-NAME 为 ngrok URL。
- 替换 YOUR-MICROSOFT-APP-ID 为机器人的 Microsoft 应用 ID。
  
  注意
  
  视情况 [YOUR-MICROSOFT-APP-ID] 而定，并 [DOMAIN-NAME] 可能多次发生。
- 替换 resource 为 api://*******.ngrok.io/botid-{AppID}.

生成并运行服务

若要生成和运行服务，请使用 Visual Studio 或命令行。

Visual Studio
命令行

打开 Visual Studio。
选择文件>打开> *项目/解决方案...
在 csharp 文件夹中，选择 应用 SSO Sample.csproj 文件。
按 F5 运行项目。
如果出现以下对话框，请选择“ 是 ”：

将出现一个网页，显示一条消息“ 你的机器人已准备就绪！

显示“机器人已准备就绪”的网页的屏幕截图。

转到命令提示符窗口中的 csharp 文件夹，然后输入以下命令：

dotnet run

dotnet

将 SSO 应用上传到 Teams

在克隆的存储库中，转到 csharp>应用 SSO 示例>TeamsAppManifest。
使用 Manifest 文件夹中的以下文件创建一个 .zip 文件：
- manifest.json
- icon-outline.png
- icon-color.png
在 Teams 客户端中，选择 “应用 ”图标。
选择 “管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。如果看到该选项，则表示已启用自定义应用上传。

注意

如果找不到上传自定义应用的选项，请联系 Teams 管理员。
选择“ 打开 ”以上传在清单文件夹中创建的 .zip 文件。
选择“添加”。
选择 “打开 ”并向机器人发送消息。
机器人执行 SSO 并显示个人资料卡以及用于查看令牌的选项提示。
选择 “是 ”可查看令牌，选择 “否 ”可继续聊天。
如果未执行 SSO，则机器人将对选项卡执行默认身份验证方法。
若要登录，如果未执行 SSO，请执行以下操作：
1. 在 Teams 的左窗格中，选择“更多添加的应用” (“●●●) ”。
2. 选择新的 SSO 应用程序。
3. 选择 “登录”。
4. 在登录窗口中输入凭据 ，然后选择下一步。
5. 选择“接受”。
6. 在搜索框下选择你的个人资料。你将看到以下输出：
发送https://profile.botframework.com到应用程序以获取个人资料卡。