Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Este artigo ajuda você a começar a usar a API da Plataforma Microsoft Learn. Se você não estiver familiarizado com os detalhes da API ou os casos de uso para ela, recomendamos que você examine primeiro o artigo visão geral da API da Plataforma Microsoft Learn .
Autenticação da API da Plataforma Learn
As APIs REST da Plataforma Learn usam a ID do Microsoft Entra para autenticação. Antes de fazer chamadas à API, você precisa escolher um método de acesso e seu aplicativo cliente deve se autenticar com credenciais válidas.
Acesso somente de aplicativo
Quando seu aplicativo acessa diretamente o Learn, seu acesso não está vinculado a nenhum usuário. O aplicativo chama APIs diretamente usando sua própria identidade, esse cenário é acesso somente de aplicativo. Saiba mais na plataforma de identidade da Microsoft.
Para começar, você precisa de uma identidade válida na Plataforma de Identidade da Microsoft, que pode ser um registro de aplicativo ou uma identidade gerenciada. O ideal é que cada parceiro tenha uma única identidade para simplificar o gerenciamento de cotas e parceiros. O uso de uma identidade gerenciada atribuída pelo usuário pode ajudar a unificar identidades gerenciadas em diferentes serviços.
Depois que sua identidade no Entra ID for configurada, obtenha um token de acesso do Entra ID com o escopo definido em https://learn.microsoft.com/.default como prova de autenticação. Inclua o token de acesso no cabeçalho de Autorização HTTP ao fazer solicitações de API REST para o Learn.
Acesso delegado
Quando um usuário entra em seu aplicativo e o usa para acessar o Learn, o aplicativo primeiro precisa pedir permissão para acessar esse recurso em nome do usuário. Esse cenário é chamado de acesso delegado. Saiba mais na plataforma de identidade da Microsoft.
Para começar, você precisa registrar um registro de aplicativo. Depois que o registro do aplicativo for configurado, seu aplicativo precisará pedir ao usuário que conceda um escopo específico ou um conjunto de escopos para acessar o Learn em nome do usuário. O Learn fornece uma lista de escopos para acesso a recursos refinados. A lista de escopos inclui:
-
https://learn.microsoft.com/PublicContent.Read.All: este escopo permite que os usuários acessem conteúdo público no Learn como se fossem o usuário conectado.
Noções básicas sobre o controle de versão da API da Plataforma Microsoft Learn
Quando alterações interruptivas são feitas na API, nós lançamos uma nova versão datada. Alterações interruptivas são alterações que podem potencialmente interromper uma integração. Quaisquer alterações não significativas (aditivas) estarão disponíveis em todas as versões de API com suporte.
A versão da API é especificada como parâmetro de consulta de versão de api e usa yyyy-MM-dd para versões estáveis e yyyyy-MM-dd-preview para versões prévias. O parâmetro de consulta de versão de API é necessário para cada solicitação de API.
Quando uma nova versão estável da API for lançada, a versão anterior da API estável terá suporte por pelo menos mais 24 meses após o lançamento da nova versão da API. As APIs de versão prévia têm um ciclo de suporte mais curto de mais três meses após o lançamento de novas APIs de versão prévia.
A versão atual é 2023-11-01-preview.
O segmento de URL /v1/ antes de cada API é parte da URL base e não da versão da API. Ele é reservado para alterações de padrão e protocolo de API substanciais no futuro.
Limitação de taxa da API da Plataforma Learn
O Learn limita o número de solicitações de API REST que você pode fazer em um período específico. Esse limite ajuda a evitar abusos e ataques de negação de serviço, além de garantir que a API permaneça disponível para todos os usuários.
O Learn aplica limites de taxa com base na declaração oid no token de acesso. Para acesso somente ao aplicativo, o limite é aplicado ao próprio aplicativo, enquanto para acesso delegado, o limite é aplicado ao usuário conectado ao aplicativo.
Por padrão, o limite de taxa é de 100 chamadas à API por minuto, calculadas em uma janela de 5 minutos. Se você precisar de um limite maior para produção, entre em contato com o Suporte do Learn Integrations para solicitar um aumento.
Determinadas APIs, como a API de pesquisa de conhecimento, também implementam a limitação de taxa baseada em token. Isso se baseia no número de tokens do Microsoft Azure OpenAI consumidos, com um limite padrão de 10.000 tokens por minuto. Para aumentar esse limite de produção, entre em contato com o Suporte do Learn Integrations.
Paginação da API do Learn Platform
Todos os recursos de API de nível superior dão suporte à recuperação em massa por meio de métodos de API de 'lista'. Por exemplo, você pode recuperar listas de módulos ou exames. Esses métodos retornam respostas paginadas após uma abordagem padronizada.
Os métodos de API de lista usam paginação baseada em cursor, indicada pelo campo nextLink no corpo da resposta. Esse campo contém uma URL opaca com as informações necessárias para buscar a próxima página de resultados. Por padrão, as APIs de lista retornam 30 itens por solicitação, mas você pode ajustar o tamanho da página usando o parâmetro maxpagesize.
Nossas bibliotecas do SDK do cliente oferecem auxiliares de autopaginação para percorrer todas as páginas de uma lista.