Creación de API sin servidor en Visual Studio usando Azure Functions y la integración de API Management
Las API de REST a menudo se describen con una definición de OpenAPI. Este archivo contiene información acerca de operaciones en una API y sobre cómo se deben estructurar los datos de la solicitud y la respuesta para dicha API.
En este tutorial aprenderá a:
- crear un proyecto de función sin servidor en Visual Studio;
- probar localmente API de función mediante la funcionalidad integrada de OpenAPI;
- publicar un proyecto en una aplicación de funciones de Azure mediante la integración de API Management;
- obtener la clave de acceso para la función y establecerla en API Management;
- descargar el archivo de definición de OpenAPI.
La función sin servidor que cree proporciona una API con la que puede determinar si resulta rentable una reparación de emergencia en una turbina eólica. Dado que tanto la aplicación de funciones como la instancia de API Management que cree usan planes de consumo, completar este tutorial tiene un coste mínimo para usted.
Nota
Actualmente, la integración de OpenAPI y API Management que se incluye en este artículo solo se admite para las funciones de biblioteca de clases de C# en proceso. Las funciones de la biblioteca de clases de C# de proceso de trabajo aislado y todos los otros runtimes de lenguaje deben usar la integración de API Management de Azure desde el portal en su lugar.
Requisitos previos
Visual Studio 2022. Asegúrese de seleccionar la carga de trabajo de desarrollo de Azure durante la instalación.
Una suscripción a Azure que esté activa. Si no la tiene, cree una cuenta gratuita antes de empezar.
Creación de un proyecto de Functions
La plantilla del proyecto de Azure Functions de Visual Studio crea un proyecto que puede publicar en una aplicación de función en Azure. También creará una función desencadenada por HTTP que permite generar el archivo de definición de OpenAPI (anteriormente archivo Swagger).
En el menú de Visual Studio, seleccione Archivo>Nuevo>Proyecto.
En Crear un proyecto, escriba functions en el cuadro de búsqueda, elija la plantilla Azure Functions y seleccione Siguiente.
En Configurar el nuevo proyecto, rellene el campo Nombre del proyecto (por ejemplo,
TurbineRepair) y seleccione Crear.En la configuración de Crear aplicación de Azure Functions, use los valores de la tabla siguiente:
Configuración Value Descripción Trabajo de Functions .NET 6 Este valor crea un proyecto de función que se ejecuta en-proceso en la versión 4.x del runtime de Azure Functions, que es necesario para la generación de archivos OpenAPI. Plantilla de función Desencadenador HTTP con OpenAPI Este valor crea una función desencadenada por una solicitud HTTP, con la opción de generar un archivo de definición de OpenAPI. Usar Azurita para la cuenta de almacenamiento de runtime (AzureWebJobsStorage) Selected Puede usar el emulador para el desarrollo local de funciones de desencadenador HTTP. Dado que una aplicación de funciones de Azure necesita una cuenta de almacenamiento, se asigna o se crea una cuando publica su proyecto en Azure. Nivel de autorización Función Cuando se ejecutan en Azure, los clientes deben proporcionar una clave al acceder al punto de conexión. Para obtener más información sobre las claves y la autorización, consulte Claves de acceso de función. 
Seleccione Crear para crear el proyecto de función y la función de desencadenador HTTP, con la opción de usar OpenAPI.
Visual Studio crea un proyecto y una clase de nombre Function1, que contiene código reutilizable para el tipo de función de desencadenador HTTP. A continuación, reemplace este código de plantilla de función por su propio código personalizado.
Actualización del código de la función
La función usa un desencadenador HTTP que toma dos parámetros:
| Nombre de parámetro | Descripción |
|---|---|
| hours | Tiempo estimado para reparar una turbina, redondeado a la hora completa más cercana. |
| capacidad | La capacidad de la turbina, en kilovatios. |
A continuación, la función calcula el coste de la reparación y los ingresos que podría generar la turbina en un período de 24 horas. Los parámetros se proporcionan en la cadena de consulta o en la carga de una solicitud POST.
En el archivo de proyecto Function1.cs, reemplace el contenido del código de biblioteca de clases generado por el siguiente código:
using System;
using System.IO;
using System.Net;
using System.Threading.Tasks;
using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.WebJobs;
using Microsoft.Azure.WebJobs.Extensions.Http;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Attributes;
using Microsoft.Azure.WebJobs.Extensions.OpenApi.Core.Enums;
using Microsoft.Extensions.Logging;
using Microsoft.OpenApi.Models;
using Newtonsoft.Json;
namespace TurbineRepair
{
public static class Turbines
{
const double revenuePerkW = 0.12;
const double technicianCost = 250;
const double turbineCost = 100;
[FunctionName("TurbineRepair")]
[OpenApiOperation(operationId: "Run")]
[OpenApiSecurity("function_key", SecuritySchemeType.ApiKey, Name = "code", In = OpenApiSecurityLocationType.Query)]
[OpenApiRequestBody("application/json", typeof(RequestBodyModel),
Description = "JSON request body containing { hours, capacity}")]
[OpenApiResponseWithBody(statusCode: HttpStatusCode.OK, contentType: "application/json", bodyType: typeof(string),
Description = "The OK response message containing a JSON result.")]
public static async Task<IActionResult> Run(
[HttpTrigger(AuthorizationLevel.Function, "post", Route = null)] HttpRequest req,
ILogger log)
{
// Get request body data.
string requestBody = await new StreamReader(req.Body).ReadToEndAsync();
dynamic data = JsonConvert.DeserializeObject(requestBody);
int? capacity = data?.capacity;
int? hours = data?.hours;
// Return bad request if capacity or hours are not passed in
if (capacity == null || hours == null)
{
return new BadRequestObjectResult("Please pass capacity and hours in the request body");
}
// Formulas to calculate revenue and cost
double? revenueOpportunity = capacity * revenuePerkW * 24;
double? costToFix = (hours * technicianCost) + turbineCost;
string repairTurbine;
if (revenueOpportunity > costToFix)
{
repairTurbine = "Yes";
}
else
{
repairTurbine = "No";
};
return (ActionResult)new OkObjectResult(new
{
message = repairTurbine,
revenueOpportunity = "$" + revenueOpportunity,
costToFix = "$" + costToFix
});
}
}
public class RequestBodyModel
{
public int Hours { get; set; }
public int Capacity { get; set; }
}
}
Este código de función devuelve un mensaje de Yes o No para indicar si una reparación de emergencia es rentable. También devuelve la oportunidad de ingresos que representa la turbina y el costo de repararla.
Ejecución y comprobación locales de la API
Al ejecutar la función, los puntos de conexión de OpenAPI hacen que resulte fácil probar la función localmente usando una página generada. No es necesario proporcionar claves de acceso de función cuando se ejecuta localmente.
Presione F5 para iniciar el proyecto. Cuando el entorno de ejecución de Functions se inicia localmente, se muestra un conjunto de puntos de conexión de OpenAPI y Swagger en la salida, junto con el punto de conexión de la función.
En el explorador, abra el punto de conexión RenderSwaggerUI, que debe tener un aspecto parecido a
http://localhost:7071/api/swagger/ui. Se representa una página en función de las definiciones de OpenAPI.Seleccione POST>Pruébelo, especifique valores para
hoursycapacity, ya sea como parámetros de consulta o en el cuerpo de la solicitud JSON, y seleccione Ejecutar.
Si especifica valores enteros, como 6 para
hoursy 2500 paracapacity, obtendrá una respuesta JSON similar al siguiente ejemplo:
Ahora ya existe una función que determina la rentabilidad de las reparaciones de emergencia. A continuación, publique el proyecto y las definiciones de API en Azure.
Publicar el proyecto en Azure
Para poder publicar el proyecto, debe tener una aplicación de funciones en la suscripción de Azure. La publicación de Visual Studio crea una aplicación de funciones la primera vez que publica su proyecto. También puede crear una instancia de API Management que se integra con su aplicación de funciones para exponer la API TurbineRepair.
En el Explorador de soluciones, haga clic con el botón derecho en el proyecto y seleccione Publicar, en Destino, seleccione Azure y, a continuación, seleccione Siguiente.
En Destino específico, elija Aplicación de funciones de Azure (Windows) , para crear una aplicación de funciones que se ejecute en Windows, y seleccione Siguiente.
En Instancia de la función, seleccione + Crear una nueva función de Azure… .
Crear una nueva instancia con los valores especificados en la tabla siguiente:
Configuración Value Descripción Nombre Nombre único globalmente Nombre que identifica de forma única la nueva aplicación de función. Acepte este nombre o escriba uno nuevo. Los caracteres válidos son a-z,0-9y-.Suscripción Su suscripción La suscripción de Azure que se va a usar. Acepte esta suscripción o seleccione una nueva en la lista desplegable. Grupo de recursos Nombre del grupo de recursos Nombre del grupo de recursos en el que se va a crear la aplicación de función. Seleccione un grupo de recursos existente en la lista desplegable o elija la opción Nuevo para crear un nuevo grupo de recursos. Tipo de plan Consumo Cuando publique el proyecto en una aplicación de funciones que se ejecute en un plan Consumo, solo pagará por las ejecuciones de la aplicación. Otros planes de hospedaje suponen costos más elevados. Ubicación Ubicación del servicio Elija una ubicación en una región próxima a usted o a otros servicios a los que las funciones accedan. Azure Storage Cuenta de almacenamiento de uso general El entorno de ejecución de Functions necesita una cuenta de Azure Storage. Seleccione Nueva para configurar una cuenta de almacenamiento de uso general. También puede elegir una cuenta existente que cumpla los requisitos de la cuenta de almacenamiento. 
Seleccione Crear para crear una aplicación de funciones y sus recursos relacionados en Azure. El estado de la creación del recurso se muestra en la parte inferior izquierda de la ventana.
En Instancia de Functions, asegúrese de que la opción Ejecutar desde archivo de paquete esté activada. La aplicación de funciones se implementa con la implementación de un archivo zip y con el modo de ejecución desde el paquete habilitado. Este es el método de implementación recomendado para su proyecto de Functions, ya que proporciona un mejor rendimiento.
Seleccione Siguiente y, en la página API Management, elija también + Crear una API de API Management.
Para crear una API en API Management, use los valores de la siguiente tabla:
Configuración Value Descripción Nombre de la API TurbineRepair Nombre de la API. Nombre de la suscripción Su suscripción La suscripción de Azure que se va a usar. Acepte esta suscripción o seleccione una nueva en la lista desplegable. Grupos de recursos Nombre del grupo de recursos En la lista desplegable, seleccione el mismo grupo de recursos que la aplicación de funciones. Servicio API Management Nueva instancia Seleccione Nuevo para crear una instancia de API Management en el nivel sin servidor. 
Seleccione Crear para crear la instancia de API Management con la API TurbineRepair a partir de la integración de funciones.
Seleccione Finalizar y verifique que aparece Listo para publicar en la página de publicación. A continuación, seleccione Publicar para implementar el paquete con los archivos del proyecto en su nueva aplicación de funciones de Azure.
Una vez finalizada la implementación, en la pestaña Publicar aparecerá la dirección URL raíz de la aplicación de funciones de Azure.
Obtención de la clave de acceso de función
En la pestaña Publicar, seleccione los puntos suspensivos ( … ) junto a Hospedaje y seleccione Abrir en Azure Portal. La aplicación de funciones que ha creado se abrirá en Azure Portal en su navegador predeterminado.
En Funciones, seleccione Funciones>TurbineRepair y, a continuación, Claves de función.
En Claves de función, seleccione valor predeterminado y copie el valor. Ya puede establecer esta clave en API Management para que pueda acceder al punto de conexión de la función.
Configuración de API Management
En la pestaña Publicar, seleccione los puntos suspensivos ( … ) junto a Hospedaje y seleccione Abrir API en Azure Portal. La instancia de API Management que ha creado se abrirá en Azure Portal en su navegador predeterminado. Esta instancia de API Management ya está vinculada a la aplicación de funciones.
En API, seleccione Documento OpenAPI en Azure Functions>Ejecución de POST y, luego, en Procesamiento de entrada, seleccione Agregar directiva.
En Procesamiento de entrada, en Establecer parámetros de consulta, escriba
codeen Nombre, seleccione + Valor, pegue la clave de función que se copió y seleccione Guardar. API Management incluye la clave de función cuando pasa llamadas al punto de conexión de la función.
Ahora que la clave de función está establecida, puede llamar a la API para comprobar que funciona cuando se hospeda en Azure.
Comprobación de la API en Azure
En la API, seleccione la pestaña Prueba y Ejecución POST. A continuación, especifique el siguiente código en Cuerpo de la solicitud>Sin formato y seleccione Enviar:
{ "hours": "6", "capacity": "2500" }
Como antes, también puede proporcionar los mismos valores que los parámetros de consulta.
Seleccione Enviar y, a continuación, consulte la respuesta HTTP para comprobar que la API devuelve los mismos resultados.
Descarga de la definición de OpenAPI
Si la API funciona según lo previsto, puede descargar la definición de OpenAPI.
-
- En API, seleccione Documento OpenAPI en Azure Functions, seleccione los tres puntos suspensivos (…) y seleccione Exportar.
Elija el medio de exportación de API, incluidos los archivos OpenAPI en varios formatos. También puede exportar API de Azure API Management a Power Platform.
Limpieza de recursos
En los pasos anteriores, creó recursos de Azure en un grupo de recursos. Si no cree que vaya a necesitar estos recursos en el futuro, puede eliminarlos mediante la eliminación del grupo de recursos.
En el menú de Azure Portal o la página Inicio, seleccione Grupos de recursos. A continuación, en la página Grupos de recursos, seleccione el grupo que ha creado.
En la página myResourceGroup, asegúrese de que los recursos enumerados sean los que desea eliminar.
Seleccione Eliminar grupo de recursos, escriba el nombre de su grupo en el cuadro de texto para confirmar la acción y, a continuación, seleccione Eliminar.
Pasos siguientes
Ha usado Visual Studio 2022 para crear una función que se autodocumenta debido a la extensión OpenAPI y está integrada con API Management. Ahora puede refinar la definición de API Management en el portal. También puede obtener más información acerca de API Management.