Esercitazione: Ospitare un'API RESTful con CORS nel servizio app di AzureTutorial: Host a RESTful API with CORS in Azure App Service

Servizio app di Azure offre un servizio di hosting Web con scalabilità elevata e funzioni di auto-correzione.Azure App Service provides a highly scalable, self-patching web hosting service. Il servizio app mette anche a disposizione il supporto integrato per la condivisione di risorse tra le origini (CORS) per le API RESTful.In addition, App Service has built-in support for Cross-Origin Resource Sharing (CORS) for RESTful APIs. Questa esercitazione illustra come distribuire un'app per le API ASP.NET Core nel servizio app con supporto per CORS.This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. L'app verrà configurata usando gli strumenti da riga di comando e distribuita tramite Git.You configure the app using command-line tools and deploy the app using Git.

In questa esercitazione si apprenderà come:In this tutorial, you learn how to:

  • Creare risorse del servizio app usando l'interfaccia della riga di comando di AzureCreate App Service resources using Azure CLI
  • Distribuire un'API RESTful in Azure con GitDeploy a RESTful API to Azure using Git
  • Abilitare il supporto per CORS del servizio appEnable App Service CORS support

I passaggi illustrati in questa esercitazione possono essere eseguiti in macOS, Linux e Windows.You can follow the steps in this tutorial on macOS, Linux, Windows.

Se non si ha una sottoscrizione di Azure, creare un account gratuito prima di iniziare.If you don't have an Azure subscription, create a free account before you begin.

PrerequisitiPrerequisites

Per completare questa esercitazione:To complete this tutorial:

Creare un'app ASP.NET Core localeCreate local ASP.NET Core app

In questo passaggio si configura il progetto ASP.NET Core locale.In this step, you set up the local ASP.NET Core project. Il servizio app supporta lo stesso flusso di lavoro per le API scritte in altri linguaggi.App Service supports the same workflow for APIs written in other languages.

Clonare l'applicazione di esempioClone the sample application

Nella finestra del terminale usare il comando cd per passare a una directory di lavoro.In the terminal window, cd to a working directory.

Eseguire il comando seguente per clonare l'archivio di esempio.Run the following command to clone the sample repository.

git clone https://github.com/Azure-Samples/dotnet-core-api

Questo repository contiene un'app creata in base all'esercitazione Pagine della Guida dell'API Web ASP.NET Core con Swagger.This repository contains an app that's created based on the following tutorial: ASP.NET Core Web API help pages using Swagger. Usa un generatore di Swagger per distribuire l'interfaccia utente Swagger e l'endpoint JSON Swagger.It uses a Swagger generator to serve the Swagger UI and the Swagger JSON endpoint.

Eseguire l'applicazioneRun the application

Usare i comandi seguenti per installare i pacchetti necessari, eseguire le migrazioni dei database e avviare l'applicazione.Run the following commands to install the required packages, run database migrations, and start the application.

cd dotnet-core-api
dotnet restore
dotnet run

Passare a http://localhost:5000/swagger in un browser per provare a usare l'interfaccia utente Swagger.Navigate to http://localhost:5000/swagger in a browser to play with the Swagger UI.

API ASP.NET Core in esecuzione in locale

Passare a http://localhost:5000/api/todo e visualizzare un elenco di elementi ToDo JSON.Navigate to http://localhost:5000/api/todo and see a list of ToDo JSON items.

Passare a http://localhost:5000 e provare a usare l'app browser.Navigate to http://localhost:5000 and play with the browser app. L'app browser verrà successivamente puntata a un'API remota del servizio app per testare la funzionalità CORS.Later, you will point the browser app to a remote API in App Service to test CORS functionality. Il codice per l'app browser è disponibile nella directory wwwroot del repository.Code for the browser app is found in the repository's wwwroot directory.

Per arrestare ASP.NET Core in qualsiasi momento, premere Ctrl+C nel terminale.To stop ASP.NET Core at any time, press Ctrl+C in the terminal.

Usare Azure Cloud ShellUse Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattivo ospitato in Azure e usato tramite il browser.Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Cloud Shell consente di usare bash o PowerShell per interagire con i servizi di Azure.Cloud Shell lets you use either bash or PowerShell to work with Azure services. È possibile usare i comandi preinstallati di Cloud Shell per eseguire il codice contenuto in questo articolo senza dover installare strumenti nell'ambiente locale.You can use the Cloud Shell pre-installed commands to run the code in this article without having to install anything on your local environment.

Per avviare Azure Cloud Shell:To launch Azure Cloud Shell:

OpzioneOption Esempio/CollegamentoExample/Link
Selezionare Prova nell'angolo superiore destro di un blocco di codice.Select Try It in the upper-right corner of a code block. La selezione di Prova non comporta la copia automatica del codice in Cloud Shell.Selecting Try It doesn't automatically copy the code to Cloud Shell. Esempio di Prova per Azure Cloud Shell
Passare a https://shell.azure.com o selezionare il pulsante Avvia Cloud Shell per aprire Cloud Shell nel browser.Go to https://shell.azure.com or select the Launch Cloud Shell button to open Cloud Shell in your browser. Avviare Cloud Shell in una nuova finestraLaunch Cloud Shell in a new window
Selezionare il pulsante Cloud Shell nella barra dei menu nell'angolo superiore destro del portale di Azure.Select the Cloud Shell button on the top-right menu bar in the Azure portal. Pulsante Cloud Shell nel portale di Azure

Per eseguire il codice di questo articolo in Azure Cloud Shell:To run the code in this article in Azure Cloud Shell:

  1. Avviare Cloud Shell.Launch Cloud Shell.

  2. Selezionare il pulsante Copia in un blocco di codice per copiare il codice.Select the Copy button on a code block to copy the code.

  3. Incollare il codice nella sessione di Cloud Shell premendo CTRL+MAIUSC+V in Windows e Linux o CMD+MAIUSC+V in macOS.Paste the code into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS.

  4. Premere INVIO per eseguire il codice.Press Enter to run the code.

Distribuire l'app in AzureDeploy app to Azure

In questo passaggio si distribuisce l'applicazione .NET Core connessa al database SQL nel servizio app.In this step, you deploy your SQL Database-connected .NET Core application to App Service.

Configurare la distribuzione con l'istanza Git localeConfigure local git deployment

FTP e l'istanza Git locale possono essere usati per la distribuzione in un'app Web tramite un utente della distribuzione.FTP and local Git can deploy to an Azure web app by using a deployment user. Dopo aver configurato l'utente della distribuzione, è possibile usarlo per tutte le distribuzioni di Azure.Once you configure your deployment user, you can use it for all your Azure deployments. Il nome utente e la password della distribuzione a livello di account sono diversi dalle credenziali della sottoscrizione di Azure.Your account-level deployment username and password are different from your Azure subscription credentials.

Per configurare l'utente della distribuzione, eseguire il comando az webapp deployment user set in Azure Cloud Shell.To configure the deployment user, run the az webapp deployment user set command in Azure Cloud Shell. Sostituire <username> e <password> con il nome utente e la password di un utente della distribuzione.Replace <username> and <password> with a deployment user username and password.

  • Il nome utente deve essere univoco in Azure e per i push Git locali non deve contenere il simbolo "@".The username must be unique within Azure, and for local Git pushes, must not contain the ‘@’ symbol.
  • La password deve essere composta da almeno otto caratteri, con due dei tre elementi seguenti: lettere, numeri e simboli.The password must be at least eight characters long, with two of the following three elements: letters, numbers, and symbols.
az webapp deployment user set --user-name <username> --password <password>

L'output JSON mostra la password come null.The JSON output shows the password as null. Se viene visualizzato un errore 'Conflict'. Details: 409, modificare il nome utente.If you get a 'Conflict'. Details: 409 error, change the username. Se viene visualizzato un errore 'Bad Request'. Details: 400, usare una password più complessa.If you get a 'Bad Request'. Details: 400 error, use a stronger password.

Registrare il nome utente e la password da usare per distribuire le app Web.Record your username and password to use to deploy your web apps.

Creare un gruppo di risorseCreate a resource group

Un gruppo di risorse è un contenitore logico in cui vengono distribuite e gestite risorse di Azure come app Web, database e account di archiviazione.A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. Ad esempio, si può scegliere in un secondo momento di eliminare l'intero gruppo di risorse in un unico semplice passaggio.For example, you can choose to delete the entire resource group in one simple step later.

In Cloud Shell creare un gruppo di risorse con il comando az group create.In the Cloud Shell, create a resource group with the az group create command. L'esempio seguente crea un gruppo di risorse denominato myResourceGroup nella località West Europe.The following example creates a resource group named myResourceGroup in the West Europe location. Per visualizzare tutte le località supportate per il servizio app nel livello gratuito, eseguire il comando az appservice list-locations --sku FREE.To see all supported locations for App Service in Free tier, run the az appservice list-locations --sku FREE command.

az group create --name myResourceGroup --location "West Europe"

In genere, il gruppo di risorse e le risorse vengono create in un'area vicina alla località dell'utente.You generally create your resource group and the resources in a region near you.

Al termine del comando, un output JSON visualizza le proprietà del gruppo di risorse.When the command finishes, a JSON output shows you the resource group properties.

Creare un piano di servizio appCreate an App Service plan

In Cloud Shell creare un piano di servizio app con il comando az appservice plan create.In the Cloud Shell, create an App Service plan with the az appservice plan create command.

L'esempio seguente crea un piano di servizio app denominato myAppServicePlan nel piano tariffario Gratuito:The following example creates an App Service plan named myAppServicePlan in the Free pricing tier:

az appservice plan create --name myAppServicePlan --resource-group myResourceGroup --sku FREE

Al termine della creazione del piano di servizio app, l'interfaccia della riga di comando di Azure visualizza informazioni simili all'esempio seguente:When the App Service plan has been created, the Azure CLI shows information similar to the following example:

{ 
  "adminSiteName": null,
  "appServicePlanName": "myAppServicePlan",
  "geoRegion": "West Europe",
  "hostingEnvironmentProfile": null,
  "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
  "kind": "app",
  "location": "West Europe",
  "maximumNumberOfWorkers": 1,
  "name": "myAppServicePlan",
  < JSON data removed for brevity. >
  "targetWorkerSizeId": 0,
  "type": "Microsoft.Web/serverfarms",
  "workerTierName": null
} 

Creare un'app WebCreate a web app

Creare un'app Web nel piano di servizio app myAppServicePlan.Create a web app in the myAppServicePlan App Service plan.

In Cloud Shell è possibile usare il comando az webapp create.In the Cloud Shell, you can use the az webapp create command. Nell'esempio seguente sostituire <app-name> con un nome app univoco globale. I caratteri validi sono a-z, 0-9 e -.In the following example, replace <app-name> with a globally unique app name (valid characters are a-z, 0-9, and -).

az webapp create --resource-group myResourceGroup --plan myAppServicePlan --name <app-name> --deployment-local-git

Dopo la creazione dell'app Web, l'interfaccia della riga di comando di Azure mostra un output simile all'esempio seguente:When the web app has been created, the Azure CLI shows output similar to the following example:

Local git is configured with url of 'https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<app-name>.azurewebsites.net",
  "deploymentLocalGitUrl": "https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

Nota

L'URL dell'elemento Git remoto è riportato nella proprietà deploymentLocalGitUrl, con il formato https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git.The URL of the Git remote is shown in the deploymentLocalGitUrl property, with the format https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Salvare questo URL, perché è necessario in un secondo momento.Save this URL as you need it later.

Effettuare il push in Azure da GitPush to Azure from Git

Nella finestra del terminale locale aggiungere un'istanza remota di Azure al repository Git locale.Back in the local terminal window, add an Azure remote to your local Git repository. Sostituire <deploymentLocalGitUrl-from-create-step> con l'URL del Git remoto salvato in Creare un'app Web.Replace <deploymentLocalGitUrl-from-create-step> with the URL of the Git remote that you saved from Create a web app.

git remote add azure <deploymentLocalGitUrl-from-create-step>

Effettuare il push all'istanza remota di Azure per distribuire l'app con il comando seguente.Push to the Azure remote to deploy your app with the following command. Quando Git Credential Manager chiede le credenziali, assicurarsi di immettere quelle create in Configurare un utente della distribuzione, non quelle usate per accedere al portale di Azure.When prompted for credentials by Git Credential Manager, make sure that you enter the credentials you created in Configure a deployment user, not the credentials you use to sign in to the Azure portal.

git push azure master

L'esecuzione del comando può richiedere alcuni minuti.This command may take a few minutes to run. Durante l'esecuzione, il comando visualizza informazioni simili all'esempio seguente:While running, it displays information similar to the following example:

Counting objects: 98, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (92/92), done.
Writing objects: 100% (98/98), 524.98 KiB | 5.58 MiB/s, done.
Total 98 (delta 8), reused 0 (delta 0)
remote: Updating branch 'master'.
remote: .
remote: Updating submodules.
remote: Preparing deployment for commit id '0c497633b8'.
remote: Generating deployment script.
remote: Project file path: ./DotNetCoreSqlDb.csproj
remote: Generated deployment script files
remote: Running deployment command...
remote: Handling ASP.NET Core Web Application deployment.
remote: .
remote: .
remote: .
remote: Finished successfully.
remote: Running post deployment command(s)...
remote: Deployment successful.
remote: App container will begin restart within 10 seconds.
To https://<app_name>.scm.azurewebsites.net/<app_name>.git
 * [new branch]      master -> master

Passare all'app AzureBrowse to the Azure app

Passare a http://<app_name>.azurewebsites.net/swagger in un browser e provare a usare l'interfaccia utente Swagger.Navigate to http://<app_name>.azurewebsites.net/swagger in a browser and play with the Swagger UI.

API ASP.NET Core in esecuzione nel servizio app di Azure

Passare a http://<app_name>.azurewebsites.net/swagger/v1/swagger.json per visualizzare il file swagger.json per l'API distribuita.Navigate to http://<app_name>.azurewebsites.net/swagger/v1/swagger.json to see the swagger.json for your deployed API.

Passare a http://<app_name>.azurewebsites.net/api/todo per visualizzare l'API distribuita in funzione.Navigate to http://<app_name>.azurewebsites.net/api/todo to see your deployed API working.

Aggiungere funzionalità CORSAdd CORS functionality

Abilitare ora il supporto integrato per CORS nel servizio app per l'API.Next, you enable the built-in CORS support in App Service for your API.

Testare CORS nell'app di esempioTest CORS in sample app

Nel repository locale aprire wwwroot/index.html.In your local repository, open wwwroot/index.html.

Nella riga 51 impostare la variabile apiEndpoint sull'URL dell'API distribuita (http://<app_name>.azurewebsites.net).In Line 51, set the apiEndpoint variable to the URL of your deployed API (http://<app_name>.azurewebsites.net). Sostituire <appname> con il nome dell'app nel servizio app.Replace <appname> with your app name in App Service.

Nella finestra del terminale locale eseguire di nuovo l'app di esempio.In your local terminal window, run the sample app again.

dotnet run

Passare all'app browser all'indirizzo http://localhost:5000.Navigate to the browser app at http://localhost:5000. Aprire la finestra degli strumenti di sviluppo nel browser (Ctrl+Shift+i in Chrome per Windows) ed esaminare la scheda Console. Verrà visualizzato il messaggio di errore No 'Access-Control-Allow-Origin' header is present on the requested resourceOpen the developer tools window in your browser (Ctrl+Shift+i in Chrome for Windows) and inspect the Console tab. You should now see the error message, No 'Access-Control-Allow-Origin' header is present on the requested resource.

Errore CORS nel client browser

A causa della mancata corrispondenza di dominio tra l'app browser (http://localhost:5000) e la risorsa remota (http://<app_name>.azurewebsites.net) e dato che l'API nel servizio app non invia l'intestazione Access-Control-Allow-Origin, il browser ha impedito il caricamento di contenuto tra domini nell'app browser.Because of the domain mismatch between the browser app (http://localhost:5000) and remote resource (http://<app_name>.azurewebsites.net), and the fact that your API in App Service is not sending the Access-Control-Allow-Origin header, your browser has prevented cross-domain content from loading in your browser app.

Nell'ambiente di produzione, l'app browser avrebbe un URL pubblico anziché l'URL localhost, ma la modalità di abilitazione di CORS per un URL localhost e per un URL pubblico è la stessa.In production, your browser app would have a public URL instead of the localhost URL, but the way to enable CORS to a localhost URL is the same as a public URL.

Abilitare CORSEnable CORS

In Cloud Shell abilitare CORS per l'URL del client usando il comando az resource update.In the Cloud Shell, enable CORS to your client's URL by using the az resource update command. Sostituire il segnaposto <appname> .Replace the <appname> placeholder.

az resource update --name web --resource-group myResourceGroup --namespace Microsoft.Web --resource-type config --parent sites/<app_name> --set properties.cors.allowedOrigins="['http://localhost:5000']" --api-version 2015-06-01

È possibile impostare più di un URL client in properties.cors.allowedOrigins ("['URL1','URL2',...]").You can set more than one client URL in properties.cors.allowedOrigins ("['URL1','URL2',...]"). È anche possibile abilitare tutti gli URL client con "['*']".You can also enable all client URLs with "['*']".

Nota

Se l'app richiede l'invio di credenziali, ad esempio cookie o token di autenticazione, il browser potrebbe richiedere l'intestazione ACCESS-CONTROL-ALLOW-CREDENTIALS nella risposta.If your app requires credentials such as cookies or authentication tokens to be sent, the browser may require the ACCESS-CONTROL-ALLOW-CREDENTIALS header on the response. Per abilitarla nel servizio app, impostare properties.cors.supportCredentials su true nel file di configurazione di CORS. Non è possibile abilitarla quando allowedOrigins include '*'.To enable this in App Service, set properties.cors.supportCredentials to true in your CORS config. This cannot be enabled when allowedOrigins includes '*'.

Testare di nuovo CORSTest CORS again

Aggiornare l'app browser all'indirizzo http://localhost:5000.Refresh the browser app at http://localhost:5000. Il messaggio di errore nella finestra Console non viene più visualizzato ed è possibile esaminare i dati dell'API distribuita e interagirvi.The error message in the Console window is now gone, and you can see the data from the deployed API and interact with it. L'API remota supporta ora CORS per l'app browser in esecuzione in locale.Your remote API now supports CORS to your browser app running locally.

Supporto per CORS abilitato nel client browser

L'API viene ora eseguita nel servizio app di Azure con il supporto per CORS.Congratulations, you're running an API in Azure App Service with CORS support.

CORS del servizio app e CORS personalizzatoApp Service CORS vs. your CORS

È possibile usare le proprie utilità CORS anziché le utilità CORS del servizio app per una maggiore flessibilità.You can use your own CORS utilities instead of App Service CORS for more flexibility. Può essere ad esempio opportuno specificare origini consentite differenti per route e metodi diversi.For example, you may want to specify different allowed origins for different routes or methods. Poiché CORS del servizio app consente di specificare un set di origini accettate per tutte le route e i metodi dell'API, si vuole usare il proprio codice CORS.Since App Service CORS lets you specify one set of accepted origins for all API routes and methods, you would want to use your own CORS code. Per informazioni sul modo in cui ASP.NET Core esegue questa operazione, vedere Abilitare le richieste tra le origini (CORS).See how ASP.NET Core does it at Enabling Cross-Origin Requests (CORS).

Nota

Non provare a usare il codice CORS del servizio app e il proprio codice CORS insieme.Don't try to use App Service CORS and your own CORS code together. Se usati insieme, il codice CORS del servizio app ha la precedenza e il proprio codice CORS non avrà alcun effetto.When used together, App Service CORS takes precedence and your own CORS code has no effect.

Pulire le risorseClean up resources

Nei passaggi precedenti sono state create risorse di Azure in un gruppo di risorse.In the preceding steps, you created Azure resources in a resource group. Se si ritiene che queste risorse non saranno necessarie in futuro, eliminare il gruppo di risorse eseguendo questo comando in Cloud Shell:If you don't expect to need these resources in the future, delete the resource group by running the following command in the Cloud Shell:

az group delete --name myResourceGroup

L'esecuzione del comando può richiedere un minuto.This command may take a minute to run.

Passaggi successiviNext steps

Contenuto dell'esercitazione:What you learned:

  • Creare risorse del servizio app usando l'interfaccia della riga di comando di AzureCreate App Service resources using Azure CLI
  • Distribuire un'API RESTful in Azure con GitDeploy a RESTful API to Azure using Git
  • Abilitare il supporto per CORS del servizio appEnable App Service CORS support

Passare all'esercitazione successiva per apprendere come autenticare e autorizzare gli utenti.Advance to the next tutorial to learn how to authenticate and authorize users.