教學課程：在 Azure App 服務 中使用CORS裝載 RESTful API

  • 發行項

Azure App Service 提供可高度調整且自我修補的虛擬主機服務。 此外，App Service 也內建支援 RESTful API 的跨原始來源資源分享 （CORS）。 本教學課程示範如何使用 CORS 支援，將 ASP.NET 核心 API 應用程式部署到 App Service。 您可以使用命令行工具來設定應用程式，並使用 Git 部署應用程式。

在本教學課程中，您會了解如何：

  • 使用 Azure CLI 建立 App Service 資源
  • 使用 Git 將 RESTful API 部署至 Azure
  • 啟用 App Service CORS 支援

您可以在macOS、Linux、Windows上遵循本教學課程中的步驟。

如果您沒有 Azure 訂閱，請在開始之前，先建立 Azure 免費帳戶。

必要條件

完成本教學課程：

建立本機 ASP.NET Core 應用程式

在此步驟中，您會設定本機 ASP.NET Core 專案。 App Service 針對以其他語言撰寫的 API 支援相同的工作流程。

複製範例應用程式

  1. 在終端機視窗中， cd 移至工作目錄。

  2. 複製範例存放庫並變更至存放庫根目錄。

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

    此存放庫包含根據下列教學課程所建立的應用程式： 使用 Swagger ASP.NET Core Web API 說明頁面。 它會使用 Swagger 產生器來提供 Swagger UI 和 Swagger JSON 端點。

  3. 請確定預設分支為 main。

    git branch -m main

    提示

    App Service 不需要變更分支名稱。 不過，由於許多存放庫正在將其預設分支變更為 main （請參閱 變更部署分支），本教學課程也會示範如何從 main部署存放庫。

執行應用程式

  1. 執行下列命令來安裝必要的套件、執行資料庫移轉，以及啟動應用程式。

    dotnet restore
dotnet run

  2. 在瀏覽器中流覽至 http://localhost:5000/swagger 以使用 Swagger UI 播放。

    ASP.NET Core API running locally

  3. 流覽至 http://localhost:5000/api/todo 並查看 ToDo JSON 項目清單。

  4. 瀏覽至 http://localhost:5000 瀏覽器應用程式並播放。 稍後，您會將瀏覽器應用程式指向 App Service 中的遠端 API，以測試 CORS 功能。 瀏覽器應用程式的程式代碼可在存放庫的 wwwroot 目錄中找到。

  5. 若要隨時停止 ASP.NET Core，請在終端機中按 Ctrl+C 。

Azure Cloud Shell

Azure Cloud Shell 是裝載於 Azure 中的互動式殼層環境，可在瀏覽器中使用。 您可以使用 Bash 或 PowerShell 搭配 Cloud Shell，與 Azure 服務共同使用。 您可以使用 Cloud Shell 預先安裝的命令，執行本文提到的程式碼，而不必在本機環境上安裝任何工具。

要啟動 Azure Cloud Shell：

選項 範例/連結
選取程式碼或命令區塊右上角的 [試試看]。 選取 [試試看] 並不會自動將程式碼或命令複製到 Cloud Shell 中。 Screenshot that shows an example of Try It for Azure Cloud Shell.
請前往 https://shell.azure.com，或選取 [啟動 Cloud Shell] 按鈕，在瀏覽器中開啟 Cloud Shell。 Button to launch Azure Cloud Shell.
選取 Azure 入口網站右上方功能表列上的 [Cloud Shell] 按鈕。 Screenshot that shows the Cloud Shell button in the Azure portal

若要使用 Azure Cloud Shell：

  1. 啟動 Cloud Shell。

  2. 選取程式碼區塊 (或命令區塊) 上的 [複製] 按鈕以複製程式碼或命令。

  3. 透過在 Windows 和 Linux 上選取 Ctrl+Shift+V；或在 macOS 上選取 Cmd+Shift+V，將程式碼或命令貼到 Cloud Shell 工作階段中。

  4. 選取 Enter 鍵執行程式碼或命令。

將應用程式部署至 Azure

在此步驟中，您會將 .NET Core 應用程式部署至 App Service。

設定本機 Git 部署

FTP 和本機 Git 可以使用部署使用者部署至 Azure Web 應用程式。 設定部署用戶之後，即可將其用於所有 Azure 部署。 您的帳戶層級部署使用者名稱和密碼與您的 Azure 訂用帳戶認證不同。

若要設定部署使用者，請在 Azure Cloud Shell 中執行 az webapp deployment user set 命令。 將使用者>名稱和<密碼>取代<為部署使用者名稱和密碼。

  • 用戶名稱在 Azure 內必須是唯一的，而且對於本機 Git 推送，不得包含 『@』 符號。
  • 密碼長度必須至少為八個字元，且下列三個元素有兩個：字母、數位和符號。
az webapp deployment user set --user-name <username> --password <password>

JSON 輸出會將密碼顯示為 null。 如果您收到 'Conflict'. Details: 409 錯誤，請變更用戶名稱。 如果您收到 'Bad Request'. Details: 400 錯誤，請使用更強的密碼。

記錄您的使用者名稱和密碼，以用來部署 Web 應用程式。

建立資源群組

資源群組是一個邏輯容器，其中會部署和管理 Azure 資源，例如 Web 應用程式、資料庫和記憶體帳戶。 例如，您可以選擇稍後在一個簡單的步驟中刪除整個資源群組。

在 Cloud Shell 中，使用 az group create 命令建立資源群組。 下列範例會在西歐位置建立名為 myResourceGroup 的資源群組。 若要查看免費層中 App Service 的所有支援位置，請執行 az appservice list-locations --sku FREE 命令。

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

您通常會在附近的區域中建立您的資源群組和資源。

當命令完成時，JSON 輸出會顯示資源群組屬性。

建立 App Service 方案

在 Cloud Shell 中，使用 az appservice plan create 命令建立 App Service 方案。

下列範例會在免費定價層中建立名為 myAppServicePlan 的 App Service 方案：

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

建立 App Service 方案之後，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
}

建立 Web 應用程式

在 myAppServicePlan App Service 方案中建立 Web 應用程式。

在 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

建立 Web 應用程式後，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. >
}

注意

Git 遠端的網址會顯示在屬性中 deploymentLocalGitUrl ， 格式為 https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git。 請稍後視需要儲存此 URL。

從 Git 推送至 Azure

  1. 由於您要部署 main 分支，因此您必須將App Service 應用程式的預設部署分支設定為 main （請參閱 變更部署分支）。 在 Cloud Shell 中，使用 az webapp config appsettings set 命令設定DEPLOYMENT_BRANCH應用程式設定。

    az webapp config appsettings set --name <app-name> --resource-group myResourceGroup --settings DEPLOYMENT_BRANCH='main'

  2. 回到本機終端視窗，將 Azure 遠端新增至本機 Git 存放庫。 將 deploymentLocalGitUrl-from-create-step> 取代<為您從建立 Web 應用程式儲存的 Git 遠端 URL。

    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 UI 播放。

    ASP.NET Core API running in Azure App Service

  2. 流覽至 http://<app_name>.azurewebsites.net/swagger/v1/swagger.json 以查看 已部署 API 的 swagger.json。

  3. 流覽至 以查看 http://<app_name>.azurewebsites.net/api/todo 已部署的 API 運作。

新增 CORS 功能

接下來，您會為 API 啟用 App Service 中的內建 CORS 支援。

在範例應用程式中測試CORS

  1. 在您的本機存放庫中，開啟 wwwroot/index.html。

  2. 在第 51 行中，將 apiEndpoint 變數設定為已部署 API 的 URL （http://<app_name>.azurewebsites.net）。 將 appname> 取代<為 App Service 中的應用程式名稱。

  3. 在您的本機終端機視窗中，再次執行範例應用程式。

    dotnet run

  4. 瀏覽至位於 http://localhost:5000的瀏覽器應用程式。 在瀏覽器中開啟開發人員工具視窗（CtrliShift++在 Chrome for Windows 中），並檢查 [控制台] 索引標籤。您現在應該會看到錯誤訊息No 'Access-Control-Allow-Origin' header is present on the requested resource。

    CORS error in browser client

    瀏覽器應用程式 （） 和遠端資源 （http://localhost:5000http://<app_name>.azurewebsites.net） 之間的網域不符，會由瀏覽器辨識為跨原始來源資源要求。 此外，由於您的 REST API App Service 應用程式未傳送 Access-Control-Allow-Origin 標頭，瀏覽器已防止跨網域內容載入。

    在生產環境中，您的瀏覽器應用程式會有公用URL，而不是localhost URL，但啟用CORS至localhostURL的方式與公用URL相同。

啟用 CORS

在 Cloud Shell 中，使用 az webapp cors add 命令將 CORS 啟用至用戶端的 URL。 <取代應用程式名稱>佔位元。

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

您可以多次執行 命令，或在 中 --allowed-origins新增逗號分隔清單，以新增多個允許的來源。 若要允許所有來源，請使用 --allowed-origins '*'。

再次測試 CORS

在重新整理瀏覽器應用程式 http://localhost:5000。 控制台視窗中的錯誤訊息現在已消失，您可以看到已部署 API 中的數據，並與它互動。 您的遠端 API 現在支援 CORS 到本機執行的瀏覽器應用程式。

CORS success in browser client

恭喜您，您正以 CORS 支援在 Azure App 服務 中執行 API。

常見問題集

App Service CORS 與 CORS

您可以使用自己的 CORS 公用程式，而不是 App Service CORS，以取得更大的彈性。 例如，您可能想要為不同的路由或方法指定不同的允許來源。 由於 App Service CORS 可讓您為所有 API 路由和方法指定一組可接受的原始來源，因此您想要使用自己的 CORS 程式代碼。 請參閱 ASP.NET Core 如何在啟用跨原始來源要求 （CORS） 中執行此作業。

內建的 App Service CORS 功能沒有選項，只允許您指定之每個來源的特定 HTTP 方法或動詞。 它會自動允許每個定義來源的所有方法和標頭。 當您使用選項.AllowAnyHeader()和.AllowAnyMethod()程式代碼時，此行為類似於 ASP.NET Core CORS 原則。

注意

請勿嘗試一起使用App Service CORS和您自己的CORS程式碼。 一起使用時，App Service CORS 具有優先權，而您自己的 CORS 程式碼沒有任何作用。

如何? 將允許的來源設定為通配符子域？

像 這樣的 *.contoso.com 通配符子域比通配符來源 *更嚴格。 不過，Azure 入口網站 中的應用程式 CORS 管理頁面不會讓您將通配符子域設定為允許的來源。 不過，您可以使用 Azure CLI 來執行此動作，如下所示：

az webapp cors add --resource-group <group-name> --name <app-name> --allowed-origins 'https://*.contoso.com'

如何? 在回應上啟用 ACCESS-CONTROL-ALLOW-CREDENTIALS 標頭？

如果您的應用程式需要傳送 Cookie 或驗證令牌等認證，瀏覽器可能需要 ACCESS-CONTROL-ALLOW-CREDENTIALS 回應上的標頭。 若要在 App Service 中啟用此功能，請將 設定 properties.cors.supportCredentials 為 true。

az resource update --name web --resource-group <group-name> \
  --namespace Microsoft.Web --resource-type config \
  --parent sites/<app-name> --set properties.cors.supportCredentials=true

當允許的來源包含通配符來源 '*'時，不允許此作業。 同時指定 AllowAnyOrigin 和 AllowCredentials 是一種不安全的組態，可能會導致跨網站偽造要求。 若要允許認證，請嘗試使用通配符子域取代通配符原點。

清除資源

在上述步驟中，您已建立資源群組中的 Azure 資源。 如果您未來不需要這些資源，請在 Cloud Shell 中執行下列命令來刪除資源群組：

az group delete --name myResourceGroup

此命令可能需要一分鐘的時間才能執行。

下一步

您學到的內容：

  • 使用 Azure CLI 建立 App Service 資源
  • 使用 Git 將 RESTful API 部署至 Azure
  • 啟用 App Service CORS 支援

前進到下一個教學課程，以瞭解如何驗證和授權使用者。

教學課程：驗證和授權用戶端對端