生成基于 API 的消息扩展的高级教程
注意
基于 API 的消息扩展仅支持搜索命令。
使用 API 构建的消息扩展 (基于 API 的) 通过允许 Teams 应用与外部服务交互来显著增强其功能。 基于 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 资源。 |
| OpenAPI 说明 (OAD) 文档 | 介绍 API 功能的文档。 有关详细信息，请参阅 OpenAPI 说明。 |
设置 Teams 开发租户
租户类似于 Teams 中组织的空间或容器，可在其中聊天、共享文件和运行会议。 此空间也是上传和测试自定义应用的位置。 让我们验证是否已准备好使用租户进行开发。
检查自定义应用上传选项
创建应用后，必须在 Teams 中加载应用，而无需分发它。 此过程称为自定义应用上传。 登录到 Microsoft 365 帐户以查看此选项。
注意
自定义应用上传对于在 Teams 本地环境中预览和测试应用是必需的。 如果未启用，则无法在 Teams 本地环境中预览和测试应用。
是否已拥有租户，并且是否具有管理员访问权限？ 我们来检查，如果你真的这样做了！
验证是否可以在 Teams 中上传自定义应用：
在 Teams 客户端中，选择“ 应用” 图标。
选择“管理应用”。
选择 “上传应用”。
查找“ 上传自定义应用”选项。 如果看到 选项，则表示已启用自定义应用上传。
注意
如果找不到上传自定义应用的选项，请与 Teams 管理员联系。
创建免费的 Teams 开发人员租户 (可选)
如果没有 Teams 开发人员帐户，可以免费获取它。 加入 Microsoft 365 开发人员计划！
选择“ 立即加入 ”，然后按照屏幕上的说明进行操作。
在欢迎屏幕中，选择“ 设置 E5 订阅”。
设置管理员帐户。 完成后，将显示以下屏幕。
使用刚刚设置的管理员帐户登录到 Teams。 验证在 Teams 中是否具有 “上传自定义应用 ”选项。
获取免费的 Azure 帐户
如果要在 Azure 中托管应用或访问资源，则必须拥有 Azure 订阅。 在开始之前创建一个免费帐户。
你拥有设置帐户的所有工具。 接下来，让我们设置开发环境并开始生成！ 选择要首先生成的应用。
创建 OpenAPI 说明文档
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 请求正文中的嵌套对象。
- 请求正文（如果存在）必须是 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, 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 说明粘贴到编辑器中。
在右窗格中，选择“ GET”。
选择“ 试用”。
输入 搜索 参数的值作为 创建音乐的工具。
选择“ 执行”。 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" } ] }若要验证生成的自适应卡片是否绑定到示例数据，请执行以下步骤：
转到 “选择主机应用”，然后从下拉列表中选择“ Microsoft Teams ”。
转到 卡片有效负载编辑器 并粘贴自适应卡片模板代码。
转到 示例数据编辑器 并粘贴之前保存的 GET API 响应。
选择 “预览模式”。 自适应卡片设计器显示自适应卡片，其中包含将响应绑定到模板的数据。
创建预览卡模板
预览卡模板可以包含 title、 subtitle 和 image 属性。 如果 API 响应没有图像，则可以删除图像属性。
下面是预览卡模板的示例：
预览卡模板
"previewCardTemplate": {
"title": "${if(name, name, 'N/A')}",
"subtitle": "$${if(price, price, 'N/A')}",
}
为 title 和 subtitle创建 if 条件，其中：
- 如果存在名称，机器人将使用名称。
- 如果名称不存在，机器人将使用 NA。
例如，"title": "Name: ${if(name, name, 'N/A')}"。
保存预览卡模板以供将来参考。
响应呈现模板
响应呈现模板必须符合 托管在 的 https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.ResponseRenderingTemplate.schema.json架构。
若要创建响应呈现模板，请执行以下步骤：
创建 JSON 文件并将以下代码添加到该文件：
{ "version": "1.0.0", "$schema": "<URL_REFERENCE_TO_SCHEMA>", "jsonPath": "", "responseLayout": "", "responseCardTemplate": { }, "previewCardTemplate": { } }按如下所示更新响应呈现模板中的属性：
"version":"1.0.0""$schema":"http://adaptivecards.io/schemas/adaptive-card.json""jsonPath":"tools"jsonPath是响应 JSON 响应中的一个或多个结果的路径。jsonPath将 添加到 API 响应中产品列表中的相关数据/数组。 在本例中，jsonPath为 工具。 有关如何确定 JSON 路径的详细信息，请参阅 使用 JSON 路径查询 JSON。"responseLayout":"list"responseLayout指定附件的布局。 用于结果类型的响应。 支持的类型是列表和网格。 如果响应正文包含具有多个元素（如文本、标题和图像）的对象，则必须将响应布局设置为list。 如果 API 响应仅包含图像或缩略图，则必须将响应布局设置为grid。"responseCardTemplate"：粘贴前面保存的自适应卡片模板代码。responseCardTemplate是一个自适应卡片模板，用于将 JSON 响应映射到自适应卡片。"previewCardTemplate"：粘贴之前保存的预览卡模板代码。previewCardTemplate是预览卡模板用于在消息扩展浮出控件中显示结果的预览。
将响应呈现模板保存在保存 OpenAPI 说明文档的同一文件夹中。
以下代码是响应呈现模板的示例：
响应呈现模板
{
"version": "devPreview",
"jsonPath": "tools",
"responseLayout": "list",
"responseCardTemplate": {
"$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. 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 文件。 应用清单必须符合 公共开发人员预览版应用清单架构中定义的架构。
将以下代码添加到 JSON 文件：
应用清单
{ "$schema": "https://developer.microsoft.com/json-schemas/teams/vDevPreview/MicrosoftTeams.schema.json", "manifestVersion": "devPreview", "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更新为service URLOpenAPI 说明文件中定义的终结点。
- 将 替换为
将 Teams 应用清单保存在保存 OpenAPI 说明文档和响应呈现模板的同一文件夹中。
- 需要彩色图像和轮廓图像。 这些图像应包含在 文件夹中，并在 Teams 应用清单中引用。
- 压缩文件夹的内容。 zip 文件必须包含以下文件：
- OpenAPI 说明文档
- 响应呈现模板
- 应用部件清单
- 彩色图标
- 大纲图标
将自定义应用上传到 Teams
登录到 Teams 测试环境以在 Teams 中测试应用。 若要在 Teams 中上传自定义应用，请执行以下步骤：
转到 Microsoft Teams 并使用测试租户凭据登录。
转到 “应用>”“管理应用>”“上传应用”。
选择 “上传自定义应用”。
选择创建的 zip 文件，然后选择“ 打开”。
选择“添加”。
选择 “打开”。
转到聊天，然后从邮件撰写区域选择 + ，然后搜索你的应用。
选择应用并进行搜索查询。
应用在聊天窗口中使用自适应卡片进行响应。
选择“发送”。
恭喜！
你做到了! 你已了解如何使用 OpenAPI 说明文档创建基于 API 的消息扩展。
你有关于此部分的问题？ 如果有，请向我们提供反馈，以便我们对此部分作出改进。