Altova FlowForce Server 2023 Advanced Edition

En este ejemplo aprenderá a llamar a un servicio web REST que requiere autorización OAuth 2.0. La aplicación cliente es trabajo de FlowForce Server que obtiene eventos de calendario usando la API de Google Calendar (https://developers.google.com/calendar/). Para no complicarnos, el trabajo obtiene la información "como está" y da como resultado los datos JSON sin procesar.

Requisitos:

•MapForce Enterprise Edition

•MapForce Server Advanced Edition

•FlowForce Server Advanced 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.

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.

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.

Implementar la asignación en FlowForce Server

En este apartado explicamos cómo ejecutar la asignación OAuth 2.0 de muestra con MapForce Server instalado bajo el control de FlowForce Server. Para ello hay varios requisitos:

1.Debe tener instalado FlowForce Server Advanced Edition y contar con la licencia correspondiente.

2.Debe tener instalado MapForce Server Advanced Edition y contar con la licencia correspondiente.

3.Debe iniciar el servicio de FlowForce Web Server, que tiene que escuchar en la dirección y el puerto de la configuración. Si FlowForce Web Server se instaló en el equipo actual con la configuración predeterminada, la dirección es http://localhost:8082.

4.Debe tener una cuenta de usuario de FlowForce Server y contar con acceso a uno de los contenedores de FlowForce Server. En este ejemplo usamos la cuenta predeterminada de FlowForce Server root e implementamos la asignación al contenedor predeterminado public; por lo demás estos son detalles que se pueden configurar.

Para ejecutar la asignación como un trabajo en un entorno servidor debe implementarla en la instancia de FlowForce Server designada. Antes de implementar la asignación puede gestionar las credenciales OAuth 2.0 de dos maneras:

•Incluir el token OAuth 2.0 (de forma cifrada) en el paquete que se implementa en FlowForce Server. Con este método no necesita suministrar más credenciales OAuth 2.0 al ejecutar el trabajo porque se usa la credencial incrustada. Puede ejecutar el trabajo de FlowForce hasta que el token que se ha incluido expire o servidor de autorización lo cancele. Recuerde que siempre puede sobrescribir los detalles de autorización OAuth 2.0 con unos nuevos (véase el punto siguiente).

•No incluir el token OAuth 2.0 en el paquete que se implementa en FlowForce. En este caso debe indicar la ruta de acceso al registro de la credencial OAuth 2.0 del trabajo al configurarlo. Para ello puede crear un registro de credencial OAuth 2.0 completamente nuevo en FlowForce Server o implementar uno de MapForce en FlowForce Server.

En este tutorial no incluimos la credencial OAuth 2.0 en el paquete que se implementa. En su lugar debe implementar la credencial por separado y configurar el trabajo de FlowForce para que haga referencia a ella. Puede hacerlo siguiendo estos pasos:

1.En MapForce haga clic con el botón derecho en un área vacía de la asignación y seleccione Abrir el gestor de credenciales.

2.Haga doble clic en el registro de la credencial ("my.oauth" en este ejemplo) y desmarque la casilla Incluir credencial cifrada en el archivo .mfx y en la implementación de la asignación.

3.Guarde el archivo de diseño de la asignación (.mfd).

Ahora implemente la asignación en FlowForce Server:

1.En el menú Archivo haga clic en Implementar en FlowForce Server.

2.Rellene los detalles relevantes en FlowForce Server y haga clic en Aceptar. Si la asignación se implementa correctamente podrá verlo en la ventana Mensajes:

También debe implementar la credencial OAuth 2.0 por separado:

1.En MapForce haga clic con el botón derecho en un área vacía de la asignación y seleccione Abrir el gestor de credenciales.

2.En Gestor de credenciales haga clic con el botón derecho en el registro "my.oauth" y seleccione Implementar credencial en FlowForce Server en el menú contextual.

3.Rellene los detalles correspondientes de FlowForce Server y haga clic en Aceptar. Si la credencial se implementó correctamente podrá verlo en la ventana Mensajes:

Para ver la credencial implementada inicie sesión en FlowForce Server y abra la página de la credencial desde la ruta indicada en la imagen anterior.

Configurar el trabajo de FlowForce Server

En uno de los pasos anteriores implementó la asignación GetCalendarEvents.mfd en una instancia de FlowForce Server que se ejecutaba de forma local. En este paso vamos a convertir esa asignación implementada en un trabajo de FlowForce. En este ejemplo llamaremos al trabajo como servicio web para que se pueda desencadenar a petición.

1.Inicie sesión en FlowForce Server y abra GetCalendarEvents.mapping desde el contenedor "Public". En FlowForce Server la asignación implementada se convierte en funciones, de ahí la terminología que verá en la interfaz más abajo. Observe que la función espera una credencial como parámetro de entrada. El nombre de la credencial es el mismo que el que le dio en MapForce: "my.oauth".

2.Haga clic en Crear trabajo. Se abre la página de configuración.

3.En "Parámetros del trabajo" haga clic en y cree un parámetro nuevo llamado calendarId con el valor predeterminado en.usa#holiday@group.v.calendar.google.com (también puede introducir primary como valor predeterminado, que es el mismo valor que usamos antes en la ejecución de la vista previa).

4.En "Pasos de ejecución" encuentre el parámetro calendarId, haga clic en "Enviar a" y seleccione calendarId.

5.Para el parámetro my.oauth haga clic en el botón , seleccione Seleccione una credencial: y navegue hasta la credencial OAuth 2.0 que implementó antes. La encontrará en el contenedor public si no cambió la configuración predeterminada en la implementación:

6.En "Servicio" marque la casilla Permitir acceso a este trabajo por HTTP e introduzca un nombre para el servicio ("GetCalendarEvents" en este ejemplo).

7.En "Credencial" seleccione Defina una credencial local e introduzca las credenciales de su sistema operativo. Tenga en cuenta que estas credenciales son distintas a las de su cuenta de FlowForce Server y que son necesarias para ejecutar el trabajo.

8.Deje el resto de opciones como están y guarde el trabajo.

Ahora puede ejecutar el trabajo:

1.En "Servicio" haga clic en el botón Abrir la URL del trabajo en una ventana nueva.

2.Si la aplicación le pide credenciales introduzca las de su cuenta de FlowForce Server.

Si el trabajo y la autorización OAuth 2.0 se ejecutaron correctamente el explorador muestra la respuesta JSON que recibe de la APO de Google Calendar, por ejemplo:

En la llamada al servicio web de la imagen anterior se usó el valor predeterminado de calendarId. También puede, como alternativa, añadir un parámetro de entrada a la URL, por ejemplo: http://localhost:4646/service/GetCalendarEvents?calendarId=primary. Al llamar al servicio web obtendría datos de la API de Google Calendar para el identificador de calendario dado como parámetro.

En este ejemplo el parámetro calendarId se suministró con el método HTTP GET porque se llamaba al servicio web directamente desde el explorador. Si llama a un servicio web de forma programática se puede usar también el método HTTP POST. Para más información consulte Exponer trabajos como servicios web.