Практичні поради з використання API каталогу Microsoft Learn

Стаття
02/19/2025

У цій статті описано поради з використання API каталогу Learn.

Ознайомтеся з Умовами надання послуг

Хоча API каталогу Learn загальнодоступний і вільний у використанні, користувачі підпадають під дію Умови використання API Microsoft. Ознайомтеся з умовами використання API та ознайомтеся з ними, перш ніж використовувати API каталогу Learn і перед включенням вихідних даних у будь-якому робочому середовищі.

Розуміння обмежень API каталогу Learn

Див. статтю Обмеження в огляді функцій API каталогу .

Загальні відомості про модель вмісту Learn

Щоб ефективно використовувати відповідь API каталогу Learn, важливо розуміти типи вмісту, доступного в Microsoft Learn, і їхні зв'язки між собою. Докладні відомості див. в статті моделі вмісту Learn.

Зокрема:

Ідентифікатор UID означає унікальний ідентифікатор і унікальний для кожного об'єкта вмісту. Якщо ідентифікатор UID зміниться, навіть якщо заголовок або інші метадані залишаються незмінними, вміст вважається новим об'єктом.
Модулі – це основний об'єкт у каталозі навчальних курсів Learn. Всі вони здатні стояти поодинці, в тому сенсі, що вони навчають сценарію або концепції наскрізного в них і не вимагають прийняття обов'язкових модулів. Для деяких це так, і вони не є частиною навчального шляху. Для інших користувачів вони об'єднуються в один або кілька навчальних шляхів, які допомагають користувачу створювати більш розширені концепції. Модуль не має бути частиною навчального шляху, або він може бути частиною одного або кількох.
Одиниці не написані як автономний вміст. Вони мають бути прийняті в певному порядку для модуля. З цієї причини ми включаємо посилання на сторінку відомостей про модуль і першу одиницю, щоб користувачі могли почати роботу з ним і продовжити роботу з вмістом.

Дізнайтеся, як працює локалізація в learn і як локалізований вміст відображається у виводі API

Microsoft Learn підтримує понад 65 мов на сайті, і значна частина вмісту перекладається на ці мови. Ми прагнемо зробити вміст доступним на всіх мовах, у яких доступні продукти, які викладаються в вмісті, але не всі мовні можливості мають доступний локалізований вміст.

Якщо пов'язаний із цим перекладом запис локалізації недоступний, вміст сайту та відповідь API "повертаються" до англійської мови як стандартний. У виводі API відображаються англійські метадані в інших відповідях локалізації після повернення. Однак URL-адреса вмісту все ще вказує на мову, навіть якщо основний вміст може відкотитися назад, і причина полягає в тому, щоб користувач міг і надалі переходити сайтом у цій локалізації (у якій відображається переклад колонтитула та будь-яке інше посилання з доступним перекладом).

Коли оновлення публікуються в англійському вмісті, наші конвеєри локалізації працюють над тим, щоб локалізовані версії оновилися якомога швидше – зазвичай протягом кількох днів після початкової зміни. Повний список підтримуваних локалізаторів можна переглянути в нижньому колонтитулі сайту Microsoft Learn (виберіть мову, що переглядається). Кожну з цих мов можна запитувати за допомогою API каталогу Learn за допомогою фільтра locale.

Наші записи про завершення навчального вмісту є локалізованими, тобто ми не розрізняємо локалізовані версії вмісту як окремі об'єкти в записах про завершення навчання користувачів. Незалежно від мови, якою користувач завершив навчання, він отримує кредит за загальний об'єкт, і ми не зберігаємо посилання на те, якою мовою його завершено. Це локагностичне завершення означає, що якщо ви впроваджуєте API каталогу Learn у своєму навчальному досвіді, вам потрібно взяти його до уваги і, якщо ви завантажуєте об'єкти вмісту як окремі об'єкти, впроваджуєте рівновідновленість між ними, щоб незалежно від того, якою мовою користувач не завершив навчання, він отримує кредит на них іншими мовами і не повинен його перезаписувати.

Дізнайтеся, як працює керування версіями вмісту в Learn і як воно відображається у виводі API

Примітно, що весь час оновлюється вміст. Ми публікуємо доступні оновлення двічі на день. Вони можуть бути незначними, наприклад незначними змінами тексту або основними, наприклад основними виправленнями, додаваннями або видаленнями. Загалом, портфелем вмісту керується як масовий, висококонкурсований проект із відкритим кодом із тисячами співавторів, і, як такий, зміни відбуваються весь час. Якщо ви використовуєте API каталогу Learn у своїй виробничій системі, ви маєте знати про це та мати можливість працювати з нею.

Коли додаються нові об'єкти вмісту, вони відображаються у відповіді як новий об'єкт (визначений ідентифікатором UID). Коли вміст змінюється, ви можете визначити його last_modified значення. Коли вміст видаляється, об'єкт вмісту видаляється з відповіді. Хоча іноді в відповіді API оновлюється незначна затримка вмісту, коли користувач стежить за URL-адресою вмісту, він завжди бачитиме найновіші відомості. У разі видалення стара URL-адреса переспрямовуватиметься на новий вміст чи можливості або на наступний найкращий варіант.

Наразі немає посилань на версії вмісту, окрім дати last_modified.

Регулярно оновлюйте дані

Якщо відомості про каталог із API каталогу Learn використовуються для підтримки бізнес-процесів або відображення для клієнтів як частини інтерфейсу сайту, переконайтеся, що вміст оновлюється принаймні раз на день.

Перегляньте рекомендації в документації розробника

Документація розробника API каталогу Learn містить повний список даних, наданих у рамках відповіді, і рекомендації щодо того, як кожне поле рекомендовано використовувати для підтримки чудових навчальних можливостей.

Розуміння логіки запиту

Є багато фільтрів, які можна використовувати для попереднього фільтрування відповіді, тому ви отримаєте лише те, що шукаєте, і можете обробляти менші розміри файлів. Повний список фільтрів запитів можна переглянути в довідковій статті розробника API Learn Catalog. Примітно, що потрібно правильно сформувати запит і якщо в запиті використовується кілька параметрів запиту, запит оцінюється за допомогою оператора AND.

Наступні кроки

Докладні відомості про підтримку API каталогу Learn див. в таких статтях:

довідник розробника API каталогу Learn
API каталогу

Поділитися через