Руководство по Размещение API-интерфейсов RESTful с поддержкой CORS в службе приложений Azure

Служба приложений Azure — это служба веб-размещения с самостоятельной установкой исправлений и высоким уровнем масштабируемости. Кроме того, служба приложений включает встроенную поддержку общего доступа к ресурсам независимо от источника (CORS) для API-интерфейсов RESTful. В этом руководстве рассматривается развертывание приложения API ASP.NET Core в службу приложений с поддержкой CORS. Вы настроите приложение с помощью программ командной строки и развернете его с помощью Git.

В этом руководстве описано следующее:

  • создавать ресурсы службы приложений с помощью Azure CLI;
  • развертывать API-интерфейс RESTful в Azure с помощью Git;
  • включать в службе приложений поддержку CORS.

Шаги, описанные в этом руководстве, можно выполнить для macOS, Linux и Windows.

Если у вас еще нет подписки Azure, создайте бесплатную учетную запись Azure, прежде чем начинать работу.

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

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

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

На этом шаге вы настроите локальный проект ASP.NET Core. Служба приложений поддерживает единый рабочий процесс для API-интерфейсов, написанных на других языках.

Клонирование примера приложения

  1. Откройте окно терминала и c помощью команды cd перейдите в рабочий каталог.

  2. Клонируйте пример репозитория и перейдите в корневой каталог репозитория.

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

    Этот репозиторий содержит приложение, созданное во время работы с предыдущим руководством: Использование страниц справки по веб-API ASP.NET Core со Swagger. В этом руководстве генератор Swagger используется для обслуживания пользовательского интерфейса Swagger и конечной точки JSON Swagger.

  3. Убедитесь, что по умолчанию задана ветвь main.

    git branch -m main
    

    Совет

    В Службе приложений не требуется менять имя ветви. Но, так как для многих репозиториев меняется ветка по умолчанию на main (см. раздел Изменение ветки развертывания), в этом руководстве также показано, как развернуть репозиторий из main.

Выполнение приложения

  1. Выполните указанные ниже команды, чтобы установить необходимые пакеты, перенести базы данных и запустить приложение.

    dotnet restore
    dotnet run
    
  2. Перейдите в расположение http://localhost:5000/swagger в браузере, чтобы поэкспериментировать с пользовательским интерфейсом Swagger.

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

  3. Перейдите в расположение http://localhost:5000/api/todo, чтобы просмотреть список элементов списка задач в формате JSON.

  4. Перейдите в расположение http://localhost:5000, чтобы поэкспериментировать с приложением браузера. Позже вы перейдете из приложения браузера к удаленному API в службе приложений, чтобы проверить функции CORS. Код для приложения браузера находится в каталоге wwwroot репозитория.

  5. Чтобы остановить ASP.NET Core в любое время, нажмите клавиши Ctrl+C в окне терминала.

Azure Cloud Shell

В Azure есть Azure Cloud Shell, интерактивная оболочка среды, с которой можно работать в браузере. Для работы со службами Azure можно использовать Bash или PowerShell с Cloud Shell. Для запуска кода из этой статьи можно использовать предварительно установленные команды Cloud Shell. Ничего дополнительного в локальной среде устанавливать не нужно.

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

Параметр Пример и ссылка
Нажмите кнопку Попробовать в правом верхнем углу блока кода или команд. При нажатии кнопки Попробовать код или команда не копируется в Cloud Shell автоматически. Снимок экрана: пример открытия Azure Cloud Shell с помощью кнопки
Чтобы открыть Cloud Shell в браузере, перейдите по адресу https://shell.azure.com или нажмите кнопку Запуск Cloud Shell. Снимок экрана: запуск Cloud Shell в новом окне.
Нажмите кнопку Cloud Shell в строке меню в правом верхнем углу окна портала Azure. Снимок экрана: кнопка

Чтобы использовать Azure Cloud Shell:

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

  2. Нажмите кнопку Копировать в блоке кода (или блоке команд), чтобы скопировать код или команду.

  3. Вставьте код или команду в окно сеанса Cloud Shell, нажав клавиши CTRL+SHIFT+V в Windows и Linux или CMD+SHIFT+V в macOS.

  4. Нажмите клавишу ВВОД, чтобы выполнить код или команду.

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

На этом этапе разверните приложение .NET Core в Службе приложений.

Настройка локального развертывания Git

Для развертывания в веб-приложение Azure из FTP и локального репозитория Git можно использовать пользователя развертывания. Настроив один раз пользователя развертывания, вы сможете использовать его для всех последующих развертываний в Azure. Имя пользователя и пароль учетной записи развертывания отличаются от учетных данных подписки Azure.

Чтобы настроить пользователя развертывания, выполните в Azure Cloud Shell команду az webapp deployment user set. Вместо <username> и <password> укажите имя пользователя и пароль развертывания.

  • Имя пользователя должно быть уникальным в Azure. Кроме того, чтобы отправка в локальный репозиторий Git работала, имя пользователя не должно содержать символ @.
  • Пароль должен содержать не менее восьми символов и включать два из трех следующих элементов: буквы, цифры и символы.
az webapp deployment user set --user-name <username> --password <password>

В выходных данных JSON пароль отображается как null. Если появляется сообщение об ошибке 'Conflict'. Details: 409, измените имя пользователя. Если появляется сообщение об ошибке 'Bad Request'. Details: 400, используйте более надежный пароль.

Запишите имя пользователя и пароль и используйте их для развертывания веб-приложений.

Создание группы ресурсов

Группа ресурсов — это логический контейнер, в котором происходит развертывание ресурсов Azure (например, веб-приложений, баз данных и учетных записей хранения) и управление ими. Например, в дальнейшем можно удалить всю группу ресурсов при помощи одного простого действия.

В Cloud Shell создайте группу ресурсов с помощью команды az group create. В следующем примере создается группа ресурсов с именем myResourceGroup в расположении Западная Европа. Чтобы просмотреть все поддерживаемые расположения для службы приложений уровня Бесплатный, выполните команду az appservice list-locations --sku FREE.

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

Обычно группа ресурсов и ресурсы создаются в ближайших регионах.

По завершении команды в выходных данных JSON будут отображаться свойства группы ресурсов.

Создание плана службы приложений

В Cloud Shell создайте план службы приложений с помощью команды az appservice plan create.

В следующем примере создается план службы приложений с именем myAppServicePlan и ценовой категорией Бесплатный.

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

После создания плана службы приложений в Azure CLI отображается информация следующего вида:

{ 
  "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
} 

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

Создайте веб-приложение в плане службы приложений myAppServicePlan.

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

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

Когда веб-приложение будет создано, в Azure CLI отобразится примерно следующее:

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. Сохраните этот URL-адрес для дальнейшего использования.

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

  1. Так как вы развертываете ветвь main, для Службы приложений нужно указать main как ветвь развертывания по умолчанию (см. раздел Изменение ветви развертывания). В Azure Cloud Shell настройте параметр приложения DEPLOYMENT_BRANCH с помощью команды az webapp config appsettings set.

    az webapp config appsettings set --name <app-name> --resource-group myResourceGroup --settings DEPLOYMENT_BRANCH='main'
    
  2. Вернитесь к окну терминала (в локальном расположении) и добавьте удаленное приложение Azure в локальный репозиторий Git. Замените <deploymentLocalGitUrl-from-create-step> URL-адресом удаленного репозитория Git, который вы сохранили при создании веб-приложения.

    git remote add azure <deploymentLocalGitUrl-from-create-step>
    
  3. Отправьте код в удаленное приложение Azure, чтобы развернуть приложение. При появлении запроса на ввод учетных данных в диспетчере учетных данных Git введите учетные данные, созданные на шаге настройки пользователя развертывания (а не те, которые используются для входа на портал Azure).

    git push azure main
    

    Выполнение этой команды может занять несколько минут. При выполнении эта команда выводит приблизительно следующие сведения:

   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
   

Переход к приложению Azure

  1. Перейдите в расположение http://<app_name>.azurewebsites.net/swagger в браузере и ознакомьтесь с пользовательским интерфейсом Swagger.

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

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

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

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

Далее вы включите встроенную поддержку CORS в службе приложений для API.

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

  1. В локальном репозитории откройте wwwroot/index.html.

  2. В строке 51 задайте для переменной apiEndpoint URL-адрес развернутого API (http://<app_name>.azurewebsites.net). Замените <appname> именем своего приложения в службе приложений.

  3. В локальном окне терминала снова запустите пример приложения.

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

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

Включение CORS

В Cloud Shell включите CORS для URL-адреса своего клиента с помощью команды az webapp cors add. Замените заполнитель <app-name>.

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

Можно задать несколько URL-адресов клиента в properties.cors.allowedOrigins ("['URL1','URL2',...]"). Также можно включить CORS для всех URL-адресов клиента с помощью "['*']".

Примечание

Если для вашего приложения требуется отправка учетных данных, например cookie или маркеров проверки подлинности, для браузера может понадобиться заголовок ACCESS-CONTROL-ALLOW-CREDENTIALS в ответе. Чтобы активировать этот заголовок в службе приложений, в конфигурации CORS установите значение параметра properties.cors.supportCredentials равным true. Его нельзя активировать, если параметр allowedOrigins содержит '*'.

Примечание

Указание AllowAnyOrigin и AllowCredentials является небезопасной конфигурацией и может привести к подделке межсайтовых запросов. Служба CORS возвращает недопустимый ответ CORS, если приложение настроено с использованием обоих методов.

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

Обновите приложение браузера, перейдя по адресу http://localhost:5000. Сообщение об ошибке в окне консоли исчезнет, вы сможете просмотреть данные из развернутого API и выполнить с ними операции. Теперь ваш удаленный API поддерживает CORS для приложения браузера, запущенного в локальной среде.

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

Поздравляем! Вы запустили API в службе приложений Azure с поддержкой CORS.

Сравнение CORS в службе приложений и вашей среде

Вы можете использовать собственные служебные программы CORS вместо программ в службе приложений для большей гибкости. Например, вы можете указать разные разрешенные источники для разных маршрутов или методов. Так как CORS в службе приложений позволяет указать один набор принятых источников для всех маршрутов и методов API, вы можете использовать собственный код CORS. Подробные сведения об этом см. в статье о включении запросов независимо от источника (CORS).

Встроенная Служба приложений функция CORS не имеет параметров, позволяющих разрешать только определенные методы HTTP или команды для каждого указанного источника. Он автоматически разрешает все методы и заголовки для каждого определенного источника. Такое поведение аналогично ASP.NET Core политикам CORS при использовании параметров .AllowAnyHeader() и .AllowAnyMethod() кода.

Примечание

Не используйте совместно CORS службы приложений и собственный код CORS. В противном случае ваш код CORS не принесет никаких результатов, так как CORS службы приложений имеет приоритет.

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

На предыдущем шаге вы создали ресурсы Azure в группе ресурсов. Если эти ресурсы вам не понадобятся в будущем, вы можете удалить группу ресурсов, выполнив следующую команду в Cloud Shell:

az group delete --name myResourceGroup

Ее выполнение может занять до минуты.

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

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

  • создавать ресурсы службы приложений с помощью Azure CLI;
  • развертывать API-интерфейс RESTful в Azure с помощью Git;
  • включать в службе приложений поддержку CORS.

Перейдите к следующему руководству, чтобы узнать, как выполнять аутентификацию и авторизацию пользователей.