Rozpocznij korzystanie z interfejsu API platformy Microsoft Learn

Ten artykuł ułatwia rozpoczęcie korzystania z interfejsu API platformy Microsoft Learn. Jeśli nie znasz szczegółów interfejsu API lub przypadków użycia, zalecamy zapoznanie się z artykułem Omówienie interfejsu API platformy Microsoft Learn .

Poznaj uwierzytelnianie interfejsu API platformy

Interfejsy API REST platformy Learn używają Tożsamość Microsoft Entra do uwierzytelniania. Przed wywołaniami interfejsu API należy wybrać metodę dostępu, a aplikacja kliencka musi uwierzytelniać się przy użyciu prawidłowych poświadczeń.

Dostęp tylko do aplikacji

Gdy aplikacja uzyskuje bezpośredni dostęp do usługi Learn, jej dostęp nie jest powiązany z żadnym pojedynczym użytkownikiem. Aplikacja wywołuje interfejsy API bezpośrednio przy użyciu własnej tożsamości. Ten scenariusz jest dostępem tylko do aplikacji. Dowiedz się więcej na temat platformy tożsamości firmy Microsoft.

Aby rozpocząć, potrzebujesz prawidłowej tożsamości na platformie tożsamości Microsoft, która może być rejestracją aplikacji lub tożsamością zarządzaną. W idealnym przypadku każdy partner powinien mieć jedną tożsamość, aby uprościć limit przydziału i zarządzanie partnerami. Użycie tożsamości zarządzanej przypisanej przez użytkownika może pomóc w ujednoliceniu tożsamości zarządzanych w różnych usługach.

Po skonfigurowaniu tożsamości Entra ID uzyskaj token dostępu z Entra ID z ustawionym zakresem jako w celu potwierdzenia uwierzytelnienia. Dołącz token dostępu w nagłówku autoryzacji HTTP podczas wprowadzania żądań interfejsu API REST do usługi Learn.

Dostęp delegowany

Gdy użytkownik loguje się do aplikacji i używa jej do uzyskiwania dostępu do usługi Learn, aplikacja musi najpierw poprosić o uprawnienie dostępu do tego zasobu w imieniu użytkownika. Ten scenariusz jest nazywany dostępem delegowanym. Dowiedz się więcej na temat platformy tożsamości firmy Microsoft.

Aby rozpocząć, musisz zarejestrować rejestrację aplikacji. Po skonfigurowaniu rejestracji aplikacji aplikacja musi poprosić użytkownika o udzielenie określonego zakresu lub zestaw zakresów w celu uzyskania dostępu do usługi Learn w imieniu użytkownika. Poznaj listę zakresów umożliwiających dostęp do zasobów z wysoką szczegółowością. Lista zakresów obejmuje:

• : Ten zakres umożliwia użytkownikom dostęp do publicznej zawartości w usłudze Learn personifikowany jako zalogowany użytkownik.

Zrozumienie wersjonowania interfejsu API platformy Microsoft Learn

Po wprowadzeniu zmian powodujących niezgodność w interfejsie API publikujemy nową wersję oznaczoną datą. Istotne zmiany to zmiany, które mogą potencjalnie przerwać integrację. Wszelkie zmiany niepowodujące niezgodności (addytywne) będą dostępne we wszystkich wersjach obsługiwanego API.

Wersja interfejsu API jest określona jako parametr zapytania api-version i używa yyyy-MM-dd dla stabilnych wersji oraz yyyy-MM-dd-preview dla wersji zapoznawczych. Parametr zapytania "api-version" jest wymagany przy każdym żądaniu do interfejsu API.

Po wydaniu nowej stabilnej wersji interfejsu API poprzednia stabilna wersja interfejsu API jest obsługiwana przez co najmniej 24 miesiące po wydaniu nowej wersji interfejsu API. Interfejsy API w wersjach zapoznawczych mają krótszy cykl wsparcia, który wynosi trzy miesiące od momentu wydania nowych wersji preview API.

Bieżąca wersja to 2023-11-01-preview.

Segment /v1/ URL przed każdym interfejsem API jest częścią podstawowego adresu URL, a nie wersji interfejsu API. Jest on zarezerwowany dla znaczących zmian protokołu i wzorca interfejsu API w przyszłości.

Ograniczenia szybkości interfejsu API Learn Platform

Learn ogranicza liczbę żądań interfejsu API REST, jakie można wykonać w określonym czasie. Ten limit pomaga zapobiegać nadużyciom i atakom typu "odmowa usługi" oraz zapewnia dostępność interfejsu API dla wszystkich użytkowników.

Limity szybkości są stosowane na podstawie oświadczenia oid w tokenie dostępu. W przypadku dostępu tylko do aplikacji limit jest stosowany na samą aplikację, podczas gdy w przypadku dostępu delegowanego limit jest stosowany do użytkownika zalogowanego do aplikacji.

Domyślnie limit szybkości to 100 wywołań interfejsu API na minutę, obliczanych w 5-minutowym oknie. Jeśli potrzebujesz wyższego limitu dla środowiska produkcyjnego, możesz skontaktować się z pomocą techniczną platformy Learn Integrations, aby poprosić o zwiększenie.

Niektóre interfejsy API, takie jak interfejs API wyszukiwania wiedzy, implementują również ograniczanie szybkości oparte na tokenach. Jest to oparte na liczbie użytych Microsoft Azure tokenów OpenAI z domyślnym limitem 10 000 tokenów na minutę. Aby zwiększyć ten limit dla środowiska produkcyjnego, skontaktuj się z pomocą techniczną Learn Integrations.

Stronicowanie interfejsu API platformy learn

Wszystkie zasoby interfejsu API najwyższego poziomu obsługują pobieranie zbiorcze za pomocą metod interfejsu API "list". Możesz na przykład pobrać listy modułów lub egzaminów. Te metody zwracają odpowiedzi podzielone na strony zgodnie z ustandaryzowanym podejściem.

Metody API list wykorzystują stronicowanie oparte na kursorze, co jest wskazane przez pole nextLink w treści odpowiedzi. To pole zawiera nieprzezroczysty adres URL zawierający informacje potrzebne do pobrania następnej strony wyników. Domyślnie interfejsy API listy zwracają 30 elementów na żądanie, ale można dostosować rozmiar strony przy użyciu parametru maxpagesize.

Nasze biblioteki klienta SDK oferują narzędzia do autopaginacji, które umożliwiają przeglądanie wszystkich stron listy.

Treści powiązane

• Szybki start: konfigurowanie i używanie danych wykazu interfejsów API platformy Microsoft Learn
• Dokumentacja dla deweloperów korzystających z danych katalogu API Platformy
• Interfejs API platformy Learn — często zadawane pytania