Melhores práticas de uso da API de Catálogo do Microsoft Learn

Artigo
05/20/2024

Este artigo descreve as melhores práticas de uso da API de Catálogo do Learn.

Entender os Termos de Serviço

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

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

Confira as limitações no artigo Visão geral do recurso API de Catálogo do Learn.

Entender o modelo de conteúdo do Learn

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

Observação:

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çam iguais, o conteúdo será considerado um novo objeto.
Os módulos são o objeto principal no catálogo de treinamentos do Learn. Todos eles são autônomos, no sentido de ensinar um cenário ou conceito de ponta a ponta neles e não exigem a realização de módulos como pré-requisito. Para alguns deles, é assim, 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 a acompanhar a 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 gravadas como conteúdo autônomo. Elas devem ser seguidas 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 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 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 à API fazer o "fallback" para o inglês como padrão. Na saída da API, você verá metadados em inglês em outras respostas de localidade quando ocorrer fallback. No entanto, a URL para o conteúdo continua apontando para a localidade, mesmo que o conteúdo principal possa fazer fallback 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 em poucos dias após a alteração original. Você pode ver uma lista completa das localidades com suporte no rodapé do site do Microsoft Learn (selecione o idioma que você está exibindo). Cada uma dessas localidades pode ser consultada com a API de 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 consideramos as versões localizadas do conteúdo como objetos separados em nossos registros de conclusão de treinamentos do usuário. Não importa em qual idioma um usuário faça um treinamento, ele recebe crédito pelo objeto geral e não armazenamos uma referência em qual idioma ele foi feito. Essa conclusão independente de localidade significa que, se você implementar a API do Catálogo do Learn em sua experiência de aprendizagem, precisará levar em conta e, se carregar os objetos de conteúdo como objetos separados, implementar uma equivalência entre eles para que, independentemente de qual idioma o usuário conclua o treinamento, obtenha crédito por ele em outros idiomas e não precise retomá-lo.

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

É preciso ressaltar que o conteúdo está sendo atualizado o tempo todo. Publicamos atualizações disponíveis duas vezes por dia. Elas podem ser menores, como pequenas alterações de texto ou grandes, como revisões, adições ou exclusões significativas. Em geral, o portfólio de conteúdo é gerenciado como um projeto de código aberto massivo e altamente controlado, com milhares de colaboradores e, como tal, as alterações acontecem o tempo todo. Se você usar a API de Catálogo do Learn em seu sistema de produção, deverá estar ciente disso e seu sistema deverá lidar com isso.

Quando novos objetos de conteúdo são adicionados, eles aparecem como um novo objeto (identificado pelo UID) na resposta. Quando o conteúdo é modificado, é possível saber com base no 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 da API, quando um usuário segue a URL até o conteúdo, ele sempre verá as informações mais atuais. Em caso de exclusões, o URL antigo redirecionará 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 no momento além da data last_modified.

Atualizar os dados regularmente

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

Examine as recomendações da documentação para desenvolvedores

A documentação para desenvolvedores da API de Catálogo do Learn tem uma lista completa dos dados fornecidos como parte da resposta, além de recomendações sobre o uso de cada campo para dar suporte a ótimas experiências de aprendizagem.

Entender a lógica de consulta

Há muitos filtros disponíveis para pré-filtrar a resposta, para que você obtenha apenas o que está procurando e possa ter tamanhos de arquivo menores. Você pode ver a lista completa de filtros de consulta no artigo de referência para desenvolvedores da API de 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 sobre como dar suporte à API de Catálogo do Learn, leia os seguintes artigos:

Compartilhar via