Szybki start: wdrażanie aplikacji interfejsu API RESTful w usłudze Azure Spring Apps

Note

Plany Podstawowy, Standardowy i Enterprise weszły w okres wycofania z dniem 17 marca 2025 r. Aby uzyskać więcej informacji, zobacz ogłoszenie o wycofaniu usługi Azure Spring Apps.

W tym artykule opisano sposób wdrażania aplikacji interfejsu API RESTful chronionej przez identyfikator Entra firmy Microsoft w usłudze Azure Spring Apps. Przykładowy projekt jest uproszczoną wersją opartą na aplikacji internetowej Simple Todo , która udostępnia tylko usługę zaplecza i używa identyfikatora Entra firmy Microsoft do ochrony interfejsów API RESTful.

Te interfejsy API RESTful są chronione przez zastosowanie kontroli dostępu opartej na rolach (RBAC). Użytkownicy anonimowi nie mogą uzyskiwać dostępu do żadnych danych i nie mogą kontrolować dostępu dla różnych użytkowników. Użytkownicy anonimowi mają tylko następujące trzy uprawnienia:

• Przeczytaj: Z tym uprawnieniem użytkownik może odczytywać dane zadań do wykonania.
• Napisz: za pomocą tego uprawnienia użytkownik może dodawać lub aktualizować dane zadań do wykonania.
• Usuń: za pomocą tego uprawnienia użytkownik może usunąć dane zadań do wykonania.

Po pomyślnym wdrożeniu można przeglądać i testować interfejsy API za pomocą Swagger UI.

Na poniższym diagramie przedstawiono architekturę systemu:

W tym artykule opisano następujące opcje tworzenia zasobów i wdrażania ich w usłudze Azure Spring Apps:

• Opcja wtyczki Azure Portal + Maven zapewnia bardziej konwencjonalny sposób tworzenia zasobów i wdrażania aplikacji krok po kroku. Ta opcja jest odpowiednia dla deweloperów platformy Spring korzystających z usług w chmurze platformy Azure po raz pierwszy.
• Opcja interfejsu wiersza polecenia platformy Azure używa zaawansowanego narzędzia wiersza polecenia do zarządzania zasobami platformy Azure. Ta opcja jest odpowiednia dla deweloperów platformy Spring, którzy znają usługi w chmurze platformy Azure.

1. Wymagania wstępne

Witryna Azure Portal i wtyczka Maven

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

• Jedna z następujących ról:

  • Administrator globalny lub administrator ról uprzywilejowanych w celu udzielenia zgody dla aplikacji żądających jakichkolwiek uprawnień dla dowolnego interfejsu API.
  • Administrator aplikacji w chmurze lub administrator aplikacji jest odpowiedzialny za udzielanie zgody aplikacjom, które żądają jakichkolwiek uprawnień dla dowolnego interfejsu API, z wyjątkiem ról aplikacji w Microsoft Graph (uprawnienia aplikacji).
  • Niestandardowa rola katalogu obejmująca uprawnienia do udzielania uprawnień aplikacjom, dla uprawnień wymaganych przez aplikację.

  Aby uzyskać więcej informacji, zobacz Udzielanie zgody administratora dla całej dzierżawy na aplikację.

• Git.

• Java Development Kit (JDK), wersja 17.

• Klient Microsoft Entra. Aby uzyskać instrukcje dotyczące tworzenia dzierżawy, zobacz Szybki start: Tworzenie nowej dzierżawy w usłudze Microsoft Entra ID.

"Azure CLI"

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

• Jedna z następujących ról:

  • Administrator globalny lub administrator ról uprzywilejowanych w celu udzielenia zgody dla aplikacji żądających jakichkolwiek uprawnień dla dowolnego interfejsu API.
  • Administrator aplikacji w chmurze lub administrator aplikacji jest odpowiedzialny za udzielanie zgody aplikacjom, które żądają jakichkolwiek uprawnień dla dowolnego interfejsu API, z wyjątkiem ról aplikacji w Microsoft Graph (uprawnienia aplikacji).
  • Niestandardowa rola katalogu obejmująca uprawnienia do udzielania uprawnień aplikacjom, dla uprawnień wymaganych przez aplikację.

  Aby uzyskać więcej informacji, zobacz Udzielanie zgody administratora dla całej dzierżawy na aplikację.

• Git.

• Java Development Kit (JDK), wersja 17.

• Klient Microsoft Entra. Aby uzyskać instrukcje dotyczące tworzenia dzierżawy, zobacz Szybki start: Tworzenie nowej dzierżawy w usłudze Microsoft Entra ID.

• Interfejs wiersza polecenia platformy Azure w wersji 2.53.1 lub nowszej.

2. Przygotowanie projektu Spring

Aby wdrożyć aplikację interfejsu API RESTful, pierwszym krokiem jest przygotowanie projektu Spring do uruchomienia lokalnie.

Aby sklonować i uruchomić aplikację lokalnie, wykonaj następujące kroki:

1. Użyj następującego polecenia, aby sklonować przykładowy projekt z usługi GitHub:

   git clone https://github.com/Azure-Samples/ASA-Samples-Restful-Application.git
   

2. Jeśli chcesz uruchomić aplikację lokalnie, najpierw wykonaj kroki opisane w sekcjach Uwidaczniaj interfejsy API RESTful i Zaktualizuj konfigurację aplikacji , a następnie uruchom przykładową aplikację za pomocą narzędzia Maven za pomocą następującego polecenia:

   cd ASA-Samples-Restful-Application
   ./mvnw spring-boot:run
   

3. Przygotowanie środowiska chmury

Główne zasoby wymagane do uruchomienia tej przykładowej aplikacji to wystąpienie usługi Azure Spring Apps i wystąpienie usługi Azure Database for PostgreSQL. W poniższych sekcjach opisano sposób tworzenia tych zasobów.

Witryna Azure Portal i wtyczka Maven

3.1. Zaloguj się do witryny Azure Portal.

Przejdź do witryny Azure Portal i wprowadź swoje poświadczenia, aby zalogować się do portalu. Domyślny widok to panel kontrolny usług.

3.2. Tworzenie wystąpienia usługi Azure Spring Apps

Aby utworzyć wystąpienie usługi Azure Spring Apps, wykonaj następujące kroki:

1. Wybierz pozycję Utwórz zasób w rogu witryny Azure Portal.

2. Wybierz Compute>Azure Spring Apps.

3. Wypełnij formularz Podstawowe, korzystając z następujących informacji:

   Setting	Sugerowana wartość	Description
   Subscription	Nazwa subskrypcji.	Subskrypcja platformy Azure, która ma być używana dla serwera. Jeśli masz wiele subskrypcji, wybierz subskrypcję, w której chcesz naliczać opłaty za zasób.
   Grupa zasobów	myresourcegroup	Nowa nazwa grupy zasobów lub istniejąca nazwa z subskrypcji.
   Name	myasa	Unikatowa nazwa identyfikująca usługę Azure Spring Apps. Nazwa musi mieć długość od 4 do 32 znaków i może zawierać tylko małe litery, cyfry i łączniki. Pierwszy znak nazwy usługi musi być literą, a ostatni znak musi być literą lub cyfrą.
   Plan	Enterprise	Plan cenowy określający zasoby i koszt powiązany z Twoim przypadkiem.
   Region	Region najbliżej Twoich użytkowników.	Lokalizacja znajdująca się najbliżej użytkowników.
   Redundancja strefowa	Unselected	Opcja tworzenia usługi Azure Spring Apps w strefie dostępności platformy Azure. Ta funkcja nie jest obecnie obsługiwana we wszystkich regionach.
   Plan adresów IP oprogramowania	Pay-as-You-Go	Plan cenowy, który umożliwia płacenie zgodnie z rzeczywistym użyciem za pomocą usługi Azure Spring Apps.
   Terms	Selected	Pole wyboru zgody skojarzone z ofertą Marketplace. Musisz zaznaczyć to pole wyboru.
   Wdrażanie przykładowego projektu	Unselected	Opcja użycia wbudowanej przykładowej aplikacji.

4. Wybierz Przejrzyj i Utwórz, aby przejrzeć swoje wybory. Następnie wybierz pozycję Utwórz , aby aprowizować wystąpienie usługi Azure Spring Apps.

5. Na pasku narzędzi wybierz ikonę Powiadomienia (dzwonek), aby monitorować proces wdrażania. Po zakończeniu wdrażania możesz wybrać pozycję Przypnij do pulpitu nawigacyjnego, co spowoduje utworzenie kafelka dla tej usługi na pulpicie nawigacyjnym Azure Portal jako skrótu do strony Przegląd usługi.

   

6. Wybierz Przejdź do zasobu, aby przejść do strony Przegląd usługi Azure Spring Apps.

3.3. Przygotowywanie wystąpienia bazy danych PostgreSQL

Aby utworzyć serwer usługi Azure Database for PostgreSQL, wykonaj następujące czynności:

1. Przejdź do witryny Azure Portal i wybierz pozycję Utwórz zasób.

2. Wybierz Bazy danych>Azure Database for PostgreSQL.

3. Wybierz opcję Wdrożenie serwera elastycznego .

   

4. Wypełnij kartę Podstawy następującymi informacjami:

   • Nazwa serwera: my-demo-pgsql
   • Region: Wschodnie stany USA
   • Wersja bazy danych PostgreSQL: 14
   • Typ obciążenia: Programowanie
   • Włącz wysoką dostępność: niezaznaczone
   • Metoda uwierzytelniania: tylko uwierzytelnianie postgreSQL
   • Nazwa użytkownika administratora: myadmin
   • Hasło i potwierdź hasło: wprowadź hasło.

5. Użyj poniższych informacji, aby skonfigurować kartę Sieć :

   • Metoda łączności: dostęp publiczny (dozwolone adresy IP)
   • Zezwalaj na dostęp publiczny z dowolnej usługi platformy Azure na platformie Azure do tego serwera: wybrane

6. Wybierz pozycję Przejrzyj i utwórz , aby przejrzeć wybrane opcje, a następnie wybierz pozycję Utwórz , aby aprowizować serwer. Ta operacja może potrwać kilka minut.

7. W witrynie Azure Portal przejdź do serwera PostgreSQL. Na stronie Przegląd wyszukaj wartość Nazwa serwera , a następnie zapisz ją do późniejszego użycia. Jest potrzebne do skonfigurowania zmiennych środowiskowych aplikacji w usłudze Azure Spring Apps.

8. Wybierz pozycję Bazy danych z menu nawigacji, aby utworzyć bazę danych — na przykład todo.

   

3.4. Połącz instancję aplikacji z instancją PostgreSQL

Aby połączyć wystąpienia usługi, wykonaj następujące czynności:

1. Przejdź do wystąpienia usługi Azure Spring Apps w portalu Azure.

2. W menu nawigacji otwórz pozycję Aplikacje, a następnie wybierz pozycję Utwórz aplikację.

3. Na stronie Tworzenie aplikacji wypełnij nazwę aplikacji simple-todo-api, a następnie wybierz pozycję Artefakty Java jako typ wdrożenia.

4. Wybierz pozycję Utwórz , aby zakończyć tworzenie aplikacji, a następnie wybierz aplikację, aby wyświetlić szczegóły.

5. Przejdź do aplikacji utworzonej w witrynie Azure Portal. Na stronie Przegląd wybierz pozycję Przypisz punkt końcowy , aby uwidocznić publiczny punkt końcowy dla aplikacji. Zapisz adres URL na potrzeby uzyskiwania dostępu do aplikacji po wdrożeniu.

6. Wybierz pozycję Łącznik usługi w okienku nawigacji, a następnie wybierz pozycję Utwórz , aby utworzyć nowe połączenie z usługą.

   

7. Wypełnij kartę Podstawy następującymi informacjami:

   • Typ usługi: DB for PostgreSQL Flexible Server
   • Nazwa połączenia: jest wypełniana automatycznie wygenerowana nazwa, którą można również zmodyfikować.
   • Subskrypcja: wybierz swoją subskrypcję.
   • Serwer elastyczny PostgreSQL: my-demo-pgsql
   • Baza danych PostgreSQL: wybierz utworzoną bazę danych.
   • Typ klienta: SpringBoot

   

8. Skonfiguruj kartę Dalej: Uwierzytelnianie przy użyciu następujących informacji:

   Note

   Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tej procedurze, taki jak bazy danych, pamięci podręczne, komunikaty lub usługi sztucznej inteligencji, wymaga bardzo wysokiego stopnia zaufania w aplikacji i niesie ze sobą ryzyko, które nie występują w innych przepływach. Użyj tego przepływu tylko wtedy, gdy bardziej bezpieczne opcje, takie jak tożsamości zarządzane dla połączeń bez hasła lub bez kluczy, nie są opłacalne. W przypadku operacji maszyny lokalnej preferuj tożsamości użytkowników dla połączeń bez hasła lub bez klucza.

   • Wybierz typ uwierzytelniania, którego chcesz użyć między usługą obliczeniową a usługą docelową.: Wybierz pozycję Parametry połączenia.
   • Kontynuuj z...: wybierz poświadczenia bazy danych
   • Nazwa użytkownika: myadmin
   • Hasło: wprowadź hasło.

   

9. Wybierz Dalej: Sieć. Użyj opcji domyślnej Skonfiguruj reguły zapory, aby włączyć dostęp do usługi docelowej.

10. Wybierz pozycję Dalej: Przejrzyj i utwórz , aby przejrzeć wybrane opcje, a następnie wybierz pozycję Utwórz , aby utworzyć połączenie.

3.5. Uwidacznianie interfejsów API RESTful

Wykonaj następujące kroki, aby uwidocznić interfejsy API RESTful w identyfikatorze Entra firmy Microsoft:

1. Zaloguj się do witryny Azure Portal.

2. Jeśli masz dostęp do wielu dzierżaw, użyj filtru Katalog i subskrypcja ( ), aby wybrać dzierżawę, w której chcesz zarejestrować aplikację.

3. Wyszukaj i wybierz Microsoft Entra ID.

4. W obszarze Zarządzanie wybierz pozycję >.

5. Wprowadź nazwę aplikacji w polu Nazwa — na przykład Todo. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.

6. W obszarze Obsługiwane typy kont wybierz pozycję Konta w dowolnym katalogu organizacyjnym (dowolny katalog Microsoft Entra — Multitenant) i osobiste konta Microsoft.

7. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

8. Na stronie Przegląd aplikacji wyszukaj wartość Identyfikator aplikacji (klienta), a następnie zapisz ją do późniejszego użycia. Potrzebny jest go do skonfigurowania pliku konfiguracji YAML dla tego projektu.

9. W obszarze Zarządzanie wybierz pozycję Eksponuj interfejs API, znajdź URI identyfikatora aplikacji na początku strony, a następnie wybierz pozycję Dodaj.

10. Na stronie Edytowanie identyfikatora URI aplikacji zaakceptuj proponowany identyfikator URI aplikacji (api://{client ID}) lub użyj znaczącej nazwy zamiast identyfikatora klienta, jak api://simple-todo, a następnie wybierz Zapisz.

11. W obszarze Zarządzanie wybierz pozycję Uwidacznianie interfejsu API>Dodaj zakres, a następnie wprowadź następujące informacje:

    • W polu Nazwa zakresu wprowadź ToDo.Read.
    • W obszarze Kto może wyrazić zgodę, wybierz pozycję Tylko administratorzy.
    • W polu Nazwa wyświetlana zgody administratora wprowadź ciąg Odczyt danych zadań do wykonania.
    • W polu Opis zgody administratora wprowadź Zezwala uwierzytelnionym użytkownikom na odczyt danych ToDo.
    • W obszarze Stan zachowaj włączoną wartość .
    • Wybierz Dodaj zakres.

12. Powtórz poprzednie kroki, aby dodać dwa pozostałe zakresy: ToDo.Write i ToDo.Delete.

    

3.6. Aktualizowanie konfiguracji aplikacji

Wykonaj następujące kroki, aby zaktualizować plik YAML w celu użycia informacji o aplikacji zarejestrowanej w Microsoft Entra do ustanowienia relacji z aplikacją RESTful API:

1. Znajdź plik src/main/resources/application.yml dla aplikacji simple-todo-api. Zaktualizuj konfigurację w spring.cloud.azure.active-directory sekcji, aby odpowiadała poniższemu przykładowi. Pamiętaj, aby zastąpić symbole zastępcze utworzonymi wcześniej wartościami.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Note

   W tokenach w wersji 1.0 konfiguracja wymaga identyfikatora klienta interfejsu API, natomiast w tokenach w wersji 2.0 można użyć identyfikatora klienta lub identyfikatora URI aplikacji w żądaniu. Oba te elementy można skonfigurować tak, aby prawidłowo ukończyć walidację odbiorców.

   Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

2. Użyj następującego polecenia, aby ponownie skompilować przykładowy projekt:

   ./mvnw clean package
   

"Azure CLI"

3.1. Podaj nazwy dla każdego zasobu

Utwórz zmienne do przechowywania nazw zasobów przy użyciu następujących poleceń. Pamiętaj, aby zastąpić symbole zastępcze własnymi wartościami.

Note

Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tej procedurze, taki jak bazy danych, pamięci podręczne, komunikaty lub usługi sztucznej inteligencji, wymaga bardzo wysokiego stopnia zaufania w aplikacji i niesie ze sobą ryzyko, które nie występują w innych przepływach. Użyj tego przepływu tylko wtedy, gdy bardziej bezpieczne opcje, takie jak tożsamości zarządzane dla połączeń bez hasła lub bez kluczy, nie są opłacalne. W przypadku operacji maszyny lokalnej preferuj tożsamości użytkowników dla połączeń bez hasła lub bez klucza.

export RESOURCE_GROUP=myresourcegroup
export LOCATION=<location>
export POSTGRESQL_SERVER=my-demo-pgsql
export POSTGRESQL_DB=Todo
export POSTGRESQL_ADMIN_USERNAME=<admin-username>
export POSTGRESQL_ADMIN_PASSWORD=<admin-password>
export AZURE_SPRING_APPS_NAME=myasa
export APP_NAME=simple-todo-api
export TODO_APP_NAME=Todo
export TODO_APP_URL=api://simple-todo
export TODOWEB_APP_NAME=TodoWeb
export TODOWEB_APP_URL=api://simple-todoweb
export NEW_MEMBER_USERNAME=<new-member-username>
export NEW_MEMBER_PASSWORD=<new-member-password>
export USER_PRINCIPAL_NAME=<user-principal-name>

3.2. Tworzenie nowej grupy zasobów

Aby utworzyć nową grupę zasobów, wykonaj następujące czynności:

1. Użyj następującego polecenia, aby zalogować się do interfejsu wiersza polecenia platformy Azure:

   az login
   

2. Użyj następującego polecenia, aby ustawić lokalizację domyślną:

   az configure --defaults location=${LOCATION}
   

3. Użyj następującego polecenia, aby wyświetlić listę wszystkich dostępnych subskrypcji, aby określić identyfikator subskrypcji do użycia:

   az account list --output table
   

4. Użyj następującego polecenia, aby ustawić domyślną subskrypcję:

   az account set --subscription <subscription-ID>
   

5. Użyj następującego polecenia, aby utworzyć grupę zasobów:

   az group create --resource-group ${RESOURCE_GROUP}
   

6. Użyj następującego polecenia, aby ustawić nowo utworzoną grupę zasobów jako domyślną grupę zasobów:

   az configure --defaults group=${RESOURCE_GROUP}
   

3.3. Instalowanie rozszerzenia i rejestrowanie przestrzeni nazw

Użyj następujących poleceń, aby zainstalować rozszerzenie Azure Spring Apps dla interfejsu wiersza polecenia platformy Azure i zarejestrować Microsoft.SaaS przestrzeń nazw:

az extension add --name spring --upgrade
az provider register --namespace Microsoft.SaaS

3.4. Tworzenie wystąpienia usługi Azure Spring Apps

Wykonaj następujące kroki, aby utworzyć wystąpienie usługi i aplikację w jego ramach:

1. Użyj następującego polecenia, aby zaakceptować warunki prawne i oświadczenia o ochronie prywatności dla planu Enterprise:

   Note

   Ten krok jest niezbędny tylko wtedy, gdy subskrypcja nigdy nie została użyta do utworzenia instancji planu Enterprise w usłudze Azure Spring Apps.

   az term accept \
       --publisher vmware-inc \
       --product azure-spring-cloud-vmware-tanzu-2 \
       --plan asa-ent-hr-mtr
   

2. Użyj następującego polecenia, aby utworzyć wystąpienie usługi Azure Spring Apps:

   az spring create --name ${AZURE_SPRING_APPS_NAME} --sku enterprise
   

3. Użyj następującego polecenia, aby utworzyć aplikację w wystąpieniu usługi Azure Spring Apps:

   az spring app create \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --assign-endpoint true
   

3.5. Przygotowywanie wystąpienia bazy danych PostgreSQL

Aplikacja internetowa Spring używa H2 dla bazy danych na hoście lokalnym i Azure Database for PostgreSQL dla bazy danych na platformie Azure.

Użyj następującego polecenia, aby utworzyć wystąpienie bazy danych PostgreSQL:

Note

Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tej procedurze, taki jak bazy danych, pamięci podręczne, komunikaty lub usługi sztucznej inteligencji, wymaga bardzo wysokiego stopnia zaufania w aplikacji i niesie ze sobą ryzyko, które nie występują w innych przepływach. Użyj tego przepływu tylko wtedy, gdy bardziej bezpieczne opcje, takie jak tożsamości zarządzane dla połączeń bez hasła lub bez kluczy, nie są opłacalne. W przypadku operacji maszyny lokalnej preferuj tożsamości użytkowników dla połączeń bez hasła lub bez klucza.

az postgres flexible-server create \
    --name ${POSTGRESQL_SERVER} \
    --database-name ${POSTGRESQL_DB} \
    --admin-user ${POSTGRESQL_ADMIN_USERNAME} \
    --admin-password ${POSTGRESQL_ADMIN_PASSWORD} \
    --public-access 0.0.0.0

Określenie 0.0.0.0 umożliwia dostęp publiczny z dowolnych zasobów wdrożonych na platformie Azure w celu uzyskania dostępu do serwera.

3.6. Połącz instancję aplikacji z instancją PostgreSQL

Po utworzeniu wystąpienia aplikacji i wystąpienia bazy danych PostgreSQL wystąpienie aplikacji nie może bezpośrednio uzyskać dostępu do wystąpienia bazy danych PostgreSQL. Wykonaj następujące kroki, aby umożliwić aplikacji nawiązywanie połączenia z wystąpieniem bazy danych PostgreSQL:

1. Użyj następującego polecenia, aby uzyskać w pełni kwalifikowaną nazwę domeny wystąpienia PostgreSQL:

   export PSQL_FQDN=$(az postgres flexible-server show \
       --name ${POSTGRESQL_SERVER} \
       --query fullyQualifiedDomainName \
       --output tsv)
   

2. Użyj następującego polecenia, aby udostępnić spring.datasource. właściwości aplikacji za pomocą zmiennych środowiskowych:

   Note

   Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tej procedurze, taki jak bazy danych, pamięci podręczne, komunikaty lub usługi sztucznej inteligencji, wymaga bardzo wysokiego stopnia zaufania w aplikacji i niesie ze sobą ryzyko, które nie występują w innych przepływach. Użyj tego przepływu tylko wtedy, gdy bardziej bezpieczne opcje, takie jak tożsamości zarządzane dla połączeń bez hasła lub bez kluczy, nie są opłacalne. W przypadku operacji maszyny lokalnej preferuj tożsamości użytkowników dla połączeń bez hasła lub bez klucza.

   az spring app update \
       --service ${AZURE_SPRING_APPS_NAME} \
       --name ${APP_NAME} \
       --env SPRING_DATASOURCE_URL="jdbc:postgresql://${PSQL_FQDN}:5432/${POSTGRESQL_DB}?sslmode=require" \
             SPRING_DATASOURCE_USERNAME="${POSTGRESQL_ADMIN_USERNAME}" \
             SPRING_DATASOURCE_PASSWORD="${POSTGRESQL_ADMIN_PASSWORD}"
   

3.7. Uwidacznianie interfejsów API RESTful

Aby uwidocznić interfejsy API RESTful, wykonaj następujące czynności:

1. Użyj następującego polecenia, aby utworzyć aplikację Microsoft Entra ID:

   az ad app create \
       --display-name ${TODO_APP_NAME} \
       --sign-in-audience AzureADandPersonalMicrosoftAccount \
       --identifier-uris ${TODO_APP_URL}
   

2. Użyj następującego polecenia, aby utworzyć główną jednostkę usługi dla aplikacji:

   az ad sp create --id ${TODO_APP_URL}
   

3. Użyj następującego polecenia, aby wygenerować identyfikatory uprawnień:

   permissionid1=$(uuidgen);permissionid2=$(uuidgen);permissionid3=$(uuidgen)
   

4. Dodaj następujące zakresy jako dane JSON:

   api=$(echo '{
    "oauth2PermissionScopes": [
        {
            "adminConsentDescription": "Allows authenticated users to delete the ToDo data",
            "adminConsentDisplayName": "Delete the ToDo data",
            "id": "'$permissionid1'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Delete"
        },
   
        {
            "adminConsentDescription": "Allows authenticated users to write the ToDo data",
            "adminConsentDisplayName": "Write the ToDo data",
            "id": "'$permissionid2'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Write"
        },
        {
            "adminConsentDescription": "Allows authenticated users to read the ToDo data",
            "adminConsentDisplayName": "Read the ToDo data",
            "id": "'$permissionid3'",
            "isEnabled": true,
            "type": "Admin",
            "userConsentDescription": null,
            "userConsentDisplayName": null,
            "value": "ToDo.Read"
        }
    ]}')
   

5. Użyj następującego polecenia, aby dodać zakresy:

   az ad app update \
       --id ${TODO_APP_URL} \
       --set api="$api"
   

6. Użyj następującego polecenia, aby uzyskać identyfikator dzierżawy do użycia w następnym kroku:

   az account show --query "tenantId" --output tsv
   

7. Użyj następującego polecenia, aby uzyskać identyfikator aplikacji do użycia w następnych krokach:

   appid=$(az ad app show \
       --id ${TODO_APP_URL} \
       --query appId \
       --output tsv);
   echo $appid
   

3.8. Aktualizowanie konfiguracji aplikacji

Wykonaj następujące kroki, aby zaktualizować plik YAML w celu użycia informacji o aplikacji zarejestrowanej w Microsoft Entra do ustanowienia relacji z aplikacją RESTful API:

1. Znajdź plik src/main/resources/application.yml dla aplikacji simple-todo-api. Zaktualizuj konfigurację w spring.cloud.azure.active-directory sekcji, aby odpowiadała poniższemu przykładowi. Pamiętaj, aby zastąpić symbole zastępcze utworzonymi wcześniej wartościami.

   spring:
     cloud:
       azure:
         active-directory:
           profile:
             tenant-id: <tenant>
           credential:
             client-id: <your-application-ID-of-ToDo>
           app-id-uri: <your-application-ID-URI-of-ToDo>
   

   Note

   W tokenach w wersji 1.0 konfiguracja wymaga identyfikatora klienta interfejsu API, natomiast w tokenach w wersji 2.0 można użyć identyfikatora klienta lub identyfikatora URI aplikacji w żądaniu. Oba te elementy można skonfigurować tak, aby prawidłowo ukończyć walidację odbiorców.

   Dozwolone wartości dla tenant-id to: common, organizations, consumerslub identyfikator dzierżawy. Aby uzyskać więcej informacji na temat tych wartości, zobacz sekcję Użyto nieprawidłowego punktu końcowego (kont osobistych i organizacyjnych) w Błąd AADSTS50020 — konto użytkownika od dostawcy tożsamości nie istnieje w dzierżawie. Aby uzyskać informacje na temat konwertowania aplikacji jednolicencjonowanej na wielolicencjonowaną, zobacz Convert single-tenant app to multitenant on Microsoft Entra ID.

2. Użyj następującego polecenia, aby ponownie skompilować przykładowy projekt:

   ./mvnw clean package
   

4. Wdrażanie aplikacji w usłudze Azure Spring Apps

Witryna Azure Portal i wtyczka Maven

Teraz możesz wdrożyć aplikację w usłudze Azure Spring Apps.

Wykonaj następujące kroki, aby wdrożyć przy użyciu wtyczki Maven dla usługi Azure Spring Apps:

1. Przejdź do kompletnego katalogu, a następnie uruchom następujące polecenie, aby skonfigurować aplikację w usłudze Azure Spring Apps:

   ./mvnw com.microsoft.azure:azure-spring-apps-maven-plugin:1.19.0:config
   

   Poniższa lista zawiera opis interakcji poleceń:

   • Logowanie OAuth2: musisz autoryzować logowanie do platformy Azure na podstawie protokołu OAuth2.
   • Wybierz subskrypcję: wybierz numer listy subskrypcji utworzonego wystąpienia usługi Azure Spring Apps, które jest domyślnie ustawione na pierwszą subskrypcję na liście. Jeśli używasz numeru domyślnego, naciśnij Enter bezpośrednio.
   • Użyj istniejących Azure Spring Apps na platformie Azure: wciśnij y aby użyć istniejącej instancji Azure Spring Apps.
   • Wybierz aplikację Azure Spring Apps do wdrożenia: wybierz utworzone wystąpienie usługi Azure Spring Apps. Jeśli używasz numeru domyślnego, naciśnij Enter bezpośrednio.
   • Użyj istniejącej aplikacji w usłudze Azure Spring Apps <nazwa-wystąpienia>: naciśnij y , aby użyć utworzonej aplikacji.
   • Potwierdź, aby zapisać wszystkie powyższe konfiguracje: naciśnij y. Jeśli naciśniesz n, konfiguracja nie zostanie zapisana w plikach POM.

2. Aby wdrożyć aplikację, użyj następującego polecenia:

   ./mvnw azure-spring-apps:deploy
   

   Na poniższej liście opisano przebieg interakcji z komendą:

   • Logowanie OAuth2: musisz autoryzować logowanie do platformy Azure na podstawie protokołu OAuth2.

   Po wykonaniu polecenia można zobaczyć następujące komunikaty dziennika, że wdrożenie zakończyło się pomyślnie:

[INFO] Deployment Status: Running
[INFO]   InstanceName:simple-todo-api-default-15-xxxxxxxxx-xxxxx  Status:Running Reason:null       DiscoverStatus:N/A       
[INFO] Getting public url of app(simple-todo-api)...
[INFO] Application url: https://<your-Azure-Spring-Apps-instance-name>-simple-todo-api.azuremicroservices.io

"Azure CLI"

Użyj następującego polecenia, aby wdrożyć aplikację na podstawie kodu źródłowego:

az spring app deploy \
    --service ${AZURE_SPRING_APPS_NAME} \
    --name ${APP_NAME} \
    --build-env BP_JVM_VERSION=17 \
    --source-path .

5. Weryfikowanie aplikacji

Witryna Azure Portal i wtyczka Maven

Teraz możesz uzyskać dostęp do interfejsu API RESTful, aby sprawdzić, czy działa.

5.1. Żądanie tokenu dostępu

Interfejsy API RESTful działają jako serwer zasobów, który jest chroniony przez identyfikator Entra firmy Microsoft. Przed uzyskaniem tokenu dostępu należy zarejestrować inną aplikację w usłudze Microsoft Entra ID i udzielić uprawnień aplikacji klienckiej o nazwie ToDoWeb.

Rejestrowanie aplikacji klienckiej

Wykonaj następujące kroki, aby zarejestrować aplikację w usłudze Microsoft Entra ID, która służy do dodawania ToDo uprawnień dla aplikacji:

1. Zaloguj się do witryny Azure Portal.

2. Jeśli masz dostęp do wielu dzierżaw, użyj filtru Katalog i subskrypcja ( ), aby wybrać dzierżawę, w której chcesz zarejestrować aplikację.

3. Wyszukaj i wybierz Microsoft Entra ID.

4. W obszarze Zarządzanie wybierz pozycję >.

5. Wprowadź nazwę aplikacji w polu Nazwa — na przykład ToDoWeb. Użytkownicy aplikacji mogą zobaczyć tę nazwę i możesz ją zmienić później.

6. W przypadku obsługiwanych typów kont użyj wartości domyślnej Konta tylko w tym katalogu organizacyjnym.

7. Wybierz pozycję Zarejestruj, aby utworzyć aplikację.

8. Na stronie Przegląd aplikacji wyszukaj wartość Identyfikator aplikacji (klienta), a następnie zapisz ją do późniejszego użycia. Potrzebujesz go, aby uzyskać token dostępu.

9. Wybierz Uprawnienia interfejsu API>Dodaj uprawnienie>Moje interfejsy API. Wybierz zarejestrowaną wcześniej aplikację ToDo , a następnie wybierz uprawnienia ToDo.Read, ToDo.Write i ToDo.Delete . Wybierz Dodaj uprawnienia.

10. Wybierz pozycję Udziel zgody administratora dla <twojej-nazwy-dzierżawy>, aby zatwierdzić dodane uprawnienia.

    

Dodaj użytkownika dla dostępu do interfejsów API RESTful

Wykonaj poniższe kroki, aby utworzyć użytkownika członkowskiego w dzierżawie firmy Microsoft Entra. Następnie użytkownik może zarządzać danymi ToDo aplikacji za pomocą interfejsów API RESTful.

1. W obszarze Zarządzanie wybierz pozycję Użytkownicy>Nowy użytkownik>Utwórz nowego użytkownika.

2. Na stronie Tworzenie nowego użytkownika wprowadź następujące informacje:

   • Główna nazwa użytkownika: wprowadź nazwę użytkownika.
   • Nazwa wyświetlana: wprowadź nazwę wyświetlaną użytkownika.
   • Hasło: skopiuj automatycznie wygenerowane hasło podane w polu Hasło .

   Note

   Nowi użytkownicy muszą ukończyć pierwsze uwierzytelnianie logowania i zaktualizować swoje hasła. W przeciwnym razie podczas uzyskiwania tokenu dostępu zostanie wyświetlony AADSTS50055: The password is expired błąd.

   Kiedy nowy użytkownik się zaloguje, otrzyma monit działania wymagane. Mogą wybrać pozycję Zapytaj później , aby pominąć walidację.

3. Wybierz Przejrzyj i utwórz, aby przejrzeć swoje wybory. Wybierz pozycję Utwórz , aby utworzyć użytkownika.

Aktualizowanie konfiguracji protokołu OAuth2 na potrzeby autoryzacji interfejsu użytkownika programu Swagger

Wykonaj poniższe kroki, aby zaktualizować konfigurację protokołu OAuth2 dla autoryzacji interfejsu użytkownika struktury Swagger. Następnie możesz autoryzować użytkowników do uzyskiwania tokenów dostępu za pośrednictwem ToDoWeb aplikacji.

1. Otwórz klienta Microsoft Entra ID w portalu Azure i przejdź do zarejestrowanej aplikacji ToDoWeb.

2. W obszarze Zarządzanie wybierz pozycję Uwierzytelnianie, wybierz pozycję Dodaj platformę, a następnie wybierz pozycję Aplikacja jednostronicowa.

3. Użyj formatu <your-app-exposed-application-URL-or-endpoint>/swagger-ui/oauth2-redirect.html jako adresu URL przekierowania OAuth2 w polu Identyfikatory URI przekierowania, a następnie wybierz Konfiguruj.

   

"Azure CLI"

Teraz możesz uzyskać dostęp do interfejsu API RESTful, aby sprawdzić, czy działa.

5.1. Żądanie tokenu dostępu

Interfejsy API RESTful działają jako serwer zasobów, który jest chroniony przez identyfikator Entra firmy Microsoft. Przed uzyskaniem tokenu dostępu musisz zarejestrować inną aplikację w identyfikatorze Entra firmy Microsoft i udzielić uprawnień aplikacji klienckiej o nazwie ToDoWeb.

Rejestrowanie aplikacji klienckiej

Aby zarejestrować aplikację kliencą, wykonaj następujące kroki:

1. Użyj następującego polecenia, aby utworzyć aplikację Microsoft Entra ID, która służy do dodawania ToDo uprawnień dla aplikacji:

   az ad app create \
       --display-name ${TODOWEB_APP_NAME} \
       --sign-in-audience AzureADMyOrg \
       --identifier-uris ${TODOWEB_APP_URL}
   

2. Użyj następującego polecenia, aby dodać uprawnienia:

   az ad app permission add \
       --id api://simple-todowebtest2 \
       --api $appid \
       --api-permissions $permissionid1=Scope $permissionid2=Scope $permissionid3=Scope
   

3. Użyj następującego polecenia, aby udzielić zgody administratora dla dodanych uprawnień:

   az ad app permission admin-consent --id ${TODOWEB_APP_URL}
   

4. Użyj następującego polecenia, aby uzyskać identyfikator ToDoWeb klienta aplikacji używanej w kroku Uzyskiwanie tokenu dostępu :

   az ad app show \
       --id ${TODOWEB_APP_URL} \
       --query appId \
       --output tsv
   

Dodaj użytkownika dla dostępu do interfejsów API RESTful

Użyj następującego polecenia, aby utworzyć użytkownika-gościa w Twojej dzierżawie Microsoft Entra. Następnie użytkownik może zarządzać danymi ToDo aplikacji za pomocą interfejsów API RESTful:

Note

Firma Microsoft zaleca korzystanie z najbezpieczniejszego dostępnego przepływu uwierzytelniania. Przepływ uwierzytelniania opisany w tej procedurze, taki jak bazy danych, pamięci podręczne, komunikaty lub usługi sztucznej inteligencji, wymaga bardzo wysokiego stopnia zaufania w aplikacji i niesie ze sobą ryzyko, które nie występują w innych przepływach. Użyj tego przepływu tylko wtedy, gdy bardziej bezpieczne opcje, takie jak tożsamości zarządzane dla połączeń bez hasła lub bez kluczy, nie są opłacalne. W przypadku operacji maszyny lokalnej preferuj tożsamości użytkowników dla połączeń bez hasła lub bez klucza.

az ad user create \
    --display-name ${NEW_MEMBER_USERNAME} \
    --password ${NEW_MEMBER_PASSWORD} \
    --user-principal-name ${USER_PRINCIPAL_NAME}

Aktualizowanie konfiguracji protokołu OAuth2 na potrzeby autoryzacji interfejsu użytkownika programu Swagger

Aby zaktualizować konfigurację protokołu OAuth2, wykonaj następujące czynności:

1. Użyj następującego polecenia, aby uzyskać identyfikator ToDoWeb obiektu aplikacji:

   az ad app show --id ${TODOWEB_APP_URL} --query id
   

2. Użyj następującego polecenia, aby uzyskać adres URL aplikacji simple-todo-api :

   az spring app show \
       --name ${APP_NAME} \
       --service ${AZURE_SPRING_APPS_NAME} \
       --query properties.url
   

3. Użyj następującego polecenia, aby zaktualizować konfigurację OAuth2 dla autoryzacji interfejsu użytkownika Swagger, zastępując symbole zastępcze <object-id> i <URL> wartościami parametrów, które otrzymałeś. Następnie możesz autoryzować użytkowników do uzyskiwania tokenów dostępu za pośrednictwem ToDoWeb aplikacji.

   az rest \
       --method PATCH \
       --uri "https://graph.microsoft.com/v1.0/applications/<object-id>" \
       --headers 'Content-Type=application/json' \
       --body '{"spa":{"redirectUris":["<URL>/swagger-ui/oauth2-redirect.html"]}}'
   

Uzyskiwanie tokenu dostępu

Wykonaj następujące kroki, aby użyć metody przepływu kodu autoryzacji OAuth 2.0 w celu uzyskania tokenu dostępu z Microsoft Entra ID, a następnie uzyskać dostęp do RESTful API aplikacji ToDo.

1. Otwórz adres URL uwidoczniony przez aplikację, a następnie wybierz pozycję Autoryzuj , aby przygotować uwierzytelnianie OAuth2.

2. W oknie Dostępne autoryzacje, wprowadź identyfikator klienta aplikacji w polu ToDoWeb, wybierz wszystkie zakresy w polu Scopes, pomiń pole client_secret, a następnie wybierz Autoryzuj, aby przekierować do strony logowania Microsoft Entra.

Po zakończeniu logowania przy użyciu poprzedniego użytkownika wrócisz do okna Dostępne autoryzacje .

5.2. Uzyskiwanie dostępu do interfejsów API RESTful

Wykonaj następujące kroki, aby uzyskać dostęp do RESTful API aplikacji ToDo w interfejsie użytkownika Swagger:

1. Wybierz interfejs API POST /api/simple-todo/lists , a następnie wybierz pozycję Wypróbuj. Wprowadź następującą treść żądania, a następnie wybierz pozycję Wykonaj , aby utworzyć listę zadań do wykonania.

   {
     "name": "My List"
   }
   

   Po zakończeniu wykonywania zostanie wyświetlona następująca treść odpowiedzi:

   {
     "id": "<ID-of-the-ToDo-list>",
     "name": "My List",
     "description": null
   }
   

2. Wybierz API POST /api/simple-todo/lists/{listId}/items, a następnie wybierz Wypróbuj. W listId wpisz wcześniej utworzony identyfikator listy ToDo, wprowadź treść żądania jak poniżej, a następnie wybierz Wykonaj, aby utworzyć element ToDo.

   {
     "name": "My first ToDo item", 
     "listId": "<ID-of-the-ToDo-list>",
     "state": "todo"
   }
   

   Ta akcja zwraca następujący element ToDo:

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": null,
     "state": "todo",
     "dueDate": "2023-07-11T13:59:24.9033069+08:00",
     "completedDate": null
   }
   

3. Wybierz interfejs API GET /api/simple-todo/lists , a następnie wybierz pozycję Wykonaj , aby wykonać zapytanie o listy zadań do wykonania. Ta akcja zwraca następujące listy zadań do wykonania:

   [
     {
       "id": "<ID-of-the-ToDo-list>",
       "name": "My List",
       "description": null
     }
   ]
   

4. Wybierz interfejs API GET /api/simple-todo/lists/{listId}/items , a następnie wybierz pozycję Wypróbuj. W polu listId wprowadź utworzony wcześniej identyfikator listy zadań do wykonania, a następnie wybierz pozycję Wykonaj , aby wykonać zapytanie o elementy zadań do wykonania. Ta akcja zwraca następujący element ToDo:

   [
     {
       "id": "<ID-of-the-ToDo-item>",
       "listId": "<ID-of-the-ToDo-list>",
       "name": "My first ToDo item",
       "description": null,
       "state": "todo",
       "dueDate": "2023-07-11T13:59:24.903307+08:00",
       "completedDate": null
     }
   ]
   

5. Wybierz interfejs API PUT /api/simple-todo/lists/{listId}/items/{itemId}, a następnie wybierz opcję Wypróbuj. W polu listId wprowadź identyfikator listy zadań. W polu itemId wprowadź identyfikator elementu ToDo, wprowadź następującą treść żądania, a następnie wybierz pozycję Wykonaj , aby zaktualizować element ToDo.

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": "Updated description.",
     "dueDate": "2023-07-11T13:59:24.903307+08:00",
     "state": "inprogress"
   }
   

   Ta akcja zwraca następujący zaktualizowany element ToDo:

   {
     "id": "<ID-of-the-ToDo-item>",
     "listId": "<ID-of-the-ToDo-list>",
     "name": "My first ToDo item",
     "description": "Updated description.",
     "state": "inprogress",
     "dueDate": "2023-07-11T05:59:24.903307Z",
     "completedDate": null
   }
   

6. Wybierz interfejs API DELETE /api/simple-todo/lists/{listId}/items/{itemId} i następnie wybierz pozycję Wypróbuj to. W polu listId wprowadź identyfikator listy rzeczy do zrobienia. W polu itemId wprowadź identyfikator elementu ToDo, a następnie wybierz pozycję Wykonaj , aby usunąć element ToDo. Powinien zostać wyświetlony kod odpowiedzi serwera: 204.

6. Czyszczenie zasobów

Możesz usunąć grupę zasobów platformy Azure zawierającą wszystkie zasoby w tej grupie.

Witryna Azure Portal i wtyczka Maven

Wykonaj następujące kroki, aby usunąć całą grupę zasobów, w tym nowo utworzoną usługę:

1. Znajdź grupę zasobów w witrynie Azure Portal.

2. W menu nawigacji wybierz pozycję Grupy zasobów. Następnie wybierz nazwę grupy zasobów — na przykład myresourcegroup.

3. Na stronie grupy zasobów wybierz pozycję Usuń. Wprowadź nazwę grupy zasobów w polu tekstowym, aby potwierdzić usunięcie — na przykład myresourcegroup. Następnie wybierz pozycję Usuń.

"Azure CLI"

Użyj następującego polecenia, aby usunąć całą grupę zasobów, w tym nowo utworzoną usługę:

az group delete --name ${RESOURCE_GROUP}

7. Następne kroki

Szybki start: wdrażanie aplikacji opartej na zdarzeniach w usłudze Azure Spring Apps

Szybki start: wdrażanie aplikacji mikrousług w usłudze Azure Spring Apps

Dziennik aplikacji ze strukturą dla usługi Azure Spring Apps

Skojarz istniejącą domenę niestandardową z usługą Azure Spring Apps

Używanie ciągłej integracji/ciągłego wdrażania usługi Azure Spring Apps z funkcją GitHub Actions

Automatyzowanie wdrożeń aplikacji w usłudze Azure Spring Apps

Aby uzyskać więcej informacji, zobacz następujące artykuły:

• Przykłady usługi Azure Spring Apps.
• Oprogramowanie Spring na platformie Azure
• Spring Cloud Azure