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

Artigo
05/16/2024

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

Compreender os Termos de Serviço

Embora a API do Catálogo do Learn esteja disponível publicamente e seja gratuita, os usuários estão sujeitos aos Termos de Uso da API da Microsoft. Leia e compreenda 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.

Compreender as limitações da API do Learn Catalog

Consulte Limitações no artigo de visão geral do recurso da API do Learn Catalog.

Compreender o modelo de conteúdo do Learn

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

Nomeadamente:

UID significa Unique ID e é exclusivo para cada objeto de conteúdo. Se um UID for alterado, mesmo que o título ou outros metadados permaneçam os mesmos, o conteúdo será considerado um novo objeto.
Os módulos são o objeto central dentro do catálogo de treinamento do Learn. Todos eles são capazes de ficar sozinhos, no sentido de que ensinam um cenário ou conceito de ponta a ponta dentro deles e não exigem módulos de pré-requisitos. Alguns não fazem parte de um percurso de aprendizagem. Outros estão agrupados num ou em mais percursos de aprendizagem que levam um utilizador a acompanhar a criação de conceitos mais avançados. Um módulo não precisa de fazer parte de um percurso de aprendizagem ou pode fazer parte de um ou mais.
As unidades não são escritas como conteúdo independente. Devem ser seguidas por uma ordem específica no módulo. Por este motivo, incluímos a ligação para a página de detalhes do módulo e a primeira unidade para que os utilizadores possam começar lá e prosseguir ao longo do 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 oferece suporte a mais de 65 localidades no site e grande parte do conteúdo é traduzido para essas localidades. Nosso objetivo é disponibilizar o conteúdo em todos os idiomas em que os produtos 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 do site e a resposta da API "retornam" ao inglês como padrão. Na saída da API, você vê metadados em inglês em outras respostas de localidade quando o fallback acontece. No entanto, a URL para o conteúdo ainda aponta para a localidade, mesmo que o conteúdo principal possa cair para trás e o motivo é permitir que o usuário ainda navegue no site nessa localidade (que mostra o cabeçalho/rodapé traduzido e qualquer outro link que tenha tradução disponível).

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

Nossos registros de conclusão de conteúdo de treinamento são agnósticos à localidade, ou seja, não diferenciamos versões localizadas de 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 ao idioma em que ele foi concluído. 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á levá-la em consideração e, se carregar os objetos de conteúdo como objetos separados, implementar uma equivalência entre eles para que, independentemente do idioma em que o usuário conclua o treinamento, ele obtenha crédito por ele nos outros idiomas e não precise retomá-lo.

Entenda 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. Podem ser menores, como pequenas alterações de texto, ou maiores, como grandes revisões, adições ou exclusões. Em geral, o portfólio de conteúdo é gerenciado como um projeto de código aberto massivo e altamente governado com milhares de contribuidores e, como tal, mudanças estão acontecendo o tempo todo. Se você usa a API do Learn Catalog em seu sistema de produção, deve 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 pelo UID) na resposta. Quando o conteúdo é modificado, você pode saber 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 na atualização do conteúdo na resposta da API, quando um usuário segue a URL do conteúdo, ele sempre verá as informações mais atuais. No 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 last_modified data.

Atualize os dados regularmente

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

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

A documentação do desenvolvedor da API do Learn Catalog 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 aprendizagem.

Compreender a lógica da consulta

Há muitos filtros disponíveis para usar para pré-filtrar a resposta, para que você obtenha apenas 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 do Learn Catalog API Developer. 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óximos passos

Para obter mais informações para apoiá-lo com a API do Catálogo do Learn, revise os seguintes artigos:

Partilhar via