生成基于 API 的消息扩展

注意

基于 API 的消息扩展是一种 Teams 应用,可将聊天功能直接集成到 Teams 中,从而增强应用的可用性并提供无缝的用户体验。

在开始之前,请确保满足以下要求:

1. OpenAPI 说明 (OAD)

用户不得为标头或 Cookie 输入参数。 如果需要传递标头,可以在规范中设置标头的默认值。 这简化了用户体验并降低了出错的风险。

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

2.应用清单
  • 设置为 composeExtensions.composeExtensionTypeapiBased
  • 定义为 composeExtensions.apiSpecificationFile 文件夹中 OpenAPI 说明文件的相对路径。
  • 定义为 apiResponseRenderingTemplateFile 响应呈现模板的相对路径。
  • 每个命令都必须具有指向响应呈现模板的链接。
  • 完整说明不得超过 128 个字符。
  • 命令必须正好具有一个参数。

3. 响应呈现模板
  • 在 属性中 $schema 定义架构引用 URL。
  • 定义 jsonPath 为 API 响应中相关数据/数组的路径。 如果路径指向数组,则数组中的每个条目将是单独的结果,如果路径指向对象,则只有一个结果。 [可选]
  • 支持的值为 responseLayoutlistgrid

JsonPath响应呈现模板中的 属性为 $,指示响应数据的根对象用于呈现自适应卡片,并且你可以更新jsonPath属性以指向响应数据中的另一个属性。

如果 OpenAPI 架构的根对象包含已知的数组属性名称,则 Teams 工具包使用数组属性作为根元素来生成自适应卡片,并且数组属性名称用作 JsonPath 响应呈现模板的属性。 例如,如果属性名称包含 、、、、rootqueriesmatchesitemslist、,output并且类型为 array,则将其用作根元素。 dataresult


4. API 消息扩展

基于 API 的消息扩展是一种强大的工具,可通过与外部 API 集成来增强 Teams 应用的功能。 这增强了应用的功能,并提供更丰富的用户体验。 若要从 API 实现消息扩展,需要遵循以下准则:

  • Commands.id应用清单中的 属性必须与 OpenAPI 说明中相应的 operationId 匹配。
  • 如果必需参数没有默认值,则应用清单中的命令 parameters.name 必须与 OpenAPI 说明中的 匹配 parameters.name
  • 如果没有必需的参数,则应用清单中的命令 parameters.name 必须与 OpenAPI 说明中的 可选 parameters.name 匹配。
  • 一个命令不能有多个参数。
  • 必须为每个命令定义响应呈现模板,该命令用于转换来自 API 的响应。 清单的命令部分必须指向应用清单中下的 composeExtensions.commands.apiResponseRenderingTemplateFile 此模板文件。 每个命令指向不同的响应呈现模板文件。

可以使用适用于 Teams 的开发人员门户、Visual Studio Code、Teams 工具包命令行界面 (CLI) 或 Visual Studio 创建基于 API 的消息扩展。

若要使用适用于 Teams 的开发人员门户创建基于 API 的消息扩展,请执行以下步骤:

  1. 转到 Teams 开发人员门户

  2. 转到 “应用”。

  3. 选择“ + 新建应用”。

  4. 输入应用的名称,并选择 “清单版本 ”作为 “最新预发行版” (devPreview)

  5. 选择“添加”。

    屏幕截图显示了在开发人员门户中选择为“最新预发行 (devPreview) ”的应用名称和清单版本。

  6. 在左窗格中的 “配置”下,更新以下 “基本信息”:

    1. 全名
    2. 简短说明
    3. 较长说明
    4. 开发人员或公司名称
    5. 网站 (必须是有效的 HTTPS URL)
    6. 隐私策略
    7. 使用条款
  7. 选择“保存”。

  8. 选择“ 应用功能”。

  9. 选择 “消息传递扩展”。

    屏幕截图显示了 Teams 开发人员门户中的消息扩展选项。

  10. “消息扩展类型”下,选择“ API”。

    1. 如果收到免责声明,该免责声明显示 机器人消息扩展已被用户使用。是否将消息扩展类型更改为 API?。 选择“ 是,更改”。
  11. “OpenAPI 规范”下,选择“ 立即上传”。

    屏幕截图显示了 Teams 开发人员门户中的“立即上传”选项。

  12. 选择 JSON 或 YAML 格式的 OpenAPI 说明文档,然后选择“ 打开”。

  13. 选择“保存”。 此时会显示一个弹出窗口,其中包含 已成功保存的消息 API 规范

  14. 选择“ 已获取”。

    屏幕截图显示了 API 规范已成功保存消息和“已获取”按钮的示例。

添加命令

注意

从 API 生成的消息扩展仅支持单个参数。

可以将命令和参数添加到消息扩展,以添加命令:

  1. “消息扩展类型”下,选择“ 添加”。

    屏幕截图显示用于在 Teams 开发人员门户中添加命令的添加选项。

    此时将显示 “添加”命令 弹出窗口,其中包含 OpenAPI 说明文档中所有可用 API 的列表。

  2. 从列表中选择一个 API,然后选择“ 下一步”。

    屏幕截图显示了“添加命令”弹出窗口中 OpenAPI 说明文档中的 API 列表。

    此时会显示 命令详细信息

  3. “命令详细信息”下,转到“自适应卡模板”,然后选择“立即上传”。

    屏幕截图显示“立即上传”选项,用于为 命令添加自适应卡片模板。

    注意

    如果有多个 API,请确保为每个 API 上传自适应卡模板

  4. 选择 JSON 格式的自适应卡片模板文件,然后选择 “打开”。

    从自适应卡片模板自动更新以下属性:

    • 命令类型
    • 命令 ID
    • 命令标题
    • 参数名称
    • 参数说明

    屏幕截图显示了命令详细信息页中可用的字段。

  5. “详细信息”下,更新 命令说明

    1. 如果要在 Microsoft 365 聊天中使用触发器启动命令,请打开 “当用户打开扩展时自动运行命令 ”开关。
  6. 选择“添加”。 已成功添加命令。

  7. 选择“保存”。

创建基于 API 的消息扩展。

屏幕截图显示在 Teams 开发人员门户的应用功能页中创建的 copilot 应用的插件。

若要测试在 Teams 开发人员门户中创建的基于 API 的消息扩展,可以使用以下方法:

  • 在 Teams 中预览:在开发人员门户中,打开邮件扩展,然后选择右上角的“ 在 Teams 中预览 ”。 你将重定向到 Teams,可在其中将应用添加到 Teams 以预览应用。

  • 下载应用包:在消息扩展页上,从左窗格中选择 “应用包 ”,然后在窗口左上角选择“ 下载应用包”。 应用包在 .zip 文件中下载到本地计算机。 可以将应用包上传到团队并测试消息扩展。

分步指南

若要生成基于 API 的消息扩展,请遵循以下分步指南: