Zelfstudie: een RESTful API hosten met CORS in Azure App Service

Azure App Service biedt een uiterst schaalbare webhostingservice met self-patchfunctie. Daarnaast bevat App Service ingebouwde ondersteuning voor CORS (Cross-Origin Resource Sharing) voor RESTful API's. In deze zelfstudie leert u hoe u een ASP.NET Core API-app in App Service met CORS-ondersteuning implementeert. U configureert de app met opdrachtregelprogramma's en implementeert de app met behulp van Git.

In deze zelfstudie leert u het volgende:

U kunt de stappen in deze zelfstudie volgen voor macOS, Linux en Windows.

Als u geen Azure-abonnement hebt, kunt u een gratis Azure-account maken voordat u begint.

Vereisten

Vereisten om deze zelfstudie te voltooien:

• Git installeren
• De nieuwste .NET Core 3.1-SDK installeren

Lokale ASP.NET Core-app maken

In deze stap stelt u het lokale ASP.NET Core-project in. App Service ondersteunt dezelfde werkstroom voor API's die in andere talen zijn geschreven.

De voorbeeldtoepassing klonen

1. Voer in het terminalvenster de opdracht cd naar een werkmap uit.

2. Kloon de voorbeeldopslagplaats en ga naar de hoofdmap van de opslagplaats.

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

   Deze opslagplaats bevat een app die wordt gemaakt op basis van de volgende zelfstudie: ASP.NET Core Web API help pages using Swagger (Help-pagina's van ASP.NET Core Web API met behulp van Swagger). Er wordt een Swagger-generator gebruikt voor de Swagger-gebruikersinterface en het Swagger JSON-eindpunt.

3. Zorg ervoor dat de standaardbranch is main.

   git branch -m main
   

   Tip

   De wijziging van de naam van de vertakking is niet vereist voor App Service. Aangezien veel opslagplaatsen echter hun standaardbranch wijzigen in (zie Implementatiebranchmain wijzigen), ziet u in deze zelfstudie ook hoe u een opslagplaats implementeert vanuitmain.

De toepassing uitvoeren

1. Voer de volgende opdrachten uit om de vereiste pakketten te installeren, databasemigraties uit te voeren en de toepassing te starten.

   dotnet restore
   dotnet run
   

2. Ga naar http://localhost:5000/swagger in een browser om kennis te maken met de Swagger-gebruikersinterface.

   

3. Ga naar http://localhost:5000/api/todo om een lijst met ToDo JSON-items te bekijken.

4. Ga naar http://localhost:5000 om met de browser-app kennis te maken. Later wijst u de browser-app naar een externe API in App Service om CORS functioneel te testen. Code voor de browser-app vindt u in de map wwwroot van de opslagplaats.

5. Druk op Ctrl+C in de terminal als u ASP.NET Core wilt stoppen.

Azure Cloud Shell

Azure host Azure Cloud Shell, een interactieve shell-omgeving die u via uw browser kunt gebruiken. U kunt Bash of PowerShell gebruiken met Cloud Shell om met Azure-services te werken. U kunt de vooraf geïnstalleerde Cloud Shell-opdrachten gebruiken om de code in dit artikel uit te voeren zonder dat u iets hoeft te installeren in uw lokale omgeving.

Om Azure Cloud Shell op te starten:

Optie	Voorbeeld/koppeling
Selecteer Uitproberen in de rechterbovenhoek van een code- of opdrachtblok. Als u Try It selecteert, wordt de code of opdracht niet automatisch gekopieerd naar Cloud Shell.
Ga naar https://shell.azure.com, of selecteer de knop Cloud Shell starten om Cloud Shell in uw browser te openen.
Klik op de knop Cloud Shell in het menu in de balk rechtsboven in de Azure-portal.

Azure Cloud Shell gebruiken:

1. Start Cloud Shell.

2. Selecteer de knop Kopiëren op een codeblok (of opdrachtblok) om de code of opdracht te kopiëren.

3. Plak de code of opdracht in de Cloud Shell-sessie door Ctrl+Shift+V in Windows en Linux te selecteren of door Cmd+Shift+V te selecteren in macOS.

4. Selecteer Enter om de code of opdracht uit te voeren.

App in Azure implementeren

In deze stap implementeert u uw .NET Core-toepassing in App Service.

Lokale Git-implementatie configureren

FTP en lokale Git kunnen worden geïmplementeerd in een Azure-web-app met behulp van een implementatiegebruikers. Zodra u deze implementatiegebruiker hebt gemaakt, kunt u deze voor al uw Azure-implementaties gebruiken. Uw gebruikersnaam en wachtwoord voor implementatie op accountniveau verschillen van de referenties voor uw Azure-abonnement.

Als u de implementatiegebruiker wilt configureren, voert u de opdracht az webapp deployment user set uit in Azure Cloud Shell. Vervang <de gebruikersnaam> en het wachtwoord> door de gebruikersnaam en <het wachtwoord van een implementatiegebruiker.

• De gebruikersnaam moet uniek zijn binnen Azure en voor lokale Git-pushes en mag het symbool @ niet bevatten.
• Het wachtwoord moet ten minste acht tekens lang zijn en minimaal twee van de volgende drie typen elementen bevatten: letters, cijfers en symbolen.

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

De JSON-uitvoer toont het wachtwoord als null. Als er een 'Conflict'. Details: 409-fout optreedt, wijzigt u de gebruikersnaam. Als er een 'Bad Request'. Details: 400-fout optreedt, kiest u een sterker wachtwoord.

Noteer uw gebruikersnaam en wachtwoord om te gebruiken bij het implementeren van uw web-apps.

Een brongroep maken

Een resourcegroep is een logische container waarin Azure-resources, zoals web-apps, databases en opslagaccounts, worden geïmplementeerd en beheerd. U kunt bijvoorbeeld later de hele resourcegroep in één stap verwijderen.

Maak een resourcegroep in Cloud Shell met de opdracht az group create. In het volgende voorbeeld wordt een resourcegroep met de naam myResourceGroup gemaakt op de locatie Europa - west. Als u alle ondersteunde locaties voor App Service in de Gratis laag wilt zien, voert u de opdracht az appservice list-locations --sku FREE uit.

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

In het algemeen maakt u een resourcegroep en resources in een regio bij u in de buurt.

Wanneer de opdracht is voltooid, laat een JSON-uitvoer u de eigenschappen van de resource-groep zien.

Een App Service-plan maken

Maak in Cloud Shell een App Service-plan met de opdracht az appservice plan create.

In het volgende voorbeeld wordt een App Service-plan gemaakt met de naam myAppServicePlan en de prijscategorie Gratis:

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

Wanneer het App Service-plan is gemaakt, toont de Azure CLI soortgelijke informatie als in het volgende voorbeeld:

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

Een webtoepassing maken

Een web-app maken in het App Service-plan myAppServicePlan.

In Cloud Shell kunt u de opdracht az webapp create gebruiken. Vervang in het volgende voorbeeld <app-name> door een unieke naam (geldige tekens zijn a-z, 0-9, en -).

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

Wanneer de web-app is gemaakt, toont de Azure CLI soortgelijke uitvoer als in het volgende voorbeeld:

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

Pushen naar Azure vanaf Git

1. Omdat u de main vertakking implementeert, moet u de standaardimplementatievertakking voor uw App Service-app main instellen (zie Implementatievertakking wijzigen). Stel in Cloud Shell de DEPLOYMENT_BRANCH app-instelling in met de az webapp config appsettings set opdracht.

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

2. Voeg, eenmaal terug in het lokale terminalvenster, een externe Azure-instantie toe aan uw lokale Git-opslagplaats. Vervang <deploymentLocalGitUrl-from-create-step> door de URL van de externe Git-app die u hebt opgeslagen vanuit Een web-app maken.

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

3. Push naar de externe Azure-instantie om uw app te implementeren met de volgende opdracht. Wanneer Git Credential Manager u om referenties vraagt, geeft u de referenties op die u hebt gemaakt in Een implementatiegebruiker configureren, en niet de referenties die u gebruikt om u aan te melden bij de Azure-portal.

   git push azure main
   

   Het kan enkele minuten duren voor deze opdracht is uitgevoerd. De opdracht geeft informatie weer die lijkt op het volgende voorbeeld:

   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
   

Naar de Azure-app bladeren

1. Ga naar http://<app_name>.azurewebsites.net/swagger in een browser om kennis te maken met de Swagger-gebruikersinterface.

   

2. Ga naar http://<app_name>.azurewebsites.net/swagger/v1/swagger.json om de swagger.json om uw geïmplementeerde API te zien.

3. Ga naar http://<app_name>.azurewebsites.net/api/todo om de geïmplementeerde API in werking te zien.

CORS-functionaliteit toevoegen

Schakel vervolgens de ingebouwde CORS-ondersteuning in App Service voor uw API in.

CORS in voorbeeld-app testen

1. Open wwwroot/index.html in uw lokale opslagplaats.

2. Stel in regel 51 de variabele apiEndpoint in op de URL van uw geïmplementeerde API (http://<app_name>.azurewebsites.net). Vervang <de app-naam> door uw app-naam in App Service.

3. Voor de voorbeeld-app opnieuw uit in het lokale terminalvenster.

   dotnet run
   

4. Ga naar de browser-app op http://localhost:5000. Open het venster Ontwikkelhulpprogramma's in uw browser (Ctrl+Shifti+in Chrome voor Windows) en inspecteer het tabblad Console. U ziet nu het foutbericht. No 'Access-Control-Allow-Origin' header is present on the requested resource

   

   Het domein komt niet overeen tussen de browser-app (http://localhost:5000) en de externe resource (http://<app_name>.azurewebsites.net) wordt door uw browser herkend als een aanvraag voor cross-origin-resources. Het feit dat uw REST API de App Service-app niet de Access-Control-Allow-Origin header verzendt, heeft de browser ook voorkomen dat inhoud tussen domeinen wordt geladen.

   In productie zou de browser-app een openbare URL hebben in plaats van de localhost-URL. De manier om CORS voor een localhost-URL in te schakelen, is echter dezelfde als voor een openbare URL.

CORS inschakelen

Schakel in Cloud Shell CORS in voor de URL van de client met de opdracht az webapp cors add. Vervang de tijdelijke aanduiding voor de app-naam>.<

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

U kunt meerdere toegestane origins toevoegen door de opdracht meerdere keren uit te voeren of door een door komma's gescheiden lijst toe te voegen in --allowed-origins. Als u alle oorsprongen wilt toestaan, gebruikt u --allowed-origins '*'.

CORS opnieuw testen

Vernieuw de browser-app op http://localhost:5000. Het foutbericht in het Console-venster is nu verdwenen. U kunt de gegevens van de geïmplementeerde API zien en ermee werken. De externe API biedt nu ondersteuning voor CORS voor uw browser-app, die lokaal wordt uitgevoerd.

Gefeliciteerd! U voert een API uit in Azure App Service met CORS-ondersteuning.

Veelgestelde vragen

• App Service CORS versus uw CORS
• Hoe kan ik toegestane origins instellen op een subdomein met jokertekens?
• Hoe kan ik de header ACCESS-CONTROL-ALLOW-CREDENTIALS inschakelen in het antwoord?

CORS voor App Service versus uw eigen CORS

U kunt uw eigen CORS-hulpprogramma's gebruiken in plaats van CORS voor App Service voor meer flexibiliteit. U kunt bijvoorbeeld verschillende toegestane oorsprongen opgeven voor verschillende routes of methoden. Omdat u met CORS voor App Service één set geaccepteerde oorsprongen voor alle API-routes en -methoden kunt opgeven, kunt u ook uw eigen CORS-code gebruiken. Zie hoe ASP.NET Core dit doet op Enabling Cross-Origin Requests (CORS) (CORS (Cross-Origin Requests) inschakelen).

De ingebouwde App Service CORS-functie heeft geen opties om alleen specifieke HTTP-methoden of werkwoorden toe te staan voor elke oorsprong die u opgeeft. Hiermee worden automatisch alle methoden en headers toegestaan voor elke gedefinieerde oorsprong. Dit gedrag is vergelijkbaar met ASP.NET Core CORS-beleid wanneer u de opties .AllowAnyHeader() en .AllowAnyMethod() in de code gebruikt.

Hoe kan ik toegestane origins instellen op een subdomein met jokertekens?

Een jokertekensubdomein is *.contoso.com meer beperkend dan de jokerteken-oorsprong *. Op de CORS-beheerpagina van de app in Azure Portal kunt u echter geen subdomein met jokertekens instellen als toegestane oorsprong. U kunt dit echter doen met behulp van de Azure CLI, zoals:

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

Hoe kan ik de header ACCESS-CONTROL-ALLOW-CREDENTIALS inschakelen in het antwoord?

Als er voor uw app referenties, zoals cookies of verificatietokens, moeten worden verzonden, is het mogelijk dat de browser de header ACCESS-CONTROL-ALLOW-CREDENTIALS van het antwoord vereist. Als u dit wilt inschakelen in App Service, stelt u in op properties.cors.supportCredentialstrue.

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

Deze bewerking is niet toegestaan wanneer toegestane origins de jokerteken-oorsprong '*'bevatten. AllowAnyOrigin Opgeven en AllowCredentials is een onveilige configuratie en kan leiden tot vervalsing van aanvragen op meerdere sites. Als u referenties wilt toestaan, vervangt u de oorsprong van jokertekens door subdomeinen met jokertekens.

Resources opschonen

In de voorgaande stappen hebt u Azure-resources in een resourcegroep gemaakt. Als u deze resources niet meer nodig denkt te hebben, verwijdert u de resourcegroep door de volgende opdracht in Cloud Shell uit te voeren:

az group delete --name myResourceGroup

Het kan een minuut duren voordat deze opdracht is uitgevoerd.

Volgende stappen

Wat u hebt geleerd:

Ga naar de volgende zelfstudie voor informatie over het verifiëren en autoriseren van gebruikers.