面向初学者的基于 API 的消息扩展 - Teams

注意

基于 API 的消息扩展仅支持搜索命令。
Teams 工具包支持 OpenAPI 规范版本 2.0 和 3.0.x。

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

可以使用 API 消息扩展来集成业务工作流中常用的外部服务。例如，经常使用 CRM 系统进行客户管理的企业可以使用消息扩展直接从 Teams 提取和显示客户数据。通过减少在不同应用程序之间切换的需要，用户可以节省时间并改进。 Teams 桌面、Web 和移动客户端支持基于 API 的消息扩展。

先决条件

剩余 4 分钟

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

安装	用于使用...
Teams 工具包	一个Microsoft Visual Studio Code扩展，用于为应用创建项目基架。使用最新版本。
Microsoft Teams	Microsoft Teams，在一个位置通过聊天、会议和通话应用与你合作的每个人协作。
Node.js	后端 JavaScript 运行时环境。有关详细信息，请参阅项目类型的Node.js 版本兼容性表。
Microsoft Edge（推荐）或 Google Chrome	包含开发人员工具的浏览器。
Visual Studio Code	JavaScript、TypeScript 或 SharePoint 框架 (SPFx) 生成环境。使用版本 1.55 或更高版本。
Microsoft 365 开发人员帐户	具有安装应用的相应权限的 Teams 帐户的访问权限。
Teams 开发人员门户	基于 Web 的门户，用于配置、管理 Teams 应用并将其分发到组织或 Microsoft Teams 应用商店。
OpenAPI 说明 (OAD) 文档	介绍 API 功能的文档。有关详细信息，请参阅 OpenAPI 说明。

准备开发环境

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

安装 Teams 工具包

Teams 工具包通过为应用预配和部署云资源、发布到 Teams 应用商店等工具来帮助简化开发过程。

可以将工具包与 Visual Studio Code 或 CLI (命令行接口) 配合使用，称为 Teamsapp。

Visual Studio Code
命令行

打开Visual Studio Code并选择“扩展”视图， (Ctrl+Shift+X / ⌘⇧-X 或“查看>扩展”) 。
在搜索框中，输入 Teams 工具包。
选择 Teams 工具包旁边的 “安装 ”。

Teams 工具包图标显示在Visual Studio Code活动栏中。

还可以在Visual Studio Code市场中找到 Teams 工具包。

注意

最新版本的 Teams 工具包是 v5。

若要安装 Teamsapp CLI，请使用 npm 包管理器：


npm install -g @microsoft/teamsapp-cli

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


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

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

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

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

警告

在 PowerShell 终端中运行 Teamsapp 之前，必须为 PowerShell 启用“远程签名”执行策略。

设置 Teams 开发租户

租户类似于 Teams 中组织的空间或容器，可在其中聊天、共享文件和运行会议。此空间也是上传和测试自定义应用的位置。让我们验证是否已准备好使用租户进行开发。

检查自定义应用上传选项

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

注意

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

是否已拥有租户，并且是否具有管理员访问权限？我们来检查，如果你真的这样做了！

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

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

注意

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

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

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

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

获取免费的 Azure 帐户

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

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

生成基于 API 的消息扩展

剩余 3 分钟

使用 Teams 工具包设置项目工作区后，生成机器人项目。确保已登录到 Microsoft 365 帐户。

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

Visual Studio Code
命令行

打开 Visual Studio Code。
选择边栏中的“Teams 工具包” 图标。
选择“ 登录到 M365”。

此时会打开默认 Web 浏览器，以便登录帐户。
使用凭据登录到 Microsoft 365 帐户。
出现提示时关闭浏览器并返回到Visual Studio Code。
返回到 Visual Studio Code 内的 Teams 工具包。

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

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

使用 Teamsapp CLI 登录到 Microsoft 365：
```
teamsapp account login m365
```
此时会打开默认 Web 浏览器，以便登录帐户。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。
使用 Teamsapp CLI 登录到 Azure：
```
teamsapp account login azure
```
此时会打开默认 Web 浏览器，以便登录帐户。使用凭据登录到 Azure 帐户。出现提示时关闭浏览器。

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

配置开发环境后，可以创建、生成和部署第一个 Teams 应用。

创建 OpenAPI 说明文档

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

在创建基于 API 的消息扩展之前，必须具有 OpenAPI 说明 (OAD) 文档。 API 规范必须满足以下条件：

auth不能指定属性。
JSON 和 YAML 是支持的格式。
支持 OpenAPI 版本 2.0 和 3.0.x。
Teams 不支持 oneOf、anyOf、allOf，并且不支持 (swagger.io) 构造。
不支持为请求构造数组，但支持 JSON 请求正文中的嵌套对象。
请求正文（如果存在）必须是 application/Json，以确保与各种 API 兼容。
为 servers.url 属性定义 HTTPS 协议服务器 URL。
仅支持单个参数搜索。
仅允许一个不带默认值的必需参数。
仅支持 POST 和 GET HTTP 方法。
OpenAPI 说明文档必须具有 operationId。
操作不得具有没有默认值的必需标头或 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, search="tool to create music" gives 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.

注意

Teams 工具包支持 OpenAPI 规范版本 2.0 和 3.0.x。

现在，你已拥有 OpenAPI 说明文档，它还需要响应呈现模板，以便应用响应 GET 或 POST 请求。响应呈现模板由自适应卡片模板、预览卡模板和元数据组成。如果使用 Teams 工具包或 Teams 开发人员门户生成应用，则会自动从 OpenAPI 说明文档中提取响应呈现模板。

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

响应呈现模板

   {
   "version": "1.0.0",
   "jsonPath": "tools",
   "responseLayout": "list",
   "responseCardTemplate": {
       "type": "AdaptiveCard",
       "version": "1.4",
       "body": [
       {
           "type": "TextBlock",
           "text": "${if(name, name, 'N/A')}",
           "size": "Large",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Categories: ${join(categories, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(main_summary, main_summary, 'N/A')}",
           "size": "Medium",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Supported Platforms: ${join(platforms, ', ')}",
           "size": "Small",
           "isSubtle": true,
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "Pricing Summary:",
           "size": "Medium",
           "weight": "Bolder",
           "wrap": true
       },
       {
           "type": "TextBlock",
           "text": "${if(pricing_summary, pricing_summary, 'N/A')}",
           "size": "Small",
           "wrap": true
       }
       ],
       "actions": [
       {
           "type": "Action.OpenUrl",
           "title": "Learn More",
           "url": "${opentools_url}",
           "$when": "${opentools_url != null}"
       },
       {
           "type": "Action.OpenUrl",
           "title": "Chat with Chatbot",
           "url": "${chatbot_short_url}",
           "$when": "${chatbot_short_url != null}"
       }
       ],
       "$schema": "http://adaptivecards.io/schemas/adaptive-card.json"
   },
   "previewCardTemplate": {
       "title": "${if(name, name, 'N/A')}"
   }
   }

现在可以创建使用 OpenAPI 说明文档的消息扩展。若要使用 OpenAPI 说明文档创建 am message 扩展，请执行以下步骤：

打开 Visual Studio Code。
选择“Visual Studio Code活动栏中的 Teams 工具包”图标。
选择“ 创建新应用”。
选择 “消息扩展”。
选择“自定义搜索结果”
选择 “使用 OpenAPI 说明文档开始”。
选择“ 浏览 ”，然后选择之前保存的 OpenAPI 说明文档。此时会显示文档中可用的 API 列表。
从列表中选择 API，然后选择“ 确定”。
选择“ 默认文件夹 ”，将项目根文件夹存储在默认位置。

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

此时会显示一个对话框。根据你的要求，选择“ 是，我信任作者 ”或“ 否，我不信任作者 ”。

几秒钟内即可创建具有基于 API 的消息扩展功能的 Teams 应用。

创建应用后，Teams 工具包会显示以下消息：

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

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

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

文件夹名	目录
`env/.env.dev.user`	用于 `teamsapp.yml` 自定义预配和部署规则的本地环境的配置文件。
`appPackage`	应用清单模板文件和应用图标 (color.png 和 outline.png) 。
`appPackage/manifest.json`	用于在本地和远程环境中运行应用的应用清单。
`appPackage/apiSpecificationFiles/openapi.yml`	一个说明文件，该文件包含 OpenAPI 说明中 API 的结构和语法。
`appPackage/responseTemplates`	响应呈现模板，由自适应卡片模板、预览卡模板和元数据组成。
`teamsapp.yml`	这是定义属性和配置阶段定义的main Teams 工具包项目。

提示

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

预配应用

若要在 Azure 上预配应用，请执行以下操作：

转到 Teams 工具包，然后从左窗格中选择 “运行和调试 ” (Ctrl+Shift+D) 。
从启动配置下拉列表 中选择“在 Teams (Edge) 中启动远程”。

Teams 工具包在 Azure 上预配应用并将其部署到 Teams。

注意

首次预配应用时，需要几分钟才能完成。后续预配速度更快。
转到聊天消息，然后选择 “操作和应用” 图标。在浮出控件菜单中，搜索你的应用。
从列表中选择应用，并从撰写消息区域触发搜索命令。

Teams 在聊天消息中将搜索结果作为自适应卡片发送。

完成挑战

剩余 2 分钟

你想出了这样的东西吗？

屏幕截图显示了自适应卡片，其中包含 Teams 中聊天消息中的搜索结果。

恭喜！

100% 完成！

你做到了! 你创建了基于 API 的消息扩展。

通过

面向初学者的 API-Based 消息扩展