Oktatóanyag: CORS-támogatással rendelkező RESTful API üzemeltetése az Azure App Service-ben

Az Azure App Service nagymértékben skálázható önjavító web hosting szolgáltatást nyújt. Emellett az App Service beépített támogatást nyújt a több forrásból származó erőforrásmegosztáshoz (CORS) a RESTful API-khoz. Ez az oktatóanyag bemutatja, hogyan telepíthető ASP.NET Core API-alkalmazás az App Service-ben CORS-támogatással. Az alkalmazást parancssori eszközökkel konfigurálhatja, és üzembe helyezheti az alkalmazást a Git használatával.

Ebben az oktatóanyagban az alábbiakkal fog megismerkedni:

• App Service-erőforrások létrehozása az Azure CLI használatával.
• RESTful API üzembe helyezése az Azure-ban a Git használatával.
• Engedélyezze az App Service CORS támogatását.

Ezt az oktatóanyagot macOS, Linux vagy Windows rendszeren is elvégezheti.

Ha még nem rendelkezik Azure-fiókkal, első lépésként hozzon létre egy ingyenes fiókot.

Előfeltételek

• Telepítse a Gitet.
• Telepítse a legújabb .NET Core 3.1 SDK-t.

Helyi ASP.NET Core-alkalmazás létrehozása

Ebben a lépésben a helyi ASP.NET Core-projektet állíthatja be. Az App Service támogatja az API-k más nyelven írt azonos munkafolyamatait.

A mintaalkalmazás klónozása

1. A terminálablakban cd nyissa meg a munkakönyvtárat.

2. Klónozza a mintaadattárat, majd nyissa meg az adattár gyökerét.

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

   Ez az adattár egy olyan alkalmazást tartalmaz, amely az ASP.NET Core web API dokumentációhoz készült tutorialon alapul, a Swagger/OpenAPI használatával. Egy Swagger-generátort használ a Swagger felhasználói felületének és a Swagger JSON-végpontjának kiszolgálásához.

3. Győződjön meg arról, hogy az alapértelmezett ág az main.

   git branch -m main
   

   Tipp.

   Az App Service nem követeli meg az ágnév módosítását. Azonban, mivel számos adattár módosítja az alapértelmezett ágát main (lásd: Üzembehelyezési ág módosítása), ez az oktatóanyag bemutatja, hogyan telepíthet egy adattárat a main ágból.

Az alkalmazás futtatása

1. Futtassa az alábbi parancsokat a szükséges csomagok telepítéséhez, adatbázisok migrálásához és az alkalmazás elindításához.

   dotnet restore
   dotnet run
   

2. Nyissa meg http://localhost:5000/swagger a böngészőben a Swagger felhasználói felületének kipróbálásához.

   

3. Nyissa meg a http://localhost:5000/api/todo ToDo JSON-elemek listáját.

4. Nyissa meg http://localhost:5000 és kísérletezzen a böngészőalkalmazással. Később a böngészőalkalmazást egy távoli API-ra fogjaja az App Service-ben a CORS-funkciók teszteléséhez. A böngészőalkalmazás kódja az adattár wwwroot könyvtárában található.

5. Ha bármikor le szeretné állítani ASP.NET Core-t, válassza a Ctrl+C billentyűkombinációt a terminálban.

Azure Cloud Shell

Az Azure által üzemeltetett Azure Cloud Shell egy interaktív felület, amelyet a böngészőből használhat. A Bash vagy a PowerShell segítségével is használhatja a Cloud Shellt az Azure-szolgáltatásokhoz. A Cloud Shell előre telepített parancsaival futtathatja a jelen cikkben szereplő kódot anélkül, hogy bármit telepítenie kellene a helyi környezetben.

Az Azure Cloud Shell indítása:

Lehetőség	Példa/hivatkozás
Válassza a Kipróbálás lehetőséget egy kód vagy parancsblokk jobb felső sarkában. A Kipróbálás lehetőség választása nem másolja automatikusan a kódot vagy a parancsot a Cloud Shellbe.
Nyissa meg https://shell.azure.coma Cloud Shellt, vagy válassza a Cloud Shell indítása gombot a Cloud Shell böngészőben való megnyitásához.
Válassza a Cloud Shell gombot az Azure Portal jobb felső sarkában található menüsávon.

Az Azure Cloud Shell használata:

1. Indítsa el a Cloud Shellt.

2. A kód vagy parancs másolásához kattintson a Másolás gombra egy kódblokkon (vagy parancsblokkon).

3. Illessze be a kódot vagy parancsot a Cloud Shell-munkamenetbe a Windows és Linux rendszeren a CtrlShift+V+, vagy a Cmd+Shift+V macOS rendszeren való kiválasztásával.

4. A kód vagy parancs futtatásához válassza az Enter lehetőséget .

Az alkalmazás üzembe helyezése az Azure-ban

Ebben a lépésben üzembe helyezi a .NET Core-alkalmazást az App Service-ben.

A Git helyi üzemelő példányának konfigurálása

Az FTP és a helyi Git üzembe helyezhető egy Azure-webalkalmazásban egy üzembehelyezési felhasználó használatával. Miután konfigurálta az üzembehelyezési felhasználót, az összes Azure-üzembe helyezéshez használhatja. A fiókszintű üzembehelyezési felhasználónév és jelszó eltér az Azure-előfizetés hitelesítő adataitól.

Az üzembe helyezési felhasználó konfigurálásához futtassa az az webapp deployment user set parancsot az Azure Cloud Shellben. Cserélje le <a felhasználónevet> és <a jelszót> egy üzembehelyezési felhasználónevére és jelszavára.

• A felhasználónévnek egyedinek kell lennie az Azure-ban, és a helyi Git-leküldések esetében nem tartalmazhat "@" szimbólumot.
• A jelszónak legalább nyolc karakter hosszúnak kell lennie, és a következő három elem közül kettőnek kell lennie: betűk, számok és szimbólumok.

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

A JSON-kimenet a jelszót a következőként nulljeleníti meg: . 'Conflict'. Details: 409 hibaüzenet esetén változtassa meg a felhasználónevet. 'Bad Request'. Details: 400 hibaüzenet esetén használjon erősebb jelszót.

Jegyezze fel a webalkalmazások üzembe helyezéséhez használandó felhasználónevet és jelszót.

Erőforráscsoport létrehozása

Az erőforráscsoport egy logikai tároló, amelybe az Azure-erőforrásokat, például webalkalmazásokat, adatbázisokat és tárfiókokat helyezik üzembe és felügyelik. Dönthet úgy is például, hogy később egyetlen egyszerű lépésben törli a teljes erőforráscsoportot.

A Cloud Shellben hozzon létre egy erőforráscsoportot az az group create paranccsal. Az alábbi példa egy myResourceGroup nevű erőforráscsoportot hoz létre a nyugat-európai helyen. Ha az App Service minden támogatott helyét ingyenes szinten szeretné megtekinteni, futtassa a az appservice list-locations --sku FREE parancsot.

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

Az erőforráscsoportot és az erőforrásokat általában a közelében található régiókban hozhatja létre.

A parancs befejeződésekor a JSON-kimenet megjeleníti az erőforráscsoport tulajdonságait.

App Service-csomag létrehozása

A Cloud Shellben hozzon létre egy App Service-csomagot az az appservice plan create paranccsal.

Az alábbi példa létrehoz egy App Service-csomagot myAppServicePlan az ingyenes árszabási szinten.

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

Az App Service-csomag létrehozása után az Azure CLI az alábbi példához hasonló információkat jelenít meg:

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

Webalkalmazás létrehozása

Webalkalmazás létrehozása az myAppServicePlan App Service-csomagban.

A Cloud Shellben használhatja az az webapp create parancsot. Az alábbi példában cserélje le <app-name> egy globálisan egyedi alkalmazásnévre. (Az érvényes karakterek a következők a-z: , 0-9és -.)

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

A webalkalmazás létrehozása után az Azure CLI az alábbi példához hasonló kimenetet jelenít meg:

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

Feljegyzés

A távoli Git URL-címe a deploymentLocalGitUrl tulajdonságban látható, a következő formátumban: https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Mentse ezt az URL-címet, mert később szüksége lesz rá.

Leküldéses üzenet küldése a Gitből az Azure-ra

1. Mivel az main ágat telepíti, be kell állítania az App Service-alkalmazás alapértelmezett üzembehelyezési ágát main. (Lásd: Az üzembehelyezési ág módosítása.) A Cloud Shellben állítsa be az DEPLOYMENT_BRANCH alkalmazásbeállítást a az webapp config appsettings set parancs használatával.

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

2. A helyi terminálablakba visszatérve adjon hozzá egy távoli Azure-mappát a helyi Git-adattárhoz. Cserélje le a <deploymentLocalGitUrl-from-create-step> elemet arra a Git-távoli URL-címre, amelyet a Webalkalmazás létrehozása lépés során mentett el.

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

3. A távoli Azure-mappához történő küldéssel helyezze üzembe az alkalmazást a következő paranccsal. Amikor a Git Credential Manager kéri a hitelesítő adatok megadását, győződjön meg arról, hogy a Helyi Git-telepítés konfigurálása területen létrehozott hitelesítő adatokat adja meg, nem pedig az Azure Portalra való bejelentkezéshez használt hitelesítő adatokat.

   git push azure main
   

   A parancs futtatása eltarthat néhány percig. Futtatás közben a parancs a következő példához hasonló információkat jelenít meg:

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

Tallózás az Azure-alkalmazáshoz

1. Nyissa meg http://<app_name>.azurewebsites.net/swagger a böngészőben, és tekintse meg a Swagger felhasználói felületét.

   

2. Menjen a http://<app_name>.azurewebsites.net/swagger/v1/swagger.json az üzembe helyezett API swagger.json megnézéséhez.

3. Menjen az http://<app_name>.azurewebsites.net/api/todo, hogy lássa az üzembe helyezett API működését.

CORS-funkció hozzáadása

A következő lépésben engedélyezi az App Service beépített CORS-támogatását az API-hoz.

CORS tesztelése a mintaalkalmazásban

1. A helyi adattárban nyissa meg a wwwroot/index.html.

2. Az 51. sorban állítsa a változót apiEndpoint az üzembe helyezett APIhttp://<app_name>.azurewebsites.net () URL-címére. Cserélje le <az alkalmazásnevet> az alkalmazás nevére.

3. A helyi terminálablakban futtassa ismét a mintaalkalmazást.

   dotnet run
   

4. Nyissa meg a böngészőalkalmazást a következő helyen http://localhost:5000: . Nyissa meg a fejlesztői eszközök ablakát a böngészőben (Ctrl+Shift+i in Chrome for Windows) és vizsgálja meg a Konzol lapot. Ekkor megjelenik a hibaüzenet No 'Access-Control-Allow-Origin' header is present on the requested resource.

   

   A böngészőalkalmazás (http://localhost:5000) és a távoli erőforrás (http://<app_name>.azurewebsites.net) közötti tartományeltérést a böngésző forrásközi erőforrás-kérésként ismeri fel. Mivel az App Service-alkalmazás nem küldi el a Access-Control-Allow-Origin fejlécet, a böngésző megakadályozta a tartományok közötti tartalmak betöltését.

   Éles környezetben a böngészőalkalmazásnak nyilvános URL-címe lenne a localhost URL-cím helyett, de a CORS localhost URL-címhez való engedélyezésének folyamata megegyezik a nyilvános URL-címek folyamatával.

CORS engedélyezése

A Cloud Shellben engedélyezze a CORS-t az ügyfél URL-címére a az webapp cors add parancs használatával. Cserélje le az <alkalmazásnév> helyőrzőt.

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

Több engedélyezett forrást is hozzáadhat a parancs többszöri futtatásával vagy egy vesszővel tagolt lista hozzáadásával.--allowed-origins Az összes forrás engedélyezéséhez használja --allowed-origins '*'a következőt: .

A CORS újbóli tesztelése

Frissítse a böngészőalkalmazást a http://localhost:5000 címen. A konzolablakban megjelenő hibaüzenet már nem jelenik meg, és láthatja az üzembe helyezett API-ból származó adatokat, és kezelheti azokat. A távoli API már támogatja a CORS-t a helyileg futtatott böngészőalkalmazásban.

Gratulálunk, sikeresen beállította az API CORS-támogatással való futtatását az Azure App Service-ben.

Gyakori kérdések

• App Service CORS és a saját CORS
• Hogyan állíthatom be az engedélyezett forrásokat egy helyettesítő karakteres altartományra?
• Hogyan engedélyezhetem az ACCESS-CONTROL-ALLOW-CREDENTIALS fejlécet a válaszon?

Az App Service-beli és a saját CORS összehasonlítása

A nagyobb rugalmasság érdekében saját CORS-segédprogramokat használhat az App Service CORS helyett. Előfordulhat például, hogy különböző útvonalakhoz vagy metódusokhoz különböző engedélyezett forrásokat szeretne megadni. Mivel az App Service CORS lehetővé teszi, hogy az összes API-útvonalhoz és metódushoz csak egy elfogadott forráskészletet adjon meg, saját CORS-kódot kell használnia. A CORS ASP.NET Core-ban való engedélyezéséről további információt a CORS engedélyezése című témakörben talál.

A beépített App Service CORS szolgáltatás nem rendelkezik olyan beállításokkal, amelyekkel csak adott HTTP-metódusokat vagy igéket engedélyezhet minden megadott forráshoz. Automatikusan engedélyezi az összes metódust és fejlécet minden meghatározott forráshoz. Ez a viselkedés hasonló az ASP.NET Core CORS-szabályzatokhoz, amikor a .AllowAnyHeader() és .AllowAnyMethod() beállításokat használja a kódban.

Feljegyzés

Ne próbálja együtt használni az App Service CORS-t és a saját CORS-kódját. Ha együtt próbálja használni őket, az App Service CORS elsőbbséget élvez, és a saját CORS-kódnak nincs hatása.

Hogyan helyettesítő karakterek altartományára állítja be az engedélyezett forrásokat?

A helyettesítő karakterek altartománya a *.contoso.com helyettesítő karakterek forrásánál *szigorúbb. Az alkalmazás CORS-felügyeleti oldala az Azure Portalon nem engedélyezi a helyettesítő karakterek altartományának beállítását engedélyezett forrásként. Ezt azonban az Azure CLI használatával teheti meg:

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

Hogyan engedélyezi az ACCESS-CONTROL-ALLOW-CREDENTIALS fejlécet a válaszon?

Ha az alkalmazás hitelesítő adatokat, például cookie-kat vagy hitelesítési jogkivonatokat igényel, előfordulhat, hogy a böngészőnek szüksége van a ACCESS-CONTROL-ALLOW-CREDENTIALS válasz fejlécére. Ha engedélyezni szeretné ezt az App Service-ben, állítsa a properties.cors.supportCredentials következőre 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

Ez a művelet nem engedélyezett, ha az engedélyezett források közé tartozik a helyettesítő karakter.'*' Adja meg, AllowAnyOrigin és AllowCredentials nem biztonságos. Ha így tesz, az a helyek közötti kérések hamisítását eredményezheti. A hitelesítő adatok engedélyezéséhez próbálja meg a helyettesítő karakteres forrást helyettesítő altartományokra cserélni.

Az erőforrások eltávolítása

Az előző lépésekben Azure-erőforrásokat hozott létre egy erőforráscsoportban. Ha várhatóan nem lesz szüksége ezekre az erőforrásokra a jövőben, törölje az erőforráscsoportot a következő parancs Cloud Shellben történő futtatásával:

az group delete --name myResourceGroup

A parancs futtatása eltarthat egy percig.

Következő lépés

Az alábbiak elvégzését ismerte meg:

• App Service-erőforrások létrehozása az Azure CLI használatával.
• RESTful API üzembe helyezése az Azure-ban a Git használatával.
• Engedélyezze az App Service CORS támogatását.

A következő oktatóanyagból megtudhatja, hogyan hitelesítheti és engedélyezheti a felhasználókat.

Oktatóanyag: Felhasználók hitelesítése és engedélyezése végpontok között