Práticas recomendadas para usar a API do Catálogo do Microsoft Learn

Este artigo descreve as práticas recomendadas para usar a API do Catálogo do Learn.

Entender os Termos de Serviço

Embora a API do Catálogo do Learn esteja disponível publicamente e gratuitamente para uso, os usuários estão sujeitos aos Termos de Uso da API da Microsoft. Leia e entenda os Termos de Uso da API antes de usar a API do Catálogo do Learn e antes de incluir a saída em qualquer ambiente de produção.

Entender as limitações da API do Catálogo do Learn

Consulte as limitações na seção Visão Geral de Recursos da API do Catálogo Learn do artigo.

Entender o modelo de conteúdo do Learn

Para usar a resposta da API do Catálogo do Learn com eficiência, é importante entender os tipos de conteúdo disponíveis no Microsoft Learn e suas relações entre si. Examine o artigo do modelo de conteúdo do Learn para obter mais informações.

Notavelmente:

• UID significa ID Exclusiva e é exclusiva para cada objeto de conteúdo. Se uma UID for alterada, mesmo que o título ou outros metadados permaneça o mesmo, o conteúdo será considerado um novo objeto.
• Os módulos são o objeto principal dentro do catálogo de treinamento do Learn. Todos eles são capazes de funcionar de forma independente, no sentido de que ensinam completamente um cenário ou conceito em si mesmos e não exigem a realização de módulos de pré-requisito. Para alguns, é isso e eles não fazem parte de um roteiro de aprendizagem. Para outros, eles são agrupados em um ou mais roteiros de aprendizagem que levam um usuário através da criação de conceitos mais avançados. Um módulo não precisa fazer parte de um roteiro de aprendizagem ou pode fazer parte de um ou mais.
• As unidades não são escritas como conteúdo autônomo. Eles têm a intenção de serem executados em uma ordem específica para o módulo. Por esse motivo, incluímos o link para a página de detalhes do módulo e a primeira unidade para que os usuários possam começar por lá e prosseguir com o conteúdo.

Entender como a localização funciona no Learn e como o conteúdo localizado é refletido na saída da API

O Microsoft Learn dá suporte a mais de 65 localidades no site e grande parte do conteúdo é traduzido para essas localidades. Pretendemos disponibilizar o conteúdo em todos os idiomas em que os produtos que estão sendo ensinados no conteúdo estão disponíveis, mas nem todas as experiências de localidade têm conteúdo localizado disponível.

Quando um registro de localidade não tem a tradução associada disponível, o conteúdo no site e a resposta da API "recuam" para o inglês como o padrão. Na saída da API, você verá metadados em inglês nas respostas de outras localidades quando ocorrer um fallback. No entanto, a URL para o conteúdo ainda aponta para a localidade, mesmo que o conteúdo principal possa recuar e o motivo é permitir que o usuário ainda navegue pelo site nessa localidade (que mostra o cabeçalho/rodapé traduzido e qualquer outro link que tenha a tradução disponível).

Quando as atualizações são publicadas no conteúdo em inglês, nossos pipelines de localização funcionam para que as versões localizadas sejam atualizadas o mais rápido possível – geralmente dentro de alguns dias da alteração original. Você pode ver uma lista completa de localidades com suporte no rodapé do site do Microsoft Learn (selecione no idioma que você está exibindo). Cada uma dessas localidades pode ser consultada com a API do Catálogo do Learn usando o filtro locale.

Nossos registros de conclusão de conteúdo de treinamento são independentes de localidade, ou seja, não diferenciamos versões localizadas do conteúdo como objetos separados em nossos registros de conclusão de treinamento do usuário. Não importa em qual idioma um usuário conclua um treinamento, ele recebe crédito pelo objeto geral e não armazenamos uma referência em qual idioma ele foi concluído. Essa conclusão independente de localidade significa que, se você implementar a API do Catálogo Learn em sua experiência de aprendizagem, é necessário considerá-la. Se você carregar os objetos de conteúdo como objetos separados, deve implementar uma equivalência entre eles. Isso garante que, independentemente do idioma em que o usuário conclua o treinamento, ele receba crédito por ele nos outros idiomas e não precise refazer o treinamento.

Entender como o controle de versão de conteúdo funciona no Learn e como ele é refletido na saída da API

Notavelmente, o conteúdo está sendo atualizado o tempo todo. Publicamos atualizações disponíveis duas vezes por dia. Elas podem ser secundárias, como pequenas alterações de texto ou principais, como revisões principais, adições ou exclusões. Em geral, o portfólio de conteúdo é gerenciado como um projeto de software livre massivo e altamente controlado com milhares de colaboradores e, como tal, as alterações estão acontecendo o tempo todo. Se você usar a API do Catálogo do Learn em seu sistema de produção, deverá estar ciente disso e ter seu sistema capaz de lidar com isso.

Quando novos objetos de conteúdo são adicionados, eles aparecem como um novo objeto (identificado por UID) na resposta. Quando o conteúdo é modificado, você pode identificar com base em seu valor last_modified. Quando o conteúdo é excluído, o objeto de conteúdo é removido da resposta. Embora às vezes haja um pequeno atraso no conteúdo que está sendo atualizado na resposta à API, quando um usuário segue a URL para o conteúdo, ele sempre verá as informações mais atuais. No caso de exclusões, a URL antiga será redirecionada para o novo conteúdo ou experiência ou para a próxima melhor opção.

Não há referências a versões de conteúdo neste momento após a data de last_modified.

Atualizar os dados regularmente

Se você estiver usando as informações de catálogo da API do Catálogo do Learn para dar suporte aos processos de negócios ou exibindo para clientes como parte da experiência do site, atualize o conteúdo pelo menos uma vez por dia.

Notavelmente, o conteúdo está sendo atualizado o tempo todo. Publicamos atualizações disponíveis duas vezes por dia. Elas podem ser secundárias, como pequenas alterações de texto ou principais, como revisões principais, adições ou exclusões. Em geral, o portfólio de conteúdo é gerenciado como um projeto de software livre massivo e altamente controlado com milhares de colaboradores e, como tal, as alterações estão acontecendo o tempo todo. Se você usar a API do Catálogo do Learn em seu sistema de produção, deverá estar ciente disso e ter seu sistema capaz de lidar com isso.

Examine as recomendações da documentação do desenvolvedor

A documentação do desenvolvedor da API do Catálogo do Learn tem uma lista completa dos dados fornecidos como parte da resposta e recomendações sobre como cada campo é recomendado para ser usado para dar suporte a ótimas experiências de aprendizado.

Entender a lógica da consulta

Há muitos filtros disponíveis para usar para pré-filtrar a resposta, de modo que você só obtenha o que está procurando e possa lidar com tamanhos de arquivo menores. Você pode ver a lista completa de filtros de consulta no artigo de referência para desenvolvedores da API do Catálogo do Learn . Notavelmente, você precisa formar a consulta corretamente e, se estiver usando mais de um parâmetro de consulta na solicitação, a consulta será avaliada usando o operador AND.

Próximas etapas

Para obter mais informações para dar suporte a você com a API do Catálogo do Learn, examine os seguintes artigos:

• Referência para desenvolvedores da API do Catálogo Learn
• perguntas frequentes sobre a API do Catálogo do Learn