Рекомендации по использованию API каталога Microsoft Learn
В этой статье описаны рекомендации по использованию API каталога Learn.
Общие сведения об условиях обслуживания
Хотя API каталога Learn является общедоступным и бесплатным для использования, пользователи имеют условия использования API Майкрософт. Прочитайте и изучите условия использования API перед использованием API каталога Learn и прежде чем включать выходные данные в любую рабочую среду.
Общие сведения об ограничениях API каталога Learn
См. статью об ограничениях в статье о функциях API каталога Learn.
Общие сведения о con режим палатки l
Чтобы эффективно использовать ответ API каталога Learn, важно понять типы контента, доступные в Microsoft Learn, и их отношения друг с другом. Дополнительные сведения см. в статье Learn con режим палатки l.
Частности:
- 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 содержит полный список данных, предоставленных в ответе, и рекомендации по использованию каждого поля для поддержки большого опыта обучения.
Общие сведения о логике запроса
Существует множество фильтров, которые можно использовать для предварительного фильтрации ответа, чтобы получить только то, что вы ищете, и может обрабатывать меньшие размеры файлов. Полный список фильтров запросов можно просмотреть в справочной статье разработчика API каталога Learn. В частности, необходимо правильно сформировать запрос, и если в запросе используется несколько параметров запроса, запрос оценивается с помощью оператора AND.
Следующие шаги
Дополнительные сведения о поддержке API каталога Learn см. в следующих статьях: