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:

  • App Service-resources maken met Azure CLI
  • Een RESTful API implementeren in Azure met behulp van Git
  • CORS-ondersteuning van App Service implementeren

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

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

Vereisten

Vereisten voor het voltooien van deze zelfstudie:

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 wijzig in 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 standaard branch main is.

    git branch -m main
    

    Tip

    De naamswijziging van de vertakking is niet vereist door App Service. Omdat veel opslagplaatsen hun standaardvertakking wijzigen in (zie Implementatievertakking wijzigen), laat deze zelfstudie u echter ook zien hoe u een main opslagplaats implementeert vanuit main .

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.

    ASP.NET Core-API lokaal uitvoeren

  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 gebruiken

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 opdrachten van Cloud Shell 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 Nu proberen in de rechterbovenhoek van een codeblok. Als u Uitproberen selecteert, wordt de code niet automatisch gekopieerd naar Cloud Shell. Voorbeeld van Uitproberen voor Azure Cloud Shell
Ga naar https://shell.azure.com, of selecteer de knop Cloud Shell starten om Cloud Shell in uw browser te openen. Cloud Shell starten in een nieuw venster
Klik op de knop Cloud Shell in het menu in de balk rechtsboven in de Azure-portal. Knop Cloud Shell in de Azure Portal

Om de code in dit artikel in Azure Cloud Shell uit te voeren:

  1. Start Cloud Shell.

  2. Selecteer de knop Kopiëren op een codeblok om de code te kopiëren.

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

  4. Selecteer Invoeren om de code uit te voeren.

App in Azure implementeren

In deze stap implementeert u de met SQL Database verbonden .NET Core-app met 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 <username> en <password> door de gebruikersnaam en het wachtwoord van de gebruiker van de implementatie.

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

Notitie

De URL van de externe Git wordt weergegeven in de eigenschap deploymentLocalGitUrl, met de indeling https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Sla deze URL op, want u hebt deze later nodig.

Pushen naar Azure vanaf Git

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

    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-instantie die u hebt opgeslagen bij 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.

    ASP.NET Core-API uitvoeren in Azure App Service

  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 <appname> door de naam van de app 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 van de hulpprogramma's voor ontwikkelaars in uw browser (Ctrl+Shift+i in Chrome voor Windows) en controleer het tabblad Console. U ziet nu het foutbericht, No 'Access-Control-Allow-Origin' header is present on the requested resource.

    CORS-fout in de browserclient

    Vanwege een verschil tussen de domeinen van de browser-app (http://localhost:5000) en de externe resource (http://<app_name>.azurewebsites.net), en het feit dat de API in App Service de kop Access-Control-Allow-Origin niet verzendt, is voorkomen dat inhoud uit beide domeinen in de browser-app is 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 <app-naam> .

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

U kunt in properties.cors.allowedOrigins ("['URL1','URL2',...]") meer dan één client-URL instellen. Met "['*']" kunt u ook alle client-URL's instellen.

Notitie

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 properties.cors.supportCredentials in uw CORS-configuratie in op true. Dit kan niet worden ingeschakeld als allowedOrigins``'*' bevat.

Notitie

Opgeven en AllowAnyOrigin is een onveilige configuratie en kan leiden tot aanvraagvervalsing AllowCredentials op verschillende plaatsen. De CORS-service retourneert een ongeldig CORS-antwoord wanneer een app met beide methoden is geconfigureerd.

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.

CORS in de browserclient

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

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

Notitie

Gebruik CORS voor App Service en uw eigen CORS niet samen. Als u dat doet, heeft CORS van App Service voorrang en heeft uw eigen CORS-code geen effect.

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:

  • App Service-resources maken met Azure CLI
  • Een RESTful API implementeren in Azure met behulp van Git
  • CORS-ondersteuning van App Service implementeren

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