Tutorial: Hospedaje de una API RESTful con CORS en Azure App ServiceTutorial: Host a RESTful API with CORS in Azure App Service

Azure App Service proporciona un servicio de hospedaje web muy escalable y con aplicación de revisiones de un modo automático.Azure App Service provides a highly scalable, self-patching web hosting service. Además, App Service tiene compatibilidad integrada para el uso compartido de recursos entre orígenes (CORS) para API RESTful.In addition, App Service has built-in support for Cross-Origin Resource Sharing (CORS) for RESTful APIs. En este tutorial se muestra cómo implementar una aplicación de API de ASP. NET Core en App Service con compatibilidad con CORS.This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. Va a configurar la aplicación mediante el uso de herramientas de línea de comandos e implementar la aplicación usando Git.You configure the app using command-line tools and deploy the app using Git.

En este tutorial, aprenderá a:In this tutorial, you learn how to:

  • Crear recursos de App Service mediante la CLI de AzureCreate App Service resources using Azure CLI
  • Implementar una API RESTful en Azure con GitDeploy a RESTful API to Azure using Git
  • Habilitar la compatibilidad con CORS de App ServiceEnable App Service CORS support

También puede seguir los pasos de este tutorial en macOS, Linux, Windows.You can follow the steps in this tutorial on macOS, Linux, Windows.

Si no tiene una suscripción a Azure, cree una cuenta gratuita antes de empezar.If you don't have an Azure subscription, create a free account before you begin.

Requisitos previosPrerequisites

Para completar este tutorial:To complete this tutorial:

Creación de una aplicación ASP.NET Core localCreate local ASP.NET Core app

En este paso, configurará el proyecto ASP.NET Core local.In this step, you set up the local ASP.NET Core project. App Service admite el mismo flujo de trabajo para API escritas en otros lenguajes.App Service supports the same workflow for APIs written in other languages.

Clonación de la aplicación de ejemploClone the sample application

En la ventana del terminal, use cd para cambiar a un directorio de trabajo.In the terminal window, cd to a working directory.

Ejecute el comando siguiente para clonar el repositorio de ejemplo.Run the following command to clone the sample repository.

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

Este repositorio contiene una aplicación creada según el siguiente tutorial: Páginas de ayuda de ASP.NET Core Web API mediante Swagger.This repository contains an app that's created based on the following tutorial: ASP.NET Core Web API help pages using Swagger. Utiliza un generador de Swagger para atender la interfaz de usuario de Swagger y el punto de conexión JSON de Swagger.It uses a Swagger generator to serve the Swagger UI and the Swagger JSON endpoint.

Ejecución de la aplicaciónRun the application

Ejecute los comandos siguientes para instalar los paquetes necesarios, ejecute las migraciones de bases de datos e inicie la aplicación.Run the following commands to install the required packages, run database migrations, and start the application.

cd dotnet-core-api
dotnet restore
dotnet run

Vaya a http://localhost:5000/swagger en un explorador para reproducirla con la interfaz de usuario de Swagger.Navigate to http://localhost:5000/swagger in a browser to play with the Swagger UI.

API de ASP.NET Core en ejecución local

Vaya a http://localhost:5000/api/todo y vea una lista de elementos de JSON de ToDo.Navigate to http://localhost:5000/api/todo and see a list of ToDo JSON items.

Vaya a http://localhost:5000 y reprodúzcala con la aplicación del explorador.Navigate to http://localhost:5000 and play with the browser app. Más adelante, apuntará la aplicación del explorador a una API remota en App Service para probar la funcionalidad CORS.Later, you will point the browser app to a remote API in App Service to test CORS functionality. El código de la aplicación del explorador se encuentra en el directorio wwwroot del repositorio.Code for the browser app is found in the repository's wwwroot directory.

Para detener ASP.NET Core en cualquier momento, presione Ctrl+C en el terminal.To stop ASP.NET Core at any time, press Ctrl+C in the terminal.

Uso de Azure Cloud ShellUse Azure Cloud Shell

En Azure se hospeda Azure Cloud Shell, un entorno de shell interactivo que puede utilizar mediante el explorador.Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Puede usar Bash o PowerShell con Cloud Shell para trabajar con los servicios de Azure.You can use either Bash or PowerShell with Cloud Shell to work with Azure services. Puede usar los comandos preinstalados de Cloud Shell para ejecutar el código de este artículo sin tener que instalar nada en su entorno local.You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

Para iniciar Azure Cloud Shell:To start Azure Cloud Shell:

OpciónOption Ejemplo o vínculoExample/Link
Seleccione Probarlo en la esquina superior derecha de un bloque de código.Select Try It in the upper-right corner of a code block. Solo con seleccionar Probar no se copia automáticamente el código en Cloud Shell.Selecting Try It doesn't automatically copy the code to Cloud Shell. Ejemplo de Probarlo para Azure Cloud Shell
Vaya a https://shell.azure.com o seleccione el botón Iniciar Cloud Shell para abrir Cloud Shell en el explorador.Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Iniciar Cloud Shell en una nueva ventanaLaunch Cloud Shell in a new window
Seleccione el botón Cloud Shell en la barra de menús de la esquina superior derecha de Azure Portal.Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Botón Cloud Shell en Azure Portal

Para ejecutar el código de este artículo en Azure Cloud Shell:To run the code in this article in Azure Cloud Shell:

  1. Inicie Cloud Shell.Start Cloud Shell.

  2. Seleccione el botón Copiar de un bloque de código para copiar el código.Select the Copy button on a code block to copy the code.

  3. Pegue el código en la sesión de Cloud Shell; para ello, seleccione Ctrl+Shift+V en Windows y Linux, o bien seleccione Cmd+Shift+V en macOS.Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Seleccione Entrar para ejecutar el código.Select Enter to run the code.

Implementación de aplicación en AzureDeploy app to Azure

En este paso, va a implementar la aplicación .NET Core conectada a SQL Database en App Service.In this step, you deploy your SQL Database-connected .NET Core application to App Service.

Configuración de la implementación de Git localConfigure local git deployment

Se puede implementar FTP y Git local en una aplicación web de Azure mediante un usuario de implementación.FTP and local Git can deploy to an Azure web app by using a deployment user. Una vez configurado este usuario de implementación, podrá usarlo en todas las implementaciones de Azure.Once you configure your deployment user, you can use it for all your Azure deployments. El nombre de usuario y la contraseña en el nivel de cuenta son diferentes de las credenciales de suscripción de Azure.Your account-level deployment username and password are different from your Azure subscription credentials.

Para configurar el usuario de implementación, ejecute el comando az webapp deployment user set en Azure Cloud Shell.To configure the deployment user, run the az webapp deployment user set command in Azure Cloud Shell. Reemplace <username> y <password> por su nombre de usuario y contraseña.Replace <username> and <password> with a deployment user username and password.

  • El nombre de usuario debe ser único dentro de Azure y no debe contener el símbolo "@" para las inserciones de Git local.The username must be unique within Azure, and for local Git pushes, must not contain the ‘@’ symbol.
  • La contraseña debe tener al menos ocho caracteres y dos de los tres elementos siguientes: letras, números y símbolos.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>

La salida JSON muestra la contraseña como null.The JSON output shows the password as null. Si se produce un error 'Conflict'. Details: 409, cambie el nombre de usuario.If you get a 'Conflict'. Details: 409 error, change the username. Si se produce un error 'Bad Request'. Details: 400, use una contraseña más segura.If you get a 'Bad Request'. Details: 400 error, use a stronger password.

Anote el nombre de usuario y la contraseña que se usarán para implementar las aplicaciones web.Record your username and password to use to deploy your web apps.

Crear un grupo de recursosCreate a resource group

Un grupo de recursos es un contenedor lógico en el que se implementan y administran recursos de Azure como aplicaciones web, bases de datos y cuentas de almacenamiento.A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. Por ejemplo, más adelante puede elegir eliminar todo el grupo de recursos en un solo paso.For example, you can choose to delete the entire resource group in one simple step later.

En Cloud Shell, cree un grupo de recursos con el comando az group create.In the Cloud Shell, create a resource group with the az group create command. En el ejemplo siguiente, se crea un grupo de recursos denominado myResourceGroup en la ubicación Europa Occidental.The following example creates a resource group named myResourceGroup in the West Europe location. Para ver todas las ubicaciones que se admiten en App Service en el nivel Gratis, ejecute el 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"

Generalmente se crean el grupo de recursos y los recursos en una región cercana.You generally create your resource group and the resources in a region near you.

Cuando finaliza el comando, una salida de JSON muestra las propiedades del grupo de recursos.When the command finishes, a JSON output shows you the resource group properties.

Creación de un plan de App ServiceCreate an App Service plan

En Cloud Shell, cree un plan de App Service con el comando az appservice plan create.In the Cloud Shell, create an App Service plan with the az appservice plan create command.

En el siguiente ejemplo se crea un plan de App Service denominado myAppServicePlan con el plan de tarifa Gratis: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

Cuando se ha creado el plan de App Service, la CLI de Azure muestra información similar al ejemplo siguiente: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
} 

Creación de una aplicación webCreate a web app

Cree una aplicación web en el plan de App Service de myAppServicePlan.Create a web app in the myAppServicePlan App Service plan.

En Cloud Shell, puede usar el comando az webapp create.In the Cloud Shell, you can use the az webapp create command. En el siguiente ejemplo, reemplace <app-name> por un nombre único global de aplicación (los caracteres válidos son a-z, 0-9 y -).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

Cuando se haya creado la aplicación web, la CLI de Azure mostrará información similar a la del ejemplo siguiente: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

La dirección URL del repositorio de Git remoto se muestra en la propiedad deploymentLocalGitUrl, con el 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. Guarde esta dirección URL, ya que la necesitará más adelante.Save this URL as you need it later.

Inserción en Azure desde GitPush to Azure from Git

En la ventana del terminal local, agregue una instancia remota de Azure al repositorio de Git local.Back in the local terminal window, add an Azure remote to your local Git repository. Reemplace <deploymentLocalGitUrl-from-create-step> por la dirección URL del repositorio de Git remoto que guardó en Creación de una aplicación 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>

Inserte en la instancia remota de Azure para implementar la aplicación con el comando siguiente.Push to the Azure remote to deploy your app with the following command. Cuando el Administrador de credenciales de Git le solicite las credenciales, asegúrese de que especifica las que creó en Configuración de un usuario de implementación, no las que se usan para iniciar sesión en Azure Portal.When Git Credential Manager prompts you for credentials, make sure 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

Este comando puede tardar varios minutos en ejecutarse.This command may take a few minutes to run. Durante la ejecución, muestra información similar a la del ejemplo siguiente: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

Navegación hasta la aplicación de AzureBrowse to the Azure app

Vaya a http://<app_name>.azurewebsites.net/swagger en un explorador y reprodúzcala con la interfaz de usuario de Swagger.Navigate to http://<app_name>.azurewebsites.net/swagger in a browser and play with the Swagger UI.

API de ASP.NET Core que se ejecuta en Azure App Service

Vaya a http://<app_name>.azurewebsites.net/swagger/v1/swagger.json para ver el archivo swagger.json de la API implementada.Navigate to http://<app_name>.azurewebsites.net/swagger/v1/swagger.json to see the swagger.json for your deployed API.

Vaya a http://<app_name>.azurewebsites.net/api/todo para ver cómo trabaja la API implementada.Navigate to http://<app_name>.azurewebsites.net/api/todo to see your deployed API working.

Adición de funcionalidad CORSAdd CORS functionality

Después, habilite la compatibilidad integrada de CORS en App Service para la API.Next, you enable the built-in CORS support in App Service for your API.

Prueba de CORS en la aplicación de ejemploTest CORS in sample app

En el repositorio local, abra wwwroot/index.html.In your local repository, open wwwroot/index.html.

En la línea 51, establezca la variable apiEndpoint en la dirección URL de la API implementada (http://<app_name>.azurewebsites.net).In Line 51, set the apiEndpoint variable to the URL of your deployed API (http://<app_name>.azurewebsites.net). Reemplace <appname> por el nombre de la aplicación de App Service.Replace <appname> with your app name in App Service.

En la ventana de terminal local, vuelva a ejecutar la aplicación de ejemplo.In your local terminal window, run the sample app again.

dotnet run

Vaya a la aplicación del explorador en http://localhost:5000.Navigate to the browser app at http://localhost:5000. Abra la ventana de herramientas del desarrollador en el explorador (Ctrl+Shift+i en Chrome para Windows) e inspeccione la pestaña Consola. Ahora debería ver el mensaje de error No 'Access-Control-Allow-Origin' header is present on the requested resource.Open 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.

Error de CORS en el cliente del explorador

Debido al error de coincidencia del dominio entre la aplicación del explorador (http://localhost:5000) y el recurso remoto (http://<app_name>.azurewebsites.net), y al hecho de que la API de App Service no está enviando el encabezado Access-Control-Allow-Origin, el explorador ha impedido que el contenido entre dominios se cargue en la aplicación del explorador.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.

En producción, la aplicación del explorador tendría una dirección URL pública en lugar de la dirección URL del host local, pero la forma de habilitar CORS en una dirección URL del host local es la misma que en una dirección URL pública.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.

Habilitación de CORSEnable CORS

En Cloud Shell, habilite CORS en la dirección URL del cliente mediante el comando az resource update.In the Cloud Shell, enable CORS to your client's URL by using the az resource update command. Reemplace el marcador de posición <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

Puede establecer más de una dirección URL de cliente en properties.cors.allowedOrigins ("['URL1','URL2',...]").You can set more than one client URL in properties.cors.allowedOrigins ("['URL1','URL2',...]"). También puede habilitar todas las direcciones URL de cliente con "['*']".You can also enable all client URLs with "['*']".

Nota

Si la aplicación requiere que se envíen credenciales, como cookies o tokens de autenticación, el explorador puede requerir el encabezado ACCESS-CONTROL-ALLOW-CREDENTIALS en la respuesta.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. Para habilitarlo en App Service, establezca properties.cors.supportCredentials en true en la configuración de CORS. No se puede habilitar cuando allowedOrigins incluye '*'.To enable this in App Service, set properties.cors.supportCredentials to true in your CORS config. This cannot be enabled when allowedOrigins includes '*'.

Otra prueba de CORSTest CORS again

Actualice la aplicación del explorador en http://localhost:5000.Refresh the browser app at http://localhost:5000. El mensaje de error de la ventana Consola ha desaparecido y puede ver los datos de la API implementada e interactuar con ella.The error message in the Console window is now gone, and you can see the data from the deployed API and interact with it. La API remota ahora admite CORS en la aplicación del explorador que se ejecuta localmente.Your remote API now supports CORS to your browser app running locally.

CORS implementado correctamente en el cliente de explorador

Enhorabuena, ya está ejecutando una API en Azure App Service con compatibilidad CORS.Congratulations, you're running an API in Azure App Service with CORS support.

CORS de App Service frente a CORS del usuarioApp Service CORS vs. your CORS

Puede usar sus propias utilidades CORS en lugar de CORS de App Service para una mayor flexibilidad.You can use your own CORS utilities instead of App Service CORS for more flexibility. Por ejemplo, es posible que desee especificar diferentes orígenes permitidos para rutas o métodos distintos.For example, you may want to specify different allowed origins for different routes or methods. Dado que CORS de App Service le permite especificar un conjunto de orígenes aceptados para todos los métodos y rutas de API, debería utilizar su propio código 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. Consulte cómo lo realiza ASP.NET Core en Habilitación de solicitudes entre orígenes (CORS).See how ASP.NET Core does it at Enabling Cross-Origin Requests (CORS).

Nota

No intente utilizar juntos CORS de App Service y su propio código CORS.Don't try to use App Service CORS and your own CORS code together. Cuando se usan juntos, CORS de App Service tiene prioridad y su propio código CORS no tiene ningún efecto.When used together, App Service CORS takes precedence and your own CORS code has no effect.

Limpieza de recursosClean up resources

En los pasos anteriores, creó recursos de Azure en un grupo de recursos.In the preceding steps, you created Azure resources in a resource group. Si prevé que no necesitará estos recursos en el futuro, elimine el grupo de recursos ejecutando el siguiente comando en 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

Este comando puede tardar varios segundos en ejecutarse.This command may take a minute to run.

Pasos siguientesNext steps

¿Qué ha aprendido?What you learned:

  • Crear recursos de App Service mediante la CLI de AzureCreate App Service resources using Azure CLI
  • Implementar una API RESTful en Azure con GitDeploy a RESTful API to Azure using Git
  • Habilitar la compatibilidad con CORS de App ServiceEnable App Service CORS support

Avance al siguiente tutorial para aprender a autenticar y autorizar a los usuarios.Advance to the next tutorial to learn how to authenticate and authorize users.