Altova MapForce Server 2026 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 un archivo de ejecución de MapForce Server (.mfx) que obtiene eventos de calendario usando la API de Google Calendar (https://developers.google.com/calendar/). Para no complicarnos, el archivo .mfx obtiene la información "como está" y da como resultado los datos JSON sin procesar.

Requisitos:

•MapForce Enterprise Edition

•MapForce 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.

Ejecutar la asignación con MapForce Server (instalación independiente)

En este apartado explicamos cómo ejecutar la asignación OAuth 2.0 de muestra con MapForce Server instalado de forma independiente en lugar de bajo el control de FlowForce Server. Para más información sobre cómo ejecutar este tipo de asignaciones con MapForce Server bajo el control de FlowForce Server consulte la documentación de FlowForce Server, donde encontrará este ejemplo ampliado.
 
Para ejecutar una asignación OAuth 2.0 con MapForce Server instalado de forma independiente hay dos maneras de gestionar las credenciales OAuth 2.0:

•Incluir el token OAuth 2.0 (de forma cifrada) en el archivo .mfx compilado. Con este método no necesita suministrar más credenciales OAuth 2.0 desde la línea de comandos (o en la llamada a la API de MapForce Server) porque se usa la credencial incrustada. Sin embargo, esto también significa que cualquier usuario con acceso al archivo .mfx puede ejecutar la asignación sin tener que dar su propio token de autorización (hasta que el que se ha incluido expire o servidor de autorización lo cancele. Recuerde que siempre puede sobrescribir el token de autorización desde la línea de comandos sin tener que compilar el archivo .mfx (véase el punto siguiente).

•No incluir el token OAuth 2.0 en el archivo .mfx compilado. Con este método, cualquier usuario que ejecute el archivo .mfx deberá suministrar el token de autorización OAuth 2.0 en la línea de comandos o en la llamada a la API de MapForce Server. El token debe obtenerlo fuera de MapForce Server, por ejemplo con MapForce, como se explica más arriba.

En este ejemplo no incluimos en token de autorización en el archivo .mfx compilado, sino que lo suministraremos en tiempo de ejecución.

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 credenciales (en este ejemplo "my.oauth") 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 compilaremos la asignación en un archivo de ejecución de MapForce Server (.mfx):

1.En el menú Archivo haga clic en Compilar en archivo de ejecución de MapForce Server.

2.Seleccione un directorio de destino y guarde el archivo como GetCalendarEvents.mfx.

Ahora puede abrir una ventana de la línea de comandos y ejecutar el archivo .mfx con un comando como:

Donde:

•mapforceserver-exec es la ruta de acceso al ejecutable de MapForce, que suele ser C:\Program Files\Altova\MapForceServer2026\bin\MapForceServer.exe.

•GetCalendarEvents.mfx es la ruta de acceso al archivo .mfx relativo al directorio actual de la línea de comandos. Ajuste la ruta si es necesario o use una ruta absoluta.

•calendarId es el nombre del parámetro de entrada tal y como se creó en MapForce.

•my.oauth es el nombre de la credencial tal y como se creó en MapForce en un paso anterior.

•mytoken es el valor del token de autorización obtenido de forma externa (en este caso con MapForce).

Si el archivo y la autorización OAuth 2.0 se ejecutaron correctamente, el resultado de la línea de comandos muestra la respuesta devuelta por la API de Google Calendar, por ejemplo: