Hostuj samodzielnie portal Centrum API

W tym artykule pokazano, jak samodzielnie hostować portal Centrum interfejsów API, witrynę internetową, która umożliwia deweloperom i innym uczestnikom projektu w organizacji odnajdywanie interfejsów API w centrum interfejsów API. Wdróż referencyjną implementację portalu z repozytorium API Center portal starter.

Informacje o samodzielnym hostowaniu portalu

Możesz utworzyć i wdrożyć implementację referencyjną portalu przy użyciu kodu w repozytorium startowym portalu api Center . Portal używa interfejsu API płaszczyzny danych centrum API platformy Azure do pobierania danych z centrum API.

Implementacja referencyjna portalu centrum API zapewnia:

• Ramy do publikowania i utrzymywania portalu API zarządzanego przez klienta przy użyciu GitHub Actions
• Platforma portalu, którą klienci mogą modyfikować lub rozszerzać w celu spełnienia swoich potrzeb
• Elastyczność hostowania w różnych infrastrukturach, w tym wdrażanie w usługach, takich jak Azure Static Web Apps.

Wymagania wstępne

• Centrum API w subskrypcji Azure. Jeśli jeszcze go nie utworzono, zobacz Szybki start: tworzenie centrum interfejsu API.

• Uprawnienia do tworzenia rejestracji aplikacji w dzierżawie usługi Microsoft Entra skojarzonej z subskrypcją platformy Azure oraz uprawnienia do udzielania dostępu do danych w centrum API.

• Aby skompilować i wdrożyć portal, potrzebne jest konto usługi GitHub i następujące narzędzia zainstalowane na komputerze lokalnym:

  • Node.js i npm
  • Pakiet Vite

Tworzenie rejestracji aplikacji Microsoft Entra

Najpierw skonfiguruj rejestrację aplikacji w dzierżawie Microsoft Entra ID. Rejestracja aplikacji umożliwia portalowi Centrum interfejsów API uzyskiwanie dostępu do danych z centrum interfejsu API w imieniu zalogowanego użytkownika.

Centrum interfejsu API może automatycznie skonfigurować rejestrację aplikacji lub ręcznie utworzyć rejestrację aplikacji.

Automatyczne konfigurowanie rejestracji aplikacji

Aby automatycznie skonfigurować rejestrację aplikacji, wykonaj następujące kroki:

1. W witrynie Azure portal przejdź do centrum API.
2. W menu po lewej stronie wybierz pozycjęUstawienia portalu >Centrum interfejsu API.
3. Na karcie Identity provider (Dostawca tożsamości ) wybierz pozycję Start set up (Uruchom konfigurację).
4. Na karcie Szybka konfiguracja wybierz pozycję Zapisz i opublikuj.

Jeśli chcesz później uzyskać dostęp do rejestracji aplikacji, możesz ją znaleźć w portalu w obszarze Rejestracje aplikacji. Aplikacja ma następujący format: <api-center-name-apic-aad>.

Ręczne konfigurowanie rejestracji aplikacji

Jeśli chcesz ręcznie utworzyć rejestrację aplikacji, wykonaj następujące kroki:

1. W witrynie Azure Portal przejdź do pozycji Microsoft Entra ID> Manage App registrations (Zarządzanie rejestracjami>aplikacji).

2. Wybierz pozycję + Nowa rejestracja.

3. Na stronie Rejestrowanie aplikacji ustaw następujące wartości:

   1. Ustaw nazwę na zrozumiałą nazwę, taką jak api-center-portal
   2. W obszarze Obsługiwane typy kont wybierz pozycję Konta tylko w tym katalogu organizacyjnym (<nazwa> katalogu — pojedyncza dzierżawa).
   3. W polu URI przekierowania wybierz opcję Aplikacja jednostronicowa (SPA) i ustaw URI. Wprowadź identyfikator URI wdrożenia portalu API Center w następującym formacie: https://<service-name>.portal.<location>.azure-apicenter.ms. Zastąp <service name> i <location> nazwą centrum interfejsu API oraz lokalizacją, w której jest wdrożone, przykład: https://myapicenter.portal.eastus.azure-apicenter.ms.
   4. Wybierz pozycję Zarejestruj.

Skonfiguruj dodatkowe identyfikatory URI przekierowania dla rozszerzenia VS Code

Podczas włączania widoku portalu Centrum interfejsu API w rozszerzeniu programu Visual Studio Code dla centrum interfejsu API skonfiguruj również następujące identyfikatory URI przekierowania w rejestracji aplikacji:

1. W witrynie Azure Portal przejdź do rejestracji aplikacji.

2. Na stronie Zarządzanie>uwierzytelnianiem wybierz pozycję Dodaj platformę i wybierz pozycję Aplikacje mobilne i klasyczne.

3. Skonfiguruj następujące trzy niestandardowe adresy URI przekierowań:
   https://vscode.dev/redirect
http://localhost
ms-appx-web://Microsoft.AAD.BrokerPlugin/<application-client-id>
   

   Zastąp <application-client-id> element identyfikatorem aplikacji (klienta) tej aplikacji. Tę wartość można znaleźć na stronie Przegląd rejestracji aplikacji.

Konfigurowanie środowiska lokalnego

Wykonaj następujące kroki, aby skompilować i przetestować portal centrum interfejsów API lokalnie.

1. Sklonuj repozytorium startowe portalu API Center na komputer lokalny.

   git clone https://github.com/Azure/APICenter-Portal-Starter.git
   

2. Przejdź do APICenter-Portal-Starter katalogu.

   cd APICenter-Portal-Starter
   

3. Sprawdź główną gałąź.

   git checkout main
   

4. Aby skonfigurować usługę, skopiuj lub zmień nazwę public/config.example pliku na public/config.json.

5. Następnie zmodyfikuj public/config.json plik, aby wskazywał usługę. Zaktualizuj wartości w pliku w następujący sposób:

   1. Zastąp <service name> oraz <location> nazwą swojego centrum API i lokalizacją, w której jest wdrożone.
   2. Zastąp <client ID> i <tenant ID> za pomocą identyfikatora aplikacji (klienta) oraz identyfikatora katalogu (dzierżawy) dla rejestracji aplikacji, którą utworzyłeś w poprzedniej sekcji.
   3. Zaktualizuj wartość title na nazwę, która ma być wyświetlana na górnym pasku portalu.

   {
     "dataApiHostName": "<service name>.data.<location>.azure-apicenter.ms/workspaces/default",
     "title": "API portal",
     "authentication": {
         "clientId": "<client ID>",
         "tenantId": "<tenant ID>",
         "scopes": ["https://azure-apicenter.net/user_impersonation"],
         "authority": "https://login.microsoftonline.com/"
     }
   }
   

6. Zainstaluj wymagane pakiety.

   npm install
   

7. Uruchom serwer deweloperów. Następujące polecenie uruchamia portal w trybie programowania uruchomionym lokalnie:

   npm start
   

   Przejdź do portalu pod adresem https://localhost:5173.

Wdrażanie na platformie Azure

Aby uzyskać instrukcje dotyczące wdrażania portalu w Azure Static Web Apps, zobacz repozytorium API Center portal starter.

Włącz logowanie do portalu przez użytkowników i grupy Microsoft Entra

Aby włączyć logowanie się do portalu Centrum interfejsów API w celu uzyskania dostępu do interfejsów API, przypisz rolę Czytelnik danych centrum interfejsów API platformy Azure do użytkowników lub grup w organizacji, w zakresie centrum interfejsu API.

Aby uzyskać szczegółowe wymagania wstępne i kroki przypisywania roli do użytkowników i grup, zobacz Przypisywanie ról platformy Azure przy użyciu witryny Azure Portal. Wykonaj krótkie kroki:

1. W witrynie Azure portal przejdź do centrum API.
2. W menu po lewej stronie wybierz pozycję Kontrola dostępu (IAM)>+ Dodaj przypisanie roli.
3. W okienku Dodawanie przypisania roli ustaw następujące wartości:
   1. Na stronie Ról wyszukaj i wybierz Czytelnik danych Azure API Center. Wybierz Dalej.
   2. Na stronie Członkowie w sekcji Przypisz dostęp do, wybierz pozycję Użytkownik, grupa lub jednostka usługi>, a następnie kliknij + Wybierz członków.
   3. Na stronie Wybieranie członków wyszukaj i wybierz użytkowników lub grupy, do których ma zostać przypisana rola. Kliknij pozycję Wybierz, a następnie pozycję Dalej.
   4. Przejrzyj przypisanie roli i wybierz opcję Przegląd i przypisz.

Po skonfigurowaniu dostępu do portalu użytkownicy, którzy zostali skonfigurowani, mogą logować się do portalu i wyświetlać interfejsy API w centrum API.

Rozwiązywanie problemów

Błąd: "Nie masz autoryzacji dostępu do tego portalu"

W pewnych warunkach użytkownik może napotkać następujący komunikat o błędzie po zalogowaniu się do portalu Centrum interfejsu API przy użyciu skonfigurowanego konta użytkownika:

You are not authorized to access this portal. Please contact your portal administrator for assistance. `

Najpierw upewnij się, że użytkownik ma przypisaną rolę Czytelnik danych Azure API Center w centrum interfejsu API.

Jeśli użytkownik ma przypisaną rolę, może wystąpić problem z rejestracją dostawcy zasobów Microsoft.ApiCenter w ramach subskrypcji i może być konieczne ponowne zarejestrowanie dostawcy zasobów. W tym celu uruchom następujące polecenie w interfejsie wiersza polecenia platformy Azure:

az provider register --namespace Microsoft.ApiCenter

Nie można zalogować się do portalu

Jeśli użytkownicy, którym przypisano rolę Czytelnik danych centrum interfejsu API platformy Azure , nie mogą ukończyć przepływu logowania po wybraniu pozycji Zaloguj się w portalu Centrum interfejsu API, może wystąpić problem z konfiguracją dostawcy tożsamości Microsoft Entra ID.

W rejestracji aplikacji Microsoft Entra przejrzyj i, w razie potrzeby, zaktualizuj ustawienia identyfikatora URI przekierowania, aby upewnić się, że identyfikator URI jest zgodny z identyfikatorem URI wdrożenia portalu centrum API.

Nie można wybrać uprawnień Azure API Center w rejestracji aplikacji Microsoft Entra

Jeśli nie możesz zażądać uprawnień API do Azure API Center w rejestracji aplikacji Microsoft Entra dla portalu API Center, sprawdź, czy szukasz Azure API Center (lub identyfikatora aplikacji c3ca1a77-7a87-4dba-b8f8-eea115ae4573).

Jeśli aplikacja nie jest obecna, może wystąpić problem z rejestracją dostawcy zasobów Microsoft.ApiCenter w ramach subskrypcji. Może być konieczne ponowne zarejestrowanie dostawcy zasobów. W tym celu uruchom następujące polecenie w interfejsie wiersza polecenia platformy Azure:

az provider register --namespace Microsoft.ApiCenter

Po ponownym zarejestrowaniu dostawcy zasobów spróbuj ponownie zażądać uprawnień interfejsu API.

Polityka wsparcia

Prześlij opinię, zażądaj funkcji i uzyskaj pomoc techniczną dotyczącą implementacji referencyjnej portalu API Center w repozytorium API Center portal starter.

Powiązana zawartość

• Skonfiguruj portal Centrum API
• Co to jest kontrola dostępu na podstawie ról (RBAC) na platformie Azure?
• Najlepsze praktyki dotyczące kontroli dostępu opartej na rolach w Azure
• Rejestrowanie dostawcy zasobów