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

Articolo
06/01/2023

Le API REST vengono spesso descritte usando una definizione OpenAPI. Questo file contiene informazioni sulle operazioni in un'API e su come devono essere strutturati i dati di richiesta e risposta per l'API.

In questa esercitazione verranno illustrate le procedure per:

Creare un progetto di funzione serverless in Visual Studio
Testare le API della funzione in locale usando la funzionalità OpenAPI predefinita
Pubblicare un progetto in un'app per le funzioni in Azure con integrazione Gestione API
Ottenere la chiave di accesso per la funzione e impostarla in Gestione API
Scaricare il file di definizione OpenAPI

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

Nota

L'integrazione openAPI e Gestione API in primo piano in questo articolo è attualmente supportata solo per le funzioni della libreria di classi C# in-process. Processo di lavoro isolato Le funzioni della libreria di classi C# e tutti gli altri runtime del linguaggio devono usare invece l'integrazione di Azure Gestione API dal portale.

Prerequisiti

Visual Studio 2022. Assicurarsi di selezionare il carico di lavoro Sviluppo di Azure durante l'installazione.
Una sottoscrizione di Azure attiva, creare un account gratuito prima di iniziare.

Creare un progetto di Funzioni

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

Nel menu di Visual Studio selezionare File>Nuovo>Progetto.
In Crea un nuovo progetto immettere funzioni nella casella di ricerca, scegliere il modello Funzioni di Azure e quindi selezionare Avanti.
In Configura il nuovo progetto immettere un nome progetto per il progetto, ad esempio TurbineRepaire quindi selezionare Crea.

Per le impostazioni di Crea una nuova applicazione Funzioni di Azure usare i valori della tabella seguente:

Impostazione	Valore	Descrizione
Ruolo di lavoro per le funzioni	.NET 6	Questo valore crea un progetto di funzione che viene eseguito in-process nella versione 4.x del runtime Funzioni di Azure, necessario per la generazione di file OpenAPI.
Modello di funzione	Trigger HTTP con OpenAPI	Questo valore crea una funzione attivata da una richiesta HTTP, con la possibilità di generare un file di definizione OpenAPI.
Usare Azurite per l'account di archiviazione di runtime (AzureWebJobsStorage)	Selected	È possibile usare l'emulatore per lo sviluppo locale di funzioni trigger HTTP. Poiché un'app per le funzioni in Azure richiede un account di archiviazione, ne viene assegnata o creata una quando si pubblica il progetto in Azure.
Livello di autorizzazione	Funzione	Quando vengono eseguiti in Azure, i client devono fornire una chiave quando si accede all'endpoint. Per altre informazioni sulle chiavi e sull'autorizzazione, vedere Chiavi di accesso alle funzioni.

Impostazioni del progetto di Funzioni di Azure

Selezionare Crea per creare il progetto di funzione e la funzione trigger HTTP, con supporto per OpenAPI.

Visual Studio crea un progetto e una classe denominata Function1 che contiene il codice boilerplate per il tipo di funzione trigger HTTP. Sostituire quindi questo codice modello di funzione con il codice personalizzato.

Aggiornare il codice funzione

La funzione usa un trigger HTTP che accetta due parametri:

Nome parametro	Descrizione
Ore	Tempo stimato per la riparazione di una turbina, fino all'ora intera più vicina.
Capacità	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 Function1.cs sostituire il contenuto del codice della libreria di classi generato con il codice seguente:

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

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. Non è necessario fornire chiavi di accesso alle funzioni durante l'esecuzione in locale.

Premere F5 per avviare il progetto. 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.
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.
Selezionare POST>Prova, immettere i valori per hours e capacity come parametri di query o nel corpo della richiesta JSON e selezionare Esegui.
Quando si immettono valori integer 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 le definizioni di progetto e API in Azure.

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.

In Esplora soluzioni fare clic con il pulsante destro del mouse sul progetto e scegliere Pubblica e in Destinazione, selezionare Azure e quindi Avanti.
Per La destinazione specifica scegliere App per le funzioni di Azure (Windows) per creare un'app per le funzioni in esecuzione in Windows, quindi selezionare Avanti.
In Istanza di funzione scegliere + Crea una nuova funzione di Azure....

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 `-`.
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	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.
Posizione	Posizione 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.

Creare una nuova app per le funzioni in Azure con Archiviazione

Selezionare Crea per creare un'app per le funzioni e le relative risorse in Azure. Lo stato della creazione della risorsa viene visualizzato nella parte inferiore sinistra della finestra.
Tornare all'istanza di Funzioni, assicurarsi che sia selezionata l'opzione Esegui dal file del 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, poiché comporta prestazioni migliori.
Selezionare Avanti e nella pagina Gestione API scegliere anche + Crea un'API Gestione API.

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

Impostazione	Valore	Descrizione
Nome API	TurbineRepair	Nome per l'API.
Nome 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	Selezionare lo stesso gruppo di risorse dell'app per le funzioni dall'elenco a discesa.
Servizio Gestione API	Nuova istanza	Selezionare Nuovo per creare una nuova istanza di Gestione API nel livello serverless.

Creare Gestione API istanza con l'API

Selezionare Crea per creare l'istanza di Gestione API con l'API TurbineRepair dall'integrazione della funzione.
selezionare Fine, verificare che la pagina Pubblica indichi 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

Nella scheda Pubblica selezionare i puntini di sospensione (...) accanto a Hosting e selezionare Apri in portale di Azure. L'app per le funzioni creata viene aperta nella portale di Azure nel browser predefinito.
In Funzioni selezionare Funzioni>TurbineRepair e quindi chiavi di funzione.
In Chiavi di funzione selezionare impostazione predefinita e copiare il valore. È ora possibile impostare questa chiave in Gestione API in modo che possa accedere all'endpoint della funzione.

Configurare Gestione API

Nella scheda Pubblica selezionare i puntini di sospensione (...) accanto a Hosting e selezionare Apri API in portale di Azure. L'istanza Gestione API creata viene aperta nel portale di Azure nel browser predefinito. Questa Gestione API istanza è già collegata all'app per le funzioni.
In API selezionare OpenAPI Document on Funzioni di Azure>POST Run (Esegui openAPI) e quindi in Elaborazione in ingresso selezionare Aggiungi criterio.
Nell'elaborazione in ingresso seguente, in Imposta parametri di query digitare code per Nome, selezionare +Valore, incollare nella chiave della funzione copiata e selezionare Salva. Gestione API include la chiave della funzione quando passa chiamate all'endpoint della funzione.

Ora che la chiave di funzione è impostata, è possibile chiamare l'API per verificare che funzioni quando è ospitata in Azure.

Verificare l'API in Azure

Nell'API selezionare la scheda Test e quindi POST Run (Esegui) immettere il codice seguente nel corpo> della richiestaNon elaborato e selezionare Invia:
```
{
    "hours": "6",
    "capacity": "2500"
}
```
Come prima, è anche possibile specificare gli stessi valori dei parametri di query.
Selezionare Invia e quindi visualizzare la risposta HTTP per verificare che gli stessi risultati vengano restituiti dall'API.

Scaricare la definizione OpenAPI

Se l'API funziona come previsto, è possibile scaricare la definizione OpenAPI.

1. In API selezionare Apri documentoAPI in Funzioni di Azure, selezionare i puntini di sospensione (...) e selezionare Esporta.
Scegliere il mezzo di esportazione dell'API, inclusi i file OpenAPI in vari formati. È anche possibile esportare LE API da Azure Gestione API 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 quindi 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 e 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

Condividi tramite