Creare API serverless in Visual Studio usando Funzioni di Azure e l'integrazione di Gestione API

Le API REST vengono spesso descritte usando un file di definizione OpenAPI (noto in precedenza come Swagger). Questo file contiene informazioni sulle operazioni in un'API e sul modo in cui devono essere strutturati i dati di richiesta e risposta per l'API.

In questa esercitazione apprenderai a:

• Creare il progetto di codice in Visual Studio
• Installare l'estensione OpenAPI
• Aggiungere un endpoint trigger HTTP, che include definizioni OpenAPI
• Testare le API della funzione in locale usando la funzionalità OpenAPI predefinita
• Pubblicare un progetto in un'app per le funzioni in Azure
• Abilitare l'integrazione di Gestione API
• Scaricare il file di definizione OpenAPI

La funzione serverless creata fornisce un'API che consente di determinare se un ripristino di emergenza in una turbina eolica è conveniente. Poiché si creano sia l'app per le funzioni che l'istanza di Gestione API in un livello a consumo, il costo per il completamento di questa esercitazione è minimo.

Prerequisiti

• Visual Studio 2022. Durante l'installazione assicurarsi di selezionare il carico di lavoro Sviluppo di Azure.

• Una sottoscrizione di Azure attiva, prima di iniziare creare un account gratuito.

Creare il progetto di codice

Il modello di progetto Funzioni di Azure in Visual Studio crea un progetto che è possibile pubblicare in un'app per le funzioni in Azure. Si creerà anche una funzione attivata tramite HTTP da un modello che supporta la generazione di file di definizione OpenAPI (in precedenza file Swagger).

1. Nel menu di Visual Studio selezionare File>Nuovo>Progetto.

2. In Crea un nuovo progetto immettere funzioni nella casella di ricerca, scegliere il modello Funzioni di Azure e quindi selezionare Avanti.

3. In Configura il nuovo progetto immettere un nome progetto per il progetto, del tipo TurbineRepair, quindi selezionare Crea.

4. Per Creare una nuova Funzioni di Azure impostazioni dell'applicazione, selezionare una di queste opzioni per Il ruolo di lavoro funzioni, in cui l'opzione scelta dipende dal modello di processo scelto:

   Modello di lavoro isolato

   .NET 8.0 Isolato (supporto a lungo termine): le funzioni C# vengono eseguite nel modello di lavoro isolato, consigliato. Per altre informazioni, vedere la guida al modello di lavoro isolato.

   In-process

   Importante

   Il supporto terminerà per il modello in-process il 10 novembre 2026. È consigliabile eseguire la migrazione delle app al modello di lavoro isolato per il supporto completo.

   .NET 8.0 (supporto a lungo termine): le funzioni C# vengono eseguite nel modello in-process, che verrà ritirato. Per altre informazioni, vedere la guida al modello in-process.

5. Per le altre opzioni, usare i valori nella tabella seguente:

   Impostazione	valore	Descrizione
   Modello di funzione	vuoto	In questo modo viene creato un progetto senza un trigger, che offre un maggiore controllo sul nome della funzione attivata tramite HTTP quando viene aggiunto in un secondo momento.
   Usare Azurite per l'account storage di runtime (AzureWebJobsStorage)	Selected	È possibile usare l'emulatore per lo sviluppo locale delle funzioni trigger HTTP. Poiché un'app per le funzioni in Azure richiede un account di archiviazione, ne viene assegnato o creato uno quando si pubblica il progetto in Azure.
   Livello di autorizzazione	Funzione	Quando si esegue in Azure, i client devono fornire una chiave, quando accedono all'endpoint. Per altre informazioni, vedere Livello di autorizzazione.

6. Selezionare Crea per creare il progetto di funzione.

Aggiornare quindi il progetto installando l'estensione OpenAPI per Funzioni di Azure, che consente l'individuazione degli endpoint API nell'app.

Installare l'estensione OpenAPI

Per installare l'estensione OpenAPI:

1. Nel menu Strumenti selezionare Gestione pacchetti NuGet>Console di Gestione pacchetti.

2. Nella console eseguire il comando Install-Package seguente per installare l'estensione OpenAPI:

   Modello di lavoro isolato

   command

   NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1
   

   Potrebbe essere necessario aggiornare la versione specifica, in base alla versione di .NET.

   Modello di processo

   command

   NuGet\Install-Package Microsoft.Azure.WebJobs.Extensions.OpenApi -Version 1.5.1
   

   Potrebbe essere necessario aggiornare la versione specifica, in base alla versione di .NET.

A questo punto, è possibile aggiungere la funzione endpoint HTTP.

Aggiungere una funzione endpoint HTTP

In una libreria di classi C# le associazioni usate dalla funzione vengono definite applicando attributi nel codice. Per creare una funzione con un trigger HTTP:

1. In Esplora soluzioni, fare clic con il pulsante destro del mouse sul nodo del progetto e selezionare Aggiungi>Nuova funzione di Azure.

2. Immettere Turbine.cs per la classe e quindi selezionare Aggiungi.

3. Scegliere il modello di trigger Http, impostare Livello di autorizzazione su Funzione e quindi selezionare Aggiungi. Un file di codice Turbine.cs viene aggiunto al progetto che definisce un nuovo endpoint di funzione con un trigger HTTP.

È ora possibile sostituire il codice del modello di trigger HTTP con il codice che implementa l'endpoint della funzione Turbine, insieme agli attributi che usano OpenAPI per definire l'endpoint.

Aggiornare il codice funzione

La funzione usa un trigger HTTP che accetta due parametri:

Nome parametro	Descrizione
hours	Il tempo stimato per il ripristino della turbina, fino all'ora intera più vicina.
capacity	La capacità della turbina in kilowatt.

La funzione calcola quindi la quantità di costi di riparazione e la quantità di ricavi che la turbina potrebbe produrre in un periodo di 24 ore. I parametri vengono forniti nella stringa di query o nel payload di una richiesta POST.

Nel file di progetto Turbine.cs sostituire il contenuto della classe generata dal modello di trigger HTTP con il codice seguente, che dipende dal modello di processo:

Modello di lavoro isolato

C#

using Microsoft.AspNetCore.Http;
using Microsoft.AspNetCore.Mvc;
using Microsoft.Azure.Functions.Worker;
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;
using System.Net;

namespace TurbineRepair
{
    public class Turbine
    {
        const double revenuePerkW = 0.12;
        const double technicianCost = 250;
        const double turbineCost = 100;

        private readonly ILogger<Turbine> _logger;

        public Turbine(ILogger<Turbine> logger)
        {
            _logger = logger;
        }

        [Function("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 new OkObjectResult(new
            {
                message = repairTurbine,
                revenueOpportunity = "$" + revenueOpportunity,
                costToFix = "$" + costToFix
            });
        }
        public class RequestBodyModel
        {
            public int Hours { get; set; }
            public int Capacity { get; set; }
        }
    }
}

Modello di processo

C#

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

Questo codice di funzione restituisce un messaggio Yes o No per indicare se una riparazione urgente è economicamente conveniente. Restituisce inoltre l'opportunità di ricavi offerta dalla turbina e il costo della riparazione.

Eseguire e verificare l'API in locale

Quando si esegue la funzione, gli endpoint OpenAPI semplificano la prova della funzione in locale usando una pagina generata. Durante l'esecuzione in locale, non è necessario fornire le chiavi di accesso alle funzioni.

1. Per avviare il progetto premere F5. Quando il runtime di Funzioni viene avviato in locale, nell'output viene visualizzato un set di endpoint OpenAPI e Swagger, insieme all'endpoint della funzione.

2. Nel browser aprire l'endpoint RenderSwaggerUI, che dovrebbe essere simile a http://localhost:7071/api/swagger/ui. Viene eseguito il rendering di una pagina in base alle definizioni OpenAPI.

3. Selezionare POST>Provalo, immettere i valori per hours e capacity come parametri di query o nel corpo della richiesta JSON, quindi selezionare Esegui.

   

4. Quando si immettono valori interi come 6 per hours e 2500 per capacity, si ottiene una risposta JSON simile all'esempio seguente:

   

A questo punto si ha una funzione che determina la convenienza delle riparazioni urgenti. Successivamente, si pubblicano in Azure le definizioni di progetto e delle API.

Pubblicare il progetto in Azure

Per poter pubblicare il progetto, è prima necessario che la sottoscrizione di Azure includa un'app per le funzioni. La pubblicazione di Visual Studio crea un'app per le funzioni la prima volta che si pubblica il progetto. Può anche creare un'istanza di Gestione API che si integra con l'app per le funzioni, per esporre l'API TurbineRepair.

1. In Esplora soluzionifare clic con il pulsante destro del mouse sul progetto e scegliere Pubblica e in Destinazioneselezionare Azure. Quindi selezionare Avanti.

2. Per Destinazione specifica scegliere App per le funzioni di Azure (Windows) per creare un'app per le funzioni in esecuzione in Windows. Quindi selezionare Avanti.

3. In Istanza funzione, scegliere + Crea una nuova funzione di Azure...

   

4. Creare una nuova istanza usando i valori specificati nella tabella seguente:

   Impostazione	valore	Descrizione
   Nome	Nome globalmente univoco	Nome che identifica in modo univoco la nuova app per le funzioni. Accettare questo nome o immetterne uno nuovo. I caratteri validi sono a-z, 0-9 e -.
   Abbonamento	Sottoscrizione in uso	Sottoscrizione di Azure da usare. Accettare questa sottoscrizione o selezionarne una nuova dall'elenco a discesa.
   Gruppo di risorse	Nome del gruppo di risorse	Gruppo di risorse in cui creare l'app per le funzioni. Selezionare un gruppo di risorse esistente dall'elenco a discesa oppure scegliere Nuovo per creare un nuovo gruppo di risorse.
   Tipo di piano	Consumo	Quando si pubblica il progetto in un'app per le funzioni eseguita in un piano a consumo, vengono addebitati solo i costi relativi alle esecuzioni dell'app per le funzioni. Altri piani di hosting comportano costi più elevati.
   Location	Ubicazione del servizio	Scegliere una località in un'area nelle vicinanze o vicino ad altri servizi a cui accedono le funzioni.
   Archiviazione di Azure	Account di archiviazione per utilizzo generico	Per il runtime di Funzioni è richiesto un account di archiviazione di Azure. Selezionare Nuovo per configurare un account di archiviazione per utilizzo generico. È anche possibile scegliere un account esistente che soddisfi i requisiti dell'account di archiviazione.

   

5. Selezionare Crea per creare un'app per le funzioni e le relative risorse in Azure. Lo stato della creazione della risorsa viene visualizzato nell'angolo in basso a sinistra della finestra.

6. In Istanza funzione, assicurarsi che sia selezionata l'opzione Esegui da file di pacchetto. L'app per le funzioni viene distribuita usando la distribuzione ZIP con la modalità esecuzione da pacchetto abilitata. Questo metodo di distribuzione è consigliato per il progetto di funzioni, perché offre prestazioni migliori.

7. Selezionare Avanti e nella pagina Gestione API scegliere anche + Crea un'API di Gestione API.

8. Creare un'API in Gestione API usando i valori nella tabella seguente:

   Impostazione	valore	Descrizione
   Nome API	TurbineRepair	Nome per l'API.
   Nome della sottoscrizione	Sottoscrizione in uso	Sottoscrizione di Azure da usare. Accettare questa sottoscrizione o selezionarne una nuova dall'elenco a discesa.
   Gruppo di risorse	Nome del gruppo di risorse	Dall’elenco a discesa, selezionare lo stesso gruppo di risorse dell'app per le funzioni.
   Servizio Gestione API	Nuova istanza	Selezionare Nuovo per creare una nuova istanza di Gestione API nella stessa posizione nel livello serverless. Selezionare OK per creare l'istanza.

   

9. Selezionare Crea per creare l'istanza di Gestione API con l'API TurbineRepair dall'integrazione della funzione.

10. Selezionare Fine e al termine del processo di creazione del profilo di pubblicazione selezionare Chiudi.

11. Verificare che la pagina Pubblica sia ora Pronto per la pubblicazione e quindi selezionare Pubblica per distribuire il pacchetto contenente i file di progetto nella nuova app per le funzioni in Azure.

    Al termine della distribuzione, l'URL radice dell'app per le funzioni in Azure viene visualizzato nella scheda Pubblica.

Ottenere la chiave di accesso alla funzione

1. Nella scheda Pubblicare selezionare i puntini di sospensione (...) accanto a Hosting e selezionare Apri nel portale di Azure. L'app per le funzioni creata viene aperta nel portale di Azure nel browser predefinito.

2. In Funzioni nella pagina Panoramica selezionare> Turbine e quindi chiavi funzione.

   

3. In Chiavi funzione selezionare l'icona copia negli Appunti accanto alla chiave predefinita . È ora possibile impostare questa chiave copiata in Gestione API in modo che possa accedere all'endpoint della funzione.

Configurare Gestione API

1. Nella pagina dell'app per le funzioni espandere API e selezionare Gestione API.

2. Se l'app per le funzioni non è già connessa alla nuova istanza di Gestione API, selezionarla in Gestione API, selezionare Documento OpenAPI API>in Funzioni di Azure, verificare che l'opzione Importa funzioni sia selezionata e selezionare Collega API. Assicurarsi che solo TurbineRepair sia selezionato per l'importazione e quindi selezionare.

3. Selezionare Vai a Gestione API nella parte superiore della pagina e nell'istanza di Gestione API espandere LE API.

4. In API Tutte le>API selezionare OpenAPI Document on Funzioni di Azure POST Run (Apri documento OPENAPI in Funzioni di Azure> POST Run), quindi in Elaborazione in ingresso selezionare Aggiungi>parametri di query Imposta criteri.

5. Sotto Elaborazione in ingresso, in Imposta parametri di query, digitare code per Nome, selezionare +Valore, incollare la chiave della funzione copiata e selezionare Salva. Gestione API include la chiave di funzione quando passa le chiamate all'endpoint della funzione.

   

Ora che la chiave della funzione è impostata, è possibile chiamare l'endpoint turbine API per verificare che funzioni quando è ospitato in Azure.

Verificare l'API in Azure

1. Nell'API selezionare la scheda Test e quindi Esecuzione POST, immettere il codice seguente nel Corpo della richiesta>Non elaborato e selezionare Invia:

   JSON

   {
       "hours": "6",
       "capacity": "2500"
   }
   

   

   Come in precedenza, è anche possibile specificare gli stessi valori dei parametri di query.

2. Selezionare Invia e quindi visualizzare la risposta HTTP per verificare che gli stessi risultati siano restituiti dall'API.

Scaricare la definizione OpenAPI

Se l'API funziona come previsto, è possibile scaricare la definizione OpenAPI per le nuove API ospitate da Gestione API.

1. 1. In API selezionare Documento OpenAPI in Funzioni di Azure, selezionare i puntini di sospensione (...) e selezionare Esporta.

   

2. Scegliere i mezzi di esportazione dell'API, inclusi i file OpenAPI in vari formati. È anche possibile esportare LE API da Gestione API di Azure a Power Platform.

Pulire le risorse

Nei passaggi precedenti sono state create risorse di Azure in un gruppo di risorse. Se non si prevede di aver bisogno di queste risorse in futuro, è possibile eliminarle eliminando il gruppo di risorse.

Nel menu del portale di Azure o nella pagina Home selezionare Gruppi di risorse. Nella pagina Gruppi di risorse selezionare il gruppo creato.

Nella pagina myResourceGroup assicurarsi che le risorse elencate siano quelle da eliminare.

Selezionare Elimina gruppo di risorse, digitare il nome del gruppo nella casella di testo per confermare, quindi selezionare Elimina.

Passaggi successivi

È stato usato Visual Studio 2022 per creare una funzione autodocumentante a causa dell'estensione OpenAPI e integrata con Gestione API. Ora è possibile perfezionare la definizione in Gestione API nel portale. Sono anche disponibili altre informazioni su Gestione API.

Modificare la definizione OpenAPI in Gestione API