Créer des API serverless dans Visual Studio à l’aide d’Azure Functions et de l’intégration d’API Management

Article
06/01/2023

Les API REST sont souvent décrites à l’aide d’une définition OpenAPI. Ce fichier contient des informations sur les opérations d’une API et sur la manière dont les données de requête et de réponse de l’API doivent être structurées.

Dans ce tutoriel, vous allez apprendre à :

Créer un projet de fonction serverless dans Visual Studio
Tester les API de fonction localement à l’aide des fonctionnalités OpenAPI intégrées
Publier le projet dans une application de fonction dans Azure avec l’intégration de Gestion des API
Obtenir la clé d’accès pour la fonction et la définir dans Gestion des API
Télécharger le fichier de définition OpenAPI

La fonction serverless que vous créez fournit une API qui vous permet de déterminer si une réparation d’urgence sur une éolienne est rentable. Étant donné que l’application de fonction et l’instance Gestion des API que vous créez utilisent des plans de consommation, le coût d’exécution de ce didacticiel est minime.

Notes

L’intégration d’OpenAPI et du service Gestion des API décrite dans cet article est actuellement prise en charge uniquement pour les fonctions de bibliothèque de classes C# in-process. Les fonctions de bibliothèque de classes C# Processus worker isolé et tous les autres runtimes de langage doivent plutôt utiliser l’intégration du service Gestion des API Azure à partir du portail.

Prérequis

Visual Studio 2022. Assurez-vous de sélectionner la charge de travail Développement Azure lors de l’installation.
Un abonnement Azure actif, créez un compte gratuit avant de commencer.

Créer un projet Functions

Le modèle de projet Azure Functions dans Visual Studio crée un projet que vous pouvez publier dans une application de fonction dans Azure. Vous allez également créer une fonction déclenchée par HTTP qui prend en charge la génération du fichier de définition OpenAPI (anciennement Swagger).

Dans le menu de Visual Studio, sélectionnez Fichier>Nouveau>Projet.
Dans Créer un projet, entrez functions dans la zone de recherche, choisissez le modèle Azure Functions, puis sélectionnez Suivant.
Dans Configurer votre nouveau projet, entrez un Nom de projet tel que TurbineRepair, puis sélectionnez Créer.

Pour les paramètres Créer une application Azure Functions, utilisez les valeurs du tableau suivant :

Paramètre	Valeur	Description
Worker Functions	.NET 6	Cette valeur crée un projet de fonction qui s’exécute in-process sur la version 4.x du runtime Azure Functions, ce qui est obligatoire pour la génération de fichiers OpenAPI.
Modèle de fonction	Déclencheur HTTP avec OpenAPI	Cette valeur crée une fonction déclenchée par une requête HTTP, avec la possibilité de générer un fichier de définition OpenAPI.
Utiliser Azurite pour le compte de stockage du runtime (AzureWebJobsStorage)	Selected	Vous pouvez utiliser l’émulateur pour le développement local des fonctions de déclencheur HTTP. Étant donné qu’une application de fonction dans Azure nécessite un compte de stockage, celui-ci est attribué ou créé quand vous publiez votre projet sur Azure.
Niveau d’autorisation	Fonction	Dans Azure, les clients doivent fournir une clé lors de l’accès au point de terminaison. Pour plus d’informations sur les clés et l’autorisation, consultez la section sur les clés d’accès de fonction.

Paramètres de projet Azure Functions

Sélectionnez Créer pour créer le projet de fonction et la fonction de déclencheur HTTP avec prise en charge d’OpenAPI.

Visual Studio crée un projet et la classe Function1 qui contient un code réutilisable pour le type de fonction de déclencheur HTTP. Ensuite, vous remplacez ce code de modèle de fonction par votre propre code personnalisé.

Mettre à jour le code de fonction

La fonction utilise un déclencheur HTTP qui accepte deux paramètres :

Nom du paramètre	Description
hours	Durée estimée pour la réparation d’une turbine, jusqu’à l’heure entière la plus proche.
capacité	La capacité de l’éolienne, exprimée en kilowatts.

La fonction calcule ensuite le coût de la réparation et les revenus engendrés par 24 heures de fonctionnement de l’éolienne. Les paramètres sont fournis dans la chaîne de requête ou dans la charge utile d’une requête POST.

Dans le fichier de projet Function1.cs, remplacez le contenu du code de la bibliothèque de classes générée par le code suivant :

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; } 
    }
}

Ce code de fonction retourne un message Yes ou No pour indiquer si une réparation d’urgence est rentable. Elle retourne également l’opportunité de revenu que représente la turbine et le coût de la réparation.

Exécuter et vérifier l’API localement

Lorsque vous exécutez la fonction, les points de terminaison OpenAPI facilitent l’essai de la fonction localement à l’aide d’une page générée. Vous n’avez pas besoin de fournir des clés d’accès de fonction lors de l’exécution locale.

Appuyez sur F5 pour démarrer le projet. Lorsque le runtime Azure Functions démarre localement, un jeu de points de terminaison OpenAPI et Swagger est affiché dans la sortie, ainsi que le point de terminaison de la fonction.
Dans votre navigateur, ouvrez le point de terminaison RenderSwaggerUI, qui doit ressembler à http://localhost:7071/api/swagger/ui. Une page est produite en fonction de vos définitions OpenAPI.
Sélectionnez POST>Essayer, entrez des valeurs pour hours et capacity en tant que paramètres de requête ou dans le corps de la requête JSON, puis sélectionnez Exécuter.
Lorsque vous entrez des valeurs entières telles que 6 pour hours et 2500 pour capacity, vous obtenez une réponse JSON ressemblant à l’exemple suivant :

Vous disposez maintenant d’une fonction qui détermine la rentabilité des réparations d’urgence. Ensuite, vous publiez votre projet et vos définitions d’API dans Azure.

Publication du projet sur Azure

Avant de pouvoir publier votre projet, vous devez disposer d’une application de fonction dans votre abonnement Azure. La publication Visual Studio crée une application de fonction automatiquement la première fois que vous publiez votre projet. Elle peut également créer une instance Gestion des API qui s’intègre à votre application de fonction pour exposer l’API TurbineRepair.

Dans l’Explorateur de solutions, cliquez avec le bouton droit sur le projet et sélectionnez Publier puis, dans Cible, sélectionnez Azure, puis Suivant.
Pour Cible spécifique, choisissez Application de fonction Azure (Windows) afin de créer une application de fonction s’exécutant sur Windows, puis sélectionnez Suivant.
Dans Instance de la fonction, choisissez + Créer une application Azure Function... .

Créez une instance en utilisant les valeurs spécifiées dans le tableau suivant :

Paramètre	Valeur	Description
Nom	Nom globalement unique	Nom qui identifie uniquement votre nouvelle application de fonction. Acceptez ce nom ou entrez un nouveau nom. Les caractères valides sont `a-z`, `0-9` et `-`.
Abonnement	Votre abonnement	Sélectionnez l’abonnement Azure à utiliser. Acceptez cet abonnement ou sélectionnez-en un nouveau dans la liste déroulante.
Groupe de ressources	Nom de votre groupe de ressources	Groupe de ressources dans lequel créer votre application de fonction. Sélectionnez un groupe de ressources existant dans la liste déroulante, ou choisissez Créer pour créer un groupe de ressources.
Type de plan	Consommation	Quand vous publiez votre projet dans une application de fonction qui s’exécute dans un Plan Consommation, vous payez uniquement pour les exécutions de votre application de fonction. D’autres plans d’hébergement occasionnent des coûts plus élevés.
Lieu	Emplacement du service	Choisissez un Emplacement dans une région proche de chez vous, ou proche d’autres services auxquels vos fonctions ont accès.
Stockage Azure	Compte de stockage à usage général	Le runtime Functions exige un compte Stockage Azure. Sélectionnez Nouveau pour configurer un compte de stockage universel. Vous pouvez également choisir un compte existant qui répond aux exigences relatives aux comptes de stockage.

Créer une application de fonction dans Azure avec Stockage

Sélectionnez Créer pour créer une application de fonction et les ressources associées dans Azure. L’état de la création des ressources est affiché en bas à gauche de la fenêtre.
De retour dans Instance de fonction, vérifiez que Exécuter à partir du fichier de package est coché. Votre application de fonction est déployée en utilisant Zip Deploy avec le mode Exécuter à partir du fichier de package activé. Cette méthode de déploiement est recommandée pour votre projet Functions, car elle offre de meilleures performances.
Sélectionnez Suivant, puis, dans la page Gestion des API, choisissez également + Create an API Management API (Créer une API Gestion des API).

Créez une API dans Gestion des API à l’aide des valeurs du tableau suivant :

Paramètre	Valeur	Description
Nom de l’API	TurbineRepair	Nom de l’API.
Nom d’abonnement	Votre abonnement	Sélectionnez l’abonnement Azure à utiliser. Acceptez cet abonnement ou sélectionnez-en un nouveau dans la liste déroulante.
Groupe de ressources	Nom de votre groupe de ressources	Sélectionnez le même groupe de ressources que votre application de fonction dans la liste déroulante.
Service Gestion des API	Nouvelle instance	Sélectionnez Nouveau pour créer une nouvelle instance Gestion des API dans le niveau serverless.

Créer une instance Gestion des API avec une API

Sélectionnez Créer pour créer l’instance Gestion des API avec l’API TurbineRepair à partir de l’intégration de la fonction.
Sélectionnez Terminer, vérifiez la page Publier qui indique Prêt à publier, puis sélectionnez Publier pour déployer le package contenant vos fichiers de projet vers votre nouvelle application de fonction dans Azure.

Une fois le déploiement terminé, l’URL racine de l’application de fonction dans Azure est affichée sous l’onglet Publier.

Obtenir la clé d’accès à une fonction

Sous l’onglet Publier, sélectionnez les points de suspension ( ... ) en regard de Hébergement, puis sélectionnez Ouvrir dans le portail Azure. L’application de fonction que vous avez créée est ouverte dans le Portail Azure dans votre navigateur par défaut.
Sous Fonctions, sélectionnez Fonctions>TurbineRepair, puis sélectionnez Touches de fonction.
Sous Clés de fonction, sélectionnez Par défaut et copiez la valeur. Vous pouvez maintenant définir cette clé dans Gestion des API pour qu’elle puisse accéder au point de terminaison de la fonction.

Configuration de Gestion des API

Sous l’onglet Publier , sélectionnez les points de suspension ( ... ) en regard de Hébergement , puis sélectionnez Open API in Azure portal (Ouvrir l’API dans le portail Azure). L’instance Gestion des API que vous avez créée est ouverte dans le Portail Azure dans votre navigateur par défaut. Cette instance Gestion des API est déjà liée à votre application de fonction.
Sous API, sélectionnez OpenAPI Document sur Azure Functions>POST Run, puis, sous Traitement entrant, sélectionnez Ajouter une stratégie.
Dans Traitement entrant, choisissez Définir les paramètres de la requête, tapez code dans Name (Nom), sélectionnez +Value (Valeur), collez la touche de fonction copiée, puis sélectionnez Enregistrer. La Gestion des API comprend la touche de fonction lors du passage de l’appel au point de terminaison de la fonction.

Maintenant que la clé de fonction est définie, vous pouvez appeler l’API pour vérifier qu’elle fonctionne lorsqu’elle est hébergée dans Azure.

Vérifier l’API dans Azure

Dans l’API, sélectionnez l’onglet Test, puis POST Run, entrez le code suivant dans le Corps de la demande>Raw (Brut), puis sélectionnez Envoyer :
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Comme précédemment, vous pouvez également fournir les mêmes valeurs que les paramètres de requête.
Sélectionnez Envoyer, puis affichez la Réponse HTTP pour vérifier que les mêmes résultats sont retournés à partir de l’API.

Télécharger la définition OpenAPI

Si votre API fonctionne comme prévu, vous pouvez télécharger la définition OpenAPI.

1. Sous API, sélectionnez OpenAPI Document sur Azure Functions, sélectionnez les points de suspension (...) et sélectionnez Exporter.
Choisissez les moyens d’exportation d’API, y compris les fichiers OpenAPI dans différents formats. Vous pouvez également exporter des API depuis Gestion des API Azure vers Power Platform.

Nettoyer les ressources

Au cours des étapes précédentes, vous avez créé des ressources Azure au sein d’un groupe de ressources. Si vous ne pensez pas avoir besoin de ces ressources à l’avenir, vous pouvez les supprimer en supprimant le groupe de ressources.

Dans le menu ou la page d’accueil du portail Azure, sélectionnez Groupes de ressources. Ensuite, dans la page Groupes de ressources, sélectionnez le groupe que vous avez créé.

Dans la page myResourceGroup, assurez-vous que les ressources répertoriées sont bien celles que vous souhaitez supprimer.

Sélectionnez Supprimer le groupe de ressources, tapez le nom de votre groupe dans la zone de texte pour confirmer, puis sélectionnez Supprimer.

Étapes suivantes

Vous avez utilisé Visual Studio 2022 pour créer une fonction qui est auto-documentée en raison de l’extension OpenAPI et qui est intégrée à Gestion des API. Vous pouvez maintenant affiner la définition dans la page Gestion des API du portail. Vous pouvez aussi en savoir plus sur la Gestion des API.

Modifier la définition OpenAPI dans la Gestion des API