Ejemplo: autorización OAuth 2.0
En este ejemplo aprenderá a llamar a un servicio web REST que requiere autorización OAuth 2.0. La aplicación cliente es una asignación de MapForce que obtiene eventos de calendario usando la API de Google Calendar (https://developers.google.com/calendar/). Para no complicarnos, la asignación obtiene la información "como está" y da como resultado los datos JSON sin procesar.
Requisitos:
•MapForce Enterprise Edition
•Para seguir los pasos de este ejemplo debe tener una cuenta de Google. Si quiere llamar a otro servicio web necesita pedir credenciales OAuth 2.0 a su proveedor web y usarlas en los pasos que explicamos a continuación.
Obtener las credenciales OAuth 2.0
Si ya tiene las credenciales OAuth 2.0 necesarias para acceder al servicio web, puede saltarse este paso. De lo contrario, las instrucciones exactas para obtenerlas dependen del proveedor del servicio web al que llame su asignación. Para llamar a la API de Google Calendar, como en este ejemplo, siga estos pasos:
1.Inicie sesión en Google API Console (https://console.developers.google.com/).
2.Cree un proyecto nuevo.
3.Haga clic en la Pantalla de consentimiento de OAuth.
4.Seleccione Externo como tipo de usuario, a no ser que tenga una cuenta G Suite, que le permitiría otorgar acceso a la API solo a usuarios de su organización.
5.Introduzca "mapforce-demo" como nombre de aplicación y guarde la configuración.
6.Haga clic en Crear credenciales y seleccione ID de cliente de OAuth.
7.Introduzca Aplicación de escritorio como tipo de aplicación y "MapForce Client" como nombre de cliente.
8.Haga clic en Create. Se crea el ID del cliente, que está disponible en la página Credenciales.
9.Haga clic en 
para descargar los detalles de la autorización OAuth 2.0 en forma de archivo JSON.
Ahora debería tener los detalles de autorización Oauth 2.0 de la Google Console API, que son:
1.Authorization Endpoint (punto final de autorización)
2.Token Endpoint (punto final del token)
3.Client ID (ID del cliente)
4.Client Secret (secreto del cliente)
Habilitar la API de Google Calendar
Para aceptar llamadas de clientes debe habilitar la Google Calendar API. En la Google API Console haga clic en Biblioteca, busque la Google Calendar API y habilítela:
En este ejemplo vamos a llamar al método list de la entidad Events. Puede encontrar una referencia detallada de este método API en https://developers.google.com/calendar/v3/reference/events/list. Por ahora tenga en cuenta los puntos siguientes:
1.Como se explica en la documentación, para llamar al método hay que enviar una solicitud GET a https://www.googleapis.com/calendar/v3/calendars/calendarId/events, donde calendarId es el identificador de un calendario de Google. El parámetro de solicitud calendarId se configura desde MapForce en un paso posterior.
2.Para llamar a este método API necesita al menos uno de estos ámbitos:
•https://www.googleapis.com/auth/calendar.readonly
•https://www.googleapis.com/auth/calendar
•https://www.googleapis.com/auth/calendar.events.readonly
•https://www.googleapis.com/auth/calendar.events
Durante el proceso de autorización OAuth 2 la asignación deberá suministrar uno de esos ámbitos (este paso también se configura más adelante). En este ejemplo basta con que usemos el primer ámbito "read-only".
Solicitar un token de autorización
Para previsualizar la asignación en MapForce deberá añadir los detalles de autorización de OAuth 2.0 a la asignación y solicitar un token de autorización, como se explica más abajo.
1.En MapForce haga clic con el botón derecho en una zona vacía de la asignación y seleccione Abrir el gestor de credenciales desde el menú contextual.
2.Haga clic en 
Agregar credencial.
3.Introduzca un nombre (en este ejemplo "my.oauth") y seleccione el tipo OAuth 2.
4.Rellene los campos de texto Extremo de autorización, Extremo del token, ID del cliente y Secreto del cliente con los valores correspondientes del archivo JSON que descargó antes.
5.Introduzca https://www.googleapis.com/auth/calendar.readonly en la caja de texto Alcance.
6.Deje el resto de opciones tal y como están.
7.Haga clic en Solicitar token de acceso para obtener el token del servidor de autorización (en este ejemplo, Google). Se abre una ventana del explorador que le pide que se conecte a su cuenta de Google.
8.Inicie sesión en su cuenta de Google. Al no haber enviado todavía ninguna solicitud de confirmación de aplicación a Google, aparece esta página.
9.Haga clic en Avanzadas y después en Ir a mapforce-demo (no seguro).
10.Haga clic en Permitir. Ahora aparece una confirmación en el explorador.
MapForce también informa de que ha obtenido el código OAuth 2.0 correctamente.
11.Haga clic en Aceptar. Observe que los campo Token de acceso y Actualizar token ahora contienen datos.
12.Guarde la asignación como GetCalendarEvents.mfd.
En este tutorial hemos marcado la casilla Guardar credencial cifrada en el archivo MFD en el cuadro de diálogo "Editar credenciales". Esto significa que los campos de información sensible Secreto del cliente, Token de autorización y Actualizar token se guardan de forma cifrada en el archivo de diseño de la asignación (.mfd) al guardarla. |
Tenga en cuenta que el token de autorización expira pasado un tiempo. Cuando eso ocurra ya no podrá ejecutar la asignación (en este punto no hemos diseñado ninguna asignación, pero lo haremos en un paso posterior). Siempre que necesite obtener una nueva autorización manualmente haga clic en Solicitar token de acceso y siga los pasos que se explican más arriba.
Diseñar la llamada al servicio web
La asignación GetCalendarEvents.mfd que ha creado hasta ahora de momento no hace nada. Solo contiene las credenciales OAuth 2.0 que permiten acceder a la API de Google Calendar.
Ahora vamos a diseñar la llamada al servicio web en MapForce:
1.Abra la asignación GetCalendarEvents.mfd.
2.En el menú Insertar haga clic en Función de servicio web. Aparece el cuadro de diálogo "Configuración de la llamada a servicio web".
3.Haga clic en Manual.
4.Seleccione GET como método de solicitud e introduzca la URL del servicio web que mencionamos en el paso anterior: https://www.googleapis.com/calendar/v3/calendars/calendarId/events.
5.El elemento calendarId es un marcador de posición que se debe indicar como parámetro, por lo que debe indicarlo entre llaves, com se ve en la imagen.
6.Haga clic en el botón 
Agregar parámetro y defina los detalles del parámetro así:
En la configuración de la imagen anterior, el estilo "Plantilla" permite reemplazar la parte de la URL que se encuentra entre llaves con el valor del parámetro en tiempo de ejecución. "Asignable" significa que puede pasar el valor desde la asignación (por ejemplo, desde una constante o un parámetro de entrada). Por último, el parámetro está marcado como "Obligatorio" porque la llamada a la API no se puede hacer sin él. Para más información consulte Definir los parámetros del servicio web.
7.Haga clic en el botón Editar que hay junto a Configuración de seguridad HTTP.
8.En el cuadro de diálogo "Configuración de seguridad HTTP" seleccione Usar credencial y elija el registro de credencial "my.oauth" que configuró antes.
El servicio web que ha configurado hasta ahora debería tener este aspecto en la asignación:
Ahora puede completar el diseño con los pasos siguientes:
1.En el menú Insertar haga clic en Insertar componente de entrada y configure ese componente como sigue:
Como se ve en la imagen anterior, el componente de entrada tiene el valor de tiempo de diseño "primary". Según la documentación de la API, este valor indica al servidor API que acceda al calendario primario de Google del usuario que ha iniciado sesión. Tenga en cuenta que es un valor de tiempo de diseño y solo se aplica al previsualizar la asignación en MapForce. Si la ejecuta en un entorno de servidor deberá suministrar el valor deseado en tiempo de ejecución.
2.Arrastre la función decode-mime-entity desde la ventana Bibliotecas hasta el área de asignación.
3.En el menú Insertar haga clic en Insertar componente de entrada y añada un componente simple de salida cuya función sea generar el resultado como una cadena de texto simple.
4.Trace las conexiones entre los componentes como se ve en la imagen siguiente.
Con este paso termina la parte de diseño en MapForce.
Probar la ejecución de la asignación
Para probar la ejecución de la asignación en MapForce haga clic en la pestaña Resultados y observe el resultado que aparece en la ventana Mensajes.
Si aparece un error de autorización como "Sin autorización (401)" tenga en cuenta estos consejos:
1.Asegúrese de que la API de Google Calendar está habilitada, véase Habilitar la API de Google Calendar.
2.Solicite un token de autorización nuevo si el que obtuvo antes ya ha expirado.
3.Compruebe de nuevo si introdujo todos los detalles OAuth 2.0 correctamente en MapForce.
Si la asignación se ejecuta correctamente y la autorización OAuth 2.0 en MapForce funciona, el resultado de la asignación se parecerá a este:
Si la cuenta de Google que usó no tiene eventos de calendario, la matriz "items" estará vacía en la respuesta. Sin embargo, si añade un evento a su calendario de Google y vuelve a ejecutar la asignación, el resultado reflejará este cambio. También puede recuperar eventos de un calendario que no sea el predeterminado. Por ejemplo, puede obtener datos de un calendario público como "Festivos en Estados Unidos". Para ello defina el valor del parámetro calendarId como en.usa#holiday@group.v.calendar.google.com en lugar de primary.
Para más información sobre los demás parámetros que puede añadir a la llamada a la API consulte la documentación de los métodos API en https://developers.google.com/calendar/v3/reference/events/list.