Nota
O acesso a esta página requer autorização. Podes tentar iniciar sessão ou mudar de diretório.
O acesso a esta página requer autorização. Podes tentar mudar de diretório.
Este artigo ajuda-o a começar a usar a API da Microsoft Learn Platform. Se não estiver familiarizado com os detalhes da API ou os seus casos de uso, recomendamos que consulte primeiro o artigo de Visão Geral da API da Microsoft Learn Platform .
Aprenda Autenticação da API da Plataforma
As APIs REST da Learn Platform utilizam o Microsoft Entra ID para autenticação. Antes de fazer chamadas à API, precisa de escolher um método de acesso, e a sua aplicação cliente deve autenticar-se com credenciais válidas.
Acesso somente ao aplicativo
Quando a sua aplicação acede diretamente ao Learn, o acesso não está ligado a nenhum utilizador individual. A aplicação liga diretamente às APIs usando a sua própria identidade, este cenário é de acesso apenas por app. Saiba mais sobre a Microsoft Identity Platform.
Para começar, precisa de uma identidade válida na Microsoft Identity Platform, que pode ser um registo de aplicação ou uma identidade gerida. Idealmente, cada parceiro deveria ter uma identidade única para simplificar a gestão das quotas e dos parceiros. Utilizar uma identidade gerida atribuída pelo utilizador pode ajudar a unificar identidades geridas entre diferentes serviços.
Depois de configurar a sua identidade do Entra ID, obtenha um token de acesso do Entra ID com o âmbito 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 pedidos de API REST ao Learn.
Acesso delegado
Quando um utilizador inicia sessão na sua aplicação e a usa para aceder ao Learn, a aplicação precisa primeiro de pedir permissão para aceder a este recurso em nome do utilizador. Este cenário chama-se acesso delegado. Saiba mais sobre a Microsoft Identity Platform.
Para começar, é necessário registar um registo de aplicação. Assim que o registo da sua aplicação estiver configurado, a sua aplicação precisa de pedir ao utilizador que conceda um âmbito específico, ou conjunto de escopos, para aceder ao Learn em nome do utilizador. O Learn fornece uma lista de escopos para acesso detalhado a recursos. A lista de âmbitos inclui:
-
https://learn.microsoft.com/PublicContent.Read.All: Este âmbito permite aos utilizadores aceder a conteúdos públicos no Learn como se fossem o utilizador autenticado.
Compreender a Versionação da API da Microsoft Learn Platform
Quando são feitas alterações urgentes à API, lançamos uma nova versão datada. Alterações disruptivas são alterações que podem potencialmente quebrar uma integração. Quaisquer alterações não quebrantes (aditivas) estarão disponíveis em todas as versões da API suportadas.
A versão da API é especificada como parâmetro de consulta de versão API e usa yyyy-MM-dd para versões estáveis e yyyy-MM-dd-preview para versões de pré-visualização. O parâmetro de consulta de versão da API é necessário para cada pedido de API.
Quando uma nova versão estável da API é lançada, a versão estável anterior é suportada por pelo menos mais 24 meses após o lançamento da nova versão da API. As APIs de pré-visualização têm um ciclo de suporte mais curto, de mais três meses, após o lançamento das novas APIs de pré-visualização.
A versão atual é 2023-11-01-preview.
O segmento do URL /v1/ antes de cada API faz parte do URL base, não da versão da API. Está reservado para alterações substanciais de protocolos e padrões de API no futuro.
Aprenda a Limitar a Taxa da API da Plataforma
Learn limita o número de pedidos de API REST que pode fazer num determinado período de tempo. Este limite ajuda a prevenir abusos e ataques de negação de serviço, e garante que a API permanece disponível para todos os utilizadores.
Learn aplica limites de taxa baseando-se na declaração OID no token de acesso. Para o acesso apenas pela aplicação, o limite é aplicado à própria aplicação, enquanto para o acesso delegado, o limite é aplicado ao utilizador que iniciou sessão na aplicação.
Por defeito, o limite de taxa é de 100 chamadas API por minuto, calculado numa janela de 5 minutos. Se precisar de um limite mais elevado para produção, pode contactar o Suporte de Integrações Learn para solicitar um aumento.
Certas APIs, como a API de pesquisa de conhecimento, também implementam limitação de taxa baseada em tokens. Isto baseia-se no número de tokens Microsoft Azure OpenAI consumidos, com um limite padrão de 10.000 tokens por minuto. Para aumentar este limite para produção, contacte o Suporte de Integrações da Aprendizagem.
Aprender Paginação da API da Plataforma
Todos os recursos de API de topo suportam recuperação em massa através de métodos API 'list'. Por exemplo, podes recuperar listas de módulos ou exames. Estes métodos devolvem respostas paginadas seguindo uma abordagem padronizada.
Os métodos da API de listas utilizam paginação baseada em cursor, indicada pelo campo nextLink no corpo da resposta. Este campo contém uma URL opaca com a informação necessária para obter a página seguinte dos resultados. Por defeito, as APIs de listas devolvem 30 itens por pedido, mas pode ajustar o tamanho da página usando o parâmetro maxpagesize.
As nossas bibliotecas de SDK de clientes oferecem ajudantes de autopaginação para percorrer todas as páginas de uma lista.