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).
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, del tipo
TurbineRepair, quindi selezionare Crea.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:
.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.
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. 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:
Nel menu Strumenti selezionare Gestione pacchetti NuGet>Console di Gestione pacchetti.
Nella console eseguire il comando Install-Package seguente per installare l'estensione OpenAPI:
NuGet\Install-Package Microsoft.Azure.Functions.Worker.Extensions.OpenApi -Version 1.5.1Potrebbe 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:
In Esplora soluzioni, fare clic con il pulsante destro del mouse sul nodo del progetto e selezionare Aggiungi>Nuova funzione di Azure.
Immettere Turbine.cs per la classe e quindi selezionare Aggiungi.
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:
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; }
}
}
}
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.
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.
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>Provalo, immettere i valori per
hoursecapacitycome parametri di query o nel corpo della richiesta JSON, quindi selezionare Esegui.
Quando si immettono valori interi come 6 per
hourse 2500 percapacity, 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.
In Esplora soluzionifare clic con il pulsante destro del mouse sul progetto e scegliere Pubblica e in Destinazioneselezionare Azure. Quindi selezionare Avanti.
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.
In Istanza 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-9e-.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. 
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.
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.
Selezionare Avanti e nella pagina Gestione API scegliere anche + Crea un'API di 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 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. 
Selezionare Crea per creare l'istanza di Gestione API con l'API TurbineRepair dall'integrazione della funzione.
Selezionare Fine e al termine del processo di creazione del profilo di pubblicazione selezionare Chiudi.
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
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.
In Funzioni nella pagina Panoramica selezionare> Turbine e quindi chiavi funzione.
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
Nella pagina dell'app per le funzioni espandere API e selezionare Gestione API.
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.
Selezionare Vai a Gestione API nella parte superiore della pagina e nell'istanza di Gestione API espandere LE API.
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.
Sotto Elaborazione in ingresso, in Imposta parametri di query, digitare
codeper 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
Nell'API selezionare la scheda Test e quindi Esecuzione POST, immettere il codice seguente nel Corpo della richiesta>Non elaborato e selezionare Invia:
{ "hours": "6", "capacity": "2500" }
Come in precedenza, è anche possibile specificare gli stessi valori dei parametri di query.
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.
-
- In API selezionare Documento OpenAPI in Funzioni di Azure, selezionare i puntini di sospensione (...) e selezionare Esporta.
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.