Начало работы с API платформы Microsoft Learn

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

Изучите аутентификацию API платформы

ИНТЕРФЕЙСы REST API платформы Learn используют идентификатор Microsoft Entra для проверки подлинности. Перед вызовами API необходимо выбрать метод доступа, а клиентское приложение должно пройти проверку подлинности с помощью допустимых учетных данных.

Доступ только для приложений

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

Чтобы приступить к работе, вам потребуется действительная учетная запись на платформе идентификации Microsoft, которая может быть регистрацией приложения или управляемым удостоверением. В идеале каждый партнер должен иметь одно удостоверение, чтобы упростить квоту и управление партнерами. Использование управляемого удостоверения, назначаемого пользователем, может помочь объединить управляемые удостоверения между различными службами.

После настройки удостоверения Entra ID получите маркер доступа из Entra ID с областью https://learn.microsoft.com/.default, установленной в качестве подтверждения аутентификации. Включите маркер доступа в заголовок авторизации HTTP при выполнении запросов REST API в Learn.

Делегированный доступ

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

Чтобы приступить к работе, необходимо зарегистрировать регистрацию приложения. После настройки регистрации приложения приложение должно попросить пользователя предоставить определенную область или набор областей для доступа к Learn от имени пользователя. Узнайте больше о списке областей доступа для детального управления доступом к ресурсам. Список областей:

https://learn.microsoft.com/PublicContent.Read.All: Эта область действия позволяет пользователям получать доступ к общедоступному контенту в Learn от имени вошедшего в систему пользователя.

Общие сведения об управлении версиями API платформы Microsoft Learn

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

Версия API указывается в виде параметра запроса api-version и использует формат гггг-ММ-dd для стабильных версий и гггг-ММ-dd-preview для предварительных версий. Для каждого запроса API требуется параметр запроса версии API.

При выпуске новой стабильной версии API предыдущая стабильная версия API поддерживается не менее 24 месяцев после выпуска новой версии API. Интерфейсы API предварительной версии имеют более короткий цикл поддержки сроком в три дополнительных месяца после выпуска новых интерфейсов API предварительной версии.

Текущая версия — 2023-11-01-preview.

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

Узнайте об ограничении скорости API платформы

Узнайте, сколько запросов REST API можно выполнять в течение определенного периода времени. Это ограничение помогает предотвратить злоупотребления и атаки типа "отказ в обслуживании" и гарантирует, что API остается доступным для всех пользователей.

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

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

Некоторые API, такие как API поиска знаний, также реализуют ограничение скорости на основе токенов. Это основано на количестве потребляемых токенов Microsoft Azure OpenAI с ограничением по умолчанию в 10 000 токенов в минуту. Чтобы увеличить это ограничение для рабочей среды, обратитесь в службу поддержки интеграции Learn.

Изучите пагинацию API платформы

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

Методы API списка используют разбиение на страницы на основе курсоров, что указывается полем nextLink в ответе. Это поле содержит непрозрачный URL-адрес со сведениями, необходимыми для получения следующей страницы результатов. По умолчанию API списка возвращают 30 элементов на запрос, но можно настроить размер страницы с помощью параметра maxpagesize.

Наши клиентские библиотеки SDK предлагают вспомогательные средства автопагинации для обхода всех страниц списка.

Last updated on 2026-02-11