Najlepsze rozwiązania dotyczące korzystania z interfejsu API wykazu usługi Microsoft Learn
W tym artykule opisano najlepsze rozwiązania dotyczące korzystania z interfejsu API wykazu platformy Learn.
Omówienie warunków użytkowania usługi
Mimo że interfejs API wykazu platformy Learn jest publicznie dostępny i bezpłatny, użytkownicy podlegają warunkom użytkowania interfejsu API firmy Microsoft. Przeczytaj i zapoznaj się z warunkami użytkowania interfejsu API przed użyciem interfejsu API wykazu platformy Learn i przed dołączeniem danych wyjściowych w dowolnym środowisku produkcyjnym.
Omówienie ograniczeń interfejsu API wykazu platformy Learn
Zobacz Artykuł Omówienie funkcji interfejsu API wykazu platformy Learn.
Omówienie witryny Learn con tryb namiotu l
Aby efektywnie korzystać z odpowiedzi interfejsu API wykazu platformy Learn, ważne jest, aby zrozumieć typy zawartości dostępne w środowisku Microsoft Learn i ich relacje ze sobą. Aby uzyskać więcej informacji, zapoznaj się z artykułem Learn con tryb namiotu l.
Szczególności:
- UID oznacza unikatowy identyfikator i jest unikatowy dla każdego obiektu zawartości. Jeśli identyfikator UID zmieni się, nawet jeśli tytuł lub inne metadane pozostaną takie same, zawartość jest traktowana jako nowy obiekt.
- Moduły są podstawowym obiektem w katalogu szkoleniowym usługi Learn. Wszyscy są w stanie stanąć w spokoju, w tym sensie, że uczą scenariusza lub koncepcji end-to-end w nich i nie wymagają podejmowania modułów wymagań wstępnych. Dla niektórych jest to i nie są częścią ścieżki szkoleniowej. W przypadku innych użytkowników są one połączone w jedną lub więcej ścieżek szkoleniowych, które przyjmują użytkownika przez tworzenie bardziej zaawansowanych pojęć. Moduł nie musi być częścią ścieżki szkoleniowej lub może być częścią co najmniej jednej.
- Jednostki nie są zapisywane jako zawartość autonomiczna. Mają one zostać podjęte w określonej kolejności dla modułu. Z tego powodu dołączymy link do strony szczegółów modułu i pierwszą jednostkę, aby użytkownicy mogli tam rozpocząć pracę i przejść przez zawartość.
Informacje o sposobie działania lokalizacji w usłudze Learn i sposobie odzwierciedlenia zlokalizowanej zawartości w danych wyjściowych interfejsu API
Platforma Microsoft Learn obsługuje ponad 65 ustawień regionalnych w witrynie i większość zawartości jest tłumaczona na te ustawienia regionalne. Chcemy udostępnić zawartość we wszystkich językach, w których są dostępne produkty nauczane w treści, ale nie wszystkie środowiska regionalne mają dostęp do zlokalizowanej zawartości.
Jeśli rekord ustawień regionalnych nie ma dostępnego skojarzonego tłumaczenia, zawartość witryny i odpowiedź interfejsu API "wraca" do języka angielskiego jako domyślną. W danych wyjściowych interfejsu API zobaczysz metadane języka angielskiego w innych odpowiedziach regionalnych, gdy nastąpi powrót. Jednak adres URL do zawartości nadal wskazuje ustawienia regionalne, mimo że główna zawartość może wrócić i przyczyną jest umożliwienie użytkownikowi nadal nawigowania po tej witrynie w tych ustawieniach regionalnych (co pokazuje przetłumaczony nagłówek/stopkę i dowolny inny link, który ma dostępne tłumaczenie).
Po opublikowaniu aktualizacji w języku angielskim nasze potoki lokalizacji działają tak szybko, aby zlokalizowane wersje były aktualizowane tak szybko, jak to możliwe — zwykle w ciągu kilku dni od pierwotnej zmiany.
Pełną listę obsługiwanych ustawień regionalnych można wyświetlić w stopce witryny Microsoft Learn (wybierz wyświetlany język). Do każdego z tych ustawień regionalnych można wykonywać zapytania przy użyciu interfejsu API wykazu platformy Learn przy użyciu filtru locale .
Nasze rekordy ukończenia zawartości szkoleniowej są niezależne od ustawień regionalnych, co oznacza, że nie rozróżniamy zlokalizowanych wersji zawartości jako oddzielnych obiektów w naszych rekordach ukończenia trenowania użytkownika. Bez względu na język, w jakim użytkownik ukończy szkolenie, otrzymuje środki na ogólny obiekt i nie przechowujemy odwołania do tego, w jakim języku został ukończony. To niezależne od ustawień regionalnych oznacza zaimplementowanie interfejsu API wykazu platformy Learn w środowisku szkoleniowym, należy wziąć pod uwagę i, jeśli załadujesz obiekty zawartości w oddzielnych obiektach, zaimplementuj równoważność między nimi, aby bez względu na język, w którym użytkownik ukończy szkolenie, uzyska kredyt w innych językach i nie musi go ponownie pobierać.
Dowiedz się, jak działa przechowywanie wersji zawartości w usłudze Learn i jak jest ono odzwierciedlane w danych wyjściowych interfejsu API
W szczególności zawartość jest aktualizowana przez cały czas. Publikujemy dostępne aktualizacje dwa razy dziennie. Mogą one być drobne, takie jak drobne zmiany tekstu lub główne, takie jak główne poprawki, dodatki lub usunięcia. Ogólnie rzecz biorąc, portfolio zawartości jest zarządzane jako ogromny, wysoce zarządzany projekt open source z tysiącami współautorów, a w związku z tym zmiany są wykonywane przez cały czas. Jeśli używasz interfejsu API wykazu platformy Learn w systemie produkcyjnym, należy pamiętać o tym i mieć możliwość obsługi tego systemu.
Po dodaniu nowych obiektów zawartości są one wyświetlane jako nowy obiekt (zidentyfikowany przez UID) w odpowiedzi. Podczas modyfikowania zawartości można określić na podstawie jej last_modified wartości. Po usunięciu zawartości obiekt zawartości zostanie usunięty z odpowiedzi. Chociaż czasami występuje niewielkie opóźnienie w aktualizowaniu zawartości w odpowiedzi interfejsu API, gdy użytkownik podąża za adresem URL do zawartości, zawsze będzie widzieć najbardziej aktualne informacje. W przypadku usunięcia stary adres URL przekierowuje do nowej zawartości lub środowiska albo do następnej najlepszej opcji.
Obecnie nie ma odwołań do wersji zawartości poza datą last_modified .
Regularnie odświeżaj dane
Jeśli używasz informacji katalogu z interfejsu API wykazu platformy Learn do obsługi procesów biznesowych lub wyświetlania klientom w ramach środowiska witryny, upewnij się, że odświeżasz zawartość co najmniej raz dziennie.
W szczególności zawartość jest aktualizowana przez cały czas. Publikujemy dostępne aktualizacje dwa razy dziennie. Mogą one być drobne, takie jak drobne zmiany tekstu lub główne, takie jak główne poprawki, dodatki lub usunięcia. Ogólnie rzecz biorąc, portfolio zawartości jest zarządzane jako ogromny, wysoce zarządzany projekt open source z tysiącami współautorów, a w związku z tym zmiany są wykonywane przez cały czas. Jeśli używasz interfejsu API wykazu platformy Learn w systemie produkcyjnym, należy pamiętać o tym i mieć możliwość obsługi tego systemu.
Zapoznaj się z zaleceniami dotyczącymi dokumentacji dla deweloperów
Dokumentacja dla deweloperów interfejsu API wykazu usługi Learn zawiera pełną listę danych dostarczonych w ramach odpowiedzi oraz zalecenia dotyczące sposobu użycia poszczególnych pól w celu obsługi wspaniałych środowisk szkoleniowych.
Omówienie logiki zapytań
Istnieje wiele filtrów, których można użyć do wstępnego filtrowania odpowiedzi, aby uzyskać tylko to, czego szukasz, i może obsługiwać mniejsze rozmiary plików. Pełną listę filtrów zapytań można znaleźć w artykule Learn Catalog API Developer reference (Dokumentacja dla deweloperów interfejsu API wykazu usługi Learn). W szczególności należy poprawnie utworzyć zapytanie i jeśli używasz więcej niż jednego parametru zapytania w żądaniu, zapytanie jest oceniane przy użyciu operatora AND.
Następne kroki
Aby uzyskać więcej informacji na temat obsługi interfejsu API wykazu platformy Learn, zapoznaj się z następującymi artykułami: