Publicado originalmente el 20 de febrero de 2019
Tenga en cuenta que Postman es una herramienta de desarrollo de terceros. D2L recomienda que evalúe la idoneidad de Postman dentro de su organización antes de utilizarlo.
D2L y estándares de integración
En D2L hemos sido y seguiremos siendo firmes partidarios de los estándares de integración. A finales de 2016, agregamos compatibilidad con OAuth 2.0 para el desarrollo de aplicaciones de API de Brightspace. OAuth 2.0 es un marco de autenticación de estándar abierto que proporciona múltiples flujos de autenticación, incluido el flujo de OAuth de tres patas. Permite a los desarrolladores escribir aplicaciones que acceden a diferentes servicios en nombre de un usuario.
Tenga en cuenta que continuaremos apoyando nuestro modelo de autenticación de par de identificación/clave, pero nuestro enfoque será hacia el soporte y el crecimiento continuos de OAuth 2.0. Un ejemplo de esto es una actualización reciente que hicimos a nuestra implementación de OAuth 2.0. En nuestra versión del producto de marzo de 2019, agregamos compatibilidad con Uso del parámetro Client_ID request para identificarse al enviar solicitudes al punto de conexión del token. Esperamos que esta actualización beneficie a muchos desarrolladores de Brightspace.
¿Por qué hemos realizado esta actualización?
La inclusión del valor Client_ID no afectará a ninguna aplicación de OAuth 2.0 existente. Además de ser más adherentes al estándar, a través de la comunidad de desarrolladores escuchamos de nuestros clientes que nuestra implementación de OAuth 2.0 no era compatible con algunas herramientas de API de terceros. Más específicamente, los desarrolladores de Brightspace no pudieron usar Postman con la API de Brightspace, ya que incluía el valor Client_ID en la solicitud para realizar una interacción basada en OAuth 2.0.
¿Qué es Postman?
Postman es la herramienta de prueba de API líder en el mercado. Está disponible para descargar en www.getpostman.com.
Postman es potente y fácil de usar y su Centro de soporte es muy útil. Entre sus muchas características, creemos que las siguientes serán muy útiles para los desarrolladores de API de Brightspace:
- Crear entornos de desarrollo (por ejemplo, uno para su sitio de prueba de Brightspace y otro para su sitio de producción)
- Crear variables de entorno (p. ej., dominio de Brightspace, versión de API)
- Cree colecciones que proporcionen la capacidad de ejecutar varias llamadas a la API en secuencia
- Usar JavaScript para pasar variables a una llamada a la API
- Usar JavaScript para almacenar variables después de una llamada a la API
Comience con una aplicación OAuth 2.0 de Brightspace
El uso de Postman con Brightspace requiere una aplicación OAuth 2.0 de Brightspace. Si aún no tiene una aplicación OAuth 2.0, puede crear una en su instancia de Brightspace navegando a Cómo empezar a usar OAuth 2.0, o use la aplicación pública proporcionada en el Entorno de desarrollo de Brightspace (asegúrese de unirse al grupo de desarrolladores para acceder al archivo "Credenciales de instancia de desarrollador", que contiene los detalles de la aplicación pública de OAuth 2.0).
Creación de una colección de Postman y conexión a Brightspace
Antes de comenzar, asegúrese de tener Postman instalado. Siga estos pasos para configurar la autenticación de Postman con su aplicación de Brightspace:
- Lanzamiento de Postman.
- Debería recibir un mensaje Empezar ventana. De forma predeterminada Crear nuevoescoger Colección.
- Especifique un Nombre para su nueva colección (por ejemplo, "Pruebas de API de Brightspace").
- Seleccione la opción Autorización pestaña.
- Del Tipo menú desplegable, seleccione OAuth 2.0.
- En el caso de la Agregar datos de autenticación a menú desplegable, seleccione Encabezados de solicitud.
- Clic Obtener un nuevo token de acceso.
- El Obtener un nuevo token de acceso Se abre la ventana. Deberá configurar cada campo de la siguiente manera:
- Proporcione un archivo Nombre del token (por ejemplo, "Token de entorno de desarrollo de Brightspace").
- Tipo de concesión establecido en Código de autorización.
- Establezca la URL de devolución de llamada en:
https://oauth.pstmn.io/v1/browser-callback
(según Documentación de Postman OAuth 2.0) - Establezca la URL de autenticación en: https://auth.brightspace.com/oauth2/auth
- Establezca la URL del token de acceso en: https://auth.brightspace.com/core/connect/token
- ID de cliente debe coincidir con el valor de ID de cliente de su aplicación de Brightspace.
- Secreto de cliente debe coincidir con el valor del secreto de cliente de su aplicación de Brightspace.
- Alcance debe coincidir con el valor de Alcance de su aplicación de Brightspace.
- Estado puede ser cualquier valor. Este valor es una característica de seguridad destinada a proteger contra la falsificación de solicitudes entre sitios. Para fines de prueba, este valor no es muy importante; Sin embargo, en el caso de las aplicaciones de producción, asegúrese de usar un valor criptográficamente seguro.
- Cliente Autorización Establézcalo en Enviar como encabezado de autenticación básica.
- Clic Token de solicitud. Se le solicitará una ventana de inicio de sesión para su instancia de Brightspace. Introduzca el archivo Nombre de usuario y Contraseña del usuario como desea realizar solicitudes de API y haga clic en Inicia sesión. Si se realiza correctamente, debería ver un mensaje de consentimiento para confirmar el uso de la aplicación. Acepte este mensaje (tenga en cuenta que este mensaje solo se produce para un usuario la primera vez que accede a la aplicación).
- La ventana debería cerrarse y verá un Token de acceso valor ingresado en la colección. Desplácese hasta la parte inferior de la ventana y haga clic en Usar token.
- Clic Crear para crear tu Colección.
Ahora tiene una colección de Postman conectada a Brightspace mediante OAuth 2.0. El siguiente paso es agregar una solicitud de API a su colección.
Agregar solicitudes de Brightspace a su colección de Postman
Uno de los aspectos poderosos de Postman es que puede agregar una o varias solicitudes de API a una colección.
Para añadir una solicitud a tu colección
- Clic Nuevo.
- Seleccione un Pedir e introduzca un Nombre de la solicitud y Descripción de la solicitud.
- Asegúrate de que tu colección esté Seleccionado como la ubicación de guardado. Clic Guardar en {tu colección}.
En este punto, volverá a la página de destino de Postman, pero ahora tiene la opción de agregar una solicitud de API específica. Puede proporcionar a Postman los detalles de cualquier ruta de la API de Brightspace que desee probar en esta etapa. Puede agregar una solicitud para obtener una lista de todos los cuestionarios que existen en un curso específico.
- Para el primer campo, especifique OBTENER como el método HTTP.
- En el campo URL de solicitud, debe compilar el punto de conexión de API completo. Esto incluye la URL de la instancia.
- Comience con la URL de la instancia.
- Introduzca la URL de la API a la que desea llamar (por ejemplo, /d2l/api/le/(versión)/(orgUnitId)/quizzes/).
- Sustituya el valor (versión) por la versión actual de la API.
- Sustituya el orgUnitId por el curso al que se va a dirigir.
- Haga clic en el botón Autorización tabulación y asegúrese de que Heredar la autenticación del elemento primario para Tipo está establecido.
- Con los detalles de la solicitud ingresados y la autorización específica, haga clic en Enviar para probar la nueva solicitud.
- Ahora debería recibir una respuesta de 200 con una serie de cuestionarios actualmente disponibles para que su usuario los vea en la orgUnit específica.
Si no existen cuestionarios, puede esperar un error 404 si no se encontraron cuestionarios. Si su usuario no tiene permisos para ver cuestionarios, recibirá un error 403 no autorizado.
Usos avanzados de Postman
Postman contiene características adicionales que ahorran tiempo y aumentan la comprensión de una ruta de API. El cartero permite la recolección y/o el entorno Variables. Estos le permiten sustituir valores en sus solicitudes para agregar rápidamente nuevos puntos de conexión o realizar pruebas en diferentes instancias. Estas son algunas ideas que te ayudarán a empezar:
- Cree una variable de entorno que defina la URL de su instancia de Brightspace
- Cree una variable de versión para almacenar el valor proporcionado en las URL de la API
Otra gran característica es Scripts. Postman contiene un entorno de tiempo de ejecución (basado en Node.js) que le permite agregar código dinámico a sus solicitudes, ya sea antes de la solicitud o justo después de realizar una llamada. Los usuarios pueden agregar scripts previos y posteriores a la solicitud a las carpetas de colecciones o solicitudes específicas. Los guiones son excelentes para situaciones como:
- Sondeo de la versión de la API de una instancia y suministro del valor en una variable para una solicitud posterior
- Guardar el valor de un OrgUnitId y pasarlo para una búsqueda en una solicitud siguiente
- Realización de una función de cálculo antes de enviar los datos en una API POST
Problemas con Postman y Brightspace
Nuestra evaluación de Postman fue prometedora y positiva. Sin embargo, experimentamos un par de problemas que debe tener en cuenta.
Borrado de cookies: En el momento de publicar este artículo hemos notado que no hay problemas la primera vez que se generan tokens OAuth. Sin embargo, los intentos posteriores tienen problemas. Para resolver este problema, se recomienda Borrar cookies dentro de Postman.
Sin redireccionamiento de inicio de sesión: al generar un token de OAuth, el usuario es enviado desde Postman a la página de inicio de sesión de la instancia de Brightspace con la que está desarrollando. No hay opciones para redirigir a una página de inicio de sesión de Brightspace diferente dentro del navegador integrado de Postman. Esto solo es un problema si la cuenta de usuario con la que está desarrollando no está registrada con el proveedor de identidad de su página de inicio de sesión principal.
Estamos evaluando las dos cuestiones anteriores. Sin embargo, creemos que ambos son problemas dentro de Postman. Estaremos abiertos a sugerencias sobre cómo evitar mejor estos problemas, y proporcionaremos cualquier actualización que recibamos en este artículo.
Conclusión
Cuéntanos sobre tu experiencia con Postman y comparte con nosotros cualquier colección de Postman que desarrolles. Si hay otro cliente de prueba de API que prefiera sobre Postman, nos gustaría saberlo para poder probarlo también.
Para obtener más capacitación sobre el uso de Postman, consulte Aprende a ser cartero con Paul.
Figura: Vea los detalles de una solicitud en la pantalla de solicitud.
