Compartir a través de

Realizar solicitudes HTTP

  • Artículo

En Copilot Studio, puedes 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

Utilizar el nodo de solicitud HTTP

  1. Seleccione Agregar nodo (+), abra el submenú Avanzado y luego seleccione Enviar solicitud HTTP.

    Captura de pantalla de la opción para enviar solicitud HTTP en el menú avanzado.

  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.

    Captura de pantalla de la URL de API completa y del menú desplegable de métodos

  4. En Encabezados y cuerpo del nodo, seleccione el botón Editar, que abra el panel 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.

    Captura de pantalla de la lista de pares clave-valor de encabezados para el nodo HTTP.

  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.

    Captura de pantalla del esquema Obtener del editor JSON de muestra.

  8. En Guardar respuesta como elija dónde desea que se almacene la respuesta de 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 abra el panel 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.

    Captura de pantalla del menú desplegable de opciones de contenido del cuerpo

    • 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.

      Captura de pantalla del contenido JSON seleccionado para el cuerpo tipo de contenido.

    • 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.

      Captura de pantalla del contenido RAW seleccionado para el cuerpo tipo de contenido.

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, la función "genera un error". Esto significa que cuando una solicitud HTTP devuelve un error o no se ejecuta, agente detiene su funcionamiento y activa el Error tema del sistema, que muestra un mensaje de error.

Sin embargo, puede configurar el manejo de errores para no desencadenar el tema del sistema Error. En lugar de ello, rellena el código de estado HTTP y cualquier cuerpo de respuesta de error en las variables que usted especifica, lo que le permite interrogar estas variables según sea necesario y que el tema continúe ejecutándose. Esta configuración es útil en escenarios donde desea que agente continúe funcionando, incluso si falla una solicitud HTTP particular.

Para configurar el comportamiento de manejo de errores.

  1. En Encabezados y cuerpo del nodo, seleccione el botón Editar, que abra el panel Propiedades de la solicitud HTTP.

  2. Elija el comportamiento que desee en el menú desplegable Manejo de errores .

  3. Si elige Continuar en caso de error, configure las variables Código de estado y Cuerpo de respuesta de error, ya sea creando nuevas variables o seleccionando variables existentes en el selector.

    Captura de pantalla del manejo de errores configurado para continuar en caso de error con variables especificadas para el código de estado y el cuerpo de la respuesta de error.

En este ejemplo de código, si falla la solicitud HTTP, agente almacena el código de estado HTTP en la variable Topic.StatusCode , y cuerpo de la respuesta en la variable Topic.ErrorResponse . El agente continúa con sus próximos pasos en el tema.

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

El panel de propiedades también contiene una propiedad Tiempo de espera de solicitud , que acepta un valor en milisegundos. El valor predeterminado es 30 segundos, pero puede cambiar este valor si es necesario.