Рекомендации по использованию API каталога Microsoft Learn

В этой статье описаны рекомендации по использованию API каталога Learn.

Общие сведения об условиях обслуживания

Хотя API каталога Learn является общедоступным и бесплатным для использования, пользователи имеют условия использования API Майкрософт. Прочитайте и изучите условия использования API перед использованием API каталога Learn и прежде чем включать выходные данные в любую рабочую среду.

Общие сведения об ограничениях API каталога Learn

См. ограничения в статье Обзор возможностей API каталога Learn.

Общие сведения о модели содержимого Learn

Чтобы эффективно использовать ответ API каталога Learn, важно понять типы контента, доступные в Microsoft Learn, и их отношения друг с другом. Дополнительные сведения см. в статье о модели содержимого Learn .

Примечание:

  • UID обозначает уникальный идентификатор и является уникальным для каждого объекта содержимого. Если идентификатор пользовательского интерфейса изменяется, даже если заголовок или другие метаданные остаются неизменными, содержимое считается новым объектом.
  • Модули — это основной объект в каталоге обучения Learn. Они все способны быть автономными, в том смысле, что они охватывают сценарий или концепцию целиком и не требуют прохождения предварительных модулей. Для некоторых это так, и они не являются частью пути обучения. Для других пользователей они объединяются в один или несколько учебных маршрутов, которые проводят пользователя через процесс создания более сложных концепций. Модуль не должен быть частью схемы обучения или может быть частью одного или нескольких.
  • Единицы не записываются как автономное содержимое. Они предназначены для принятия в определенном порядке в рамках модуля. Поэтому мы даем ссылку на страницу сведений о модуле и первый урок, чтобы пользователи могли начать с этого места и продолжить работу с содержимым.

Узнайте, как работает локализация в Learn и как локализованное содержимое отражается в выходных данных API

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

Если для локали отсутствует доступный перевод, содержимое сайта и ответ API переключается на английский язык по умолчанию. В выходных данных API отображаются метаданные на английском в ответах на других языках, когда используется запасной вариант. Однако URL-адрес содержимого по-прежнему указывает на языковой стандарт, несмотря на то, что основное содержимое может вернуться, и причина заключается в том, чтобы разрешить пользователю по-прежнему перемещаться по сайту в этом языковом стандарте (который отображает переведенный верхний или нижний колонтитул и любую другую ссылку, которая имеет доступный перевод).

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

Наши записи завершения содержимого обучения не зависят от языкового стандарта, то есть мы не различаем локализованные версии содержимого как отдельные объекты в записях завершения обучения пользователей. Независимо от того, на каком языке пользователь проходит обучение, он получает зачет за весь объект, и не сохраняем сведения о на каком языке оно было завершено. Это завершение, не зависящее от языкового стандарта, означает, что если вы реализуете API Learn Catalog в вашем обучающем процессе, необходимо это учитывать. Если вы загружаете объекты содержимого как отдельные объекты, реализуйте эквивалентность между ними, чтобы независимо от языка, на котором пользователь проходит обучение, он получал за это зачет на всех языках и не должен был проходить его повторно.

Узнайте, как работает управление версиями содержимого в Learn и как оно отражается в выходных данных API

В частности, содержимое обновляется все время. Мы публикуем доступные обновления дважды в день. Они могут быть незначительными, например незначительными изменениями текста или основными, такими как основные редакции, дополнения или удаления. Как правило, портфель содержимого управляется как массивный, высокоуправляемый проект с открытым исходным кодом с тысячами участников, и, как это, изменения происходят все время. Если вы используете API каталога Learn в рабочей системе, вы должны знать об этом и иметь возможность его обрабатывать.

При добавлении новых объектов содержимого в ответе они отображаются как новый объект (определяемый UID). Когда содержимое изменяется, это можно определить по значению параметра last_modified. При удалении содержимого объект содержимого удаляется из ответа. Хотя в ответе API иногда возникает небольшая задержка при обновлении содержимого, когда пользователь следует URL-адресу содержимого, они всегда будут видеть самые актуальные сведения. В случае удаления старый URL-адрес перенаправляется на новое содержимое или интерфейс или на следующий лучший вариант.

В настоящее время нет ссылок на версии содержимого за пределами last_modified даты.

Регулярное обновление данных

Если вы используете сведения о каталоге из API каталога Learn для поддержки бизнес-процессов или отображения для клиентов в процессе работы с сайтом, убедитесь, что вы обновляете содержимое по крайней мере один раз в день.

В частности, содержимое обновляется все время. Мы публикуем доступные обновления дважды в день. Они могут быть незначительными, например незначительными изменениями текста или основными, такими как основные редакции, дополнения или удаления. Как правило, портфель содержимого управляется как массивный, высокоуправляемый проект с открытым исходным кодом с тысячами участников, и, как это, изменения происходят все время. Если вы используете API каталога Learn в рабочей системе, вы должны знать об этом и иметь возможность его обрабатывать.

Ознакомьтесь с рекомендациями по документации разработчика

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

Общие сведения о логике запроса

Существует множество фильтров, которые можно использовать для предварительного фильтрации ответа, чтобы получить только то, что вы ищете, и может обрабатывать меньшие размеры файлов. Полный список фильтров запросов можно просмотреть в справочной статье разработчика API каталога Learn. В частности, необходимо правильно сформировать запрос, и если в запросе используется несколько параметров запроса, запрос оценивается с помощью оператора AND.

Дальнейшие действия

Дополнительные сведения о работе с API каталога Learn см. в следующих статьях:

  • Last updated on