Introducción a la API de plataforma de Microsoft Learn

Este artículo le ayuda a empezar a usar la API de plataforma de Microsoft Learn. Si no está familiarizado con los detalles de la API o los casos de uso para ella, le recomendamos que revise primero el artículo Introducción a la API de plataforma de Microsoft Learn .

Autenticación de API de plataforma de Learn

Las API REST de la plataforma de Learn usan Microsoft Entra ID para la autenticación. Antes de realizar llamadas API, debe elegir un método de acceso y la aplicación cliente debe autenticarse con credenciales válidas.

Acceso solo a aplicación

Cuando la aplicación accede directamente a Learn, su acceso no está vinculado a ningún usuario único. La aplicación llama a las API directamente utilizando su propia identidad; este escenario es de acceso exclusivo a la aplicación. Obtenga más información sobre la plataforma de identidad de Microsoft.

Para empezar, necesita una identidad válida en la Plataforma de identidad de Microsoft, que puede ser un registro de aplicación o una identidad administrada. Lo ideal es que cada asociado tenga una única identidad para simplificar la administración de cuotas y asociados. El uso de una identidad administrada asignada por el usuario puede ayudar a unificar las identidades administradas en distintos servicios.

Una vez configurada la identidad de Entra ID, obtenga un token de acceso de Entra ID con el ámbito establecido a como prueba de autenticación. Incluya el token de acceso en el encabezado de autorización HTTP al realizar solicitudes de API REST a Learn.

Acceso delegado

Cuando un usuario inicia sesión en la aplicación y lo usa para acceder a Learn, la aplicación primero debe solicitar permiso para acceder a este recurso en nombre del usuario. Este escenario se denomina acceso delegado. Obtenga más información sobre la plataforma de identidad de Microsoft.

Para empezar, debe registrar un registro de aplicaciones. Una vez configurado el registro de la aplicación, la aplicación debe pedir al usuario que conceda un ámbito específico o un conjunto de ámbitos para acceder a Learn en nombre del usuario. Learn proporciona una lista de ámbitos para el acceso específico a los recursos. La lista de ámbitos incluye:

• : este alcance permite a los usuarios acceder al contenido público en Learn actuando como el usuario que ha iniciado sesión.

Descripción del control de versiones de la API de plataforma de Microsoft Learn

Cuando se realizan cambios importantes en la API, publicamos una versión nueva y con fecha. Los cambios importantes son cambios que pueden interrumpir una integración. Todos los cambios no importantes (aditivos) estarán disponibles en todas las versiones de API compatibles.

La versión de la API se especifica como parámetro de consulta api-version y usa aaaa-MM-dd para versiones estables y aaaa-MM-dd-preview para versiones preliminares. El parámetro de consulta api-version es necesario para cada solicitud de API.

Cuando se publica una nueva versión de API estable, se admite la versión anterior de la API estable durante al menos 24 meses más después de la publicación de la nueva versión de api. Las API en versión preliminar tienen un ciclo de soporte técnico más corto de tres meses más después de la publicación de nuevas API en versión preliminar.

La versión actual es 2023-11-01-preview.

El segmento de URL /v1/ antes de cada API es parte de la URL base, no de la versión de la API. Está reservado para cambios sustanciales en el protocolo y los patrones de la API en el futuro.

Limitación de la velocidad de la API de la plataforma de Learn

Learn limita el número de solicitudes de API REST que puedes realizar dentro de un período de tiempo específico. Este límite ayuda a evitar ataques por denegación de servicio y abuso, y garantiza que la API siga estando disponible para todos los usuarios.

Learn aplica límites de velocidad en función de la notificación OID en el token de acceso. Para el acceso de solo aplicación, el límite se aplica a la propia aplicación, mientras que para el acceso delegado, el límite se aplica al usuario que inició sesión en la aplicación.

De forma predeterminada, el límite de velocidad es de 100 llamadas API por minuto, calculadas en un período de 5 minutos. Si necesita un límite mayor para producción, puede ponerse en contacto con el soporte técnico de Learn Integrations para solicitar un aumento.

Algunas API, como la API de búsqueda de conocimiento, también implementan la limitación de velocidad basada en tokens. Esto se basa en el número de tokens de OpenAI consumidos Microsoft Azure, con un límite predeterminado de 10 000 tokens por minuto. Para aumentar este límite de producción, póngase en contacto con el soporte técnico de Learn Integrations.

Paginación de la API de Learn Platform

Todos los recursos de API de nivel superior admiten la recuperación masiva a través de métodos de API "list". Por ejemplo, puede recuperar listas de módulos o exámenes. Estos métodos devuelven respuestas paginadas siguiendo un enfoque estandarizado.

Los métodos de API de lista usan la paginación basada en cursores, indicada por el campo nextLink en el cuerpo de la respuesta. Este campo contiene una dirección URL opaca con la información necesaria para capturar la siguiente página de resultados. De forma predeterminada, las API de lista devuelven 30 elementos por solicitud, pero puede ajustar el tamaño de página mediante el parámetro maxpagesize.

Nuestras bibliotecas del SDK de cliente ofrecen asistentes de autopaginación para recorrer todas las páginas de una lista.

Contenido relacionado

• Inicio rápido: Configuración y uso de los datos del catálogo de API de plataforma de Microsoft Learn
• Documentación sobre los datos del catálogo de la API de la plataforma de Learn para desarrolladores
• Preguntas más frecuentes sobre API de la Plataforma Learn