Dela via

Självstudie: Vara värd för en RESTful-API med CORS i Azure App Service

  • Artikel

Med Azure App Service får du en automatiskt uppdaterad webbvärdtjänst med hög skalbarhet. Dessutom har App Service ett inbyggt stöd för CORS (Cross-Origin Resource Sharing) för RESTful-API:er. Den här självstudien visar hur du distribuerar en ASP.NET Core API-app till App Service med CORS-stöd. Du konfigurerar appen med hjälp av kommandoradsverktyg och distribuerar appen med Git.

I den här självstudien lär du dig att:

  • Skapa App Service-resurser med Azure CLI
  • Distribuera en RESTful-API till Azure med Git
  • Aktivera stöd för CORS i App Service

Du kan följa stegen i den här självstudien i macOS, Linux och Windows.

Om du inte har en Azure-prenumeration skapar du ett kostnadsfritt Azure-konto innan du börjar.

Förutsättningar

För att slutföra den här kursen behöver du:

Skapa en lokal ASP.NET Core-app

I det här steget konfigurerar du det lokala ASP.NET Core-projektet. App Service stöder samma arbetsflöde för API:er som skrivits på andra datorspråk.

Klona exempelprogrammet

  1. Använd kommandot cd för att komma till en arbetskatalog i terminalfönstret.

  2. Klona exempellagringsplatsen och ändra till lagringsplatsens rot.

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

    Den här lagringsplatsen innehåller ett program som baseras på följande självstudie: Hjälpsidor för ASP.NET Cores webb-API med Swagger. En Swagger-generator används för att hantera Swagger-användargränssnittet och Swagger JSON-slutpunkten.

  3. Kontrollera att standardgrenen är main.

    git branch -m main

    Dricks

    Ändringen av grennamnet krävs inte av App Service. Men eftersom många lagringsplatser ändrar sin standardgren till main (se Ändra distributionsgren) visar den här självstudien också hur du distribuerar en lagringsplats från main.

Kör appen

  1. Kör följande kommandon för att installera de nödvändiga paketen, köra databasmigreringar och starta programmet.

    dotnet restore
dotnet run

  2. Gå till http://localhost:5000/swagger i en webbläsare för att testa användargränssnittet för Swagger.

    ASP.NET Core-API som körs lokalt

  3. Gå till http://localhost:5000/api/todo och se en lista med ToDo JSON-objekt.

  4. Gå till http://localhost:5000 och testa med webbläsarappen. Senare kommer du att peka med webbläsarappen på en fjärr-API i App Service för att testa CORS-funktionerna. Koden för webbläsarappen finns i lagringsplatsens katalog wwwroot.

  5. Du kan när som helst stoppa ASP.NET Core genom att trycka på Ctrl+C i terminalen.

Azure Cloud Shell

Azure är värd för Azure Cloud Shell, en interaktiv gränssnittsmiljö som du kan använda via webbläsaren. Du kan använda antingen Bash eller PowerShell med Cloud Shell för att arbeta med Azure-tjänster. Du kan använda förinstallerade Cloud Shell-kommandon för att köra koden i den här artikeln, utan att behöva installera något i din lokala miljö.

Så här startar du Azure Cloud Shell:

Alternativ Exempel/länk
Välj Prova i det övre högra hörnet i en kod eller ett kommandoblock. Om du väljer Prova kopieras inte koden eller kommandot automatiskt till Cloud Shell. Skärmbild som visar ett exempel på Try It for Azure Cloud Shell.
Gå till https://shell.azure.com eller Välj knappen Starta Cloud Shell för att öppna Cloud Shell i webbläsaren. Knapp för att starta Azure Cloud Shell.
Välj knappen Cloud Shell på menyn längst upp till höger i Azure-portalen. Skärmbild som visar Cloud Shell-knappen i Azure-portalen

Så här använder du Azure Cloud Shell:

  1. Starta Cloud Shell.

  2. Välj knappen Kopiera i ett kodblock (eller kommandoblock) för att kopiera koden eller kommandot.

  3. Klistra in koden eller kommandot i Cloud Shell-sessionen genom att välja Ctrl+Skift+V i Windows och Linux, eller genom att välja Cmd+Shift+V på macOS.

  4. Välj Retur för att köra koden eller kommandot.

Distribuera appen till Azure

I det här steget distribuerar du .NET Core-programmet till App Service.

Konfigurera lokal git-distribution

FTP och lokal Git kan distribueras till en Azure-webbapp med hjälp av en distributionsanvändare. När du har konfigurerat distributionsanvändaren kan du använda den för alla dina Azure-distributioner. Ditt användarnamn och lösenord för distribution på kontonivå skiljer sig från dina autentiseringsuppgifter för Azure-prenumerationen.

Om du vill konfigurera distributionsanvändaren kör du kommandot az webapp deployment user set i Azure Cloud Shell. Ersätt <användarnamn> och <lösenord> med ett användarnamn och lösenord för distributionsanvändaren.

  • Användarnamnet måste vara unikt i Azure, och för lokala Git-push-meddelanden får det inte innehålla @-symbolen.
  • Lösenordet måste vara minst åtta tecken långt, med två av följande tre element: bokstäver, siffror och symboler.
az webapp deployment user set --user-name <username> --password <password>

JSON-utdata visar lösenordet som null. Om du ser felet 'Conflict'. Details: 409 ska du byta användarnamn. Om du ser felet 'Bad Request'. Details: 400 ska du använda ett starkare lösenord.

Registrera ditt användarnamn och lösenord som ska användas för att distribuera dina webbappar.

Skapa en resursgrupp

En resursgrupp är en logisk container där Azure-resurser, till exempel webbappar, databaser och lagringskonton, distribueras och hanteras. Du kan exempelvis välja att ta bort hela resursgruppen i ett enkelt steg längre fram.

Skapa i Cloud Shell en resursgrupp med kommandot az group create. I följande exempel skapas en resursgrupp med namnet myResourceGroup på platsen Europa, västra. Om du vill se alla platser som stöds för App Service på Kostnadsfri nivå, kör du kommandot az appservice list-locations --sku FREE.

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

Du skapar vanligtvis din resursgrupp och resurserna i en region nära dig.

När kommandot har slutförts visar JSON-utdata resursgruppens egenskaper.

Skapa en App Service-plan

Skapa i Cloud Shell en App Service-plan med kommandot az appservice plan create.

I följande exempel skapas en App Service-plan med namnet myAppServicePlan på prisnivån Kostnadsfri:

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

När App Service-planen har skapats visas information av Azure CLI. Informationen ser ut ungefär som i följande exempel:

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

Skapa en webbapp

Skapa en webbapp i myAppServicePlan App Service-planen.

I Cloud Shell kan du använda kommandot az webapp create. Ersätt <app-name> med ett globalt unikt appnamn (giltiga tecken är a-z, 0-9 och -) i följande exempel.

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

När webbappen har skapats visar Azure CLI utdata liknande den i följande exempel:

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

Kommentar

URL för fjärransluten Git visas i egenskapen deploymentLocalGitUrl med formatet https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Spara den här URL:en, eftersom du behöver den senare.

Skicka till Azure från Git

  1. Eftersom du distribuerar grenen main måste du ange standarddistributionsgrenen för App Service-appen till main (se Ändra distributionsgren). I Cloud Shell anger du appinställningen DEPLOYMENT_BRANCH az webapp config appsettings set med kommandot .

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

  2. I det lokala terminalfönstret kan du lägga till en Azure-fjärrdatabas till din lokala Git-databas. Ersätt <deploymentLocalGitUrl-from-create-step> med URL:en för git-fjärren som du sparade från Skapa en webbapp.

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

  3. Skicka till Azure-fjärrdatabasen för att distribuera appen med följande kommando. När Git Credential Manager frågar efter autentiseringsuppgifter kontrollerar du att du anger de autentiseringsuppgifter som du skapade i Konfigurera en distributionsanvändare, inte de autentiseringsuppgifter som du använder för att logga in på Azure-portalen.

    git push azure main

    Det kan ett par minuter att köra kommandot. Medan det körs visas information liknande den i följande exempel:

   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

Bläddra till Azure-appen

  1. Gå till http://<app_name>.azurewebsites.net/swagger i en webbläsare och testa användargränssnittet för Swagger.

    ASP.NET Core-API som körs i Azure App Service

  2. Gå till http://<app_name>.azurewebsites.net/swagger/v1/swagger.json för att se swagger.json för din distribuerade API.

  3. Gå till http://<app_name>.azurewebsites.net/api/todo för att se om din distribuerade API fungerar.

Lägga till CORS-funktioner

Därefter aktiverar du det inbyggda CORS-stödet i App Service för din API.

Testa CORS i exempelappen

  1. Öppna wwwroot/index.html på din lokala lagringsplats.

  2. På rad 51 anger du apiEndpoint-variabeln till URL:en för din distribuerade API (http://<app_name>.azurewebsites.net). Ersätt <appnamn> med ditt appnamn i App Service.

  3. Kör exempelappen igen i ditt lokala terminalfönster.

    dotnet run

  4. Gå till webbläsarappen på http://localhost:5000. Öppna fönstret utvecklarverktyg i webbläsaren (Ctrl+Shifti+i Chrome för Windows) och granska fliken Konsol. Nu bör du se felmeddelandet . No 'Access-Control-Allow-Origin' header is present on the requested resource

    CORS-fel i webbläsarklienten

    Domänens matchningsfel mellan webbläsarappen (http://localhost:5000) och fjärrresursen (http://<app_name>.azurewebsites.net) identifieras av webbläsaren som en resursbegäran mellan ursprung. Dessutom har det faktum att rest-API:et appappen Access-Control-Allow-Origin inte skickar huvudet förhindrat att innehåll mellan domäner läses in.

    Webbläsarappen bör ha en offentlig URL i stället för en localhost-URL i produktionsmiljö, men sättet att aktivera CORS till en localhost-URL är detsamma som en offentlig URL.

Aktivera CORS

I Cloud Shell aktiverar du CORS till din klient-URL med kommandot az webapp cors add. <Ersätt platshållaren för appnamn>.

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

Du kan lägga till flera tillåtna ursprung genom att köra kommandot flera gånger eller genom att lägga till en kommaavgränsad lista i --allowed-origins. Om du vill tillåta alla ursprung använder du --allowed-origins '*'.

Testa CORS igen

Uppdatera webbläsarappen i http://localhost:5000. Felmeddelandet i fönstret Konsol är nu borta och du kan se data från den distribuerade API:n samt interagera med den. Fjärr-API:n har nu stöd för CORS i webbläsarappen som körs lokalt.

CORS finns nu i webbläsarklienten

Grattis! Du kör en API i Azure App Service med CORS-stöd.

Vanliga frågor och svar

App Services CORS jämfört med din CORS

Du kan använda dina egna CORS-verktyg i stället för App Services CORS om du vill ha mer flexibilitet. Du kanske vill ange olika tillåtna ursprung för olika vägar eller metoder. Eftersom du med App Services CORS kan ange en uppsättning godkända ursprung för alla API-vägar och metoder, kan du använda din egna CORS-kod. Se hur ASP.NET Core gör detta i Aktivera CORS (Cross-Origin Requests).

Den inbyggda CORS-funktionen för App Service har inte alternativ för att endast tillåta specifika HTTP-metoder eller verb för varje ursprung som du anger. Det tillåter automatiskt alla metoder och rubriker för varje definierat ursprung. Det här beteendet liknar ASP.NET Core CORS-principer när du använder alternativen .AllowAnyHeader() och .AllowAnyMethod() i koden.

Kommentar

Försök inte att använda App Services CORS och din egen CORS-kod tillsammans. När de används tillsammans har App Services CORS företräde och din egen CORS-kod fyller ingen funktion.

Hur anger jag tillåtet ursprung till en underdomän med jokertecken?

En jokerteckenunderdomän som *.contoso.com är mer restriktiv än jokertecknets ursprung *. Men appens CORS-hanteringssida i Azure-portalen låter dig inte ange en underdomän för jokertecken som ett tillåtet ursprung. Du kan dock göra det med Hjälp av Azure CLI, så här:

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

Hur aktiverar jag huvudet ACCESS-CONTROL-ALLOW-CREDENTIALS i svaret?

Om din app kräver att autentiseringsuppgifter såsom cookies eller autentiseringstoken skickas kan webbläsaren kräva huvudet ACCESS-CONTROL-ALLOW-CREDENTIALS i svaret. Om du vill aktivera detta i App Service anger du properties.cors.supportCredentials till 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

Den här åtgärden tillåts inte när tillåtna ursprung innehåller jokertecknets ursprung '*'. Att AllowAnyOrigin ange och AllowCredentials är en osäker konfiguration och kan resultera i förfalskning av begäranden mellan platser. Om du vill tillåta autentiseringsuppgifter kan du prova att ersätta jokertecknets ursprung med jokerteckenunderdomäner.

Rensa resurser

I de föregående stegen skapade du Azure-resurser i en resursgrupp. Om du inte tror att du behöver dessa resurser i framtiden tar du bort resursgruppen genom att köra följande kommando i Cloud Shell:

az group delete --name myResourceGroup

Det kan några minuter att köra kommandot.

Nästa steg

Vad du lärt dig:

  • Skapa App Service-resurser med Azure CLI
  • Distribuera en RESTful-API till Azure med Git
  • Aktivera stöd för CORS i App Service

Gå vidare till nästa självstudie för att lära dig att autentisera och auktorisera användare.

Självstudie: Autentisera och auktorisera användare från slutpunkt till slutpunkt