Samouczek: hostowanie interfejsu API RESTful z mechanizmem CORS w usłudze Azure App Service

Usługa Azure App Service oferuje wysoce skalowalną i samonaprawialną usługę hostingu w Internecie. Usługa App Service ma dodatkowo wbudowaną obsługę mechanizmu współużytkowania zasobów między źródłami (CORS, Cross-Origin Resource Sharing) dla interfejsów API RESTful. Ten samouczek pokazuje, w jaki sposób wdrożyć aplikację interfejsu API platformy ASP.NET Core w usłudze App Service z obsługą mechanizmu CORS. Aplikacja zostanie skonfigurowana przy użyciu narzędzi wiersza polecenia i wdrożona za pomocą narzędzia Git.

Z tego samouczka dowiesz się, jak wykonywać następujące czynności:

  • Tworzenie zasobów usługi App Service przy użyciu interfejsu wiersza polecenia platformy Azure
  • Wdrażanie interfejsu API RESTful na platformie Azure za pomocą narzędzia Git
  • Włączanie obsługi mechanizmu CORS w usłudze App Service

Kroki opisane w tym samouczku można wykonać w systemie macOS, Linux i Windows.

Jeśli nie masz subskrypcji platformy Azure, przed rozpoczęciem utwórz bezpłatne konto platformy Azure.

Wymagania wstępne

W celu ukończenia tego samouczka:

Tworzenie lokalnej aplikacji ASP.NET Core

Ten krok umożliwia skonfigurowanie lokalnego projektu platformy ASP.NET Core. Usługa App Service obsługuje ten sam przepływ pracy w przypadku interfejsów API napisanych w innych językach.

Klonowanie przykładowej aplikacji

  1. W oknie terminalu dodaj element cd do katalogu roboczego.

  2. Sklonuj przykładowe repozytorium i przejdź do katalogu głównego repozytorium.

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

    To repozytorium zawiera aplikację utworzoną na podstawie następującego samouczka: ASP.NET Core Web API help pages using Swagger (Strony pomocy internetowego interfejsu API platformy ASP.NET Core korzystające ze struktury Swagger). Używa ona generatora struktury Swagger, aby obsłużyć interfejs użytkownika struktury Swagger oraz punkt końcowy JSON struktury Swagger.

  3. Upewnij się, że gałąź domyślna to main.

    git branch -m main
    

    Napiwek

    Zmiana nazwy gałęzi nie jest wymagana przez usługę App Service. Jednak ponieważ wiele repozytoriów zmienia domyślną gałąź na main (zobacz Zmienianie gałęzi wdrażania), w tym samouczku pokazano również, jak wdrożyć repozytorium z witryny main.

Uruchamianie aplikacji

  1. Uruchom następujące polecenia, aby zainstalować wymagane pakiety, uruchom migracje baz danych i uruchom aplikację.

    dotnet restore
    dotnet run
    
  2. Przejdź do adresu http://localhost:5000/swagger w przeglądarce, aby przetestować interfejs użytkownika struktury Swagger.

    ASP.NET Core API running locally

  3. Przejdź do adresu http://localhost:5000/api/todo, aby wyświetlić listę zadań w formacie JSON.

  4. Przejdź do adresu http://localhost:5000, aby przetestować aplikację przeglądarki. Później wskażesz aplikacji przeglądarki zdalny interfejs API w usłudze App Service, aby przetestować działanie mechanizmu CORS. Kod aplikacji przeglądarki znajduje się w katalogu wwwroot repozytorium.

  5. Aby zatrzymać platformę ASP.NET Core w dowolnym momencie, naciśnij kombinację klawiszy Ctrl+C w terminalu.

Azure Cloud Shell

Na platforma Azure hostowane jest Azure Cloud Shell, interaktywne środowisko powłoki, z którego można korzystać w przeglądarce. Do pracy z usługami platformy Azure można używać programu Bash lub PowerShell w środowisku Cloud Shell. Aby uruchomić kod w tym artykule, możesz użyć wstępnie zainstalowanych poleceń usługi Cloud Shell bez konieczności instalowania niczego w środowisku lokalnym.

Aby uruchomić środowisko Azure Cloud Shell:

Opcja Przykład/link
Wybierz pozycję Wypróbuj w prawym górnym rogu bloku kodu lub polecenia. Wybranie pozycji Wypróbuj nie powoduje automatycznego skopiowania kodu lub polecenia do usługi Cloud Shell. Screenshot that shows an example of Try It for Azure Cloud Shell.
Przejdź do witryny https://shell.azure.com lub wybierz przycisk Uruchom Cloud Shell, aby otworzyć środowisko Cloud Shell w przeglądarce. Button to launch Azure Cloud Shell.
Wybierz przycisk Cloud Shell na pasku menu w prawym górnym rogu witryny Azure Portal. Screenshot that shows the Cloud Shell button in the Azure portal

Aby użyć usługi Azure Cloud Shell:

  1. Uruchom usługę Cloud Shell.

  2. Wybierz przycisk Kopiuj w bloku kodu (lub bloku poleceń), aby skopiować kod lub polecenie.

  3. Wklej kod lub polecenie do sesji usługi Cloud Shell, wybierając klawisze Ctrl+Shift V w systemach Windows i Linux lub wybierając pozycję Cmd+Shift++V w systemie macOS.

  4. Wybierz klawisz Enter, aby uruchomić kod lub polecenie.

Wdrażanie aplikacji na platformie Azure

W tym kroku wdrożysz aplikację .NET Core w usłudze App Service.

Konfigurowanie lokalnego wdrożenia narzędzia Git

Protokół FTP i lokalna usługa Git może zostać wdrożona w aplikacji internetowej platformy Azure przy użyciu użytkownika wdrożenia. Po skonfigurowaniu użytkownika wdrożenia możesz go użyć dla wszystkich wdrożeń platformy Azure. Nazwa użytkownika i hasło wdrożenia na poziomie konta różnią się od poświadczeń subskrypcji platformy Azure.

Aby skonfigurować użytkownika wdrożenia, uruchom polecenie az webapp deployment user set w usłudze Azure Cloud Shell. Zastąp <nazwę użytkownika> i <hasło> użytkownika wdrożenia nazwą użytkownika i hasłem.

  • Nazwa użytkownika musi być unikatowa na platformie Azure, a w przypadku lokalnych wypychania Git nie może zawierać symbolu "@".
  • Hasło musi mieć długość co najmniej ośmiu znaków, z dwoma z następujących trzech elementów: literami, cyframi i symbolami.
az webapp deployment user set --user-name <username> --password <password>

Dane wyjściowe JSON zawierają hasło jako null. Jeśli wystąpił błąd 'Conflict'. Details: 409, zmień nazwę użytkownika. Jeśli wystąpił błąd 'Bad Request'. Details: 400, użyj silniejszego hasła.

Zarejestruj swoją nazwę użytkownika i hasło do użycia w celu wdrożenia aplikacji internetowych.

Tworzenie grupy zasobów

Grupa zasobów to logiczny kontener, w którym są wdrażane i zarządzane zasoby platformy Azure, takie jak aplikacje internetowe, bazy danych i konta magazynu. Na przykład można później usunąć całą grupę zasobów w jednym prostym kroku.

W usłudze Cloud Shell utwórz grupę zasobów za pomocą polecenia az group create. Poniższy przykład obejmuje tworzenie grupy zasobów o nazwie myResourceGroup w lokalizacji West Europe (Europa Zachodnia). Aby wyświetlić wszystkie obsługiwane lokalizacje dla usługi App Service w warstwie Bezpłatna, uruchom polecenie az appservice list-locations --sku FREE.

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

Zasadniczo grupy zasobów i zasoby są tworzone w pobliskim regionie.

Po zakończeniu działania polecenia zostaną wyświetlone dane wyjściowe JSON z właściwościami grupy zasobów.

Tworzenie planu usługi App Service

W usłudze Cloud Shell utwórz plan usługi App Service za pomocą polecenia az appservice plan create.

W poniższym przykładzie jest tworzony plan usługi App Service o nazwie myAppServicePlan przy użyciu warstwy cenowej Bezpłatna:

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

Po utworzeniu planu usługi App Service interfejs wiersza polecenia platformy Azure wyświetli informacje podobne do następujących:

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

Tworzenie aplikacji internetowej

Utwórz aplikację internetową w planie usługi App Service myAppServicePlan.

W usłudze Cloud Shell można użyć polecenia az webapp create. W poniższym przykładzie zastąp ciąg <app-name> globalnie unikatową nazwą aplikacji (prawidłowe znaki to a-z, 0-9 i -).

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

Po utworzeniu aplikacji internetowej w interfejsie wiersza polecenia platformy Azure zostaną wyświetlone dane wyjściowe podobne do następujących:

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

Uwaga

Adres URL zdalnego repozytorium Git jest wyświetlany we właściwości deploymentLocalGitUrl w formacie https://<username>@<app-name>.scm.azurewebsites.net/<app-name>.git. Zapisz ten adres URL, ponieważ będzie on potrzebny później.

Wypychanie z narzędzia Git na platformę Azure

  1. Ponieważ wdrażasz main gałąź, musisz ustawić domyślną gałąź wdrożenia dla aplikacji usługi App Service na main wartość (zobacz Zmienianie gałęzi wdrażania). W usłudze Cloud Shell ustaw DEPLOYMENT_BRANCH ustawienie aplikacji za az webapp config appsettings set pomocą polecenia .

    az webapp config appsettings set --name <app-name> --resource-group myResourceGroup --settings DEPLOYMENT_BRANCH='main'
    
  2. W lokalnym oknie terminala dodaj zdalną platformę Azure do lokalnego repozytorium Git. Zastąp ciąg <deploymentLocalGitUrl-from-create-step> adresem URL zdalnego repozytorium Git zapisanego z sekcji Tworzenie aplikacji internetowej.

    git remote add azure <deploymentLocalGitUrl-from-create-step>
    
  3. Wypchnij na zdalną platformę Azure w celu wdrożenia aplikacji za pomocą następującego polecenia. Gdy menedżer poświadczeń usługi Git wyświetli monit o podanie poświadczeń, upewnij się, że wprowadzono poświadczenia utworzone w sekcji Konfigurowanie użytkownika wdrożenia, a nie poświadczenia używane do logowania się w witrynie Azure Portal.

    git push azure main
    

    Wykonanie tego polecenia może potrwać kilka minut. Podczas wykonywania polecenie wyświetli informacje podobne do następującego przykładu:

   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
   

Przechodzenie do aplikacji platformy Azure

  1. Przejdź do adresu http://<app_name>.azurewebsites.net/swagger w przeglądarce, aby przetestować interfejs użytkownika struktury Swagger.

    ASP.NET Core API running in Azure App Service

  2. Przejdź do adresu http://<app_name>.azurewebsites.net/swagger/v1/swagger.json, aby wyświetlić plik swagger.json wdrożonego interfejsu API.

  3. Przejdź do adresu http://<app_name>.azurewebsites.net/api/todo, aby wyświetlić działający wdrożony interfejs API.

Dodawanie funkcji obsługi mechanizmu CORS

Następnie włącz wbudowaną obsługę mechanizmu CORS w usłudze App Service dla interfejsu API.

Testowanie mechanizmu CORS w aplikacji przykładowej

  1. W lokalnym repozytorium otwórz plik wwwroot/index.html.

  2. W wierszu 51 ustaw zmienną apiEndpoint na adres URL wdrożonego interfejsu API (http://<app_name>.azurewebsites.net). Zastąp <ciąg appname> nazwą swojej aplikacji w usłudze App Service.

  3. W lokalnym oknie terminala ponownie uruchom aplikację przykładową.

    dotnet run
    
  4. Przejdź do aplikacji przeglądarki pod adresem http://localhost:5000. Otwórz okno narzędzi deweloperskich w przeglądarce (Ctrl+Shifti+ w przeglądarce Chrome dla systemu Windows) i sprawdź kartę Konsola. Powinien zostać wyświetlony komunikat No 'Access-Control-Allow-Origin' header is present on the requested resourceo błędzie.

    CORS error in browser client

    Niezgodność domeny między aplikacją przeglądarki (http://localhost:5000) i zasobem zdalnym (http://<app_name>.azurewebsites.net) jest rozpoznawana przez przeglądarkę jako żądanie zasobu między źródłami. Ponadto fakt, że interfejs API REST aplikacji usługi App Service nie wysyła nagłówka Access-Control-Allow-Origin , przeglądarka uniemożliwiła ładowanie zawartości między domenami.

    W środowisku produkcyjnym aplikacja przeglądarki miałaby publiczny adres URL zamiast adresu URL hosta lokalnego, ale sposób włączania mechanizmu CORS dla adresu URL hosta lokalnego jest taki sam, jak dla publicznego adresu URL.

Włączanie mechanizmu CORS

W usłudze Cloud Shell włącz mechanizm CORS dla adresu URL klienta przy użyciu polecenia az webapp cors add. Zastąp <symbol zastępczy nazwy> aplikacji.

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

Możesz dodać wiele dozwolonych źródeł, uruchamiając polecenie wiele razy lub dodając listę rozdzielaną przecinkami w pliku --allowed-origins. Aby zezwolić na wszystkie źródła, użyj polecenia --allowed-origins '*'.

Ponowne testowanie mechanizmu CORS

Odśwież aplikację przeglądarki pod adresem http://localhost:5000. Komunikat o błędzie w oknie Konsola zniknął i możesz wyświetlić dane z wdrożonego interfejsu API oraz z nich korzystać. Zdalny interfejs API obsługuje teraz mechanizm CORS w aplikacji przeglądarki uruchomionej lokalnie.

CORS success in browser client

Gratulacje. Używasz interfejsu API w usłudze Azure App Service z obsługą mechanizmu CORS.

Często zadawane pytania

Porównanie mechanizmu CORS usługi App Service z własnym mechanizmem CORS

W celu uzyskania większej elastyczności możesz korzystać z narzędzi własnego mechanizmu CORS zamiast mechanizmu CORS usługi App Service. Możesz na przykład potrzebować określenia różnych dozwolonych źródeł dla różnych tras lub metod. Ponieważ mechanizm CORS usługi App Service umożliwia określenie jednego zestawu zaakceptowanych źródeł dla wszystkich tras i metod interfejsu API, lepsze może okazać się użycie własnego kodu mechanizmu CORS. Zobacz, jak to działa na platformie ASP.NET Core, w temacie Enabling Cross-Origin Requests (CORS) (Włączanie żądań między źródłami [CORS]).

Wbudowana funkcja CORS usługi App Service nie ma opcji zezwalania tylko na określone metody HTTP lub czasowniki dla każdego określonego źródła. Spowoduje to automatyczne zezwolenie na wszystkie metody i nagłówki dla każdego zdefiniowanego źródła. To zachowanie jest podobne do ASP.NET podstawowych zasad CORS podczas korzystania z opcji .AllowAnyHeader() i .AllowAnyMethod() w kodzie.

Uwaga

Nie próbuj używać jednocześnie mechanizmu CORS usługi App Service i własnego kodu mechanizmu CORS. W takim przypadku mechanizm CORS usługi App Service ma pierwszeństwo, a Twój kod mechanizmu CORS jest nieskuteczny.

Jak mogę ustawić dozwolone źródła do poddomeny z symbolami wieloznacznymi?

Poddomena *.contoso.com z symbolami wieloznacznymi jest bardziej restrykcyjna niż źródło *symboli wieloznacznych. Jednak strona zarządzania mechanizmem CORS aplikacji w witrynie Azure Portal nie pozwala ustawić poddomeny z symbolami wieloznacznymi jako dozwolonego źródła. Można to jednak zrobić przy użyciu interfejsu wiersza polecenia platformy Azure, w następujący sposób:

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

Jak mogę włączyć nagłówek ACCESS-CONTROL-ALLOW-CREDENTIALS w odpowiedzi?

Jeśli Twoja aplikacja wymaga wysyłania poświadczeń, takich jak pliki cookie lub tokeny uwierzytelniania, przeglądarka może wymagać nagłówka ACCESS-CONTROL-ALLOW-CREDENTIALS w odpowiedzi. Aby włączyć tę funkcję w usłudze App Service, ustaw wartość 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

Ta operacja nie jest dozwolona, gdy dozwolone źródła zawierają źródło '*'symboli wieloznacznych . Określanie AllowAnyOrigin i AllowCredentials jest niezabezpieczoną konfiguracją i może spowodować fałszerzowanie żądań między witrynami. Aby zezwolić na poświadczenia, spróbuj zastąpić źródło symboli wieloznacznych poddomenami wieloznacznymi.

Czyszczenie zasobów

W poprzednich krokach utworzono zasoby platformy Azure w grupie zasobów. Jeśli te zasoby nie będą raczej potrzebne w przyszłości, usuń grupę zasobów, uruchamiając następujące polecenie w usłudze Cloud Shell:

az group delete --name myResourceGroup

Wykonanie tego polecenia może potrwać około minutę.

Następne kroki

Które czynności umiesz wykonać:

  • Tworzenie zasobów usługi App Service przy użyciu interfejsu wiersza polecenia platformy Azure
  • Wdrażanie interfejsu API RESTful na platformie Azure za pomocą narzędzia Git
  • Włączanie obsługi mechanizmu CORS w usłudze App Service

Przejdź do następnego samouczka, aby dowiedzieć się, jak uwierzytelniać i autoryzować użytkowników.