发出 HTTP 请求

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

必备条件

• 创建和编辑主题

使用 HTTP 请求节点

1. 在您希望调用外部 API 的节点下方，选择 添加节点 图标，指向 高级，然后选择 发送 HTTP 请求。

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

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

   

4. 在节点上的标头和正文下，选择编辑按钮，这将打开 HTTP 请求属性面板。

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

   

   您可以使用“标头”部分传递身份验证令牌、内容类型或调用该 API 所需的任何其他标头。 例如，您可以添加类似 Authorization: Bearer <your_token> 的标头来对请求进行身份验证。

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

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

   您可以提供一个示例 JSON 响应，通常可以在您调用的 API 的文档中找到。 它会生成一个 Power Fx 变量，允许您在创作画布的其他位置使用该变量，并在 Power Fx 编辑器中支持智能感知功能。 选择从样本数据中，然后选择从样本 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 请求返回错误或执行失败时，代理将停止其操作并触发出错系统主题，显示错误消息。

不过，也可以配置错误处理，使其不触发出错系统主题。 您也可以将其配置为将 HTTP 状态码和任何错误响应正文存储到您指定的变量中。 您可以根据需要查询这些变量，而主题仍可继续运行。 当您希望智能体即使在特定 HTTP 请求失败时仍继续运行时，此配置非常有用。

要配置 HTTP 请求节点的错误处理行为，请执行以下操作：

1. 在标头和正文下，选择编辑。 此时将显示 HTTP 请求属性面板。

2. 在错误处理下，选择所需的行为：抛出错误或出错时继续。

3. 如果选择出错时继续，为状态代码和错误响应正文配置变量。

   

在此示例中，如果 HTTP 请求失败，代理会将 HTTP 状态代码存储在 Topic.StatusCode 变量中，并将响应正文存储在 Topic.ErrorResponse 变量中。 智能体将继续执行该主题中的后续步骤。

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

在 HTTP 请求属性面板中，还可以设置请求超时属性（以毫秒为单位）。 默认值为 30 秒。