Realizar solicitudes HTTP

En Copilot Studio puede ampliar las capacidades de un agente llamando a API REST externas mediante el nodo de solicitud HTTP. Esta llamada puede resultar útil cuando necesita recuperar datos de un sistema externo o manipular datos en ese sistema.

Requisitos previos

• Creación y edición de temas

Utilizar el nodo de solicitud HTTP

1. Seleccione el icono Agregar nodo en el nodo después del cual desea llamar a una API externa, seleccione Avanzadas y seleccione Enviar solicitud HTTP.

2. En el cuadro URL, introduzca la URL del punto de conexión de API que desea llamar.

3. Seleccione el método de solicitud correcto en la lista desplegable. Se admiten los métodos GET, POST, PATCH, PUT y DELETE.

   

4. En Encabezados y cuerpo del nodo, seleccione el botón Editar , que abre el panel de propiedades de la Solicitud HTTP.

5. Opcionalmente, puede agregar uno o más encabezados a la solicitud HTTP. Seleccione el botón Agregar para agregar la clave y el valor de cada encabezado.

   

   Puede usar la sección de encabezados para pasar tokens de autenticación, tipo de contenido o cualquier otro encabezado necesario para la API a la que llama. Por ejemplo, puede agregar un encabezado como Authorization: Bearer <your_token> para autenticar la solicitud.

6. De forma predeterminada, no se envía ningún contenido en el cuerpo de la solicitud HTTP, pero puede especificar contenido en el cuerpo.

7. En el nodo, elija el Tipo de datos de respuesta de las opciones disponibles.

   Puede proporcionar un ejemplo JSON respuesta, que normalmente puede encontrar en la documentación de la API que está llamando. Genera una variable de Power Fx que le permite usarla en otras partes de su lienzo de creación, con soporte de IntelliSense en el editor de Power Fx. Seleccione A partir de datos de muestra y luego seleccione Obtener el esquema a partir de JSON de muestra. Pegue su muestra respuesta en el editor y seleccione Confirmar.

8. En Guardar respuesta del usuario como, elija dónde desea que se almacene la respuesta a la solicitud HTTP, ya sea creando una nueva variable o seleccionando una existente.

Enviar contenido en el cuerpo de la solicitud HTTP

1. En Encabezados y cuerpo del nodo, seleccione el botón Editar , que abre el panel de propiedades de la Solicitud HTTP.

2. En Cuerpo, seleccione el tipo de contenido apropiado. De manera predeterminada, Cuerpo se establece en Sin contenido, donde no debe haber contenido dentro de cuerpo de la solicitud, que se usa más comúnmente con la solicitud GET. Para agregar contenido al cuerpo, seleccione una de las opciones disponibles.

   

   • Contenido JSON: el contenido JSON le permite proporcionar un objeto JSON en el cuerpo de la solicitud. Este objeto se utiliza a menudo al realizar solicitudes POST o PUT. Cuando se selecciona esta opción, un editor le permite ingresar su contenido JSON.

     También puede especificar el contenido JSON utilizando Power Fx, que permite incluir valores dinámicos y variables de referencia. Seleccione el botón Editar JSON, elija Fórmula y luego ingrese un objeto de Power Fx (cualquier JSON existente que se haya ingresado se convierte en un objeto de Power Fx para usted), que se convierte en JSON cuando se realiza la solicitud HTTP.

     

   • Contenido sin formato: el contenido sin formato le permite insertar una cadena de datos en el cuerpo de la solicitud, y esta cadena puede ser de cualquier tipo de contenido que especifique. El contenido sin procesar se ingresa utilizando una fórmula de Power Fx, como el contenido de cadena que se muestra en el siguiente ejemplo.

     

Control de errores y tiempo de espera

El nodo de Solicitud HTTP tiene múltiples opciones para manejar situaciones en las que la solicitud HTTP podría fallar o devolver un error.

De forma predeterminada, característica genera un error. Esto significa que cuando una solicitud HTTP devuelve un error o no se ejecuta, el agente detiene su operación y activa el tema del sistema En caso de error, que muestra un mensaje de error.

Sin embargo, puede configurar el control de errores para que no desencadene el tema del sistema En caso de error. En su lugar, puede hacer que almacene el código de estado HTTP y cualquier cuerpo de respuesta de error en las variables que especifique. Puede interrogar estas variables según sea necesario y el tema puede continuar ejecutándose. Esta configuración es útil en escenarios en los que desea que el agente continúe funcionando, incluso si se produce un error en una solicitud HTTP determinada.

Para configurar el comportamiento de control de errores de un nodo de Solicitud HTTP:

1. En Encabezados y cuerpo, seleccione Editar. Aparece el panel de Propiedades de la solicitud HTTP.

2. En Control de errores, seleccione el comportamiento deseado: Generar un error o Continuar con el error.

3. Si selecciona Continuar en caso de error, configure variables para el código de estado y el cuerpo de la respuesta al error.

   

En este ejemplo, si se produce un error en la solicitud HTTP, el agente almacena el código de estado HTTP en la variable Topic.StatusCode y el cuerpo de la respuesta en la variable Topic.ErrorResponse. El agente continúa con los siguientes pasos del tema.

El tipo de variable Error de respuesta es Cualquiera. Puede utilizar un nodo Analizar valor para convertir esta variable en un registro de Power Fx.

En el panel de propiedades de solicitud HTTP, también puede establecer una propiedad de tiempo de espera de solicitud, en milisegundos. El valor predeterminado es de 30 segundos.