Руководство по Размещение API-интерфейсов RESTful с поддержкой CORS в службе приложений AzureTutorial: Host a RESTful API with CORS in Azure App Service

Служба приложений Azure — это служба веб-размещения с самостоятельной установкой исправлений и высоким уровнем масштабируемости.Azure App Service provides a highly scalable, self-patching web hosting service. Кроме того, служба приложений включает встроенную поддержку общего доступа к ресурсам независимо от источника (CORS) для API-интерфейсов RESTful.In addition, App Service has built-in support for Cross-Origin Resource Sharing (CORS) for RESTful APIs. В этом руководстве рассматривается развертывание приложения API ASP.NET Core в службу приложений с поддержкой CORS.This tutorial shows how to deploy an ASP.NET Core API app to App Service with CORS support. Вы настроите приложение с помощью программ командной строки и развернете его с помощью Git.You configure the app using command-line tools and deploy the app using Git.

В этом руководстве описано следующее:In this tutorial, you learn how to:

  • создавать ресурсы службы приложений с помощью Azure CLI;Create App Service resources using Azure CLI
  • развертывать API-интерфейс RESTful в Azure с помощью Git;Deploy a RESTful API to Azure using Git
  • включать в службе приложений поддержку CORS.Enable App Service CORS support

Шаги, описанные в этом руководстве, можно выполнить для macOS, Linux и Windows.You can follow the steps in this tutorial on macOS, Linux, Windows.

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начать работу.If you don't have an Azure subscription, create a free account before you begin.

Предварительные требованияPrerequisites

Для работы с этим руководством сделайте следующее:To complete this tutorial:

Создание локального приложения ASP.NET CoreCreate local ASP.NET Core app

На этом шаге вы настроите локальный проект ASP.NET Core.In this step, you set up the local ASP.NET Core project. Служба приложений поддерживает единый рабочий процесс для API-интерфейсов, написанных на других языках.App Service supports the same workflow for APIs written in other languages.

Клонирование примера приложенияClone the sample application

Откройте окно терминала и c помощью команды cd перейдите в рабочий каталог.In the terminal window, cd to a working directory.

Выполните команду ниже, чтобы клонировать репозиторий с примером.Run the following command to clone the sample repository.

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

Этот репозиторий содержит приложение, созданное во время работы с предыдущим руководством: Использование страниц справки по веб-API ASP.NET Core со Swagger.This repository contains an app that's created based on the following tutorial: ASP.NET Core Web API help pages using Swagger. В этом руководстве генератор Swagger используется для обслуживания пользовательского интерфейса Swagger и конечной точки JSON Swagger.It uses a Swagger generator to serve the Swagger UI and the Swagger JSON endpoint.

Выполнение приложенияRun the application

Выполните указанные ниже команды, чтобы установить необходимые пакеты, перенести базы данных и запустить приложение.Run the following commands to install the required packages, run database migrations, and start the application.

cd dotnet-core-api
dotnet restore
dotnet run

Перейдите в расположение http://localhost:5000/swagger в браузере, чтобы поэкспериментировать с пользовательским интерфейсом Swagger.Navigate to http://localhost:5000/swagger in a browser to play with the Swagger UI.

Выполняющийся локально API ASP.NET Core

Перейдите в расположение http://localhost:5000/api/todo, чтобы просмотреть список элементов списка задач в формате JSON.Navigate to http://localhost:5000/api/todo and see a list of ToDo JSON items.

Перейдите в расположение http://localhost:5000, чтобы поэкспериментировать с приложением браузера.Navigate to http://localhost:5000 and play with the browser app. Позже вы перейдете из приложения браузера к удаленному API в службе приложений, чтобы проверить функции CORS.Later, you will point the browser app to a remote API in App Service to test CORS functionality. Код для приложения браузера находится в каталоге wwwroot репозитория.Code for the browser app is found in the repository's wwwroot directory.

Чтобы остановить ASP.NET Core в любое время, нажмите клавиши Ctrl+C в окне терминала.To stop ASP.NET Core at any time, press Ctrl+C in the terminal.

Использование Azure Cloud ShellUse Azure Cloud Shell

В Azure есть Azure Cloud Shell, интерактивная оболочка среды, с которой можно работать в браузере.Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. Для работы со службами Azure можно использовать Bash или PowerShell с Cloud Shell.You can use either Bash or PowerShell with Cloud Shell to work with Azure services. Для запуска кода из этой статьи можно использовать предварительно установленные команды Cloud Shell. Ничего дополнительного в локальной среде устанавливать не нужно.You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

Начало работы с Azure Cloud ShellTo start Azure Cloud Shell:

ПараметрOption Пример и ссылкаExample/Link
Нажмите кнопку Попробовать в правом верхнем углу блока с кодом.Select Try It in the upper-right corner of a code block. При нажатии кнопки Попробовать код не копируется в Cloud Shell автоматически.Selecting Try It doesn't automatically copy the code to Cloud Shell. Открытие Azure Cloud Shell с помощью кнопки "Попробовать"
Перейдите по адресу https://shell.azure.com или нажмите кнопку Запуск Cloud Shell, чтобы открыть Cloud Shell в браузере.Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Запуск Cloud Shell в новом окнеLaunch Cloud Shell in a new window
Нажмите кнопку Cloud Shell в строке меню в правом верхнем углу окна портала Azure.Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Кнопка "Cloud Shell" на портале Azure

Чтобы выполнить код из этой статьи в Azure Cloud Shell, выполните следующие действия:To run the code in this article in Azure Cloud Shell:

  1. Запустите Cloud Shell.Start Cloud Shell.

  2. В блоке кода нажмите кнопку Копировать, чтобы скопировать код.Select the Copy button on a code block to copy the code.

  3. Вставьте код в окно сеанса Cloud Shell, нажав клавиши CTRL+SHIFT+V в Windows и Linux или CMD+SHIFT+V в 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. Нажмите клавишу ВВОД, чтобы выполнить код.Select Enter to run the code.

Развертывание приложения в AzureDeploy app to Azure

На этом шаге вы развернете приложение .NET Core, подключенное к базе данных SQL, в службе приложений.In this step, you deploy your SQL Database-connected .NET Core application to App Service.

Настройка локального развертывания GitConfigure local git deployment

Для развертывания в веб-приложение Azure из FTP и локального репозитория Git можно использовать пользователя развертывания.FTP and local Git can deploy to an Azure web app by using a deployment user. Настроив один раз пользователя развертывания, вы сможете использовать его для всех последующих развертываний в Azure.Once you configure your deployment user, you can use it for all your Azure deployments. Имя пользователя и пароль учетной записи развертывания отличаются от учетных данных подписки Azure.Your account-level deployment username and password are different from your Azure subscription credentials.

Чтобы настроить пользователя развертывания, выполните в Azure Cloud Shell команду az webapp deployment user set.To configure the deployment user, run the az webapp deployment user set command in Azure Cloud Shell. Вместо <username> и <password> укажите имя пользователя и пароль развертывания.Replace <username> and <password> with a deployment user username and password.

  • Имя пользователя должно быть уникальным в Azure. Кроме того, чтобы отправка в локальный репозиторий Git работала, имя пользователя не должно содержать символ @.The username must be unique within Azure, and for local Git pushes, must not contain the ‘@’ symbol.
  • Пароль должен содержать не менее восьми символов и включать два из трех следующих элементов: буквы, цифры и символы.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>

В выходных данных JSON пароль отображается как null.The JSON output shows the password as null. Если появляется сообщение об ошибке 'Conflict'. Details: 409, измените имя пользователя.If you get a 'Conflict'. Details: 409 error, change the username. Если появляется сообщение об ошибке 'Bad Request'. Details: 400, используйте более надежный пароль.If you get a 'Bad Request'. Details: 400 error, use a stronger password.

Запишите имя пользователя и пароль и используйте их для развертывания веб-приложений.Record your username and password to use to deploy your web apps.

Создание группы ресурсовCreate a resource group

Группа ресурсов — это логический контейнер, в котором происходит развертывание ресурсов Azure (веб-приложений, баз данных и учетных записей хранения) и управление ими.A resource group is a logical container into which Azure resources like web apps, databases, and storage accounts are deployed and managed. Например, в дальнейшем можно удалить всю группу ресурсов при помощи одного простого действия.For example, you can choose to delete the entire resource group in one simple step later.

В Cloud Shell создайте группу ресурсов с помощью команды az group create.In the Cloud Shell, create a resource group with the az group create command. В следующем примере создается группа ресурсов с именем myResourceGroup в расположении Западная Европа.The following example creates a resource group named myResourceGroup in the West Europe location. Чтобы просмотреть все поддерживаемые расположения для службы приложений уровня Бесплатный, выполните команду 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"

Обычно группа ресурсов и ресурсы создаются в ближайших регионах.You generally create your resource group and the resources in a region near you.

По завершении команды в выходных данных JSON будут отображаться свойства группы ресурсов.When the command finishes, a JSON output shows you the resource group properties.

Создание плана службы приложенийCreate an App Service plan

В Cloud Shell создайте план службы приложений с помощью команды az appservice plan create.In the Cloud Shell, create an App Service plan with the az appservice plan create command.

В следующем примере создается план службы приложений с именем myAppServicePlan и ценовой категорией Бесплатный.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

После создания плана службы приложений в Azure CLI отображается информация следующего вида: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
} 

Создание веб-приложенияCreate a web app

Создайте веб-приложение в плане службы приложений myAppServicePlan.Create a web app in the myAppServicePlan App Service plan.

В Cloud Shell можно использовать команду az webapp create.In the Cloud Shell, you can use the az webapp create command. В следующем примере замените <app-name>глобальным уникальным именем приложения (допустимые символы: a-z, 0-9 и -).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

Когда веб-приложение будет создано, в Azure CLI отобразится примерно следующее: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,
  "clientCertExclusionPaths": null,
  "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. >
}

Примечание

URL-адрес удаленного репозитория Git отображается в свойстве deploymentLocalGitUrl в формате 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. Сохраните этот URL-адрес для дальнейшего использования.Save this URL as you need it later.

Публикация в Azure из GitPush to Azure from Git

Вернитесь к окну терминала (в локальном расположении) и добавьте удаленное приложение Azure в локальный репозиторий Git.Back in the local terminal window, add an Azure remote to your local Git repository. Замените <deploymentLocalGitUrl-from-create-step> URL-адресом удаленного репозитория Git, который вы сохранили на этапе создания веб-приложения.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>

Отправьте код в удаленное приложение Azure, чтобы развернуть приложение.Push to the Azure remote to deploy your app with the following command. При появлении запроса на ввод учетных данных в диспетчере учетных данных Git введите учетные данные, созданные на шаге настройки пользователя развертывания (а не те, которые используются для входа на портал Azure).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

Выполнение этой команды может занять несколько минут.This command may take a few minutes to run. При выполнении эта команда выводит приблизительно следующие сведения:While running, it displays information similar to the following example:

Enumerating objects: 83, done.
Counting objects: 100% (83/83), done.
Delta compression using up to 8 threads
Compressing objects: 100% (78/78), done.
Writing objects: 100% (83/83), 22.15 KiB | 3.69 MiB/s, done.
Total 83 (delta 26), reused 0 (delta 0)
remote: Updating branch 'master'.
remote: Updating submodules.
remote: Preparing deployment for commit id '509236e13d'.
remote: Generating deployment script.
remote: Project file path: .\TodoApi.csproj
remote: Generating deployment script for ASP.NET MSBuild16 App
remote: Generated deployment script files
remote: Running deployment command...
remote: Handling ASP.NET Core Web Application deployment with MSBuild16.
remote: .
remote: .
remote: .
remote: Finished successfully.
remote: Running post deployment command(s)...
remote: Triggering recycle (preview mode disabled).
remote: Deployment successful.
To https://<app_name>.scm.azurewebsites.net/<app_name>.git
 * [new branch]      master -> master

Переход к приложению AzureBrowse to the Azure app

Перейдите в расположение http://<app_name>.azurewebsites.net/swagger в браузере и ознакомьтесь с пользовательским интерфейсом Swagger.Navigate to http://<app_name>.azurewebsites.net/swagger in a browser and play with the Swagger UI.

API ASP.NET Core, выполняющийся в службе приложений Azure

Перейдите в http://<app_name>.azurewebsites.net/swagger/v1/swagger.json, чтобы просмотреть файл swagger.json для развернутого API.Navigate to http://<app_name>.azurewebsites.net/swagger/v1/swagger.json to see the swagger.json for your deployed API.

Перейдите в http://<app_name>.azurewebsites.net/api/todo, чтобы просмотреть развернутый API в режиме работы.Navigate to http://<app_name>.azurewebsites.net/api/todo to see your deployed API working.

Добавление функциональных возможностей CORSAdd CORS functionality

Далее вы включите встроенную поддержку CORS в службе приложений для API.Next, you enable the built-in CORS support in App Service for your API.

Тестирование CORS в примере приложенияTest CORS in sample app

В локальном репозитории откройте wwwroot/index.html.In your local repository, open wwwroot/index.html.

В строке 51 задайте для переменной apiEndpoint URL-адрес развернутого API (http://<app_name>.azurewebsites.net).In Line 51, set the apiEndpoint variable to the URL of your deployed API (http://<app_name>.azurewebsites.net). Замените <appname> именем своего приложения в Службе приложений.Replace <appname> with your app name in App Service.

В локальном окне терминала снова запустите пример приложения.In your local terminal window, run the sample app again.

dotnet run

Перейдите в приложение браузера по адресу http://localhost:5000.Navigate to the browser app at http://localhost:5000. Откройте окно инструментов разработчика в браузере (Ctrl+Shift+i в Chrome для Windows) и просмотрите вкладку Консоль. Вы должны увидеть сообщение об ошибке: 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.

Ошибка CORS в клиенте браузера

Из-за несоответствия домена между приложением браузера (http://localhost:5000) и удаленным ресурсом (http://<app_name>.azurewebsites.net), а также того факта, что ваш API в службе приложений не отправляет заголовок Access-Control-Allow-Origin, браузер ограничил загрузку междоменного содержимого в приложении браузера.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.

В рабочей среде для приложения браузера будет использоваться общедоступный URL-адрес вместо URL-адреса локального узла, но способ включения CORS для этих адресов одинаков.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.

Включение CORSEnable CORS

В Cloud Shell включите CORS для URL-адреса своего клиента с помощью команды az webapp cors add.In the Cloud Shell, enable CORS to your client's URL by using the az webapp cors add command. Замените заполнитель <app-name> .Replace the <app-name> placeholder.

az webapp cors add --resource-group myResourceGroup --name <app-name> --allowed-origins 'http://localhost:5000'

Можно задать несколько URL-адресов клиента в properties.cors.allowedOrigins ("['URL1','URL2',...]").You can set more than one client URL in properties.cors.allowedOrigins ("['URL1','URL2',...]"). Также можно включить CORS для всех URL-адресов клиента с помощью "['*']".You can also enable all client URLs with "['*']".

Примечание

Если для вашего приложения требуется отправка учетных данных, например cookie или маркеров проверки подлинности, для браузера может понадобиться заголовок ACCESS-CONTROL-ALLOW-CREDENTIALS в ответе.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. Чтобы активировать этот заголовок в службе приложений, в конфигурации CORS установите значение параметра properties.cors.supportCredentials равным true. Его нельзя активировать, если параметр allowedOrigins содержит '*'.To enable this in App Service, set properties.cors.supportCredentials to true in your CORS config. This cannot be enabled when allowedOrigins includes '*'.

Повторное тестирование CORSTest CORS again

Обновите приложение браузера, перейдя по адресу http://localhost:5000.Refresh the browser app at http://localhost:5000. Сообщение об ошибке в окне консоли исчезнет, вы сможете просмотреть данные из развернутого API и выполнить с ними операции.The error message in the Console window is now gone, and you can see the data from the deployed API and interact with it. Теперь ваш удаленный API поддерживает CORS для приложения браузера, запущенного в локальной среде.Your remote API now supports CORS to your browser app running locally.

Успешное тестирование CORS в клиенте браузера

Поздравляем! Вы запустили API в службе приложений Azure с поддержкой CORS.Congratulations, you're running an API in Azure App Service with CORS support.

Сравнение CORS в службе приложений и вашей средеApp Service CORS vs. your CORS

Вы можете использовать собственные служебные программы CORS вместо программ в службе приложений для большей гибкости.You can use your own CORS utilities instead of App Service CORS for more flexibility. Например, вы можете указать разные разрешенные источники для разных маршрутов или методов.For example, you may want to specify different allowed origins for different routes or methods. Так как CORS в службе приложений позволяет указать один набор принятых источников для всех маршрутов и методов API, вы можете использовать собственный код 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. Подробные сведения об этом см. в статье о включении запросов независимо от источника (CORS).See how ASP.NET Core does it at Enabling Cross-Origin Requests (CORS).

Примечание

Не используйте совместно CORS службы приложений и собственный код CORS.Don't try to use App Service CORS and your own CORS code together. В противном случае ваш код CORS не принесет никаких результатов, так как CORS службы приложений имеет приоритет.When used together, App Service CORS takes precedence and your own CORS code has no effect.

Очистка ресурсовClean up resources

На предыдущем шаге вы создали ресурсы Azure в группе ресурсов.In the preceding steps, you created Azure resources in a resource group. Если эти ресурсы вам не понадобятся в будущем, вы можете удалить группу ресурсов, выполнив следующую команду в 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

Ее выполнение может занять до минуты.This command may take a minute to run.

Дальнейшие действияNext steps

Вы научились выполнять следующие задачи:What you learned:

  • создавать ресурсы службы приложений с помощью Azure CLI;Create App Service resources using Azure CLI
  • развертывать API-интерфейс RESTful в Azure с помощью Git;Deploy a RESTful API to Azure using Git
  • включать в службе приложений поддержку CORS.Enable App Service CORS support

Перейдите к следующему руководству, чтобы узнать, как выполнять аутентификацию и авторизацию пользователей.Advance to the next tutorial to learn how to authenticate and authorize users.