مشاركة عبر

Make HTTP requests

  • مقالة

Important

Power Virtual Agents capabilities and features are now part of Microsoft Copilot Studio following significant investments in generative AI and enhanced integrations across Microsoft Copilot.

Some articles and screenshots may refer to Power Virtual Agents while we update documentation and training content.

In Copilot Studio, you can extend a copilot's capabilities by calling external REST APIs using the HTTP request node. This call can be helpful when you need to retrieve data from an external system or manipulate data on that system.

Prerequisites

Use the HTTP request node

  1. Select Add node (+), open the Advanced sub menu, and then select Send HTTP request.

    Screenshot of the send HTTP request option in the advanced menu.

  2. In the URL box, enter the URL for the API endpoint you want to call.

  3. Select the appropriate request Method from the dropdown. GET, POST, PATCH, PUT, and DELETE methods are supported.

    Screenshot of completed API URL and method dropdown

  4. Under Headers and body on the node, select the Edit button, which opens the HTTP request properties pane.

  5. You can optionally add one or more headers to the HTTP request. Select the Add button to add each header's key and value.

    Screenshot of headers key value pair list for HTTP node.

  6. By default, no content is sent in the body of the HTTP request, but you specify content to be sent on the body.

  7. On the node, choose the Response data type from the available options.

    You can provide an example JSON response, which you can usually find in the documentation for the API you're calling. It generates a Power Fx variable, allowing you to use it elsewhere in your authoring canvas, with intellisense support in the Power Fx editor. Select From Sample Data and then select Get schema from sample JSON. Paste your sample response into the editor and select Confirm.

    Screenshot of the Get schema from sample JSON editor.

  8. Under Save response as choose where you want the HTTP request response to be stored, either creating a new variable or selecting an existing one.

Send content in the HTTP request body

  1. Under Headers and body on the node, select the Edit button, which opens the HTTP request properties pane.

  2. Under Body, select the appropriate content type. By default, Body is set to No Content, where no content should be present within the request body, which is most commonly used with the GET request. To add content to the body, select from one of the available options.

    Screenshot of body content options dropdown

    • JSON Content: JSON content allows you to provide a JSON object in the request body. This object is often used when making POST or PUT requests. When this option is selected, an editor allows you to enter your JSON content.

      You can also specify your JSON content using Power Fx, allowing you to include dynamic values and reference variables. Select the Edit JSON button, choose Formula, and then enter a Power Fx object (any existing JSON that was entered is converted into a Power Fx object for you), which is converted into JSON when the HTTP request is made.

      Screenshot of JSON content selected for body content type.

    • Raw content: Raw content lets you insert a string of data into the request body, and this string can be of any content type you specify. Raw content is entered using a Power Fx formula, such as the string content shown in the following example.

      Screenshot of RAW content selected for body content type.

Error handling and timeout

The HTTP request node has multiple options for handling situations where the HTTP request might fail or return an error.

By default, the feature "raises an error." This means that when an HTTP request returns an error or fails to execute, the copilot stops its operation and triggers the Error system topic, displaying an error message.

However, you can configure the error handling to not trigger the Error system topic. Instead, it populates the HTTP status code and any error response body into variables that you specify, allowing you to interrogate these variables as needed, and for the topic to continue to run. This configuration is useful in scenarios where you want the copilot to continue operation, even if a particular HTTP request fails.

To configure the error handling behavior.

  1. Under Headers and body on the node, select the Edit button, which opens the HTTP request properties pane.

  2. Choose your desired behavior from the Error handling dropdown.

  3. If you choose Continue on error, configure the Status code and Error response body variables, either creating new variables or selecting existing variables from the picker.

    Screenshot of error handling configured to continue on error with variables specified for status code and error response body.

In this code sample, if the HTTP request fails, the copilot stores the HTTP status code in the Topic.StatusCode variable, and the response body in the Topic.ErrorResponse variable. The copilot continues to its next steps in the topic.

The Error response variable type is Any. You can use the Parse Value node to convert this variable into a Power Fx record.

The property pane also contains a Request timeout property, which accepts a value in milliseconds. The default value is 30 seconds, but you can change this value if needed.