Najlepsze praktyki dotyczące korzystania z interfejsu API katalogu Microsoft Learn

W tym artykule opisano najlepsze praktyki dotyczące korzystania z Learn Catalog API.

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 Katalogu Learn przed jego użyciem i przed dołączeniem wyników w dowolnym środowisku produkcyjnym.

Zrozumienie ograniczeń interfejsu API katalogu Learn

Zobacz ograniczenia w artykule Omówienie funkcji API wykazu Learn.

Omówienie modelu zawartości platformy Learn

Aby efektywnie korzystać z odpowiedzi interfejsu API katalogu Learn, ważne jest, aby zrozumieć typy zawartości dostępne w Microsoft Learn i ich relacje ze sobą. Aby uzyskać więcej informacji, zapoznaj się z artykułem Learn content model (Model zawartości platformy Learn ).

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. Wszystkie mogą działać samodzielnie, w tym sensie, że uczą scenariusza lub koncepcji od początku do końca i nie wymagają podejmowania modułów wstępnych. Dla niektórych to wszystko i nie są częścią ścieżki edukacyjnej. W przypadku innych użytkowników są one połączone w jedną lub więcej ścieżek szkoleniowych, które prowadzą użytkownika przez proces tworzenia bardziej zaawansowanych koncepcji. Moduł nie musi być częścią ścieżki szkoleniowej lub może być częścią co najmniej jednej.
  • Jednostki nie są zapisywane jako samodzielna treść. Muszą one zostać zrealizowane w określonej kolejności w ramach 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ść.

Zrozum, jak działa lokalizacja w usłudze Learn i jak zlokalizowana zawartość jest odzwierciedlana w wynikach 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 dostępne są produkty przedstawione w treści, ale nie wszystkie lokalne doświadczenia mają zlokalizowaną zawartość.

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 procesy lokalizacyjne pracują nad aktualizacją zlokalizowanych wersji 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 Learn Catalog API z filtrem 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 zaliczenie za cały obiekt i nie zapisujemy informacji o tym, w jakim języku zostało ukończone. Lokalizacja niezależna od ustawień regionalnych oznacza, że jeśli zaimplementujesz interfejs API Katalogu Learn w swoim środowisku edukacyjnym, musisz to uwzględnić. Jeżeli załadujesz obiekty zawartości jako oddzielne obiekty, zaimplementuj między nimi równoważność, aby bez względu na język, w którym użytkownik ukończy szkolenie, uzyskał za nie uznanie także w innych językach i nie musiał powtarzać szkolenia.

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 Learn Catalog w systemie produkcyjnym, należy pamiętać o tym i posiadać zdolność jego obsługi.

Po dodaniu nowych obiektów zawartości są one wyświetlane jako nowy obiekt (zidentyfikowany przez UID) w odpowiedzi. Po modyfikacji zawartości można to określić na podstawie wartości last_modified. 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ęć, stary adres URL zostanie przekierowany do nowej zawartości, środowiska lub 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 z katalogu Learn Catalog API 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 katalogu Learn w swoim systemie produkcyjnym, powinieneś być tego świadom i dostosować system do jego obsługi.

Zapoznaj się z zaleceniami dotyczącymi dokumentacji dla deweloperów

Dokumentacja interfejsu API Learn Catalog dla deweloperów zawiera pełną listę danych dostarczanych w odpowiedzi oraz zalecenia dotyczące optymalnego wykorzystania każdego pola, aby wspierać doskonałe doświadczenia edukacyjne.

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 dokumentacji dla deweloperów interfejsu Learn Catalog API (Learn Catalog API Developer reference). 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

Żeby uzyskać więcej informacji na temat wsparcia przy korzystaniu z interfejsu API wykazu Learn, zapoznaj się z następującymi artykułami:

  • Last updated on