Nóta
Teastaíonn údarú chun rochtain a fháil ar an leathanach seo. Is féidir leat triail a bhaint as shíniú isteach nó eolairí a athrú.
Teastaíonn údarú chun rochtain a fháil ar an leathanach seo. Is féidir leat triail a bhaint as eolairí a athrú.
This article assists you in getting started using the Microsoft Learn Platform API. If you aren't familiar with the details of the API or the use cases for it, we recommend you review the Microsoft Learn Platform API Overview article first.
Learn Platform API Authentication
The Learn Platform REST APIs use Microsoft Entra ID for authentication. Before making API calls, you need to choose an access method, and your client application must authenticate with valid credentials.
App-only access
When your app directly accesses Learn, its access isn't tied to any single user. The app calls APIs directly using its own identity, this scenario is app-only access. Learn more on Microsoft identity platform.
To get started, you need a valid identity on the Microsoft Identity Platform, which can be an app registration or a managed identity. Ideally, each partner should have a single identity to simplify quota and partner management. Using a user-assigned managed identity can help unify managed identities across different services.
Once your Entra ID identity is set up, obtain an access token from Entra ID with scope set to https://learn.microsoft.com/.default as proof of authentication. Include the access token in the HTTP Authorization header when making REST API requests to Learn.
Delegated access
When a user signs into your app and uses it to access Learn, the app first needs to ask for permission to access this resource on the user's behalf. This scenario is called delegated access. Learn more on Microsoft identity platform.
To get started, you need to register an app registration. Once your app registration is set up, your app needs to ask the user to grant a specific scope, or set of scopes to access Learn on behalf of the user. Learn provides a list of scopes for fine-grained resource access. The list of scopes include:
https://learn.microsoft.com/PublicContent.Read.All: This scope allows users to access public content on Learn impersonated as the signed-in user.
Understanding Microsoft Learn Platform API Versioning
When breaking changes are made to the API, we release a new, dated version. Breaking changes are changes that can potentially break an integration. Any non-breaking (additive) changes will be available in all supported API versions.
API version is specified as api-version query parameter and uses yyyy-MM-dd for stable versions and yyyy-MM-dd-preview for preview versions. The api-version query parameter is required for every API request.
When a new stable API version is released, the previous stable API version is supported for at least 24 more months following the release of the new API version. Preview APIs have a shorter support cycle of three more months following the release of new preview APIs.
The current version is 2023-11-01-preview.
The /v1/ URL segment before every API is part of the base URL not the API version. It's reserved for substantial API protocol and pattern changes in the future.
Learn Platform API Rate Limiting
Learn limits the number of REST API requests that you can make within a specific amount of time. This limit helps prevent abuse and denial-of-service attacks, and ensures that the API remains available for all users.
Learn applies rate limits based on the oid claim in the access token. For app-only access, the limit is applied to the app itself, while for delegated access, the limit is applied to the user signed in to the app.
By default, the rate limit is 100 API calls per minute, calculated over a 5-minute window. If you require a higher limit for production, you can contact Learn Integrations Support to request an increase.
Certain APIs, like the knowledge search API, also implement token-based rate limiting. This is based on the number of consumed Microsoft Azure OpenAI tokens, with a default limit of 10,000 tokens per minute. To increase this limit for production, contact Learn Integrations Support.
Learn Platform API Pagination
All top-level API resources support bulk retrieval via 'list' API methods. For example, you can retrieve lists of modules or exams. These methods return paginated responses following a standardized approach.
List API methods use cursor-based pagination, indicated by the nextLink field in the response body. This field contains an opaque URL with the information needed to fetch the next page of results. By default, list APIs return 30 items per request, but you can adjust the page size using the maxpagesize parameter.
Our client SDK libraries offer autopagination helpers to traverse all pages of a list.