Włączanie i wyświetlanie wykazu interfejsów API platformy Azure API Center

W tym artykule pokazano, jak zapewnić deweloperom przedsiębiorstwa dostęp do katalogu interfejsów API platformy Azure Api Center (wersja zapoznawcza) w rozszerzeniu programu Visual Studio Code dla Centrum interfejsów API platformy Azure. Korzystając z katalogu interfejsów API platformy, deweloperzy mogą odnajdywać interfejsy API w centrum interfejsu API platformy Azure, wyświetlać definicje interfejsów API i opcjonalnie generować klientów interfejsów API, gdy nie mają dostępu do zarządzania samym centrum interfejsu API lub dodawać interfejsy API do spisu. Dostęp do katalogu interfejsów API platformy jest zarządzany przy użyciu identyfikatora Entra firmy Microsoft i kontroli dostępu opartej na rolach platformy Azure.

Napiwek

Rozszerzenie programu Visual Studio Code udostępnia więcej funkcji dla deweloperów interfejsu API, którzy mają uprawnienia do zarządzania centrum interfejsu API platformy Azure. Na przykład deweloperzy interfejsów API mogą bezpośrednio rejestrować interfejsy API w centrum interfejsu API lub przy użyciu potoków ciągłej integracji/ciągłego wdrażania. Dowiedz się więcej

Wymagania wstępne

Dla administratorów centrum interfejsu API

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

Dla deweloperów aplikacji

• Rozszerzenie Centrum interfejsu API platformy Azure dla programu Visual Studio Code

  Ważne

  Obecnie dostęp do katalogu interfejsu API platformy jest dostępny tylko w wersji wstępnej rozszerzenia. Podczas instalowania rozszerzenia z witryny Marketplace programu Visual Studio Code możesz zainstalować wersję wydania lub wersję wstępną. Przełączanie między dwiema wersjami w dowolnym momencie przy użyciu menu kontekstowego przycisku Zarządzaj rozszerzeniem w widoku Rozszerzenia.

Następujące rozszerzenie programu Visual Studio Code jest opcjonalne:

• Rozszerzenie Microsoft Kiota — generowanie klientów interfejsu API

Kroki dla administratorów centrum interfejsu API w celu umożliwienia dostępu do katalogu

W poniższych sekcjach przedstawiono kroki dla administratorów centrum interfejsu API, aby umożliwić deweloperom przedsiębiorstwa dostęp do katalogu interfejsów API platformy.

Tworzenie rejestracji aplikacji Microsoft Entra

Najpierw skonfiguruj rejestrację aplikacji w dzierżawie identyfikatora entra firmy Microsoft. Rejestracja aplikacji umożliwia rozszerzenie programu Visual Studio Code dla centrum interfejsów API platformy w celu uzyskania dostępu do katalogu interfejsu API platformy 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 platform-api-catalog
   • 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 na identyfikator URI środowiska uruchomieniowego centrum interfejsu API. Na przykład https://<service name>.data.<region>.azure-apicenter.ms. Przykład: https://contoso-apic.data.eastus.azure-apicenter.ms.
   • Wybierz pozycję Zarejestruj.

   Napiwek

   Możesz użyć tej samej rejestracji aplikacji, aby uzyskać dostęp do większej liczby centrów interfejsów API. W obszarze Identyfikator URI przekierowania dodaj identyfikatory URI przekierowania dla innych centrów interfejsów API, które mają być wyświetlane w katalogu interfejsów API platformy.

4. Na stronie Przegląd skopiuj identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy). Te wartości są ustawiane później podczas nawiązywania połączenia z centrum interfejsu API z rozszerzenia programu Visual Studio Code.

5. W menu po lewej stronie w obszarze Zarządzanie wybierz pozycję Uwierzytelnianie>+ Dodaj platformę.

6. Na stronie Konfigurowanie platform wybierz pozycję Aplikacje mobilne i klasyczne.

7. Na stronie Konfigurowanie pulpitu i urządzeń wprowadź następujący identyfikator URI przekierowania i wybierz pozycję Konfiguruj:

   https://vscode.dev/redirect

8. W menu po lewej stronie w obszarze Zarządzanie wybierz pozycję Uprawnienia> interfejsu API+ Dodaj uprawnienie.

9. Na stronie Żądania uprawnień interfejsu API wykonaj następujące czynności:

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

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

   

Włączanie logowania do katalogu interfejsów API platformy według użytkowników i grup firmy Microsoft Entra

Deweloperzy w przedsiębiorstwie muszą zalogować się przy użyciu konta Microsoft, aby wyświetlić wykaz interfejsów API platformy dla centrum interfejsu API. W razie potrzeby dodaj lub zaproś deweloperów do dzierżawy firmy Microsoft Entra.

Następnie, aby włączyć logowanie, przypisz rolę Czytelnik danych centrum interfejsu API platformy Azure do użytkowników lub grup w dzierżawie, w zakresie do centrum interfejsu API.

Ważne

Domyślnie ty i inni administratorzy centrum interfejsów API nie mają dostępu do interfejsów API w katalogu interfejsów API platformy rozszerzenia usługi API Center. 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.
4. Powtórz powyższe kroki, aby włączyć logowanie do katalogu interfejsów API platformy w celu uzyskania większej liczby centrów interfejsów API.

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.

Procedura uzyskiwania dostępu do katalogu interfejsów API platformy dla deweloperów w przedsiębiorstwie

Deweloperzy mogą wykonać następujące kroki, aby nawiązać połączenie i zalogować się, aby wyświetlić wykaz interfejsów API platformy przy użyciu rozszerzenia programu Visual Studio Code. Ustawienia umożliwiające nawiązanie połączenia z centrum interfejsu API muszą być udostępniane przez administratora centrum interfejsu API.

Nawiązywanie połączenia z centrum interfejsu API

1. Zainstaluj wersję wstępną rozszerzenia Centrum interfejsu API platformy Azure dla programu Visual Studio Code dla programu Visual Studio Code .

2. W programie Visual Studio Code na pasku działań po lewej stronie wybierz pozycję Centrum interfejsu API.

   

3. Użyj skrótu klawiaturowego Ctrl+Shift+P , aby otworzyć paletę poleceń. Wpisz Centrum interfejsów API platformy Azure: Połącz się z Centrum interfejsów API i naciśnij Enter.

4. Odpowiedz na monity, aby wprowadzić następujące informacje:

   1. Adres URL środowiska uruchomieniowego centrum interfejsu API w formacie <service name>.data.<region>.azure-apicenter.ms (nie prefiksuj za pomocą https://polecenia ). Przykład: contoso-apic.data.eastus.azure-apicenter.ms. Ten adres URL środowiska uruchomieniowego jest wyświetlany na stronie Przegląd centrum interfejsu API w witrynie Azure Portal.
   2. Identyfikator aplikacji (klienta) z rejestracji aplikacji skonfigurowanej przez administratora w poprzedniej sekcji.
   3. Identyfikator katalogu (dzierżawy) z rejestracji aplikacji skonfigurowanej przez administratora w poprzedniej sekcji.

   Napiwek

   Administrator centrum interfejsu API musi podać te szczegóły połączenia deweloperom lub udostępnić bezpośredni link w następującym formacie:
   vscode://apidev.azure-api-center?clientId=<Client ID>&tenantId=<tenant ID>&runtimeUrl=<service-name>.data.<region>.azure-apicenter.ms

   Po nawiązaniu połączenia z centrum interfejsu API nazwa centrum interfejsu API zostanie wyświetlona w katalogu interfejsu API Centrum interfejsów API.

5. Aby wyświetlić interfejsy API w centrum interfejsu API, w obszarze nazwa centrum interfejsu API wybierz pozycję Zaloguj się na platformie Azure. Logowanie jest dozwolone przy użyciu konta Microsoft, które ma przypisaną rolę Czytelnik danych centrum interfejsu API platformy Azure w centrum interfejsu API.

   

6. Po zalogowaniu wybierz pozycję Interfejsy API, aby wyświetlić listę interfejsów API w centrum interfejsu API. Rozwiń interfejs API, aby eksplorować jego wersje i definicje.

   

7. Powtórz powyższe kroki, aby nawiązać połączenie z więcej centrów interfejsów API, jeśli jest skonfigurowany dostęp.

Odnajdywanie i używanie interfejsów API w wykazie

Wykaz interfejsów API platformy ułatwia deweloperom przedsiębiorstwa odnajdywanie szczegółów interfejsu API i rozpoczynanie opracowywania klienta interfejsu API. Deweloperzy mogą uzyskać dostęp do następujących funkcji, klikając prawym przyciskiem myszy definicję interfejsu API w katalogu interfejsów API platformy:

• Eksportowanie dokumentu specyfikacji interfejsu API — eksportowanie specyfikacji interfejsu API z definicji, a następnie pobieranie jej jako pliku
• Generowanie klienta interfejsu API — użyj rozszerzenia Microsoft Kiota, aby wygenerować klienta interfejsu API dla swojego ulubionego języka
• Generowanie znaczników Markdown — generowanie dokumentacji interfejsu API w formacie Markdown
• Dokumentacja interfejsu OpenAPI — wyświetl dokumentację definicji interfejsu API i spróbuj wykonać operacje w interfejsie użytkownika struktury Swagger (dostępne tylko dla definicji interfejsu OpenAPI)

Rozwiązywanie problemów

Błąd: Nie można odczytać właściwości niezdefiniowanych (czytanie 'nextLink')

W pewnych warunkach użytkownik może napotkać następujący komunikat o błędzie po zalogowaniu się do katalogu interfejsu API Centrum interfejsów API i rozwinięciu listy interfejsów API dla centrum interfejsu API:

Error: Cannot read properties of undefined (reading 'nextLink')

Sprawdź, czy użytkownik ma przypisaną rolę Czytelnik danych centrum interfejsu API platformy Azure w centrum interfejsu API. W razie potrzeby ponownie przypisz rolę użytkownikowi. Następnie odśwież katalog interfejsu API platformy API Center w rozszerzeniu programu Visual Studio Code.

Nie można zalogować się na platformie Azure

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ę do platformy Azure w katalogu interfejsu API platformy, może wystąpić problem z konfiguracją połączenia.

Sprawdź ustawienia w rejestracji aplikacji skonfigurowanej w usłudze Microsoft Entra ID. Potwierdź wartości identyfikatora aplikacji (klienta) i identyfikatora katalogu (dzierżawy) w rejestracji aplikacji oraz adresu URL środowiska uruchomieniowego centrum interfejsu API. Następnie ponownie skonfiguruj połączenie z centrum interfejsu API.

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

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.

Powiązana zawartość

• Kompilowanie i rejestrowanie interfejsów API za pomocą rozszerzenia Centrum interfejsów API platformy Azure dla programu Visual Studio Code
• Najlepsze rozwiązania dotyczące kontroli dostępu opartej na rolach platformy Azure
• Rejestrowanie dostawcy zasobów