Llamadas a servicios web
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:
•Si se trata de solicitudes o respuestas XML o JSON, MapForce necesita la estructura de la solicitud o respuesta como esquema JSON, XML o DTD. Sino MapForce también aceptará como estructura un archivo XML con una referencia a un esquema válido. 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, sólo 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. 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.En el menú Insertar haga clic en 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 también 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.Ahora tiene dos opciones:
a.Introduzca la URL del servicio web en el cuadro de texto URL. En este caso, también puede convertir partes específicas de la URL en parámetros y proporcionarlos desde la asignación principal. Si la URL del servicio web usa esos 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.
ii.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 y asegurarse de que los ha designado como parámetros de estilo "query".
iii.Consulte el apartado Definir parámetros de servicios web para ver ejemplos.
b.Si quiere proporcionar la URL completa del servicio Web desde la asignación principal (o quizás como parámetro de la asignación), seleccione la casilla URL dinámica (dada por la asignación). Así se desactiva el cuadro de texto URL y, en este caso, debe crear la URL completa del servicio web (incluyendo cualquier parámetro URL) desde la asignación principal y, luego, conectarla al elemento de entrada correspondiente que aparece en el componente del servicio web. Tenga en cuenta que con este método ya no tiene sentido especificar ningún parámetro en la tabla "Parámetros", menos los parámetros de estilo " Encabezado". De todos modos, si lo intenta recibirá un mensaje de advertencia.
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 sólo 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 lo prefiere, puede establecer en Tiempo de espera un periodo de tiempo en segundos después del cual la conexión debe expirar si el servidor no responde.
7.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.
8.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.
| 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. |
9.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 el apartado Definir los parámetros del servicio web.
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. Sólo 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 "erróneo" 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. 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. Consulte el apartado Implementar asignaciones en FlowForce Server para más información.
Para aprender a crear llamadas a servicios web genéricos y ver instrucciones paso a paso consulte estos apartados: