在 Azure 应用服务中托管启用了 CORS 的 RESTful API

Azure 应用服务提供高度可缩放、自修补的 Web 托管服务。 另外,应用服务还为 RESTful API 提供对跨域资源共享 (CORS) 的内置支持。 本教程介绍如何将 ASP.NET Core API 应用部署到提供 CORS 支持的应用服务。 请使用命令行工具来配置应用,使用 Git 来部署应用。

本教程介绍如何执行下列操作:

  • 使用 Azure CLI 创建应用服务资源
  • 使用 Git 将 RESTful API 部署到 Azure
  • 启用应用服务 CORS 支持

如果没有 Azure 订阅,可在开始前创建一个试用帐户

先决条件

完成本教程:

创建本地 ASP.NET Core 应用

在此步骤中,请设置本地 ASP.NET Core 项目。 应用服务支持以其他语言编写的适用于 API 的同一工作流。

克隆示例应用程序

在终端窗口中,通过 cd 转到工作目录。

运行下列命令,克隆示例存储库。

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

此存储库包含的应用是根据以下教程创建的:使用 Swagger 的 ASP.NET Core Web API 帮助页。 它使用 Swagger 生成器来提供 Swagger UI 和 Swagger JSON 终结点。

运行应用程序

运行以下命令,安装所需的包,运行数据库迁移并启动应用程序。

cd dotnet-core-api
dotnet restore
dotnet run

在浏览器中导航到 http://localhost:5000/swagger,以便使用 Swagger UI。

在本地运行的 ASP.NET Core API

导航到 http://localhost:5000/api/todo,此时会看到 ToDo JSON 项的列表。

导航到 http://localhost:5000 并使用浏览器应用。 稍后请将浏览器应用指向应用服务中的远程 API,以便测试 CORS 功能。 浏览器应用的代码位于存储库的 wwwroot 目录中。

在终端按 Ctrl+C 可随时停止 ASP.NET Core。

将应用部署到 Azure

在此步骤中,将已连接 SQL 数据库的 .NET Core 应用程序部署到应用服务。

配置本地 Git 部署

使用 az webapp deployment user set 命令创建部署凭据。

在 Web 应用中进行 FTP 和本地 Git 部署时需要一个部署用户。 用户名和密码都为帐户级别。 它们与 Azure 订阅凭据不同。

在以下命令中,将 <user-name> 和 <password> 替换为新的用户名和密码。 用户名必须唯一。 密码长度必须至少为 8 个字符,其中包含以下 3 种元素中的两种:字母、数字、符号。

az webapp deployment user set --user-name <username> --password <password>

如果收到 'Conflict'. Details: 409 错误,请更改用户名。 如果收到 'Bad Request'. Details: 400 错误,请使用更强的密码。

只创建此部署用户一次;可对所有 Azure 部署使用此用户。

Note

记录用户名和密码。 稍后需要使用它们来部署 Web 应用。

创建资源组

资源组是在其中部署和管理 Azure 资源(例如 Web 应用、数据库和存储帐户)的逻辑容器。

使用 az group create 命令创建资源组。 以下示例在“中国北部”位置创建名为“myResourceGroup”的资源组。 若要查看免费层中应用服务支持的所有位置,请运行 az appservice list-locations --sku F1 命令。

az group create --name myResourceGroup --location "China North"

通常在附近的区域中创建资源组和资源。

此命令完成后,JSON 输出会显示资源组属性。

创建应用服务计划

使用 az appservice plan create 命令创建应用服务计划。

Note

应用服务计划表示用于托管应用的物理资源集合。 分配到应用服务计划的所有应用程序将共享该计划定义的资源。 托管多个应用时,此共享可让你节省资金。

应用服务计划定义:

  • 区域(中国东部、中国东部 2、中国北部、中国北部 2)。
  • 实例大小(小、中、大)
  • 规模计数(默认情况为 1 到 20 个实例)
  • SKU(免费、共享、基本、标准、高级)

以下示例在免费定价层中创建名为 myAppServicePlan 的应用服务计划:

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

创建应用服务计划后,Azure CLI 将显示类似于以下示例的信息:

{ 
  "adminSiteName": null,
  "appServicePlanName": "myAppServicePlan",
  "geoRegion": "China North",
  "hostingEnvironmentProfile": null,
  "id": "/subscriptions/0000-0000/resourceGroups/myResourceGroup/providers/Microsoft.Web/serverfarms/myAppServicePlan",
  "kind": "app",
  "location": "China North",
  "maximumNumberOfWorkers": 1,
  "name": "myAppServicePlan",
  < JSON data removed for brevity. >
  "targetWorkerSizeId": 0,
  "type": "Microsoft.Web/serverfarms",
  "workerTierName": null
} 

创建 Web 应用

myAppServicePlan 应用服务计划中创建一个 Web 应用。

可以使用 az webapp create 命令。 在以下示例中,将 <app_name> 替换为全局唯一的应用名称(有效字符是 a-z0-9-)。

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

创建 Web 应用后,Azure CLI 会显示类似于以下示例的输出:

Local git is configured with url of 'https://<username>@<app_name>.scm.chinacloudsites.cn/<app_name>.git'
{
  "availabilityState": "Normal",
  "clientAffinityEnabled": true,
  "clientCertEnabled": false,
  "cloningInfo": null,
  "containerSize": 0,
  "dailyMemoryTimeQuota": 0,
  "defaultHostName": "<app_name>.chinacloudsites.cn",
  "deploymentLocalGitUrl": "https://<username>@<app_name>.scm.chinacloudsites.cn/<app_name>.git",
  "enabled": true,
  < JSON data removed for brevity. >
}

Note

Git 远程的 URL 将显示在 deploymentLocalGitUrl 属性中,其格式为 https://<username>@<app_name>.scm.chinacloudsites.cn/<app_name>.git。 保存此 URL,因为稍后需要它。

从 Git 推送到 Azure

回到本地终端窗口,将 Azure 远程功能添加到本地 Git 存储库。 将 <deploymentLocalGitUrl-from-create-step> 替换为从创建 Web 应用保存的 Git 远程 URL。

git remote add azure <deploymentLocalGitUrl-from-create-step>

使用以下命令推送到 Azure 远程功能以部署应用。 当 Git 凭据管理器提示输入凭据时,请确保输入在配置部署用户中创建的凭据,而不是用于登录到 Azure 门户的凭据。

git push azure master

此命令可能需要花费几分钟时间运行。 运行时,该命令会显示类似于以下示例的信息:

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

浏览到 Azure Web 应用

在浏览器中导航到 http://<app_name>.chinacloudapi.cn/swagger,开始使用 Swagger UI。

在 Azure 应用服务中运行的 ASP.NET Core API

导航到 http://<app_name>.chinacloudapi.cn/swagger/v1/swagger.json 即可看到已部署 API 的 swagger.json

导航到 http://<app_name>.chinacloudapi.cn/api/todo 即可看到已部署 API 正在运行。

添加 CORS 功能

接下来,在适用于 API 的应用服务中启用内置的 CORS 支持。

在示例应用中测试 CORS

在本地存储库中,打开 wwwroot/index.html

在第 51 中,将 apiEndpoint 变量设置为已部署 API 的 URL (http://<app_name>.chinacloudapi.cn)。 在应用服务中将 <appname> 替换为你的应用名称。

在本地终端窗口中,再次运行示例应用。

dotnet run

导航到浏览器应用 (http://localhost:5000)。 在浏览器中打开开发人员工具窗口(在用于 Windows 的 Chrome 中使用 Ctrl+Shift+i),检查“控制台”选项卡。此时会看到错误消息:No 'Access-Control-Allow-Origin' header is present on the requested resource

浏览器客户端中的 CORS 错误

由于浏览器应用 (http://localhost:5000) 和远程资源 (http://<app_name>.chinacloudapi.cn) 的域不匹配,并且由于应用服务中的 API 未发送 Access-Control-Allow-Origin 标头,因此浏览器已阻止跨域内容在浏览器应用中加载。

在生产中,浏览器应用会有一个公共 URL 而不是 localhost URL,但对 localhost URL 启用 CORS 的方式与对公共 URL 相同。

启用 CORS

使用 az resource update 命令对客户端的 URL 启用 CORS。 替换 <appname> 占位符。

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

可以在 properties.cors.allowedOrigins ("['URL1','URL2',...]") 中设置多个客户端 URL。 也可使用 "['*']" 启用所有客户端 URL。

再次测试 CORS

刷新浏览器应用 (http://localhost:5000)。 “控制台”窗口中的错误消息现在已消失,可以看到已部署 API 中的数据并与之交互。 远程 API 现在支持对本地运行的浏览器应用使用 CORS。

CORS 在浏览器客户端中成功

恭喜!你在包含 CORS 支持的 Azure 应用服务中运行了 API。

应用服务 CORS 与你的 CORS 的比较

为了提高灵活性,可以使用自己的 CORS 实用程序而不是应用服务 CORS。 例如,可能需要针对不同的路由或方法指定不同的允许的源。 由于应用服务 CORS 允许你为所有 API 路由和方法指定一组接受的源,因此你需要使用自己的 CORS 代码。 请参阅启用跨域请求 (CORS),了解 ASP.NET Core 如何这样做。

Note

请勿尝试将应用服务 CORS 与你自己的 CORS 代码一起使用。 一起使用时,应用服务 CORS 优先级高,你自己的 CORS 代码将无效。

清理资源

若要删除通过此快速入门创建的所有资源,请运行以下命令:

az group delete --name myResourceGroup

后续步骤

现已了解:

  • 使用 Azure CLI 创建应用服务资源
  • 使用 Git 将 RESTful API 部署到 Azure
  • 启用应用服务 CORS 支持

转到下一教程,了解如何对用户进行身份验证和授权。