发出 HTTP 请求

重要提示

继在生成式人工智能的重大投资和跨 Microsoft Copilot 的增强集成之后，Power Virtual Agents 功能和特性现已成为 Microsoft Copilot Studio 的一部分。

在我们更新文档和培训内容时，一些文章和截图可能会参考 Power Virtual Agents。

在 Copilot Studio 中，您可以通过使用 HTTP 请求节点调用外部 REST API 来扩展助手的功能。 需要从外部系统检索数据或操作该系统上的数据时，这可能会很有帮助。

先决条件

• 创建和编辑主题

使用 HTTP 请求节点

1. 选择添加节点（+），打开高级子菜单，然后选择发送 HTTP 请求。

   

2. 在 URL 框中，输入要调用的 API 端点的 URL。

3. 从下拉列表中选择适当的请求方法。 支持 GET、POST、PATCH、PUT 和 DELETE 方法。

   

4. 在节点上的标头和正文下，单击编辑按钮。 这将打开 HTTP 请求属性窗格。

5. 您可以选择在 HTTP 请求中添加一个或多个标头。 单击添加按钮添加每个标头的关键字和值。

   

6. 默认情况下，在 HTTP 请求的正文中不发送任何内容，但是您可以指定要在正文中发送的内容。

7. 在节点上，从可用选项中选择响应数据类型。

   您可以提供一个示例 JSON 响应（通常可以在正在调用的 API 的文档中找到），它将生成一个强类型的 Power FX 变量，允许您在 Power FX 编辑器的 intellisense 支持下，在创作画布的其他地方使用。 为此，请选择从示例数据，然后单击从示例 JSON 获取模式，将您的示例响应粘贴到显示的编辑器中，并选择确认。

   

8. 在将响应另存为下，选择要存储 HTTP 请求响应的位置，创建一个新变量或选择一个现有变量。

在 HTTP 请求正文中发送内容

1. 在节点上的标头和正文下，单击编辑按钮。 这将打开 HTTP 请求属性窗格。

2. 在正文下，选择适当的内容类型。 默认情况下，它被设置为无内容，其中请求正文中不应出现任何内容，这是 GET 请求最常用的方式。 要向正文添加内容，请从可用选项中选择一个。

   

   • JSON 内容：JSON 内容允许您在请求正文中提供一个 JSON 对象。 这通常在发出 POST 或 PUT 请求时使用。 选择该选项后，会出现一个编辑器，您可以在其中输入 JSON 内容。

     您还可以使用 Power FX 输入指定您的 JSON 内容，允许您包含动态值和引用变量。 为此，请选择编辑 JSON 按钮，选择公式，然后输入一个 Power FX 对象（任何已经输入的现有 JSON 将被转换为 Power FX 对象），当发出 HTTP 请求时，该对象将被转换为 JSON。

     

   • 原始内容：原始内容允许您在请求正文中插入一个数据字符串，该字符串可以是您指定的任何内容类型。 原始内容是使用 Power FX 公式输入的，例如下面示例中显示的字符串内容。

     

错误处理和超时

HTTP 请求节点有多个选项来处理 HTTP 请求可能失败或返回错误的情况。

默认情况下，该功能将“引发错误”。 这意味着当 HTTP 请求返回错误或执行失败时，助手将停止其操作并触发 Error 系统主题，显示错误消息。

但是，您可以将错误处理配置为不触发 Error 系统主题，而是将 HTTP 状态代码和任何错误响应正文填充到您指定的变量中，这样您就可以根据需要询问这些变量，并使主题继续运行。 这在即使特定的 HTTP 请求失败也希望助手继续运行的情况下非常有用。

配置错误处理行为。

1. 在节点上的标头和正文下，单击编辑按钮。 这将打开 HTTP 请求属性窗格。

2. 从错误处理下拉列表中选择您想要的行为。

3. 如果您选择出错时继续，请配置状态代码和错误响应正文变量，创建新变量或从选取器中选择现有变量。

   

在这个代码示例中，如果 HTTP 请求失败，助手将在 Topic.StatusCode 变量中存储 HTTP 状态代码，在 Topic.ErrorResponse 变量中存在响应正文。 然后，助手将继续主题中的后续步骤。

错误响应变量类型将是任何。 您可以使用解析值节点将其转换为 Power Fx 记录。

属性窗格还包含请求超时属性，该属性接受以毫秒为单位的值。 默认值为 30 秒，但如果需要，您可以更改该值。