Configurar solicitudes REST
La configuración de las solicitudes REST se define en el cuadro de diálogo Solicitud RESTful API (ver imagen siguiente). A este cuadro de diálogo se accede en dos situaciones:
•Al definir una fuente de página que use una solicitud REST para conectarse a una fuente de datos.
•Con la acción Ejecutar solicitud REST. En este caso, la respuesta a la solicitud se puede almacenar en la variable $MT_HTTPExecute_Result.
Puede elegir si prefiere (i) definir su propia configuración, (ii) importar una URL o (ii) usar un archivo WADL. Si elige definir su propia configuración, podrá crear sus propias definiciones para cada opción individual. Si importa una URL o usa un archivo WADL, hay opciones que vendrán definidas en la URL o el archivo WADL y que, por tanto, no podrá personalizar.
Estas son las diferentes opciones:
•Plantillas y análisis de resultados, incluyendo $MT_HTTPExecute_Result
•URL
Plantillas y análisis de resultados
Las plantillas son los tres marcos dentro de los cuales se pueden definir opciones de configuración, tanto si es personalizada, con una URL o con un archivo WADL (imagen anterior). Puede cambiar de una plantilla a otra en cualquier momento seleccionando el botón de opción correspondiente. Si ya ha seleccionado la plantilla de la URL o la del archivo WADL, pero quiere usar una URL o un archivo WADL diferentes, entonces haga clic en Usar una URL o Usar un archivo WADL respectivamente. Al seleccionar cualquiera de esas dos opciones (o al hacer clic en el botón Importar... que corresponda) se abre un cuadro de diálogo en el que puede especificar la URL o el archivo WADL que desea usar.
Definir configuración propia
Si define una configuración propia, puede introducir la solicitud de acceso a un servidor REST en forma de URL, indicar el formato de los datos del recurso de destino (XML, HTML o JSON) y, a continuación, introducir los datos de autenticación del usuario (y, si corresponde, los parámetros de búsqueda), así como el contenido y los encabezados HTTP. Consulte a continuación las descripciones de cada una de las opciones.
Usar una URL
Si una URL es larga o compleja, es mejor importarla en la plantilla Usar una URL que introducirla en la plantilla Definir configuración propia. Por ejemplo, una URL puede contener varios parámetros, como en el caso del siguiente ejemplo (una consulta de Google que contiene cinco parámetros):
https://www.google.at/search?q=REST+WADL&ie=utf-8&oe=utf-8&gws_rd=cr&ei=89cDVrDHMIP0Up_5vcAB
Si importa esta URL, la URL se introduce automáticamente en el campo URL de la plantilla y los parámetros pasan automáticamente a la tabla Parámetros de la plantilla. Puede seleccionar el formato de datos del recurso de destino (XML, HTML o JSON) y el Método de solicitud (GET, PUT, POST o DELETE). Ahora puede introducir valores para los parámetros, pero no puede eliminar parámetros ni cambiar su tipo. Si quiere cambiar la URL, haga clic en Importar desde una URL. Para ver las descripciones de los parámetros consulte el apartado Parámetros más abajo.
Usar un archivo WADL
Un archivo WADL es un documento XML que define los recursos que ofrece un servicio web y las relaciones entre dichos recursos. Los recursos vienen definidos por los elementos resource. Cada recurso contiene: (i) elementos param para describir las entradas de un recurso y (ii) elementos method para describir la solicitud y la respuesta de un recurso. El elemento request indica cómo se representa la entrada, qué tipos se necesitan y si hay algún encabezado HTTP concreto que sea necesario. El elemento response describe la respuesta del servicio, así como información sobre errores.
Al seleccionar la opción WADL, la aplicación le pedirá que indique qué archivo WADL quiere usar. Tras hacer clic en Aceptar, aparece el cuadro de diálogo "Elija un método para el recurso" (imagen siguiente). Este cuadro de diálogo muestra los métodos que hay definidos en el archivo WADL.
Seleccione el método que prefiera y haga clic en Aceptar. La URL del recurso se introduce en el campo URL de la plantilla y los parámetros, el contenido y los encabezados HTTP definidos en el archivo WADL para ese recurso pasan a las tablas correspondientes de la plantilla (imagen siguiente). En la plantilla, puede introducir los valores de los parámetros, del contenido y de los encabezados HTTP, pero no puede eliminar parámetros ni editar sus nombres.
Analizar resultados como
Los resultados son lo que devuelve el servicio web en respuesta a la solicitud. En las plantillas de configuración propia o a partir de una URL, deberá indicar cómo se tienen que analizar estos resultados (como XML, HTML o JSON) para que MobileTogether pueda procesarlos correctamente. En el caso de las plantillas WADL, la información sobre el formato de los resultados se toma automáticamente de las definiciones del archivo WADL, por lo que en este tipo de plantilla se deshabilitan los botones de opción.
$MT_HTTPExecute_Result
Puede elegir si el resultado se almacena en $MT_HTTPExecute_Result o no. Si decide almacenarlo aquí, puede usar el resultado en otras ubicaciones dentro del diseño mediante esta variable. Observe que esta opción no aparece en el cuadro de diálogo Solicitud RESTful API cuando la fuente de página se define por primera vez. Tenga en cuenta que esta opción solo aparece cuando el cuadro de diálogo se abre por medio de la acción Ejecutar solicitud REST.
Método de solicitud
En las plantillas de configuración propia y en las de URL, deberá indicar el método de la solicitud (GET, PUT, POST, DELETE u otro verbo, que llamaremos verbo personalizado). Un verbo personalizado es aquel que usa el servidor desde el que está solicitando los datos de origen y el que quiere usar para la solicitud. Para usar un verbo personalizado, marque esta opción e introduzca el verbo personalizado en el campo de texto que aparece. En vez de indicar directamente el verbo personalizado, también puede usar una expresión XPath para generarlo.
En el caso de las plantillas WADL, el método de la solicitud viene determinado por la selección que haga en el cuadro de diálogo "Elija un método para el recurso" (imagen anterior), tras lo cual queda automáticamente seleccionado en la plantilla, en la que, en consecuencia, se deshabilitan esos botones de opción.
En el formulario, puede definir los siguientes tiempos de espera:
•Un tiempo de espera de la conexión, que es el tiempo que transcurre hasta que se establece una conexión TCP.
•Un tiempo de espera de la solicitud, que es el tiempo para completar la solicitud.
Ambos valores pueden introducirse directamente o mediante una expresión XPath y deben indicarse en segundos, con decimales para indicar las fracciones de segundo. La fracción mínima que se acepta es el milisegundo.
URL
El campo URL solo se puede editar en la plantilla de tipo Configuración propia. En ella, puede introducir la URL directamente o como expresión XPath. Use el botón Restaurar para borrar la entrada del campo URL.
Permitir conexiones SSL desconocidas
Un certificado asociado a una URL no se considera de confianza si no está firmado por un certificado raíz de confianza o si no puede vincularse a un certificado raíz de confianza. Si el certificado está firmado por una autoridad de certificación importante, solo significa que uno de los certificados en cadena entre el suyo y el raíz no está instalado en el servidor web. Si se espera un certificado de confianza (por ejemplo, porque se especifica el protocolo HTTPS), la selección de esta opción permite establecer conexiones también con direcciones URL que tengan un certificado que no sea de confianza.
Autenticación
Puede proporcionar información de autenticación, si esta es necesaria, para acceder al servidor. Si no se requiere autenticación, seleccione la opción Ninguna en el cuadro de diálogo Solicitud RESTful API (imagen anterior).
Hay varias formas de proporcionar la información de autenticación:
•Básica: se suministra un nombre de usuario y una contraseña (imagen siguiente)
•OAuth 1.0
•OAuth 2.0
Si quiere configurar la información de autenticación, haga clic en el botón Configurar autenticación, en el cuadro de diálogo Solicitud RESTful API (imagen anterior). Esto abre el cuadro de diálogo Configurar autenticación (imagen siguiente), donde puede seleccionar el tipo de autenticación que requiere el servidor e introducir los detalles de autenticación.
Autenticación OAuth
OAuth autentica MobileTogether Designer y autoriza el acceso a los recursos del servicio web indicado por la URL. Se asume que el servicio web es compatible con OAuth. Para ver un ejemplo de servicio web compatible con OAUTH, consulte Documentación de BitBucket sobre OAuth 1.0.
A continuación, explicamos a grandes rasgos el funcionamiento del sistema OAuth:
1.En el servicio web, cree una clave (o ID) y un secreto OAuth. Estos dos elementos juntos se denominan consumidor OAuth.
2.Anote los extremos del servicio web. Hay tres extremos para OAuth 1.0 (Extremo inicial, Extremo de la autorización y Extremo de token) y dos para OAuth 2.0 (Extremo de la autorización y Extremo de token). Los extremos suelen mantenerse constantes para todos los consumidores.
3.Configure la aplicación para que acceda al servicio web con estos cinco (OAuth 1.0) y cuatro (OAuth 2.0) elementos de autenticación.
Tras obtener su clave y su secreto del servicio web (y tras anotar qué extremos necesita), ya puede configurar MobileTogether Designer para que acceda al servicio web. Para ello, siga estos pasos:
1.En el cuadro de diálogo "Configurar autenticación" (imagen anterior), haga clic en OAuth 1.0 o en OAth 2.0. Aparecerá el cuadro de diálogo "Configuración OAuth" (imagen siguiente).
2.Defina la Dirección de devolución de llamada como http://localhost:8083. Esta dirección es invariable; se trata de la dirección del equipo que está utilizando.
3.Crear configuración nueva: debe dar un nombre a su configuración. Esto le permite volver a utilizar esa configuración (con la opción del cuadro combinado Volver a utilizar configuración) para otras soluciones que usen los mismos recursos.
4.Introduzca los extremos declarados por el servicio web. Estos suelen ser constantes para todos los consumidores del servicio web.
5.Introduzca su clave (o ID) y su secreto.
6.Para finalizar, haga clic en Autorizar.
Parámetros
En la plantilla Definir configuración propia, se pueden añadir, editar y eliminar parámetros libremente. Sin embargo, en las plantillas Usar URL y Usar WADL solo puede editar los valores de los parámetros; no puede añadir parámetros, eliminarlos ni editar sus nombres.
Puede añadir los siguientes tipos (o estilos) de parámetros (ver columna "Estilos" en la imagen siguiente):
•Template: los parámetros de tipo Template usan marcadores de posición para sustituir un valor en una URL en tiempo de ejecución. Por ejemplo, en la imagen siguiente observamos que hay un parámetro de plantilla con el marcador de posición {product}. Este marcador de posición se usa en la URL (imagen siguiente). Está entre llaves para indicar que se trata de un marcador de posición. Cuando se usa la URL en tiempo de ejecución, el valor del marcador de posición es sustituido en el lugar correspondiente dentro de la URL. La parte correspondiente de la URL, por tanto, daría como resultado: https://docs.altova.com/XMLSpy.../features.
•Matrix: en el caso de parámetros de tipo Matrix, el marcador de posición de la URL es sustituido por el par name=value. En el ejemplo de más abajo, existen dos parámetros de tipo Matrix que encontramos en la URL, como los marcadores de posición {language} y {version}. Estos marcadores, una vez resueltos, corresponderían a las partes resaltadas en azul de esta URL: https://docs.altova.com/XMLSpy;lang=es;ver=2016.../features. El punto y coma ; es un separador que precede a cada parámetro como parte de la sustitución.
•Matrix boolean: Si el valor de un parámetro de tipo Matrix boolean es true, entonces el marcador de posición del parámetro es reemplazado por el nombre del parámetro. Si el valor es false, entonces el marcador de posición es reemplazado por una cadena vacía (es decir, nada). En el ejemplo de más abajo, ese marcador de posición de tipo Matrix boolean daría como resultado la parte resaltada de esta URL: https://docs.altova.com/XMLSpy;lang=es;ver=2016;sort/features. El punto y coma ; es un separador que precede a cada parámetro como parte de la sustitución.
•Query: los parámetros de tipo Query no usan marcadores de posición. Todos los parámetros de tipo Query se recogen en una cadena de consulta que se anexa en tiempo de ejecución a la parte de la URL que indica la ruta. Por ejemplo, en tiempo de ejecución, la URL de la imagen siguiente daría como resultado: https://docs.altova.com/XMLSpy;lang=es;ver=2016;sort/features?type=PDF. El signo de interrogación ? precede a la cadena de consulta. Si hay otras consultas, el estas llevan como prefijo el símbolo &. Así, una cadena de consulta con dos consultas tendría este aspecto: ?type=PDF&about=json.
Columnas de la tabla Parámetros
La tabla Parámetros contiene cuatro columnas. Hemos explicado el uso de las primeras tres más arriba, en la descripción de los tipos de parámetros. Observe que los parámetros de tipo Template, Matrix y Matrix boolean usan marcadores de posición. Mientras que los marcadores de posición de los parámetros de tipo Template son reemplazados por valores, los de los parámetros de tipo Matrix y Matrix boolean son reemplazados respectivamente por pares nombre-valor y nombres. Los parámetros de tipo Query no tienen marcadores de posición; sus pares nombre-valor se anexan a la parte de la ruta de la URL. La columna Descripción contiene las descripciones del parámetro para usted, usuario de MobileTogether Designer.
Iconos de la tabla Parámetros y edición de la tabla
En la parte superior derecha de la tabla Parámetros, encontrará los iconos que permiten gestionar las entradas de la tabla.
•Agregar e insertar parámetros: use el icono Agregar parámetro para añadir un parámetro nuevo como último parámetro de la tabla. Use el icono Insertar parámetro para añadir un parámetro nuevo justo encima del parámetro que esté seleccionado. El orden en que se añaden los parámetros a la lista no es importante. Sí lo es el orden de los marcadores de posición en la URL. Todos los parámetros de búsqueda se recogen en una cadena de búsqueda que se anexa a la parte de la ruta de la URL en tiempo de ejecución.
•Eliminar parámetros: haga clic en Eliminar para eliminar el parámetro seleccionado.
•Expresiones XPath para los valores de los parámetros: cuando seleccione un parámetro, haga clic en XPath para abrir el cuadro de diálogo "Editar expresión XPath/XQuery" e introduzca en él una expresión que dé como resultado una cadena. Esta cadena se usa como valor del parámetro. Si es el caso, en la columna Valor del parámetro aparece un icono XPath. Puede editar la expresión XPath haciendo clic en este icono.
•Restaurar el parámetro: haga clic en Restaurar el parámetro para borrar el valor del parámetro seleccionado.
•Editar nombres y valores del parámetro: haga clic en el campo en cuestión para editarlo.
Contenido multiparte HTTP
Puede especificar qué contenido enviar con las solicitudes HTTP PUT y POST. Puede enviar ese contenido como un único elemento en el cuerpo de la solicitud (Enviar contenido como cuerpo) o como varios elementos en una solicitud multiparte (Enviar contenido como multiparte). Seleccione el botón de opción que corresponda a la variante que necesite.
Use los iconos de la parte superior derecha para agregar o insertar una entrada de contenido.
Enviar contenido como cuerpo
El contenido puede enviarse en el cuerpo (i) como un archivo, (ii) como contenido obtenido mediante la resolución de una expresión XPath, o (iii) como una cadena de texto Base64. Por ejemplo, una imagen puede enviarse como archivo o como contenido Base64, y el contenido puede introducirse directamente o se puede acceder a él desde un nodo XML (mediante una expresión XPath).
Enviar contenido como multiparte
Introduzca el nombre de la parte del contenido que se va a enviar, el tipo de acceso al contenido, el contenido mismo y el tipo MIME del contenido. El valor del contenido es el contenido que se envía. En la imagen anterior, el contenido se obtiene de nodos de fuente de página con expresiones XPath. Las imágenes se envían cifradas en Base64 o como archivo.
Campos de encabezado HTTP
Los campos de encabezado HTTP son pares nombre-valor separados por punto y coma, por ejemplo: Accept:text/plain. Agregue o inserte una entrada por cada encabezado y luego introduzca el nombre y valor del encabezado (imagen siguiente).
