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.

Aprire Azure Cloud ShellOpen Azure Cloud Shell

Azure Cloud Shell è un ambiente di shell interattiva ospitato in Azure e usato tramite il browser.Azure Cloud Shell is an interactive shell environment hosted in Azure and used through your browse. Azure Cloud Shell consente di usare la shell bash o PowerShell per eseguire una varietà di strumenti da usare con i servizi di Azure.Azure Cloud Shell allows you to use either bash or PowerShell shells to run a variety of tools to work with Azure services. Azure Cloud Shell è preinstallato con i comandi per consentire di riprodurre il contenuto di questo articolo senza dover installare strumenti nell'ambiente locale.Azure Cloud Shell comes pre-installed with the commands to allow you to run the content of this article without having to install anything on your local environment.

Per eseguire il codice contenuto in questo articolo in Azure Cloud Shell, aprire una sessione di Cloud Shell, usare il pulsante Copia in un blocco di codice per copiare il codice e incollarlo nella sessione di Cloud Shell premendo CTRL+MAIUSC+V in Windows e Linux o CMD+MAIUSC+V in macOS.To run any code contained in this article on Azure Cloud Shell, open a Cloud Shell session, use the Copy button on a code block to copy the code, and paste it into the Cloud Shell session with Ctrl+Shift+V on Windows and Linux, or Cmd+Shift+V on macOS. Il testo incollato non viene eseguito automaticamente. Premere quindi INVIO per eseguire il codice.Pasted text is not automatically executed, so press Enter to run code.

È possibile avviare Azure Cloud Shell nei modi seguenti:You can launch Azure Cloud Shell with:

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. Questa azione non copia automaticamente il testo in Cloud Shell.This doesn't automatically copy text to Cloud Shell. Esempio di Prova per Azure Cloud Shell
Aprire Azure Cloud Shell nel browser.Open Azure Cloud Shell in your browser. <a href="https://shell.azure.com" title="Avvio di Azure Cloud Shell
Selezionare il pulsante Cloud Shell nel menu nell'angolo superiore destro del portale di Azure.Select the Cloud Shell button on the menu in the upper-right corner of the Azure portal. Pulsante Cloud Shell nel portale di Azure

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

In Azure Cloud Shell configurare le credenziali di distribuzione con il comando az webapp deployment user set.In the Azure Cloud Shell, configure deployment credentials with the az webapp deployment user set command. Questo utente della distribuzione è necessario per la distribuzione con FTP e l'istanza Git locale in un'app Web.This deployment user is required for FTP and local Git deployment to a web app. Nome utente e password sono a livello di account.The username and password are account level. Sono quindi diversi dalle credenziali della sottoscrizione di Azure.They're different from your Azure subscription credentials.

Nell'esempio seguente sostituire <username> e <password> (incluse le parentesi) con un nuovo nome utente e una nuova password.In the following example, replace <username> and <password>, including the brackets, with a new username and password. Il nome utente deve essere univoco in Azure.The username must be unique within Azure. 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>

Viene visualizzato un output JSON, con la password visualizzata come null.You get a JSON output with the password shown 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. Il nome utente della distribuzione non può contenere il simbolo '@' per i push Git locali.The deployment username must not contain ‘@’ symbol for local Git pushes.

L'utente della distribuzione deve essere configurato una sola volta.You configure this deployment user only once. È possibile usarlo per tutte le distribuzioni di Azure.You can use it for all your Azure deployments.

Nota

Prendere nota del nome utente e della password.Record the username and password. Saranno necessari per distribuire l'app Web in un secondo momento.You need them to deploy the web app later.

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.