使用 REST API 中的操作扩展代理（预览版）

2025-04-14

您可以使用 REST API（包括 OpenAI API）将您创建的代理与外部系统连接起来，并访问可用数据以在您的代理中使用。您可以通过 Copilot Studio 提供以下三点将您的代理连接到 REST API：

定义 API 函数和可用操作的 OpenAPI 规范
所需身份验证类型的详细信息，以及用户连接到 API 以访问外部系统的身份验证详细信息
帮助语言模型确定何时调用 API 以利用数据的说明

REST API 可通过 Copilot Studio 添加到 Copilot 代理和自定义代理中。

Copilot 代理允许制作者将多个数据源（如连接器、API、提示和知识源）合并到一个代理中。您可以使用此代理扩展 Microsoft 品牌的代理体验，如 Microsoft 365 Copilot。

自定义代理是包含连接器、API、提示和知识源的独立代理。您可以通过将自定义代理集成到网站或其他渠道中来直接使用自定义代理。

备注

API 操作必须根据 OpenAPI v2 规范创建。这一要求是由于 Power Platform 在处理 API 规范时的行为所致。如果提交的是 v3 规范，则会在创建过程中自动转换为 v2 规范。

先决条件

使用连接器操作扩展 Microsoft 品牌的代理体验需要一些先决条件。

对于所有代理体验类型，您必须拥有制作者级证书和 Copilot Studio 许可证。

您还需要 OpenAPI 规范的副本、所需身份验证类型的知识以及身份验证的详细信息。

向代理添加 REST API 操作

将 REST API 添加到代理涉及几个步骤。以下部分将引导您完成整个过程。

对于自定义代理和 Copilot 代理，添加 REST API 的过程是相同的。

整个过程有几个步骤。

向代理添加操作

从代理的概述页面开始。
在操作部分，选择添加操作。也可以转到操作标签，选择添加操作。

此时将启动操作创建向导，并显示选择操作页面。

提供 API 规范、描述和解决方案

选择页面底部的为自定义连接器添加 API。
上传要连接到的 REST API 的 OpenAPI 规范文件。您可以将规范文件拖放到上传 REST API 屏幕中，也可以浏览系统以找到要使用的文件。

备注

OpenAPI 规范必须是 v2 格式的 JSON 文件。如果提交的是 v3 规范，则会在创建过程中自动转换为 v2 规范。

上传规范后，屏幕将更新以指示规范文件名和详细信息。

在下面的步骤中，我们以 ADO 票务管理系统 SunnyADO 的特定示例为基础。在此示例中，目的是允许用户通过代理检索和更新其票证。
验证详细信息，然后选择下一步。

您将看到一个 API 插件详细信息页面，您可以在其中提供有关 API 的其他信息。

描述字段最初是根据您上传的 API 规范中的描述填充的。提供详细说明，因为代理业务流程使用说明来确定何时使用特定操作。提供详细信息，包括同义词，以帮助您的代理进行选择过程。

例如，提供的初始描述是：“管理工单的简单服务。”

更好的描述是：“一个用于从 SunnyADO 获取、检索、查找和显示现有工单的系统。它允许用户更新、更改和管理工单，以提供更多数据来改进记录。
在描述字段中输入改进后的描述。
在解决方案下，下拉列表将列出当前环境中可用的所有解决方案。选择要使用的解决方案。有关什么是解决方案的详细信息，请参阅解决方案概念。

如果您有首选解决方案，或者您选择的连接器已在解决方案中，将会自动选择该解决方案。

您可以选择一个解决方案或将其留空。如果将解决方案留空，则会使用操作名称和默认发布者为您创建解决方案。通过将操作存储在解决方案中，您可以轻松跨环境移动操作。

备注

在这种情况下，如果您没有看到默认解决方案或 CDS 默认解决方案作为选项，我们建议您使用自定义解决方案以便于管理。有关更多信息，请参阅：默认解决方案与自定义解决方案。
选择解决方案后，选择下一步继续。

提供身份验证详细信息

此时将显示身份验证页面，以选择要用于 API 的身份验证类型。

备注

目前可用的选项是 None、Auth 2.0 和 API。

选择身份验证方法。

从列表中选择身份验证方法。
填写身份验证方法的必填字段。这些字段因身份验证方法而异。
- 无：不需要其他字段。
- API 密钥：
  - 参数标签：API 参数的文本标签。
  - 参数名称：API 参数的文本名称。
  - 参数位置：可以找到参数的位置。
- Auth 2.0：
  - 客户端 ID：目标服务的客户端 GUID。
  - 客户端密钥–客户端的密钥值。之后，当用户打开编辑面板时，不会显示密钥。但是，请存储密钥，因为如果您选择进行进一步编辑，您将需要它。
  - 授权 URL：用于授权源系统的 URL。
  - 令牌 URL：可以检索令牌的 URL。
  - 刷新 URL：在刷新方案中重定向到的 URL。
  - 范围：为 Microsoft Entra 应用程序的 API 分配的范围 URL。
  - 哪个 Microsoft 365 组织访问终结点：这会将对源的访问限制为创建者的组织或所有组织。
  - 哪个应用（客户端）可以使用终结点：定义可用于访问此数据的客户端系统的 GUID。应用程序可以包括 Microsoft 365、Power Automate 和其他选项。
完成所有字段后，选择下一步。

系统将显示选择并配置插件操作页面，您可以在其中选择要为 API 启用的操作。

选择 API 的操作

选择要启用的 API 支持的操作。通常，REST API 通过 API 规范中定义的端点和 HTTP 方法（get、put、post、delete 等）的各种组合提供一系列操作。在某些情况下，您可能不希望代理的用户能够执行 API 通常提供的每个操作。例如，您的 API 规范可能包括更新和删除操作，但您只希望代理的用户能够创建记录。

从列表中选择要配置的操作。

此时将显示配置插件操作页面。
配置所选操作。与整个 API 一样，系统会要求您提供操作名称和操作描述。描述最初是根据 API 规范中的描述预填充的。名称不需要是唯一的，但它应该表示操作本身。与整个 API 描述一样，该描述应足够具体，以便为语言模型提供详细信息，以便更好地识别您的查询是否与此特定操作一致。
字段填写完成后，选择下一步。

将显示查看您的操作参数页面。

此页面显示作为可能的输入和输出值的一部分提供的值。这些值无法更改，但是可以更新输入和输出的描述。此页面中的所有内容都是直接从上传的 API 规范中提取的。
根据需要填写描述的值。这些说明提供了这些值的用途的定义。如果任何描述为空，则必须先完成这些描述，然后才能继续。如果您没有更好的描述，可以粘贴名称。
完成说明后，选择下一步。

第一个操作现已配置完毕，并显示在选择和配置插件操作页面上的选定操作列表中。
此时添加您希望包含的任何其他操作。添加完希望代理支持的操作后，选择下一步。

此时将显示查看操作页面。该页面提供配置的 REST API 操作的详细信息。