Procedimientos recomendados para usar la API de catálogo de Microsoft Learn
En este artículo se describen los procedimientos recomendados para usar la API de catálogo de Learn.
Términos de servicio
Aunque la API de catálogo de Learn está disponible públicamente y su uso es gratuito, los usuarios están sujetos a los Términos de uso de API de Microsoft. Lea y comprenda los términos de uso de la API antes de usar la API del catálogo de Learn y antes de incluir la salida en cualquier entorno de producción.
Limitaciones de la API de catálogo de Learn
Consulte las limitaciones en el artículo Introducción a la API de catálogo de Microsoft Learn.
Descripción del modelo de contenido de Learn
Para hacer un uso eficaz de la respuesta de la API de catálogo de Learn, es importante comprender los tipos de contenido disponibles en Microsoft Learn y de qué forma están relacionados. Consulte el artículo Tipos de contenido de Microsoft Learn para obtener más información.
En particular:
- UID significa Id. único y es único para cada objeto de contenido. Si cambia un UID, aunque el título u otros metadatos permanezcan iguales, el contenido se considera un nuevo objeto.
- Los módulos son el objeto principal del catálogo de aprendizaje de Learn. Todos se pueden realizar de forma independiente, porque enseñan un escenario o concepto íntegramente, sin necesidad de realizar otros módulos previamente. En algunos casos, eso es todo y no forman parte de ninguna ruta de aprendizaje. En otros casos, se agrupan en una o varias rutas de aprendizaje que guían al usuario en el desarrollo de conceptos más avanzados. Un módulo no tiene por qué formar parte de una ruta de aprendizaje, o bien puede formar parte de una o varias rutas de aprendizaje.
- Las unidades no están escritas como contenido independiente. Están pensadas para estudiarlas en un orden específico para el módulo. Por este motivo, se incluye el vínculo a la página de detalles del módulo y la primera unidad para que los usuarios puedan empezar ahí y continuar con el contenido.
Cómo funciona la localización en Learn y cómo se refleja el contenido localizado en la salida de la API
Microsoft Learn admite más de 65 configuraciones regionales en el sitio y gran parte del contenido se traduce en estas configuraciones regionales. Queremos hacer que el contenido esté disponible en todos los idiomas en los que están disponibles los productos que se enseñan en el contenido, pero no todas las experiencias regionales tienen contenido localizado disponible.
Cuando un registro de configuración regional no tiene disponible la traducción asociada, el contenido del sitio y la respuesta de la API se muestran en inglés de forma predeterminada. En la salida de la API, verá metadatos en inglés en otras respuestas de configuración regional cuando se produce la reserva. Sin embargo, la dirección URL del contenido sigue apuntando a la configuración regional, aunque el contenido principal pueda revertirse y el motivo es permitir que el usuario siga navegando por el sitio en esa configuración regional (que muestra el encabezado o pie de página traducidos y cualquier otro vínculo que tenga traducción disponible).
Cuando se publican actualizaciones del contenido en inglés, nuestras canalizaciones de localización funcionan para actualizar las versiones localizadas lo antes posible, normalmente en unos pocos días después del cambio en el original.
Puede ver una lista completa de las configuraciones regionales disponibles en el pie de página del sitio de Microsoft Learn (seleccione el idioma que está viendo). Cada una de estas configuraciones regionales se puede consultar con la API de catálogo de Learn usando el filtro locale.
Nuestros registros de finalización de contenido de aprendizaje son independientes de la configuración regional, es decir, no diferenciamos las versiones localizadas del contenido como objetos independientes en los registros de finalización de actividades de aprendizaje del usuario. Independientemente del idioma en el que un usuario complete un entrenamiento, recibirá crédito para el objeto general y no almacenaremos una referencia al idioma en el que se completó. Esta finalización independiente de la configuración regional significa que si implementa la API del catálogo de Learn en su experiencia de aprendizaje, debe tenerlo en cuenta y, si carga los objetos de contenido en como objetos independientes, implemente una equivalencia entre ellos para que, independientemente del idioma en el que el usuario complete el entrenamiento, obtenga crédito para él en los otros idiomas y no tenga que volver a aceptarlo.
Cómo funciona el control de versiones del contenido de Learn y cómo se refleja en la salida de la API
El contenido se actualiza todo el tiempo. Publicamos actualizaciones disponibles dos veces al día. Pueden ser menores, como pequeños cambios en el texto, o mayores, como revisiones, adiciones o eliminaciones importantes. En general, la cartera de contenido se administra como un proyecto masivo de código abierto muy controlado con miles de colaboradores y, como tal, se están produciendo cambios todo el tiempo. Si usa la API de catálogo de Learn en su sistema de producción, debe tener esto en cuenta y hacer que el sistema pueda controlarlo.
Cuando se agregan nuevos objetos de contenido, aparecen como un nuevo objeto (identificado por UID) en la respuesta. Cuando se modifica el contenido, se puede ver en el valor de last_modified. Cuando se elimina el contenido, el objeto de contenido se quita de la respuesta. Aunque a veces hay un ligero retraso en el contenido que se está actualizando en la respuesta de la API, cuando un usuario sigue la dirección URL del contenido, siempre ve la información más actual. En el caso de eliminaciones, la dirección URL anterior le redirigirá al nuevo contenido o experiencia, o a la siguiente mejor opción.
Actualmente, no hay referencias a las versiones del contenido más allá de la fecha de last_modified.
Actualización periódica de los datos
Si usa la información del catálogo procedente de la API de catálogo de Learn para sustentar sus procesos empresariales o para mostrárselos a los clientes como parte de la experiencia en el sitio, asegúrese de actualizar el contenido al menos una vez al día.
El contenido se actualiza todo el tiempo. Publicamos actualizaciones disponibles dos veces al día. Pueden ser menores, como pequeños cambios en el texto, o mayores, como revisiones, adiciones o eliminaciones importantes. En general, la cartera de contenido se administra como un proyecto masivo de código abierto muy controlado con miles de colaboradores y, como tal, se están produciendo cambios todo el tiempo. Si usa la API de catálogo de Learn en su sistema de producción, debe tener esto en cuenta y hacer que el sistema pueda controlarlo.
Consulta de las recomendaciones que se proporcionan en la documentación para desarrolladores
La documentación de la API de catálogo de Learn para desarrolladores incluye una lista completa de los datos proporcionados en la respuesta y recomendaciones de uso de cada campo para ofrecer experiencias de aprendizaje excelentes.
Lógica de consulta
Hay muchos filtros disponibles para filtrar previamente la respuesta, de modo que solo obtenga lo que busca y pueda controlar tamaños de archivo más pequeños. Puede ver la lista completa de los filtros de consulta en el artículo Documentación de la API de catálogo de Microsoft Learn para desarrolladores. En concreto, debe formar correctamente la consulta y si usa más de un parámetro de consulta en la solicitud, la consulta se evalúa mediante el operador AND.
Pasos siguientes
Para obtener más información que le ayude con la API de catálogo de Learn, consulte los siguientes artículos: