Procedimientos recomendados para usar la API del catálogo de Microsoft Learn
En este artículo se describen los procedimientos recomendados para usar la API de catálogo de Learn.
Descripción de los términos de servicio
Aunque la API del catálogo de Learn está disponible públicamente y es gratuita para su uso, los usuarios están sujetos a los términos de uso de la 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.
Descripción de las limitaciones de learn Catalog API
Consulte las limitaciones en el artículo "Visión General de las Características de la API del Catálogo de Learn" .
Descripción del modelo de contenido de Learn
Para poder usar la respuesta de la API del catálogo de Learn de forma eficaz, es importante comprender los tipos de contenido disponibles en Microsoft Learn y sus relaciones entre sí. Consulte el artículo del modelo de contenido de Learn para obtener más información.
Notablemente:
- UID significa Id. único y es único para cada objeto de contenido. Si cambia un UID, incluso si el título u otros metadatos permanecen iguales, el contenido se considera un nuevo objeto.
- Los módulos son el objeto principal dentro del catálogo de aprendizaje de Learn. Todos son capaces de funcionar de manera independiente, en el sentido de que enseñan un escenario o concepto de principio a fin y no requieren tomar módulos previos. Para algunos, esto es todo y no forman parte de una ruta de aprendizaje. Para otros usuarios, se agrupan en una o varias rutas de aprendizaje que llevan a un usuario a través de la creación de conceptos más avanzados. Un módulo no tiene que formar parte de una ruta de aprendizaje o puede formar parte de uno o varios.
- Las unidades no se escriben como contenido independiente. Están diseñados para ser tomados en un orden específico para el módulo. Por este motivo, incluimos el vínculo a la página de detalles del módulo y la primera unidad para que los usuarios puedan empezar allí y continuar con el contenido.
Comprender 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 local no tiene disponible la traducción asociada, el contenido del sitio y la respuesta de la API recurren al inglés como idioma predeterminado. En la salida de la API, verá metadatos en inglés en otras respuestas de configuración regional cuando ocurre un retroceso. 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 las actualizaciones se publican en el contenido en inglés, nuestras canalizaciones de localización funcionan para actualizar las versiones localizadas lo antes posible, normalmente en unos días después del cambio original.
Puede ver una lista completa de las configuraciones regionales admitidas en el pie de página del sitio de Microsoft Learn (seleccione en el idioma que está viendo). Cada uno de estos locales se puede consultar con la API Learn Catalog utilizando el filtro locale.
Nuestros registros de finalización de contenido de entrenamiento son independientes de la configuración regional, lo que significa que no diferenciamos las versiones localizadas del contenido como objetos independientes en nuestros registros de finalización de entrenamiento 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 del idioma 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 como objetos independientes, implemente una equivalencia entre ellos para que, independientemente del idioma en que el usuario complete el entrenamiento, reciba el reconocimiento correspondiente en los demás idiomas y no tenga que volver a repetirlo.
Comprender cómo funciona el control de versiones de contenido en Learn y cómo se refleja en la salida de la API
En particular, el contenido se está actualizando todo el tiempo. Publicamos actualizaciones disponibles dos veces al día. Pueden ser menores, como cambios de texto menores o importantes, como revisiones principales, adiciones o eliminaciones importantes. En general, la cartera de contenido se administra como un proyecto de código abierto masivo y altamente regulado con miles de colaboradores y, como tal, se están produciendo cambios todo el tiempo. Si usa el Learn Catalog API en su sistema de producción, debe tenerlo en cuenta y asegurarse de que su sistema pueda gestionarlo.
Cuando se agregan nuevos objetos de contenido, aparecen como un nuevo objeto (identificado por UID) en la respuesta. Cuando se modifica el contenido, puedes saberlo basándote en su valor de última modificación. 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 actualiza en la respuesta de la API, cuando un usuario sigue la dirección URL al contenido, siempre verá 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.
En este momento, no hay referencias a las versiones de contenido más allá de la fecha last_modified.
Actualización periódica de los datos
Si usa la información del API de Catálogo de Learn para respaldar sus procesos empresariales o mostrar a los clientes como parte de su experiencia en el sitio, asegurarse de actualizar el contenido al menos una vez al día.
En particular, el contenido se está actualizando todo el tiempo. Publicamos actualizaciones disponibles dos veces al día. Pueden ser menores, como cambios de texto menores o importantes, como revisiones principales, adiciones o eliminaciones importantes. En general, la cartera de contenido se administra como un proyecto de código abierto masivo y altamente regulado con miles de colaboradores y, como tal, se están produciendo cambios todo el tiempo. Si utiliza la API de Learn Catalog en su sistema de producción, debe tenerlo en cuenta y asegurarse de que su sistema pueda manejarlo.
Revise las recomendaciones de la documentación para desarrolladores.
La documentación para desarrolladores de la API de Learn Catalog tiene una lista completa de los datos proporcionados como parte de la respuesta y recomendaciones sobre cómo se recomienda usar cada campo para admitir experiencias de aprendizaje excelentes.
Descripción de la lógica de consulta
Hay muchos filtros disponibles para usar 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 filtros de consulta en el artículo de referencia Learn Catalog API Developer. 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 para ayudarle con la API del catálogo de Learn, revise los artículos siguientes: