Tutorial: Hospedar uma API RESTful com CORS no Serviço de Aplicativo do AzureTutorial: Host a RESTful API with CORS in Azure App Service

O Serviço de Aplicativo do Azure fornece um serviço de hospedagem na Web altamente escalonável e com aplicação automática de patches.Azure App Service provides a highly scalable, self-patching web hosting service. Além disso, o Serviço de Aplicativo tem suporte interno a CORS (Compartilhamento de Recursos entre Origens) para APIs RESTful.In addition, App Service has built-in support for Cross-Origin Resource Sharing (CORS) for RESTful APIs. Este tutorial mostra como implantar um aplicativo de API do ASP.NET Core no Serviço de Aplicativo com suporte a CORS.This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. Configure o aplicativo usando as ferramentas de linha de comando e implante o aplicativo usando o Git.You configure the app using command-line tools and deploy the app using Git.

Neste tutorial, você aprenderá como:In this tutorial, you learn how to:

  • Criar recursos do Serviço de Aplicativo usando a CLI do AzureCreate App Service resources using Azure CLI
  • Implantar uma API RESTful no Azure usando o GitDeploy a RESTful API to Azure using Git
  • Habilitar o suporte de CORS do Serviço de AplicativoEnable App Service CORS support

Você pode seguir as etapas deste tutorial no macOS, no Linux e no Windows.You can follow the steps in this tutorial on macOS, Linux, Windows.

Se você não tiver uma assinatura do Azure, crie uma conta gratuita antes de começar.If you don't have an Azure subscription, create a free account before you begin.

Pré-requisitosPrerequisites

Para concluir este tutorial:To complete this tutorial:

Criar um aplicativo ASP.NET Core localCreate local ASP.NET Core app

Nesta etapa, você configura o projeto ASP.NET Core local.In this step, you set up the local ASP.NET Core project. O Serviço de Aplicativo dá suporte ao mesmo fluxo de trabalho para APIs codificadas em outras linguagens.App Service supports the same workflow for APIs written in other languages.

Clonar o aplicativo de exemploClone the sample application

Na janela do terminal, cd para um diretório de trabalho.In the terminal window, cd to a working directory.

Execute o comando a seguir para clonar o repositório de exemplo.Run the following command to clone the sample repository.

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

Esse repositório contém um aplicativo que é criado com base no seguinte tutorial: Páginas de ajuda da API Web do ASP.NET Core usando o Swagger.This repository contains an app that's created based on the following tutorial: ASP.NET Core Web API help pages using Swagger. Ele usa um gerador de Swagger para servir a interface do usuário do Swagger e o ponto de extremidade JSON do Swagger.It uses a Swagger generator to serve the Swagger UI and the Swagger JSON endpoint.

Executar o aplicativoRun the application

Execute os comandos a seguir para instalar os pacotes necessários, executar as migrações de banco de dados e iniciar o aplicativo.Run the following commands to install the required packages, run database migrations, and start the application.

cd dotnet-core-api
dotnet restore
dotnet run

Navegue até http://localhost:5000/swagger em um navegador para trabalhar com a interface do usuário do Swagger.Navigate to http://localhost:5000/swagger in a browser to play with the Swagger UI.

API do ASP.NET Core em execução localmente

Navegue até http://localhost:5000/api/todo e veja uma lista de itens JSON de tarefas pendentes.Navigate to http://localhost:5000/api/todo and see a list of ToDo JSON items.

Navegue até http://localhost:5000 e experimente o aplicativo de navegador.Navigate to http://localhost:5000 and play with the browser app. Posteriormente, você vai apontar o aplicativo de navegador para uma API remota no Serviço de Aplicativo a fim de testar a funcionalidade CORS.Later, you will point the browser app to a remote API in App Service to test CORS functionality. O código do aplicativo de navegador é encontrado no diretório wwwroot do repositório.Code for the browser app is found in the repository's wwwroot directory.

Para parar o ASP.NET Core a qualquer momento, pressione Ctrl+C no terminal.To stop ASP.NET Core at any time, press Ctrl+C in the terminal.

Usar o Azure Cloud ShellUse Azure Cloud Shell

O Azure hospeda o Azure Cloud Shell, um ambiente de shell interativo que pode ser usado por meio do navegador.Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. É possível usar o bash ou o PowerShell com o Cloud Shell para trabalhar com os serviços do Azure.You can use either Bash or PowerShell with Cloud Shell to work with Azure services. É possível usar os comandos pré-instalados do Cloud Shell para executar o código neste artigo sem precisar instalar nada no seu ambiente 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 o Azure Cloud Shell:To start Azure Cloud Shell:

OpçãoOption Exemplo/LinkExample/Link
Selecione Experimente no canto superior direito de um bloco de código.Select Try It in the upper-right corner of a code block. Selecionar Experimente não copia automaticamente o código para o Cloud Shell.Selecting Try It doesn't automatically copy the code to Cloud Shell. Exemplo de “Experimente” no Azure Cloud Shell
Acesse https://shell.azure.com ou selecione o botão Iniciar o Cloud Shell para abri-lo no navegador.Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Inicie o Cloud Shell em uma nova janelaLaunch Cloud Shell in a new window
Clique no botão Cloud Shell na barra de menus no canto superior direito do portal do Azure.Select the Cloud Shell button on the top-right menu bar in the Azure portal. Botão Cloud Shell no portal do Azure

Para executar o código neste artigo no Azure Cloud Shell:To run the code in this article in Azure Cloud Shell:

  1. Inicie o Cloud Shell.Start Cloud Shell.

  2. Clique no botão Copiar no bloco de código para copiá-lo.Select the Copy button on a code block to copy the code.

  3. Cole o código na sessão do Cloud Shell ao pressionar Ctrl+Shift+V no Windows e no Linux ou Cmd+Shift+V no 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. Pressione Enter para executar o código.Select Enter to run the code.

Implantar o aplicativo no AzureDeploy app to Azure

Nesta etapa, você implantará seu aplicativo .NET Core conectado ao Banco de Dados SQL no Serviço de Aplicativo.In this step, you deploy your SQL Database-connected .NET Core application to App Service.

Configurar a implantação do git localConfigure local git deployment

O FTP e o Git local podem implantar em um aplicativo Web do Azure usando um usuário de implantação.FTP and local Git can deploy to an Azure web app by using a deployment user. Após configurar o usuário de implantação, use-o em todas as implantações do Azure.Once you configure your deployment user, you can use it for all your Azure deployments. O nome de usuário e a senha da implantação no nível da conta são diferentes das credenciais de assinatura do Azure.Your account-level deployment username and password are different from your Azure subscription credentials.

Para configurar o usuário de implantação, execute o comando az webapp deployment user set no Azure Cloud Shell.To configure the deployment user, run the az webapp deployment user set command in Azure Cloud Shell. Substitua <username> e <password> pelo nome de usuário e a senha do usuário de implantação.Replace <username> and <password> with a deployment user username and password.

  • O nome de usuário deve ser exclusivo no Azure. Para envios por push do Git local, não deve conter o símbolo "@".The username must be unique within Azure, and for local Git pushes, must not contain the ‘@’ symbol.
  • A senha deve ter pelo menos oito caracteres, com dois destes três elementos: letras, números, 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>

A saída JSON mostra a senha como null.The JSON output shows the password as null. Se receber um erro 'Conflict'. Details: 409, altere o nome de usuário.If you get a 'Conflict'. Details: 409 error, change the username. Se receber um erro 'Bad Request'. Details: 400, use uma senha mais forte.If you get a 'Bad Request'. Details: 400 error, use a stronger password.

Registre seu nome de usuário e senha para usá-los na implantação de aplicativos Web.Record your username and password to use to deploy your web apps.

Criar um grupo de recursosCreate a resource group

Um grupo de recursos é um contêiner lógico no qual os recursos do Azure, como aplicativos Web, bancos de dados e contas de armazenamento, são implantados e gerenciados.A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. Por exemplo, é possível excluir posteriormente todo o grupo de recursos com uma única etapa simples.For example, you can choose to delete the entire resource group in one simple step later.

No Cloud Shell, crie um grupo de recursos com o comando az group create.In the Cloud Shell, create a resource group with the az group create command. O exemplo a seguir cria um grupo de recursos chamado myResourceGroup no local Europa Ocidental.The following example creates a resource group named myResourceGroup in the West Europe location. Para ver todos os locais com suporte para o Serviço de Aplicativo no nível Gratuito, execute o 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"

Em geral, você cria seu grupo de recursos e os recursos em uma região próxima a você.You generally create your resource group and the resources in a region near you.

Quando o comando for concluído, uma saída JSON mostra as propriedades do grupo de recursos.When the command finishes, a JSON output shows you the resource group properties.

Criar um plano de Serviço de AplicativoCreate an App Service plan

No Cloud Shell, crie um plano do Serviço de Aplicativo com o comando az appservice plan create.In the Cloud Shell, create an App Service plan with the az appservice plan create command.

O exemplo a seguir cria um plano do Serviço de Aplicativo denominado myAppServicePlan usando o tipo de preço Gratuita: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

Quando o Plano do Serviço de Aplicativo for criado, a CLI do Azure mostrará informações semelhantes ao exemplo a seguir: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
} 

Criar um aplicativo WebCreate a web app

Crie um aplicativo Web no plano do Serviço de Aplicativo myAppServicePlan.Create a web app in the myAppServicePlan App Service plan.

No Cloud Shell, é possível usar o comando az webapp create.In the Cloud Shell, you can use the az webapp create command. No exemplo a seguir, substitua <app-name> por um nome do aplicativo exclusivo globalmente (os caracteres válidos são 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

Quando o aplicativo Web for criado, a CLI do Azure mostrará um resultado semelhante ao seguinte exemplo: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. >
}

Observação

A URL do Git remoto é mostrada na propriedade deploymentLocalGitUrl com o 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. Salve essa URL, pois você precisará dela mais tarde.Save this URL as you need it later.

Enviar do Git para o AzurePush to Azure from Git

De volta na janela do terminal local, adicione um remoto do Azure ao repositório Git local.Back in the local terminal window, add an Azure remote to your local Git repository. Substitua <deploymentLocalGitUrl-from-create-step> pela URL do Git remoto que você salvou de Criar um aplicativo 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>

Envie por push para o Azure remoto para implantar seu aplicativo com o comando a seguir.Push to the Azure remote to deploy your app with the following command. Quando solicitado a fornecer credenciais pelo Gerenciador de Credenciais do Git, insira as credenciais criadas em Configurar um usuário de implantação, não as credenciais usadas para entrar no portal do 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

Esse comando pode demorar um pouco para ser executado.This command may take a few minutes to run. Na execução, ele exibe informações semelhantes ao seguinte exemplo: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

Navegar até o aplicativo do AzureBrowse to the Azure app

Navegue até http://<app_name>.azurewebsites.net/swagger em um navegador e experimente a interface do usuário do Swagger.Navigate to http://<app_name>.azurewebsites.net/swagger in a browser and play with the Swagger UI.

API do ASP.NET Core em execução no Serviço de Aplicativo do Azure

Navegue até http://<app_name>.azurewebsites.net/swagger/v1/swagger.json para ver o swagger.json da sua API implantada.Navigate to http://<app_name>.azurewebsites.net/swagger/v1/swagger.json to see the swagger.json for your deployed API.

Navegue até http://<app_name>.azurewebsites.net/api/todo para ver sua API implantada funcionando.Navigate to http://<app_name>.azurewebsites.net/api/todo to see your deployed API working.

Adicionar funcionalidade CORSAdd CORS functionality

Em seguida, habilite o suporte interno de CORS no Serviço de Aplicativo para a sua API.Next, you enable the built-in CORS support in App Service for your API.

Testar CORS no aplicativo de exemploTest CORS in sample app

No seu repositório local, abra wwwroot/index.html.In your local repository, open wwwroot/index.html.

Na linha 51, defina a variável apiEndpoint como a URL da sua API implantada (http://<app_name>.azurewebsites.net).In Line 51, set the apiEndpoint variable to the URL of your deployed API (http://<app_name>.azurewebsites.net). Substitua <appname> pelo nome do aplicativo no Serviço de Aplicativo.Replace <appname> with your app name in App Service.

Na janela do terminal local, execute novamente o aplicativo de exemplo.In your local terminal window, run the sample app again.

dotnet run

Navegue até o aplicativo de navegador em http://localhost:5000.Navigate to the browser app at http://localhost:5000. Abra a janela de ferramentas de desenvolvedor no navegador (Ctrl + Shift + i no Chrome para Windows) e inspecione a guia Console. Agora, você verá a mensagem de erro 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.

Erro de CORS no cliente de navegador

Devido à incompatibilidade de domínio entre o aplicativo de navegador (http://localhost:5000) e o recurso remoto (http://<app_name>.azurewebsites.net), e ao fato de sua API no Serviço de Aplicativo não estar enviando o cabeçalho Access-Control-Allow-Origin, seu navegador impediu que o conteúdo entre domínios fosse carregado no aplicativo de navegador.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.

Na produção, o aplicativo de navegador teria uma URL pública em vez da URL de localhost, mas a maneira de habilitar o CORS para uma URL de localhost é a mesma de uma 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.

Habilitar CORSEnable CORS

No Cloud Shell, habilite o CORS para URL do cliente usando o comando az resource update .In the Cloud Shell, enable CORS to your client's URL by using the az resource update command. Substitua o espaço reservado <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

Você pode definir mais de uma URL de cliente properties.cors.allowedOrigins ("['URL1','URL2',...]").You can set more than one client URL in properties.cors.allowedOrigins ("['URL1','URL2',...]"). Você também pode habilitar todas as URLs de cliente com "['*']".You can also enable all client URLs with "['*']".

Observação

Se o seu aplicativo exigir credenciais, como o envio de cookies ou tokens de autenticação, o navegador poderá exigir o cabeçalho ACCESS-CONTROL-ALLOW-CREDENTIALS na resposta.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 habilitar isso no Serviço de Aplicativo, defina properties.cors.supportCredentials como true em sua configuração de CORS. Isso não pode ser habilitado quando allowedOrigins inclui '*'.To enable this in App Service, set properties.cors.supportCredentials to true in your CORS config. This cannot be enabled when allowedOrigins includes '*'.

Testar CORS novamenteTest CORS again

Atualize o aplicativo de navegador em http://localhost:5000.Refresh the browser app at http://localhost:5000. A mensagem de erro na janela Console desapareceu e você pode ver os dados da API implantada e interagir com eles.The error message in the Console window is now gone, and you can see the data from the deployed API and interact with it. Sua API remota agora dá suporte a CORS para o aplicativo de navegador em execução localmente.Your remote API now supports CORS to your browser app running locally.

Êxito do CORS no cliente de navegador

Parabéns, você estiver executando uma API no Serviço de Aplicativo do Azure com suporte de CORS.Congratulations, you're running an API in Azure App Service with CORS support.

CORS do Serviço de Aplicativo comparado com seu CORSApp Service CORS vs. your CORS

Você pode usar seus próprios utilitários CORS em vez do CORS do Serviço de Aplicativo para obter mais flexibilidade.You can use your own CORS utilities instead of App Service CORS for more flexibility. Por exemplo, convém especificar diferentes origens permitidas para rotas ou métodos diferentes.For example, you may want to specify different allowed origins for different routes or methods. Como o CORS do Serviço de Aplicativo permite especificar um conjunto de origens aceitas para todas as rotas e métodos de API, é melhor usar seu próprio 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. Veja como o ASP.NET Core faz isso em Habilitando solicitações entre origens (CORS).See how ASP.NET Core does it at Enabling Cross-Origin Requests (CORS).

Observação

Não tente usar CORS do Serviço de Aplicativo e seu próprio CORS juntos.Don't try to use App Service CORS and your own CORS code together. Quando usados juntos, o CORS do Serviço de Aplicativo terá precedência e seu próprio código CORS não terá nenhum efeito.When used together, App Service CORS takes precedence and your own CORS code has no effect.

Limpar recursosClean up resources

Nas etapas anteriores, você criou os recursos do Azure em um grupo de recursos.In the preceding steps, you created Azure resources in a resource group. Se você acha que não precisará desses recursos no futuro, exclua o grupo de recursos executando o seguinte comando no 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

Esse comando pode demorar um pouco para ser executado.This command may take a minute to run.

Próximas etapasNext steps

O que você aprendeu:What you learned:

  • Criar recursos do Serviço de Aplicativo usando a CLI do AzureCreate App Service resources using Azure CLI
  • Implantar uma API RESTful no Azure usando o GitDeploy a RESTful API to Azure using Git
  • Habilitar o suporte de CORS do Serviço de AplicativoEnable App Service CORS support

Vá para o próximo tutorial e aprenda a autenticar e autorizar os usuários.Advance to the next tutorial to learn how to authenticate and authorize users.