Agregar llamadas a servicios web (de tipo REST)
Los servicios web genéricos (no WSDL) incluyen una amplia categoría de servicios web que siguen parcial o totalmente una estructura denominada REST (y que suelen denominarse servicios web RESTful o de tipo REST). Los servicios web HTTP genéricos suelen llevar estructuras de solicitud o respuesta personalizadas en la parte del cuerpo del mensaje. Estos son los tipos de datos que MapForce admite en el cuerpo de la solicitud y de la respuesta: JSON, XML, Protocol Buffers y cuerpos sin estructura que contienen tipos MIME personalizados. Por tanto, desde el punto de vista de MapForce, los requisitos para llamar a un servicio web dependen del tipo de la solicitud:
•En el caso de solicitudes o respuestas XML o JSON, MapForce necesita que la estructura de solicitud o de respuesta sea un esquema JSON, XML o DTD, aunque también acepta archivos XML con una referencia de esquema válida. La estructura del servicio web puede estar publicada por el proveedor de servicio como esquema XML o JSON o en un lenguaje formal como WADL (o incluso en una especificación de lectura humana). Si ya tiene el esquema XML o JSON de la solicitud/respuesta, crear la llamada al servicio web será muy sencillo. Si tiene la definición de servicio web como archivo WADL, podrá importarla y realizar los ajustes que sean necesarios. Sin embargo, tenga en cuenta que WADL no ofrece ningún método estándar para definir estructuras JSON, solo estructuras XML. Por último, si tiene un archivo de instancia XML o JSON de ejemplo pero no tiene un archivo de esquema, podrá crear o generar el esquema con XMLSpy (https://www.altova.com/es/xmlspy.html). Si lo necesita, puede convertir la instancia XML en instancia JSON y viceversa desde Altova XMLSpy.
•En el caso de solicitudes o respuestas de Protocol Buffers, necesita el archivo .proto que describe el archivo binario de Protocol Buffers. En este caso, el cuerpo del servicio web se puede asignar a o desde un componente de Protocol Buffers. Para más información consulte Ejemplo: leer datos de Protocol Buffers y Ejemplo: escribir datos en Protocol Buffers.
•También puede llamar a servicios web cuya estructura de solicitud o de respuesta sea flexible y no dependa de un esquema en concreto. Para esos casos puede usar las funciones integradas mime de MapForce para crear el cuerpo base del mensaje que se envía al servicio web (la entidad MIME) o procesar desde la asignación la entidad MIME devuelta por el servicio web.
Agregar una llamada a un servicio web genérico
1.Haga clic en el comando de menú Insertar | Función de servicio web (también puede hacer clic en el botón Insertar función de servicio web 
de la barra de herramientas).
2.En el grupo de opciones Definición del servicio elija la opción Manual.
3.Si tiene un archivo WADL que describa el servicio, haga clic en Importar desde archivo WADL... y seleccione el archivo (véase Importar información del servicio web desde un archivo WADL).
4.Seleccione el método de solicitud HTTP que se debe utilizar para llamar al servicio web. Puede seleccionar un valor de la lista o escribir el nombre del método que desea usar. Debe tener en cuenta el uso de mayúsculas y minúsculas en los nombres de métodos HTTP.
5.Haga lo siguiente:
a.Introduzca la URL del servicio web. Si la URL del servicio web usa parámetros, debe tener en cuenta que:
i.si llama a un servicio web con los parámetros de estilo "Plantilla" o "Matriz", ponga los parámetros entre llaves. Por ejemplo: http://ejemplo.org/api/products/{id}. Después defina la configuración de cada parámetro en la tabla Parámetros. En tiempo de ejecución MapForce procesa los nombres de parámetro que están entre llaves y produce la URL final que incluye valores reales.
i.si llama a un servicio web con parámetros URL "Consulta" (por ejemplo http://example.org/api/products?sort=asc&category=1&page=1), no introduzca la parte de la consulta en el cuadro de texto URL. Debe definir los parámetros en la tabla Parámetros solamente.
ii.Consulte el apartado Definir parámetros de servicios web para ver un ejemplo.
b.En el grupo de opciones Tiempo de espera tiene la opción de introducir el plazo de tiempo en segundos tras el cual la conexión expirará si el servidor no responde.
URLs dinámicas Mediante cualquiera de los dos métodos que acabamos de describir (URLs en parte o completamente dinámicas) puede ajustar la URL en base a sus necesidades. Por ejemplo, puede ejecutar la asignación con una URL específica durante el desarrollo y usar una URL diferente en producción, sin tener que modificar la asignación. Esto sería posible con una URL como https://{host}/some/path/to/service, siempre que el nombre de host sea la única diferencia entre la URL de desarrollo y la de producción, y que la suministre como parámetro de la asignación. Observe que las URLs parcialmente dinámicas requieren una validación más escrita, ya que solo se reemplazan con valores asignables o en tiempo de ejecución las partes designadas de la URL.
Con las URLs completamente dinámicas se puede asignar toda la URL y tiene control absoluto sobre ella; el único requisito es que la URL empiece por http:// o https:// y que sea un URI válido. Es decir, con las URLs dinámicas puede suministrar la URL devuelta por una llamada a un servicio web como entrada de otro componente que puede llamar al mismo servicio web (o a otro). |
6.Si el método HTTP requiere o devuelve la parte del cuerpo de la solicitud (como XML o JSON, entre otros), haga clic en el botón Editar situado en el grupo de opciones Estructura y busque el esquema de la parte del cuerpo de la solicitud. Para más información consulte los apartados Definir la estructura de la solicitud y Definir la estructura de la respuesta.
7.En el grupo de opciones Parámetros defina los parámetros del servicio web. También puede hacer clic en Importar desde URL para importar los parámetros desde una URL de ejemplo del servicio web y rellenar la tabla Parámetros automáticamente, como se explica en el apartado Importar parámetros de servicio web desde una URL. Tras importar los parámetros desde la URL, podrá modificar el contenido de la tabla Parámetros si es necesario. Para más información consulte el apartado Definir los parámetros del servicio web.
| Nota: | para especificar encabezados de solicitud personales, añada un parámetro con el estilo Encabezado y asegúrese de que el nombre del parámetro coincida con el nombre del encabezado y que el valor del parámetro coincida con el valor del encabezado. Además, si necesita pasar el valor del encabezado de la solicitud desde la asignación propiamente dicha, entonces utilice el tipo de parámetro "Asignable". Para más información consulte el apartado Definir los parámetros del servicio web. |
8.Si el servicio web necesita autenticación HTTP básica, OAuth 2.0 o seguridad basada en certificado, haga clic en Editar (en el grupo de opciones Configuración de seguridad HTTP) y rellene los campos necesarios (véase también Configurar seguridad HTTP).
Cuando haga clic en Aceptar se añadirá un componente de servicio web nuevo al área de asignación. Por ejemplo, la asignación que aparece a continuación llama a un servicio web para recuperar un producto en función de su ID con ayuda de una solicitud GET. En este ejemplo, el ID que se da en la solicitud HTTP tiene el valor de constante 2. Sin embargo, también podría ser un parámetro para la asignación o puede venir dado por cualquier componente que sea compatible con MapForce. Además del parámetro id, la solicitud contiene el encabezado Accept: text/json. Puede definir los encabezados de la solicitud con los parámetros "header", como se muestra en Definir los parámetros del servicio web.
Esta asignación se configuró para tener tres resultados:
1.Código de estado HTTP devuelto por la llamada al servicio web
2.Los encabezados de respuesta como valores separados por comas
3.La estructura de la respuesta JSON
Esta configuración es solamente un ejemplo; también puede diseñar una asignación para que tenga una única salida, por ejemplo el código de estado HTTP. Si una asignación tiene varias salidas, como en el ejemplo de la imagen anterior, puede hacer clic en el botón de vista previa 
de cada componente para acceder a la vista previa de esa salida en concreto antes de ejecutar la asignación.
Observe que el componente de servicio web tiene dos partes: la solicitud y la respuesta. La parte Solicitud permite aportar datos de la asignación al servicio web, mientras que la parte Respuesta permite acceder a los datos que devuelve el servicio web y asignarlos a otros formatos. La estructura de la solicitud y de la respuesta depende de los parámetros, así como de la estructura que se haya definido haciendo clic en el botón 
. En el servicio web del ejemplo anterior la estructura del cuerpo de solicitud no está definido, mientras que la estructura del cuerpo de la respuesta está definido como JSON, lo que hace posible asignar el resultado del servicio web a un archivo JSON.
Para llamar al servicio web con parámetros de solicitud, dibuje conexiones entre cualquier tipo de componente compatible con MapForce (p. ej. un archivo XML o JSON) y la parte Solicitud. Igualmente, para asignar datos devueltos por el servicio web a otro formato, dibuje conexiones entre la parte Respuesta y cualquier tipo de componente compatible. Si acaba de empezar a utilizar MapForce y necesita información sobre cómo dibujar conexiones de asignación consulte la sección Trabajar con conexiones.
Los encabezados de respuesta devueltos por el servicio web también se pueden asignar si son encabezados adicionales (los que no empiezan por "Content"). Los valores de encabezado están disponibles en el componente de servicio web y pueden verse en el elemento Encabezados 
, que contiene dos elementos secundarios: Nombre y Valor. Esta estructura hace de secuencia y permite asignar datos de los encabezados que devuelve el servicio web. Para asignar datos desde los encabezados de la respuesta a otros formatos compatibles con MapForce, conecte el nodo de estructura Encabezados con una secuencia de destino en el área de asignación. Por ejemplo, si conecta la secuencia Encabezados (y sus secundarios) con una secuencia Filas (y sus secundarios) de un componente CSV, un encabezado correspondería a una fila del archivo CSV.
El Body 
representa el cuerpo de la entidad del mensaje HTTP. Los datos a este nivel son binarios codificados, por lo que para interactuar con ellos son necesarias las funciones mime de MapForce. Observe que por lo general no es necesario interactuar con el Body en absoluto si el servicio web espera o devuelve estructuras de datos como XML o JSON. Solo es necesario asignar datos directamente a o desde el Body al llamar a servicios web que esperan o devuelven contenido sin estructura.
Por defecto, el elemento Body está configurado para que analice el resultado si el código de estado HTTP se encuentra entre 200 y 299. Esto significa que la asignación devuelve un error para códigos de estado mayores que 299. También devuelve un error si la respuesta no se puede analizar o si no se puede llamar al servicio web debido a un error de conexión o a problemas de la resolución del DNS. |
En algunos casos puede que quiera que la asignación no devuelva un error incluso aunque el código de estado HTTP sea mayor que 299. Para cambiar esta opción haga clic en el botón que hay junto al elemento Body de la respuesta y cambie el rango del código de estado HTTP. Otra alternativa es crear varios elementos Body de respuesta. Esta opción es útil si quiere gestionar la asignación de forma condicional en función del código de estado HTTP devuelto por el servicio web. Para ello haga clic con el botón derecho en el elemento Body de la respuesta y seleccione Agregar nodo de cuerpo delante/detrás en el menú contextual. Por ejemplo, podría crear dos elementos Body:
1.Un elemento Body para todos los códigos de estado que se encuentran en el rango deseado (200 a 299). Puede configurar los rangos de estado de código haciendo clic en el botón . En este caso se recomienda que asigne la estructura Body a una salida de este primer rango, como un archivo JSON o XML.
2.Un elemento Body para el resto de códigos de estado, es decir, los del rango 300 a 566. Algunos servicios web suministran detalles suplementarios sobre los códigos de estado de error en el cuerpo . Para averiguar el motivo del error puede asignar el elemento Body a una salida que no pertenezca al rango deseado (por ejemplo, una cadena de texto).
Si existen varios elementos Body, MapForce los evalúa de arriba a abajo. Para cambiar la prioridad haga clic con el botón derecho en el elemento Body y seleccione Mover hacia arriba o Mover hacia abajo en el menú contextual. Para más información sobre cómo gestionar la respuesta HTTP de forma condicional consulte el apartado Gestionar condicionalmente la respuesta HTTP.
Las asignaciones de datos que contengan llamadas a servicios web HTTP genéricas se pueden ejecutar igual que la mayoría de asignaciones de datos:
•A mano, desde MapForce, al hacer clic en la pestaña Resultados. En este caso el resultado de la llamada puede verse inmediatamente en el panel Resultados. Si la asignación tiene varios componentes de salida, como en el ejemplo de más arriba, pulse el botón de vista previa en el componente que quiera antes de ejecutar la asignación.
•Desde la línea de comandos o con llamadas a la API con MapForce Server (https://www.altova.com/es/mapforce/mapforce-server.html). Antes será necesario compilar la asignación en un archivo de ejecución (véase Compilar asignaciones en archivos de ejecución de MapForce Server).
•Desde un trabajo de FlowForce Server que ejecute MapForce Server (https://www.altova.com/es/flowforce.html). Consulte el apartado Implementar asignaciones en FlowForce Server para obtener más información.
Para aprender a crear llamadas a servicios web genéricos y ver instrucciones paso a paso consulte estos apartados: