TAST DokuWiki

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Adaptador API/Servicios Web  ======



===== Introducción =====

Este adaptador es utilizado para ejecutar pruebas de Servicios Web: REST, SOAP y otros.

===== Configuración ======

En la configuración del adaptador debemos incluir todos los datos que consideremos descriptivos del servicio en general y que se aplican a todas sus peticiones. De forma que el usuario no tenga que pasarlos en cada mensaje del diagrama.
Como por ejemplo la url base del servicio, las cabeceras o el método de autenticación. 

===== Parámetros de configuración del Adaptador REST =====

  * **EndPoint:** URL base para acceder al servicio.
  * **Keep_Session:** Indica si la sesión debe mantenerse entre las solicitudes al servicio. Si está marcada, el adaptador añadirá las cookies que reciba en las respuestas a las peticiones que realice. 
  * **IsSecure:** Indica si las peticiones al servicio se enviaron a través del protocolo http o https.
  * **Service Charset(Opt.):** Para configurar el conjunto de caracteres que utilizará como servicio HTTP (por ejemplo, REST). Las palabras y oraciones en el texto se crean a partir de caracteres. Una codificación de caracteres proporciona una clave para desbloquear (es decir, descifrar) el código. Así, el conjunto de caracteres es la información de codificación, es decir, el conjunto de asignaciones entre los bytes del ordenador y los caracteres del conjunto de caracteres. Sin la clave, los datos parecen basura. Un ejemplo de conjunto de caracteres son UTF-8 o UTF-16. El Cp1047 es usado por defecto.
  * **WADL_File (Opt.):**Se trata de una descripción XML legible por máquina de los servicios web basados en HTTP (por ejemplo, REST). El objetivo del fichero WADL es modelar los recursos proporcionados por un servicio y las relaciones entre ellos.
  * **Headers:** Permite añadir cabeceras a todas las incidencias que se envien al servicio.
  * **Authentication Type**: Permite seleccionar el tipo de autenticación que requiere el servicio. Una vez seleccionado nos permite introducir los datos necesarios para el tipo de autenticación seleccionado. Por defecto, no se usa autenticación.\\ \\  

=====Nuevas Funciones Predefinidas para REST en el Adaptador Web=====

  * **deleteRest(resource, headers)**
      * Descripción: Permite configurar una petición HTTP de tipo Delete.
      * Recurso: Indica el recurso dentro del EndPoint en el que se realizará la solicitud.
      * Cabeceras: Indica las cabeceras que deben añadirse a la solicitud.
      * Charset: Para elegir el charset que queremos utilizar.
      * Cuerpo: Indica el contenido del parámetro.
   
  * **getALLJSONElementValueByTagname** 
      * Descripción: Si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de algún elemento, utilizando elTagName para identificarlo. Devuelve todos los elementos. El resultado se presenta con los valores separados por el carácter |, en el campo Mensaje / Resultado / Valor.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * JSonTagName: Expresión de nombre de etiqueta utilizada para identificar el elemento. 
 
  * **getALLXMLElementValueByTagName(StepResponse, ElementTag)**
      * Descripción: Si el contenido de la respuesta a una petición es XML, esta función permite recuperar todos los valores de los elementos, utilizando el TagName para identificarlo. En lugar de devolver sólo un elemento (el primero), este FP devuelve una lista de todos los elementos.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * ElementTag: XML´s etiqueta utilizada para identificar el elemento.

  * **getCookieValue(StepResponse, Cookie)**
      * Descripción: Recuperar el valor de la cookie indicada.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * Cookie: Indica el nombre de Cookie´s a recuperar.

  * **getElementsCountByJsonPath(JsonPath, ResponseName)**: Devuelve el número de elementos que tienen el mismo JsonPath.
      * JsonPath: El JsonPath a buscar.
      * ResponseName: El nombre con el que se generó la respuesta HTTP.

  * **getElementsCountByTagName(tagName, ResponseName)**: Devuelve el número de elementos que tienen el mismo nombre de tag.
      * tagName: El nombre de tag a buscar.
      * ResponseName: El nombre con el que se generó la respuesta HTTP.

  * **getElementsValueByJsonPath(JsonPath, ResponseName)**: Devuelve todos los elementos que tienen el mismo JsonPath.
      * JsonPath: El JsonPath a buscar.
      * ResponseName: El nombre con el que se generó la respuesta HTTP.

  * **getHeaderValue(StepResponse,  Header)**
      * Descripción: Permite obtener el valor de una cabecera recibida en una respuesta HTTP.
      * ResponseName: Indique el nombre con el que se generó la respuesta Http.
      * Cabecera: El nombre de la cabecera de la que desea extraer el valor.

  * **getHTMLElementValueByXpath()** 
      *	Descripción: Si el contenido de la respuesta a una petición es HTML esta función permite recuperar el valor de un elemento empleando para identificar este, una expresión Xpath
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      *	XPathExp: Expresión XPath utilizada para identificar el elemento.

  * **getJSONElementValueByJsonPath(StepResponse, JSonPathExp)**
      * Descripción: Si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de un elemento, utilizando el nombre de JsonPath para identificarlo. Si hay más de un elemento, devuelve el primero.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http. 
      * JSonPathExp: Expresión de JSonPath utilizada para identificar el elemento.

  * **getJSONElementValueByTagName(StepResponse, TagnameExp)**
      * Descripción: Si el contenido de la respuesta a una petición es JSON, esta función permite recuperar el valor de un elemento, utilizando el TagName para identificarlo. Si hay más de un elemento, devuelve el primero. El resultado se presenta con los valores separados por el carácter |, en el campo Mensaje / Resultado / Valor.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * JSonTagName: Expresión TTagname utilizada para identificar el elemento.

  * **getResponseBody**:

  * **getResponseStatus(StepResponse)**
      * Descripción: Permite recuperar el código de estado Http de la respuesta.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.

  * **getResponseTime**: Retorna el tiempo empleado en milisegundos en recibir la respuesta a una solicitud. Para identificar la respuesta recibe un parámetro con el nombre de la variable HttpResponse  de la que queremos obtener la información.

  * **getRest(resource, headers, parameters)**
      * Descripción: Permite configurar una petición HTTP del tipo Get.
      * Recurso: Indica el recurso dentro del EndPoint en el que se realizará la solicitud.
      * Cabeceras: Indica las cabeceras que deben añadirse a la solicitud.
      * Parámetros: Indica los parámetros que deben añadirse a la URL de la incidencia.
      * Charset: Para elegir el charset que queremos utilizar.

  * **getXMLElementValueByTagName(StepResponse, ElementTag)**
      * Descripción: Si el contenido de la respuesta a una petición es XML, esta función permite recuperar el valor de un elemento, utilizando la etiqueta it´s para identificarlo. Si hay más de un elemento, devuelve el primero.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * ElementTag: XML´s etiqueta utilizada para identificar el elemento.

  * **getXMLElementValueByXPath(StepResponse, XPathExp)**
      * Descripción: Si el contenido de la respuesta a una petición es XML, esta función permite recuperar el valor de un elemento, usando para identificar este, una expresión XPath. Además permite buscar valores en respuestas con un tipo de contendio XHTML.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * XPathExp: Expresión XPath utilizada para identificar el elemento.

  * **patchRest(resource, headers, content-type, body)**
      *	Descripción: Le permite configurar una petición HTTP de tipo Patch.
      *	Recurso: Indica el recurso dentro del EndPoint en el que se realizará la solicitud.
      *	Cabeceras: Indica las cabeceras que deben añadirse a la solicitud.
      *	Tipo de contenido: Cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud.
      *	Cuerpo: Contenido de la solicitud Http.

  * **postRest(resource, headers, content-type, body)** 
      * Descripción: Le permite configurar una petición HTTP de tipo Post.
      * Recurso: Indica el recurso dentro del EndPoint en el que se realizará la solicitud.
      * Cabeceras: Indica las cabeceras que deben añadirse a la solicitud.
      * Tipo de contenido: Cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud.
      * Cuerpo: Contenido de la solicitud Http.

  * **putRest(resource, headers, content-type, body)** 
      * Descripción: Permite configurar una petición HTTP de tipo Put.
      * Recurso: Indica el recurso dentro del EndPoint en el que se realizará la solicitud.
      * Cabeceras: Indica las cabeceras que deben añadirse a la solicitud.
      * Tipo de contenido: Cabecera estándar HTTP que indica el tipo de contenido que se agrega al cuerpo de la solicitud.
      * Cuerpo: Contenido de la solicitud Http.  

  * **responseBodyContainsText(responseName, searchValue)**
      * Descripción: Buscar en el campo cuerpo de la respuesta (stepResponse), si hay alguna coincidencia con el texto del parámetro searchValue. Rendimiento verdadero si es afirmativo.
      * ResponseName: Indica el nombre con el que se generó la respuesta Http.
      * SearchValue: Texto a buscar dentro del cuerpo de la respuesta.

  * **setBasicAuthentication(user, password)** 
      * Descripción: Permite configurar el esquema de autenticación de las peticiones que se envían al EndPoint como BasicAuthentication. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.
      * Usuario: Código de usuario utilizado como credencial.
      * Password: Contraseña para presentar como credencial.

  * **setBearerTokenAuthentication(token)**
      * Descripción: Permite configurar el esquema de autenticación de las peticiones que se envían al endpoint como Esquema de Autenticación de Portador de Ficha. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.
      * Token: Valor de Token que se presentará como credencial.

  * **setDigestAuthentication(user, password, realm, nonce, algorithm, Qoq, NonceCount, ClientNonce, Opaque)**
      * Descripción: Permite configurar el esquema de autenticación de las peticiones que se envían al endpoint como Digest Authentication Schema. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.
      * Usuario: Nombre de usuario utilizado como credencial.
      * Password: Contraseña para presentar como credencial.
      * Campo: Dominio de seguridad en el que debe realizarse la validación de seguridad. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * Nonce: Nonce devuelto por el servidor. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * Algoritmo: Algoritmo utilizado para el cifrado. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * Qoq: Calidad del código de protección. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * NonceCount: NonceCount asociado a la solicitud. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * ClienteNonce: Nonce generado por el cliente. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos de la respuesta al desafío.
      * Opaque: Opaque devuelto por el servidor. Es opcional, si no se conoce, el adaptador intentará realizar la validación con los datos obtenidos.

  * **setNoneAuthentication()**
      * Descripción: Permite configurar el método de autenticación de las peticiones que se envían al EndPoint como peticiones sin esquema de autenticación. Sobrescribe la configuración de seguridad realizada en la configuración del adaptador.



===== Conceptos teóricos importantes relacionados con los Servicios Web=====

====Base URL====
Sería la parte de la URL que es común a todas las peticiones o peticiones sobre ese servicio web, de forma que el usuario no tenga que introducirla en cada mensaje que configure como servicio de petición.


==== Datos de autenticación y autorización =====

Se entiende que la primera interacción que el adaptador deberá realizar con el servicio web será la de autenticación y autorización. Actualmente existen varios métodos estándar diferentes para realizar este paso y otros propietarios que dejaría para desarrollar bajo demanda, es decir, si encontramos la necesidad. 

Resaltar que no son métodos de autenticación-autorización propios de los servicios Web Rest, más bien están asociados al protocolo Http, por lo que el desarrollo debe estar orientado a ser reutilizado por el adaptador GUI Html y el adaptador Webservices SOAP, si en el futuro se pretende acceder a alguna aplicación Web que utilice alguno de estos métodos para autenticarse-autorizarse. 

	
==== Tipos de autenticación ====

Para administrar el campo authentication_type existe un campo de tipo combo, que contiene una autenticación definida, que debe ser enumerada por el usuario para su selección.{{:imagen combo auth_type english docuWiki.png?nolink&800|}}

Seguimos enumerando los tipos de autenticación, haciendo una breve descripción de los mismos y pensando en los parámetros que podríamos necesitar.	

  * **No Authorization (None Auth):** Si el usuario selecciona este método no es necesario autenticarse para utilizar el servicio.

  * **Basic Authorization (Basic Auth):** El método más simple solo requiere de los parámetros usuario y password. https://en.wikipedia.org/wiki/Basic_access_authentication

  * **Digest Authorization (Digest Auth):** Este método es un poco más complicado porque la clave está encriptada y el usuario, en la herramienta postman cuando selecciona este tipo de autenticación, solicita los siguientes parámetros:\\ \\  
      * User
      * Password\\ \\ Y como opcional (se utilizan valores por defecto si el usuario no los proporciona) lo siguiente:\\ \\ 
      * Realm: Dominio de seguridad contra el que autenticarse.
      * Algoritmo: Algoritmo de encriptación. MD5 o MD5-sess.
      * Nonce: Código que el servidor emite en la respuesta cuando una petición no está autorizada. Es único por sesión y debe ser incluido en las siguientes solicitudes.
      * Qop: Calidad de protección, los valores posibles son auth (más común) o auth-int (autorización con integridad) creo que menos soportados y utilizados.
      * Nonce Count: Número de peticiones realizadas al servidor con la misma unidad, su obligación depende del valor asignado a Qop.
      * Opaque: Es un valor devuelto por el servidor en la primera respuesta no autorizada, y debe ser añadido sin modificar todas las peticiones posteriores al servidor. https://en.wikipedia.org/wiki/Digest_access_authentication



  * ** OAuth 1.0: ** Este método, Autorización abierta, es más moderno para crear un primer estándar relacionado con la autenticación.  OAuth 2.0 se utiliza más pero podríamos encontrar un servicio que lo utilice. En Postman se solicitan los siguientes parámetros:
      * ConsumerKey: Un valor utilizado por el consumidor del servicio para identificarse con él.
      * ConsumerSecret: Token utilizado por el consumidor para validar su propiedad de la ConsumerKey.
      * Access Token: Ficha de acceso.
      * Token Secret: Otra clave para asegurar la propiedad del token de acceso.\\ \\ Y como parámetros opcionales (valores por defecto si el usuario no entra):\\ \\  
      * Signature Method: El método de firma utilizado por el consumidor para firmar las solicitudes.
      * Timestamp: Se añade una marca de tiempo a la solicitud.
      * Nonce: La cadena aleatoria generada por el cliente, se añadirá a todas las peticiones.
      * Realm: Indica el dominio de seguridad que realiza la autenticación. https://es.wikipedia.org/wiki/OAuth

  * ** OAuth 2.0: ** La evolución de OAuth 1.0, es el estándar más soportado por las grandes empresas de Internet, Google, Facebook, Twitter, etc., no siendo un experto, creo que es una autenticación de dos pasos. Postman sólo pide el parámetro:\\ 
      * Ficha de acceso. Código de acceso al servicio.\\ Pero en la opción de solicitar una petición de token de acceso los datos se autentican contra el servicio que le va a dar el código de acceso para esa operación. Además de estos métodos, en Postman aparecen otros métodos de autenticación como por ejemplo:
      * Ficha al portador. https://swagger.io/docs/specification/authentication/bearer-authentication/\\ 
      * Firma de AWS. Método propietario para autenticar en servicios web en la plataforma de nube de Amazon. http://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-authenticating-requests.html\\ 
      * Autenticación de Halcón. Nuevo. https://www.drupal.org/project/hawk_auth Implementar los diferentes métodos de autenticación en el Frontal.



====Funciones====

A continuación se muestra la lista de Funciones Predefinidas para el envío de peticiones al servidor proporcionadas por el adaptador, así como los parámetros necesarios para su ejecución. En reposo los tipos de peticiones se corresponden con los diferentes métodos/verbos contemplados en el protocolo HTTP. En principio habrá una función para formar una petición para cada método HTTP. Otro requisito es que se permita que las variables del diagrama compongan los diferentes campos de la solicitud.

Los métodos existentes son:

  * **GET:** Se utiliza para leer y recuperar la información de un recurso en el servidor. Es probablemente el más fácil de implementar ya que todos los datos más relevantes de la solicitud aparecen en la URL de la misma. 	
    * httpResponse = get (UrlBase, Resource, List Headers, List Parameters)
    * UrlBase = Se obtendría a partir de la inicialización del adaptador.
    * Recurso = El recurso que desea obtener.
    * List Headers = Una lista de encabezados que se añadirán a la solicitud y que se repetirán escribirá los valores dados en la configuración del adaptador.
    * Listar Parámetros = Lista de parámetros a añadir a la URL de la solicitud en forma de clave = valor.
    * Ejemplo = {{:Ej_GET_WS Adaptor.png?nolink&425|}}  
    * Como hemos dicho las peticiones get se utilizan para recuperar la información asociada a un recurso en el servidor, el tipo de recurso recuperado se reporta en el encabezado de tipo media, podríamos recuperar información con formato Json, Xml, Html, Pdf, Word, Excel.
    * Una de las cuestiones que la función debe responder es cómo reportar la evidencia de su correcta ejecución, más allá de incluir un mensaje en el log de la aplicación indicando si fue ejecutada correctamente, debemos considerar la opción de generar un archivo de evidencias con el contenido de la respuesta.
    * Por ejemplo supongamos que una petición llega a la aplicación cuyo resultado en la propia aplicación es la descarga de un archivo Pdf o Excel, creo que al ejecutarlo en Tast y recuperar el archivo debemos crearlo en el directorio de evidencias de la ejecución.
    * Esta es la pantalla simple en la que el usuario incluye encabezados y cabeceras como una sola cadena que será analizada por el adaptador para descomponerla, se podría hacer otro diseño en el que el usuario estaría agregando parámetros o cabeceras a su gusto.

  * **POST:** Se utiliza para crear un recurso en el servidor, con la información contenida en un formulario, o en un archivo Json, XML u otro. Es decir, la forma en que se transmiten los datos en el cuerpo de la solicitud puede variar, y es necesario permitir al usuario que lo indique de alguna manera para poder construir la solicitud. Es el tipo content_type de la cabecera. 
    * httpResponse = post (UrlBase, Resource, List Headers, Content Type, Data).
    * En este caso, los datos podrían estar representados en un archivo Json o XML que el usuario debería poder subir a la aplicación o cortar y pegar en algún editor, como en el caso de las Consultas o el código Javascript.
    * En el caso de utilizar formularios, los tipos X-WWW-FORM-URLENCODED o FORM-DATA los requisitos cambian y el usuario debe proporcionarnos una serie de parámetros en forma de valor clave.
    * Así como en algunos casos adjuntar archivos a la solicitud. 
    * Ejemplo = http://www.mkyong.com/java/how-to-send-http-request-getpost-in-java/ With two different libraries.

  * **PUT:** Se utiliza para actualizar la información relacionada con un recurso en el servidor. Similar al puesto en requisitos.
    * httpResponse = put ("UrlBase, Resource, List Headers, Content Type, Data).

  * **DELETE:** Se utiliza para borrar un recurso en el servidor.
    * httpRespuesta = borrar ("UrlBase, Banco, Usuario, Cuenta, saldo").

  * **HEAD:** Similar a GET, pero la respuesta no contiene el cuerpo, los datos, sólo contiene el encabezado.\\ \\ 
   

==== El problema del Mantenimiento de la sesión====

Como usted sabe, Http es un protocolo de solicitud/respuesta sin estado, pero a veces los flujos de trabajo obligan a relacionar varias solicitudes como si fueran del mismo cliente. Es decir, mantener la sesión entre el cliente y el servidor durante todo el flujo de trabajo. Normalmente se hace con cookies, aunque también se puede hacer a través de encabezados.\\ \\ En cualquier caso, esto es transparente para el usuario, pero el adaptador debe tenerlo en cuenta, ya que debe almacenar la cookie enviada por el servidor en la primera petición para añadirla a las siguientes peticiones Http en el diagrama. O en otros casos a través de Tokens que son proporcionados por el servidor después de autenticarse y que el cliente debe incluir en un encabezado en cada solicitud.\\ \\ Es posible que el usuario deba indicarnos si desea mantener una sesión durante el envío de varios mensajes consecutivos, y el mecanismo que el servidor utiliza para ello. En SoapUi, a la hora de crear un caso de prueba, nos ofrece la posibilidad de marcar una casilla de verificación que indica si queremos mantener la sesión, simplemente no pedimos más datos, entiendo que tratamos de mantenerla transparente para el usuario.\\ \\ 

====El problema de la validación de la Respuesta====

Funciones de recuperación de datos de la respuesta.\\ \\ 
Las funciones anteriores tienen por objeto validar la respuesta obtenida por la solicitud, pero aún no hemos proporcionado al usuario funciones que le permitan recuperar la información contenida en la respuesta.\\ \\ 
Como hemos indicado anteriormente, algunas de estas funciones podrían serlo:\\ 
   * Integer Code = GetStatusCode (httpResponse).
     * Devuelve el código de retorno como una variable del diagrama.
   * Integer timeMilis = GetResponseTime (httpResponse).
     * Devuelve el tiempo empleado en procesar la solicitud.
   * String headerValue = GetHeaderValue (httpResponse, String HeaderKey).
     * Devuelve el valor contenido en la cabecera indicada por el parámetro HeaderKey.
   * String propertyValues = GetXPathPropertyValue (httpResponse, String XPathExp);
     * Esta función devolvería el valor o lista de valores contenidos en los elementos de respuesta que se machetean con la expresión Xpath introducida como parámetro. Si hay varios elementos en el documento que cumplen la condición, todos los valores separados por algún carácter se concatenan. Sólo se aplica cuando la respuesta está en formato XML.
  * String propertyValues = GetJSonPathPropertyValue (httpResponse, String JSonPathExp); 
    * Similar a la función anterior pero utilizando el estándar JSonPath para navegar por los datos de respuesta. Sólo se aplica a las respuestas de tipo JSon. En principio desarrollaremos más funciones de este tipo que permitan recuperar los datos de la respuesta e introducirlos como variables en el flujo de ejecución del diagrama, en caso de que quieran ser utilizados como valores de entrada a otros mensajes en el diagrama.\\ \\ 

==== El problema de la sesión Mantenimiento ====

Como usted sabe, Http es un protocolo de solicitud/respuesta sin estado, pero a veces los flujos de trabajo obligan a relacionar varias solicitudes como si fueran del mismo cliente. Es decir, mantener la sesión entre el cliente y el servidor durante todo el flujo de trabajo. Normalmente se hace con cookies, aunque también se puede hacer a través de encabezados.

En cualquier caso, esto es transparente para el usuario, pero el adaptador debe tenerlo en cuenta, ya que debe almacenar la cookie enviada por el servidor en la primera petición para añadirla a las siguientes peticiones Http en el diagrama. O en otros casos a través de Tokens que son proporcionados por el servidor después de autenticarse y que el cliente debe incluir en un encabezado en cada solicitud.

Es posible que el usuario deba indicarnos si desea mantener una sesión durante el envío de varios mensajes consecutivos, y el mecanismo que el servidor utiliza para ello. En SoapUi, a la hora de crear un caso de prueba, nos ofrece la posibilidad de marcar una casilla de verificación que indica si queremos mantener la sesión, simplemente no pedimos más datos, entiendo que tratamos de mantenerla transparente para el usuario.



===== Asistente de Mapeo REST =====

El asistente de mapeo REST permite, a partir de un diagrama ya almacenado, modificar aquellos mensajes directos cuyo destino es un objeto mapeado con el adaptador WebService.

Aquellos mensajes que tengan mapeada una función predefinida pueden ejecutarse tal y como se ejecutarían cuando se lanza una prueba. La ejecución genera datos que serán presentados al usuario.

Es posible también editar y ejecutar afirmaciones que han sido asociadas previamente a los mensajes.

====Requisitos previos====

Para que el asistente de mapeo de REST funcione perfectamente es necesario incluir un prerrequisito en la configuración del navegador. Es necesario permitir la apertura de ventanas emergentes bajo la URL de la aplicación.

En Internet Explorer 11:

   * Abrir //Herramientas//:
{{:Asistente_mapeo_REST_eng_21.png?nolink&1600|}}

   * Seleccione //Internet options// en el menú desplegable.
   * Abra la pestaña //Privacidad//.
   * En la sección //Item Blocker//, compruebe si //Activate the pop-up blocker// está activado.
   * En caso afirmativo, haga click en el botón //Settings//.
   * En el cuadro de texto //Dirección del sitio web que desea permitir//, introduzca la URL base de la aplicación. Ejemplo: si estamos en la página https://TAST/opendiagram?id=5213 de nuestra aplicación TAST, tendremos que seleccionar de la barra doble a la siguiente barra: //TAST//
   * Haga click en //Add//.\\ \\ 





====Abrir el asistente de Mapeo REST====

El Asistente de mapeo REST se abre desde la vista Modelado/Diagrama UML. Para abrirlo, es necesario hacer click en el "icono de la varita mágica" de la barra de herramientas del diagrama, y seleccionar la opción REST/TAST API.

{{:Asistente_mapeo_REST_eng.png?nolink&1600|}}

Este asistente sólo se abrirá si el diagrama tiene al menos un objeto, cuyo adaptador es el Adaptador WebService. En caso contrario, se informará al usuario.

El asistente se abrirá en una ventana emergente. Antes de ser lanzado, el diagrama será guardado, y más tarde, la edición será bloqueada. Ejemplo:

{{:Asistente_mapeo_REST_eng_1.png?nolink&1600|}}

Una vez cerrado el asistente (ventana emergente), los datos de mapeo del diagrama serán actualizados y desbloqueados, para que pueda seguir siendo editado.

===Vistas===
===Vista de objeto=== 

{{:Rest mapping assistant_eng_11.png?nolink&8000|}}

Desde esta vista es posible seleccionar el objeto con el que queremos trabajar. Sólo se pueden seleccionar los objetos asignados con el adaptador WebService.

Una vez seleccionado un objeto, se mostrarán los valores asignados para ese objeto. Estos valores pueden ser editados.

===Vista de mensajes===

{{:Rest mapping assistant_eng_21.png?nolink&8000|}}

Desde la vista de mensajes se puede seleccionar uno de los mensajes directos que llegan al objeto que hemos seleccionado previamente.

Se muestran los valores asignados para ese mensaje, siempre que el mensaje se haya asignado con una función predefinida. De lo contrario, todos los campos de entrada aparecerán vacíos.

La sub-sección Aserción, mostrará los datos de la aserción asociada al mensaje seleccionado, si existe. De lo contrario, los campos de entrada para la afirmación se desactivarán.


===Acciones===

{{:Rest mapping assistant_eng_3.png?nolink&115|}}

Ejecuta el mensaje seleccionado. Presenta al usuario los resultados de la ejecución. Ejemplo:

{{:Rest mapping assistant_eng_4.png?nolink&8000|}}

Se ha ejecutado el mensaje getRest. Puede ver los parámetros de entrada asociados a ese mensaje.

El resultado de la ejecución se muestra en la subsección Resultado.

Las pestañas Encabezados y Cuerpo presentan los datos recibidos después de ejecutar la solicitud.

A continuación se muestra el estado de la solicitud, el tiempo de respuesta y el tamaño que ocupa.

{{:Rest mapping assistant_eng_5.png?nolink&150|}}

Ejecuta la aserción asociada al mensaje seleccionado.

{{:Rest mapping assistant_eng_6.png?nolink&8000|}}

El resultado de la afirmación se presenta en la pestaña "Parámetros de salida".

Por el momento, no hay aserciones específicas definidas para los mensajes REST. Por lo tanto, es necesario que dichas funciones de aserción tengan al menos dos parámetros: el primero será el valor del stepResult, y el segundo contendrá el valor del resultado de la ejecución de la petición.

Para los demás parámetros de la función, es posible dar un valor desde la pestaña "Variables de entrada" de la subsección Aserción.

{{:Rest mapping assistant_eng_7.png?nolink&8000|}}

{{:Asistente_mapeo_REST_eng_2.png?nolink&140|}}

Permite guardar los datos editados.

===Funcionalidad===

===Funciones predefinidas===

Los mensajes pueden tener tres tipos de funciones predefinidas asociadas:

   * Funciones de la tecnología REST: permiten enviar solicitudes REST
   * Funciones de autenticación: permiten cambiar la autenticación utilizada durante las peticiones REST.
   * Funciones de consulta de valor: permiten obtener un valor o propiedad, en base a la respuesta de una solicitud REST enviada previamente.

=== Funciones de la tecnología REST===

Permitir el envío de solicitudes REST de tipo: GET, POST, PUT y DELETE.


=== Parámetros de entrada para las solicitudes REST=== 

  * Variable output: indica el nombre de la variable donde se guardará la respuesta de salida de la petición.
  * Recurso: indica el punto final sobre el que se realizará la solicitud REST. Ejemplo:\\ 

{{:Asistente_mapeo_REST_eng_3.png?nolink&1900|}}

  * Resto de parámetros de las peticiones: dependiendo del tipo de petición, se habilitarán algunos parámetros de entrada que se mostrarán en la sección Parámetros, introducidos en Mensaje / Petición.
    En esta sección se habilitarán cada uno de los campos de entrada de cada tipo de solicitud de REST:

  * Parámetros WS (parámetros de solicitud)
  * Cabeceras (cabeceras de solicitud)
  * Cuerpo (cuerpo de la solicitud)

Al hacer click en cada campo de texto, se abrirá la pestaña correspondiente a ese parámetro, donde se pueden rellenar sus valores. Ejemplo:\\ 

{{:Asistente_mapeo_REST_eng_4.png?nolink&400|}}

Haciendo click en Parámetros WS, podemos editar estos valores:\\

{{:Asistente_mapeo_REST_eng_5.png?nolink&500|}}

===Ejecución del mensaje===

Si hacemos click en el botón {{:Rest mapping assistant_eng_3.png?nolink&115|}} enviaremos la petición REST que estamos visualizando.

En la sección Resultado, podemos ver los datos recibidos después de ejecutar la petición:

  * Cabeceras: muestra las cabeceras devueltas por la solicitud REST.
  * Cuerpo: muestra el cuerpo del mensaje. Este cuerpo se presentará formateado automáticamente (formatos soportados: JSON, XML, HTML o Simple Text)
  * Metadatos de respuesta: muestra el estado, la hora y el tamaño de la solicitud. Ejemplo:\\ 

{{:Asistente_mapeo_REST_eng_6.png?nolink&600|}}


=== Funciones de autenticación === 

Permite cambiar la autenticación utilizada durante las peticiones REST.
  
=== Parámetros de entrada para las solicitudes de autenticación ===

   * Cuadro de texto //Auth//: se encuentra en Mensaje / Petición / Parámetros. Resume los parámetros de autenticación.


Al hacer click en este cuadro de texto se abrirá la //pestaña Auth//, donde podrá editar los valores de los parámetros de autenticación.
Los parámetros de autenticación dependen del tipo de autenticación representada por la función predefinida seleccionada. Ejemplo:

{{:Asistente_mapeo_REST_eng_7.png?nolink&3000|}}

Lista de parámetros para la autenticación BasicAuth:

{{:Asistente_mapeo_REST_eng_8.png?nolink&3000|}}


=== Ejecución del mensaje ===

Si hacemos click en el botón {{:Rest mapping assistant_eng_3.png?nolink&115|}} enviaremos la autenticación que estamos visualizando, y que será la utilizada por el resto de las peticiones REST.

La autenticación a utilizar para cada solicitud de REST realizada puede visualizarse en el campo "Authorization set by", que existe en Message.

Al enviar un mensaje de autenticación, este campo se actualizará, indicando el nombre del mensaje responsable de modificar la autenticación de futuras peticiones REST. Ejemplo: Tras ejecutar un mensaje de autenticación, podemos ver la autenticación que se utilizará para futuras peticiones REST:

{{:Asistente_mapeo_REST_eng_9.png?nolink&3000|}}

NOTA: En caso de que la autenticación sea proporcionada por los parámetros del adaptador, también se mostrará en el campo "Authorization set by":

{{:Asistente_mapeo_REST_eng_10.png?nolink&3000|}}


===Funciones de consulta de valores===

Permite obtener un valor o propiedad, a partir de la respuesta de una solicitud de REST enviada previamente.

  * Cuadro de texto //Nombre de la respuesta//: cuadro de texto donde se especifica la variable de respuesta sobre la que se realizará la consulta.
  * El cuadro de texto //Value//: se encuentra en Mensaje / Petición / Parámetros. Resume los parámetros de consulta de valores.
Al hacer click en este cuadro de texto, se abrirá la //pestaña Value//, donde podrá editar los valores de los parámetros de la consulta de valores.
Los parámetros de consulta de valores dependen del tipo de consulta que se realice. Ejemplo:

{{:Asistente_mapeo_REST_eng_11.png?nolink&3000|}}

 Parámetros para la consulta //getJSONElementValueByJsonPath///:

{{:Asistente_mapeo_REST_eng_12.png?nolink&500|}}

===Ejecución del mensaje===

Si hacemos click en el botón {{:Rest mapping assistant_eng_3.png?nolink&115|}} enviaremos la consulta, determinada por la función predefinida seleccionada en el selector "Request", y la respuesta sobre la que se realiza la consulta, campo "Response name".
La aplicación presentará el resultado de la consulta en la //pestaña Value//, existente en Mensaje / Resultado.
  * Se mostrará el resultado de la consulta. Ejemplo:\\ 

{{:Asistente_mapeo_REST_eng_13.png?nolink&500|}}

  * En caso de que no haya respuesta a la consulta, o haya error en la propia consulta, se avisará al usuario. Ejemplo:\\ 

{{:Asistente_mapeo_REST_eng_14.png?nolink&500|}}\\ 


===Cálculo de JSONPath / XPath===

Cuando se responde en formato XML / JSON, el Xpath o JSONPath se puede obtener a partir de los elementos de la propia respuesta recibida, respectivamente.
Desde la //pestaña Body//, que existe en Mensaje / Resultado, y una vez que se ha recibido una respuesta:

{{:Asistente_mapeo_REST_eng_15.png?nolink&600|}}

Se seleccionará, XML o JSON, dependiendo del tipo de Ruta a calcular. Se hará click en el botón {{:Asistente_mapeo_REST_eng_16.png?nolink&25}} 

En caso de que la respuesta no pueda ser analizada con el formato elegido, se mostrará un mensaje advirtiendo de esta situación.

{{:Asistente_mapeo_REST_eng_17.png?nolink&3000|}}

En caso de que la respuesta esté correctamente analizada, se presentará en un cuadro de texto, donde podrá hacer click en los elementos de la respuesta para los que se puede calcular el JSONPath / XPath.

{{:Asistente_mapeo_REST_eng_18.png?nolink&3000|}}

Los elementos sobre los que se puede obtener su JSONPath / Xpath, presentarán una mano cuando el cursor pase sobre ellos.\\ 
Al hacer click en ellos, el JSONPath / XPath se presentará en el cuadro de texto inmediatamente inferior:

{{:Asistente_mapeo_REST_eng_19.png?nolink&3000|}}

El valor calculado de JSONPath / XPath se puede copiar en el portapapeles haciendo click en el botón {{:Asistente_mapeo_REST_eng_20.png?nolink&30|}}
TAST DokuWiki

User Tools

Site Tools

Page Tools
