Kurz: Hostování rozhraní RESTful API s CORS v Azure App Service

  • Článek

Azure App Service je vysoce škálovatelná služba s automatickými opravami pro hostování webů. Kromě toho zahrnuje App Service integrovanou podporu Sdílení prostředků různého původu (CORS) pro rozhraní RESTful API. V tomto kurzu se dozvíte, jak do App Service nasadit aplikaci ASP.NET Core API s podporou CORS. Aplikaci nakonfigurujete pomocí nástrojů příkazového řádku a nasadíte pomocí Gitu.

V tomto kurzu se naučíte:

  • Vytvoření prostředků App Service pomocí Azure CLI
  • Nasazení rozhraní RESTful API do Azure pomocí Gitu
  • Povolení podpory CORS v App Service

Podle kroků v tomto kurzu můžete postupovat v systémech macOS, Linux a Windows.

Pokud ještě nemáte předplatné Azure, vytvořte si bezplatný účet Azure před tím, než začnete.

Požadavky

Pro absolvování tohoto kurzu potřebujete:

Vytvoření místní aplikace ASP.NET Core

V tomto kroku nastavíte místní projekt ASP.NET Core. App Service podporuje stejný pracovní postup i pro rozhraní API napsaná v jiných jazycích.

Klonování ukázkové aplikace

  1. V okně terminálu přejděte pomocí příkazu cd do pracovního adresáře.

  2. Naklonujte ukázkové úložiště a přejděte do kořenového adresáře úložiště.

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

    Toto úložiště obsahuje aplikaci vytvořenou podle následujícího kurzu: Generování stránek nápovědy webového rozhraní ASP.NET Core API pomocí Swaggeru. Aplikace s využitím generátoru Swagger poskytuje uživatelské rozhraní Swagger a koncový bod JSON pro Swagger.

  3. Ujistěte se, že výchozí větev je main.

    git branch -m main

    Tip

    App Service nevyžaduje změnu názvu větve. Vzhledem k tomu, že mnoho úložišť mění výchozí větev na main (viz Změna větve nasazení), v tomto kurzu se také dozvíte, jak nasadit úložiště z main.

Spuštění aplikace

  1. Spuštěním následujících příkazů nainstalujte požadované balíčky, spusťte operace migrace databáze a spusťte aplikaci.

    dotnet restore
dotnet run

  2. V prohlížeči přejděte na adresu http://localhost:5000/swagger a vyzkoušejte si uživatelské rozhraní Swagger.

    ASP.NET Core API running locally

  3. Přejděte na adresu http://localhost:5000/api/todo, kde se zobrazí seznam položek úkolů ve formátu JSON.

  4. Přejděte na adresu http://localhost:5000 a vyzkoušejte si aplikaci v prohlížeči. Později otestujete funkce CORS nastavením aplikace v prohlížeči tak, aby odkazovala na vzdálené rozhraní API v App Service. Kód aplikace v prohlížeči najdete v adresáři wwwroot úložiště.

  5. ASP.NET Core můžete kdykoli zastavit stisknutím Ctrl+C v terminálu.

Azure Cloud Shell

Azure hostí interaktivní prostředí Azure Cloud Shell, které můžete používat v prohlížeči. Pro práci se službami Azure můžete v prostředí Cloud Shell použít buď Bash, nebo PowerShell. Předinstalované příkazy Cloud Shellu můžete použít ke spuštění kódu v tomto článku, aniž byste museli instalovat cokoli do místního prostředí.

Spuštění služby Azure Cloud Shell:

Možnost Příklad nebo odkaz
Vyberte Vyzkoušet v pravém horním rohu bloku kódu nebo příkazu. Výběrem možnosti Vyzkoušet se kód ani příkaz automaticky nekopíruje do Cloud Shellu. Screenshot that shows an example of Try It for Azure Cloud Shell.
Přejděte na adresu https://shell.azure.com nebo výběrem tlačítka Spustit Cloud Shell otevřete Cloud Shell v prohlížeči. Button to launch Azure Cloud Shell.
Zvolte tlačítko Cloud Shell v pruhu nabídky v pravém horním rohu webu Azure Portal. Screenshot that shows the Cloud Shell button in the Azure portal

Použití Azure Cloud Shellu:

  1. Spusťte Cloud Shell.

  2. Výběrem tlačítka Kopírovat v bloku kódu (nebo bloku příkazů) zkopírujte kód nebo příkaz.

  3. Vložte kód nebo příkaz do relace Cloud Shellu tak, že ve Windows a Linuxu vyberete ctrl+Shift+V nebo vyberete Cmd+Shift+V v macOS.

  4. Stisknutím klávesy Enter spusťte kód nebo příkaz.

Nasazení aplikace do Azure

V tomto kroku nasadíte aplikaci .NET Core do služby App Service.

Konfigurace nasazení místního gitu

FTP a místní Git se můžou nasadit do webové aplikace Azure pomocí uživatele nasazení. Jakmile nakonfigurujete uživatele nasazení, můžete ho použít pro všechna nasazení Azure. Uživatelské jméno a heslo nasazení na úrovni účtu se liší od přihlašovacích údajů předplatného Azure.

Pokud chcete nakonfigurovat uživatele nasazení, spusťte příkaz az webapp deployment user set v Azure Cloud Shellu. Nahraďte <uživatelské jméno> a <heslo> uživatelským jménem a heslem pro nasazení.

  • Uživatelské jméno musí být v Rámci Azure jedinečné a pro místní zápisy z Gitu nesmí obsahovat symbol @.
  • Heslo musí mít alespoň osm znaků, přičemž dva z následujících tří prvků: písmena, číslice a symboly.
az webapp deployment user set --user-name <username> --password <password>

Výstup JSON zobrazuje heslo jako null. Pokud se zobrazí chyba 'Conflict'. Details: 409, změňte uživatelské jméno. Pokud se zobrazí chyba 'Bad Request'. Details: 400, použijte silnější heslo.

Poznamenejte si uživatelské jméno a heslo, které chcete použít k nasazení webových aplikací.

Vytvoření skupiny zdrojů

Skupina prostředků je logický kontejner, do kterého se nasazují a spravují prostředky Azure, jako jsou webové aplikace, databáze a účty úložiště. Později se například můžete rozhodnout odstranit celou skupinu prostředků v jednom jednoduchém kroku.

Ve službě Cloud Shell vytvořte skupinu prostředků pomocí příkazu az group create. Následující příklad vytvoří skupinu prostředků myResourceGroup v umístění Západní Evropa. Pokud chcete zobrazit všechna podporovaná umístění pro službu App Service na úrovni Free, spusťte příkaz az appservice list-locations --sku FREE.

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

Obvykle budete svoji skupinu prostředků a prostředky vytvářet v oblasti, kterou máte blízko.

Po dokončení příkazu se ve výstupu JSON zobrazí vlastnosti skupiny prostředků.

Vytvoření plánu služby App Service

Ve službě Cloud Shell vytvořte pomocí příkazu az appservice plan create plán služby App Service.

Následující příklad vytvoří plán služby App Service s názvem myAppServicePlan v cenové úrovni Free:

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

Po vytvoření plánu služby App Service se v rozhraní příkazového řádku Azure zobrazí podobné informace jako v následujícím příkladu:

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

Vytvoření webové aplikace

Vytvořte webovou aplikaci v plánu služby App Service myAppServicePlan.

Ve službě Cloud Shell můžete použít příkaz az webapp create. V následujícím příkladu nahraďte <app-name> globálně jedinečným názvem aplikace (platné znaky jsou a-z, 0-9 a -).

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

Po vytvoření webové aplikace Azure CLI zobrazí výstup podobný následujícímu příkladu:

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. >
}

Poznámka:

Adresa URL vzdáleného úložiště Git se zobrazuje ve vlastnosti deploymentLocalGitUrl ve formátu https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Tuto adresu URL si uložte, protože ji budete potřebovat později.

Přenos z Gitu do Azure

  1. Vzhledem k tomu, že větev nasazujete main , musíte pro aplikaci main App Service nastavit výchozí větev nasazení (viz Změna větve nasazení). V Cloud Shellu DEPLOYMENT_BRANCH nastavte nastavení aplikace pomocí az webapp config appsettings set příkazu.

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

  2. Zpět v okně místního terminálu přidejte vzdálené úložiště Azure do místního úložiště Git. Nahraďte deploymentLocalGitUrl-from-create-step> adresou URL vzdáleného úložiště Git, který jste uložili z vytvoření webové aplikace.<

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

  3. Nasaďte aplikaci do vzdáleného úložiště Azure pomocí následujícího příkazu. Když vás Git Credential Manager vyzve k zadání přihlašovacích údajů, ujistěte se, že jste zadali přihlašovací údaje, které jste vytvořili v části Konfigurace uživatele nasazení, a ne přihlašovací údaje, které používáte pro přihlášení k webu Azure Portal.

    git push azure main

    Spuštění tohoto příkazu může trvat několik minut. Při spuštění příkaz zobrazí podobné informace jako v následujícím příkladu:

   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

Přejděte do aplikace Azure.

  1. V prohlížeči přejděte na adresu http://<app_name>.azurewebsites.net/swagger a vyzkoušejte si uživatelské rozhraní Swagger.

    ASP.NET Core API running in Azure App Service

  2. Přejděte na adresu http://<app_name>.azurewebsites.net/swagger/v1/swagger.json, kde se zobrazí soubor swagger.json pro vaše nasazené rozhraní API.

  3. Přejděte na adresu http://<app_name>.azurewebsites.net/api/todo, kde se zobrazí funkční nasazené rozhraní API.

Přidání funkcí CORS

Dále pro své rozhraní API povolíte integrovanou podporu CORS v App Service.

Test CORS v ukázkové aplikaci

  1. V místním úložišti otevřete soubor wwwroot/index.html.

  2. Na řádku 51 nastavte proměnnou apiEndpoint na adresu URL vašeho nasazeného rozhraní API (http://<app_name>.azurewebsites.net). Nahraďte <název> aplikace názvem vaší aplikace ve službě App Service.

  3. V místním okně terminálu znovu spusťte ukázkovou aplikaci.

    dotnet run

  4. Přejděte do aplikace v prohlížeči na adrese http://localhost:5000. Otevřete okno vývojářských nástrojů v prohlížeči (Ctrl+Shifti+v Chromu pro Windows) a prohlédněte si kartu Konzola. Teď by se měla zobrazit chybová zprávaNo 'Access-Control-Allow-Origin' header is present on the requested resource.

    CORS error in browser client

    Prohlížeč rozpozná neshodu domény mezi aplikací prohlížeče (http://localhost:5000) a vzdáleným prostředkem (http://<app_name>.azurewebsites.net) jako žádost o prostředek mezi zdroji. Také skutečnost, že vaše rozhraní REST API, které aplikace App Service neodesílá Access-Control-Allow-Origin , prohlížeč zabránil načtení obsahu mezi doménou.

    V produkčním prostředí by vaše aplikace v prohlížeči měla místo adresy URL místního hostitele veřejnou adresu URL, ale postup pro povolení CORS pro adresu URL místního hostitele je stejný jako u veřejné adresy URL.

Povolení CORS

Ve službě Cloud Shell povolte CORS pro adresu URL vašeho klienta pomocí příkazu az webapp cors add. <Zástupný symbol pro název> aplikace nahraďte.

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

Můžete přidat více povolených zdrojů spuštěním příkazu vícekrát nebo přidáním čárkami samostatného seznamu do --allowed-originssouboru . Chcete-li povolit všechny původy, použijte --allowed-origins '*'.

Opětovný test CORS

Aktualizujte aplikaci v prohlížeči na adrese http://localhost:5000. Chybová zpráva v okně Console (Konzola) už je pryč a zobrazí se data z nasazeného rozhraní API, se kterými můžete pracovat. Vaše vzdálené rozhraní API nyní podporuje CORS pro vaši místně spuštěnou aplikaci v prohlížeči.

CORS success in browser client

Blahopřejeme! Teď máte v Azure App Service spuštěné rozhraní API s podporou CORS.

Nejčastější dotazy

CORS v App Service vs. vlastní CORS

Místo CORS v App Service můžete použít vlastní CORS poskytující větší flexibilitu. Například můžete chtít určit různé povolené zdroje pro různé trasy a metody. Vzhledem k tomu že CORS v App Service umožňuje zadat jednu sadu povolených zdrojů pro všechny trasy a metody rozhraní API, chtěli byste použít vlastní kód CORS. Informace o tom, jak se to dělá v ASP.NET Core, najdete tématu o povolení prostředků různého původů (CORS).

Integrovaná funkce CORS služby App Service nemá možnosti povolit pouze konkrétní metody HTTP nebo příkazy pro každý zadaný zdroj. Automaticky povolí všechny metody a hlavičky pro každý definovaný původ. Toto chování se podobá ASP.NET základním zásadám CORS při použití možností .AllowAnyHeader() a .AllowAnyMethod() kódu.

Poznámka:

Nedoporučujeme používat společně CORS v App Service a vlastní kód CORS. Při společném použití bude mít přednost CORS v App Service a váš vlastní kód CORS nebude mít žádný vliv.

Návody nastavit povolené původy na subdoménu se zástupným znakem?

Subdoména se zástupným znakem je *.contoso.com více omezující než zástupný znak původu *. Stránka pro správu CORS aplikace na webu Azure Portal ale neumožňuje nastavit subdoménu se zástupnými otaží jako povoleného původu. Můžete to ale udělat pomocí Azure CLI, například takto:

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

Návody v odpovědi povolit hlavičku ACCESS-CONTROL-ALLOW-CREDENTIALS?

Pokud vaše aplikace vyžaduje odeslání přihlašovacích údajů, jako jsou soubory cookie nebo ověřovací tokeny, může prohlížeč vyžadovat hlavičku ACCESS-CONTROL-ALLOW-CREDENTIALS odpovědi. Pokud to chcete povolit ve službě App Service, nastavte properties.cors.supportCredentials na truehodnotu .

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

Tato operace není povolena, pokud povolené původy zahrnují zástupný znak '*'. AllowAnyOrigin Určení a AllowCredentials je nezabezpečená konfigurace a může vést k padělání požadavků mezi weby. Pokud chcete povolit přihlašovací údaje, zkuste nahradit zástupný znak původ subdoménami zástupných znaků.

Vyčištění prostředků

V předchozích krocích jste vytvořili prostředky Azure ve skupině prostředků. Pokud předpokládáte, že už tyto prostředky nebudete potřebovat, odstraňte skupinu prostředků spuštěním následujícího příkazu ve službě Cloud Shell:

az group delete --name myResourceGroup

Spuštění tohoto příkazu může trvat přibližně minut.

Další kroky

Naučili jste se:

  • Vytvoření prostředků App Service pomocí Azure CLI
  • Nasazení rozhraní RESTful API do Azure pomocí Gitu
  • Povolení podpory CORS v App Service

V dalším kurzu se dozvíte, jak ověřovat a autorizovat uživatele.

Kurz: Komplexní ověřování a autorizace uživatelů