Udostępnij za pośrednictwem

Samodzielne hostowanie portalu centrum interfejsów API

  • Artykuł

W tym artykule przedstawiono 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óż implementację referencyjną portalu z repozytorium startowego portalu API Center.

Zrzut ekranu przedstawiający portal Centrum interfejsów API po zalogowaniu użytkownika.

Informacje o portalu Centrum interfejsów API

Portal Centrum interfejsów API to witryna internetowa, którą można skompilować i hostować w celu wyświetlenia spisu interfejsu API w centrum interfejsu API. Portal umożliwia deweloperom i innym uczestnikom projektu w organizacji odnajdywanie interfejsów API i wyświetlanie szczegółów interfejsu API.

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 interfejsu API platformy Azure do pobierania danych z centrum interfejsu API. Dostęp użytkowników do informacji o interfejsie API jest oparty na kontroli dostępu opartej na rolach platformy Azure.

Implementacja referencyjna portalu centrum interfejsu API zapewnia:

  • Struktura do publikowania i obsługi portalu interfejsu API zarządzanego przez klienta przy użyciu funkcji 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 interfejsu API w ramach subskrypcji platformy 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 interfejsu API.

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

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.

  1. W witrynie Azure Portal przejdź do pozycji Microsoft Entra ID> Rejestracje aplikacji.

  2. Wybierz pozycję + Nowa rejestracja.

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

    • Ustaw nazwę na zrozumiałą nazwę, taką jak api-center-portal

    • W obszarze Obsługiwane typy kont wybierz pozycję Konta w tym katalogu organizacyjnym (pojedyncza dzierżawa).

    • W polu Identyfikator URI przekierowania wybierz pozycję Aplikacja jednostronicowa (SPA) i ustaw identyfikator URI.

      • W przypadku testowania lokalnego ustaw identyfikator URI na https://localhost:5173.
      • W środowisku produkcyjnym ustaw identyfikator URI na identyfikator URI wdrożenia portalu Centrum interfejsu API.

    • Wybierz pozycję Zarejestruj.

  4. Na stronie Przegląd skopiuj identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy). Te wartości są ustawiane podczas tworzenia portalu.

  5. Na stronie Uprawnienia interfejsu API wybierz pozycję + Dodaj uprawnienie.

    1. Na stronie Żądanie uprawnień interfejsu API wybierz kartę Interfejsy API używane przez moją organizację. Wyszukaj i wybierz pozycję Centrum interfejsów API platformy Azure. Możesz również wyszukać i wybrać identyfikator c3ca1a77-7a87-4dba-b8f8-eea115ae4573aplikacji .
    2. Na stronie Żądanie uprawnień wybierz pozycję user_impersonation.
    3. Wybierz Przyznaj uprawnienia.

    Uprawnienia centrum interfejsu API platformy Azure są wyświetlane w obszarze Skonfigurowane uprawnienia.

    Zrzut ekranu przedstawiający wymagane uprawnienia w rejestracji aplikacji Microsoft Entra ID w portalu.

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. Wyewidencjonuj gałąź główną.

    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:

    • Zastąp <service name> wartości i <region> nazwą centrum interfejsu API oraz regionem, w którym został wdrożony
    • Zastąp wartości i <tenant ID> identyfikatorem aplikacji (klienta) oraz identyfikatorem katalogu (dzierżawy) rejestracji aplikacji utworzonej w poprzedniej <client ID> sekcji.
    • Zaktualizuj wartość title na nazwę, która ma być wyświetlana w portalu.
    {
  "dataApiHostName": "<service name>.data.<region>.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 uruchomi portal w trybie programowania uruchomionym lokalnie:

    npm start

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

Wdróż na platformie Azure

Aby uzyskać instrukcje wdrażania portalu w usłudze Azure Static Web Apps, zobacz repozytorium startowe portalu API Center.

Włączanie logowania do portalu przez użytkowników i grupy firmy Microsoft Entra

Użytkownicy muszą się zalogować, aby zobaczyć interfejsy API w centrum interfejsu API. Aby włączyć logowanie, przypisz rolę Czytelnik danych centrum interfejsu API platformy Azure do użytkowników lub grup w organizacji, w zakresie do centrum interfejsu API.

Ważne

Domyślnie ty i inni administratorzy centrum interfejsu API nie mają dostępu do interfejsów API w portalu Centrum interfejsów API. Pamiętaj, aby przypisać rolę Czytelnik danych centrum interfejsu API platformy Azure do siebie i innych administratorów.

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 interfejsu 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:
    • Na stronie Rola wyszukaj i wybierz pozycję Czytelnik danych centrum interfejsów API platformy Azure. Wybierz Dalej.
    • Na stronie Członkowie w obszarze Przypisz dostęp do wybierz pozycję Użytkownik, grupa lub jednostka> usługi+ Wybierz członków.
    • 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 przycisk Dalej.
    • Przejrzyj przypisanie roli i wybierz pozycję Przejrzyj i przypisz.

Uwaga

Aby usprawnić konfigurację dostępu dla nowych użytkowników, zalecamy przypisanie roli do grupy Microsoft Entra i skonfigurowanie reguły członkostwa w grupie dynamicznej. Aby dowiedzieć się więcej, zobacz Tworzenie lub aktualizowanie grupy dynamicznej w identyfikatorze Entra firmy Microsoft.

Po skonfigurowaniu dostępu do portalu skonfigurowani użytkownicy mogą logować się do portalu i wyświetlać interfejsy API w Centrum interfejsów API.

Uwaga

Pierwszy użytkownik, który zaloguje się do portalu, jest monitowany o wyrażenie zgody na uprawnienia żądane przez rejestrację aplikacji w portalu centrum interfejsu API. Następnie inni skonfigurowani użytkownicy nie są monitowani o wyrażenie zgody.

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 centrum interfejsu API platformy Azure 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 interfejsu API.

Nie można wybrać uprawnień centrum interfejsu API platformy Azure w rejestracji aplikacji Microsoft Entra

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

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.

Zasady pomocy technicznej

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

Powiązana zawartość