Parámetros de los servicios web REST
Cuando necesite llamar a un servicio web con parámetros de URL, estos parámetros deben estar definidos en el cuadro de diálogo Configuración de llamadas a servicios web. Este cuadro de diálogo también sirve para configurar la solicitud del servicio web con encabezados personales. Como se describe más abajo, puede configurar los valores de los parámetros para que sean asignables (es decir, para que los provea la asignación) o fijos (definidos en el cuadro de diálogo).
Para definir los parámetros del servicio web, siga los siguientes pasos:
1.Haga doble clic en la barra de título del componente del servicio web en la asignación o haga clic con el botón derecho en ella y seleccione Propiedades. Se abrirá el cuadro de diálogo Configuración de llamadas a servicios web.
2.En la sección Definición del servicio seleccione Manual. Los parámetros se pueden introducir manualmente o automáticamente (importándolos desde una URL existente o un archivo WADL). Los parámetros importados pasan a estar disponibles en la tabla Parámetros (ver subapartado siguiente), desde donde puede modificarlos si lo necesita.
3.Utilice los botones Agregar parámetro ( 
) y Eliminar parámetro ( 
) según corresponda.
Parámetros
A continuación describimos los parámetros disponibles en el cuadro de diálogo Configuración de llamadas a servicios web.
Especifica el nombre del parámetro de URL. El nombre de parámetro debe ser único y debe estar formado por caracteres alfanuméricos, dígitos, puntos, guiones y guiones bajos. Los nombres de parámetro no pueden incluir espacios.
|
Define la sintaxis (estilo) del parámetro de URL.
•Utilice el estilo Encabezado para agregar un parámetro al encabezado HTTP cuando se llame al servicio web. Por ejemplo, si añade un parámetro llamado Accept con el valor text/xml será igual que especificar el encabezado Accept: text/xml que informa al servidor web de que MapForce espera que la respuesta esté en formato XML. Para más información sobre los encabezados HTTP consulte la especificación de encabezados de mensajes. •Utilice el estilo Consulta para parámetros URL que definan pares clave-valor en el formato ?clave=valor&clave=valor (p.ej. http://example.org/api/products?sort=asc&category=1&page=1). Se permiten estos caracteres: alfanuméricos ASCII, caracteres Unicode, -._~ /?:@!$'()*; espacio. No se permiten estos caracteres: =&#. •Utilice el estilo Plantilla para parámetros de URL que vayan entre llaves (p.ej. http://example.org/api/products/{id}). En estos casos, MapForce añade caracteres de escape a los valores siguiendo las normas RFC 6570 (https://tools.ietf.org/html/rfc6570). •Utilice el estilo Matriz para parámetros URL que definan pares clave-valor usando en el formato;clave=valor;clave=valor; (p.ej. http://example.org/api/products;sort=asc;category=1;page=1;). Para usar parámetros de matriz booleanos, elija el estilo Matriz y después el tipo boolean. •Utilice el estilo Cuerpo para enviar una estructura de solicitud con el formato application/x-www-form-urlencoded a un servicio REST (el método de solicitud debe ser POST). Para saber más sobre el formato application/x-www-form-urlencoded consulte la especificación de URL. Se permiten estos caracteres: alfanuméricos ASCII, caracteres Unicode, -._~!$'()*+,;:@%/?#[] espacio. No se permiten estos caracteres: =&.
|
Especifica el tipo de datos del parámetro (cadena, entero, fecha, etc.). Puede ser cualquier tipo de datos XML, pero recuerde que, excepto las cadenas, todos los valores se pueden convertir en cadena cuando tiene lugar la llamada al servicio web. No obstante, es importante establecer un tipo de datos si desea que MapForce muestre mensajes de error de conversión cuando intente llamar a un servicio web con valores incorrectos.
|
Marque esta casilla si quiere pasar valores a este parámetro desde la asignación. Esta opción y la opción Valor fijo se excluyen mutuamente.
|
Especifica el valor del parámetro. Solamente es relevante si el parámetro tiene un valor constante. No es relevante si el parámetro es asignable (ver opción anterior).
|
Marque esta casilla si el servicio web requiere este parámetro. En el caso de parámetros obligatorios y asignables, MapForce fuerza la validación. Es decir, si el parámetro no tiene un valor MapForce muestra un mensaje de error.
|
Especifica si el parámetro tiene un solo valor o si tiene varios. Esta opción solamente es relevante para los parámetros asignables y sirve para pasar varios valores en la misma llamada al servicio web, por medio de un solo parámetro. Si marca esta casilla, podrá conectar una secuencia de valores al nodo de estructura del parámetro en la asignación (en lugar de un solo valor). MapForce tratará la secuencia de valores en función del estilo del parámetro:
•Si se trata de parámetros de plantilla, los valores se envían al servicio web separados por comas (p.ej. http://example.org/api/products/1,2,3). •Si se trata de parámetros de consulta, se repite el nombre del parámetro tantas veces como valores haya (p.ej. http://example.org/api/products?color=red&color=green&color=blue). •Si el estilo es Matriz, los valores se separan con comas (p.ej. http://example.org/api/products;color=red;color=green;color=blue;size=big;size=small;). •Si el estilo es Encabezado, se repite el encabezado HTTP tantas veces como valores haya.
|
Indica una descripción opcional del parámetro. Si el parámetro es asignable, la descripción que se introduzca aquí aparecerá en el componente de asignación como texto de anotación del elemento de asignación.
|
Ejemplo 1: parámetros de encabezados y plantillas
El servicio web de este ejemplo recupera un producto en base a su identificador (id) por medio de un método HTTP GET. La URL del servicio web especifica el parámetro id entre llaves. Observe que el parámetro id existe en la tabla Parámetros y que tiene el estilo Plantilla. Además, está configurado como parámetro asignable, es decir, que el parámetro aparecerá en la asignación como nodo de estructura que se puede conectar al valor real de id (que se podría tomar de una base de datos, de un archivo o de una constante, por ejemplo). Cuando se ejecute la asignación, este parámetro se reemplazará con el valor real. Por tanto, si el valor es "1", la URL será http://example.org/api/products/1.
Para suministrar una constante como valor id en lugar de darle un valor desde la asignación, desmarque la casilla "Asignable" e introduzca el valor en la columna "Valor fijo".
Los parámetros Accept y Accept-Charset tienen el estilo Encabezado. Estos parámetros se usan para llamar al servicio web con encabezados de solicitud personales. Hay dos maneras de aportar un valor al encabezado:
•dejando marcada la opción Asignable y dando el valor de encabezado personal desde la asignación o
•desactivando la asilla Asignable e introduciendo el valor en la columna Valor fijo directamente.
Ejemplo 2: parámetros de matriz
El servicio web de este ejemplo recupera una lista de productos que coinciden con el color y el tamaño dados como argumentos. El estilo de los parámetros es Matriz, es decir, se pueden definir como marcadores de posición tanto dentro de la URL como en la tabla de asignación. Observe que los parámetros están marcados como asignables y que la opción Repetido está marcada. Esto significa que su valor se leerá desde una secuencia de valores de la asignación (por ejemplo, una lista de filas dentro de un archivo de texto, un nodo XML o una columna de base de datos) y se enviará al servicio web en tiempo de ejecución. Por tanto, una dirección URL como esta podrá convertirse en la URL http://example.org/api/products/;color=red;color=blue;size=big;size=small siempre y cuando la asignación aporte los valores red y blue para el color, y big y small para el tamaño.
Si necesita una URL como http://example.org/api/products;color=red,blue;size=big,small, entonces deberá:
1.Introducir la URL como http://example.org/api/products;color={color};size={size}.
2.En la tabla Parámetros cambiar el estilo del parámetro por Matriz.
Si necesita una URL como http://example.org/api/products?color=red,blue&size=big,small, entonces deberá:
1.Introducir la URL como http://example.org/api/products?color={color}&size={size}.
2.En la tabla Parámetros cambiar el estilo del parámetro por Matriz.
Ejemplo 3: parámetros de consulta
El servicio web de este ejemplo también recupera una lista de productos que coincidan con el color y el tamaño dados como argumentos, pero esta vez usando el estilo ‘Consulta’. Para este estilo no es necesario definir los parámetros como marcadores de posición en la URL, así que solamente se definen en la tabla Parámetros. En este ejemplo, imaginemos que los valores de parámetro están fijos y no hay necesidad de proporcionarlos desde la asignación. Para conseguir esto, los valores del parámetro se introdujeron en el campo ‘Valor fijo’ y se desactivó la casilla ‘Asignable’. Por tanto, cuando se ejecute la asignación, la URL pasará a ser http://example.org/api/products?color=red&size=big.
