Почніть з API Microsoft Learn Platform

Ця стаття допоможе вам почати користуватися API Microsoft Learn Platform. Якщо ви не знайомі з деталями API або його кейсами, рекомендуємо спочатку ознайомитися зі статтею Microsoft Learn Platform API Overview (Огляд API Learn Platform ).

Вивчити автентифікацію API платформи

REST API Learn Platform використовують Microsoft Entra ID для автентифікації. Перед викликом API потрібно обрати метод доступу, а клієнтський додаток має автентифікуватися з дійсними обліковими даними.

Доступ лише через додаток

Коли ваш додаток безпосередньо отримує доступ до Learn, його доступ не прив'язаний до жодного користувача. Додаток викликає API напряму, використовуючи власну ідентичність, у цьому випадку доступ лише через додаток. Дізнайтеся більше про платформу Microsoft Identity.

Щоб почати, вам потрібна дійсна ідентифікація на платформі Microsoft Identity Platform, яка може бути реєстрацією додатку або керованою особистістю. Ідеально, якщо кожен партнер має мати єдину ідентичність для спрощення управління квотами та партнерами. Використання керованої ідентичності, призначеної користувачем, може допомогти об'єднати керовані ідентичності між різними сервісами.

Після налаштування вашої ідентичності Entra ID отримайте токен доступу з Entra ID з заданим обсягом як доказ автентифікації. Включайте токен доступу в заголовок авторизації HTTP при виконанні запитів REST API до Learn.

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

Коли користувач входить у ваш додаток і використовує його для доступу до Learn, додаток спочатку повинен попросити дозвіл на доступ до цього ресурсу від імені користувача. Цей сценарій називається делегованим доступом. Дізнайтеся більше про платформу Microsoft Identity.

Щоб почати, потрібно зареєструватися на реєстрацію додатку. Після налаштування реєстрації додатку додаток має попросити користувача надати певний обсяг або набір діапазонів для доступу до Learn від імені користувача. Learn надає перелік сфер доступу до дрібних ресурсів. Список телескопів включає:

• : Цей обсяг дозволяє користувачам отримувати доступ до публічного контенту в Learn, видаючи себе за авторизованого користувача.

Розуміння версій API платформи Microsoft Learn

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

Версія API задається як параметр запиту до api-версії і використовує yyyy-MM-dd для стабільних версій та yy-MM-dd-preview для попередніх версій. Параметр запиту до версії api потрібен для кожного запиту API.

Коли виходить нова стабільна версія API, попередня стабільна версія API підтримується щонайменше ще 24 місяці після виходу нової версії. Попередні API мають коротший цикл підтримки — ще три місяці після виходу нових API.

Поточна версія — 2023-11-01-preview.

Сегмент /v1/ URL перед кожним API є частиною базового URL, а не версії API. Він призначений для суттєвих змін у протоколах API та патернів у майбутньому.

Вивчіть обмеження швидкості API платформи

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

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

За замовчуванням обмеження швидкості становить 100 викликів API на хвилину, розрахованих протягом 5-хвилинного вікна. Якщо вам потрібен вищий ліміт для виробництва, ви можете звернутися до служби підтримки Learn Integrations з проханням про підвищення.

Деякі API, як-от API пошуку знань, також реалізують обмеження швидкості на основі токенів. Це базується на кількості спожитих токенів Microsoft Azure OpenAI, з лімітом за замовчуванням 10 000 токенів за хвилину. Щоб збільшити цей ліміт для виробництва, зверніться до підтримки Learn Integrations.

Пагінування API Learn Platform

Усі ресурси API-ресурсів верхнього рівня підтримують масове отримання через методи API «списку». Наприклад, ви можете отримати списки модулів або іспитів. Ці методи повертають відповіді з пагінацією відповідно до стандартизованого підходу.

Методи API списку використовують пагінацію на основі курсора, що позначається полем nextLink у тілі відповіді. Це поле містить непрозору URL з інформацією, необхідною для отримання наступної сторінки результатів. За замовчуванням API списку повертають 30 елементів на запит, але розмір сторінки можна змінити за допомогою параметра maxpagesize.

Наші клієнтські бібліотеки SDK пропонують помічники з автопагінації для проходження всіх сторінок списку.

Пов’язаний вміст

• Швидкий старт: Налаштуйте та використовуйте дані каталогу API платформи Microsoft Learn
• Learn Platform API Каталог даних для розробника
• Поширені запитання щодо API Learn Platform