3.4.0

Servicios Web

Desde la versión 1.5.0 es posible crear y consumir Servicios Web. Internamente hace uso de la librería WSF PHP que provee acceso a diversos estándares web services. Lo que hace toba es encapsular a esta librería para facilitar la creación y consumos de estos servicios.

Instalación

WSF es un software libre que se construye en base a una implementación de SOAP llamada Apache AXIS. Para poder usarlo en PHP requiere instalar una extensión llamada wsf.

Ver Notas de Instalación de WSF

Seguridad y Configuración

Ver Seguridad y Configuración de Servicios Web

Creacion y consumo de un Servicio Web

En caso de no utilizar toba y querer comunicarse con sistemas toba ya sea como cliente o como servidor ver Integración desde/hacia servicios externos

Crear un nuevo servicio

  • Crear una operación. En el combo Tipo de operación seleccionar Servicios Web (SOAP)
  • Modificar el identificador automático de la operación, ingresar un nombre representativo. Por ej. serv_creditos
  • Una vez creada, crearle un nuevo componente de tipo servicio_web
  • Extender el componente. Las operaciones se definen con el prefijo op__, eso indica a Toba que ese metodo es una operación SOAP y no un metodo PHP común.

Se recibe como parametro el mensaje. El formato puede ser un XML on un array PHP como en el ejemplo. Como respuesta al cliente se enviara lo que se retorne de este método. El formato del payload puede ser un XML, un WSMessage o un array PHP. En este mismo formato se retornará a el cliente

    <?php

    class servicio extends toba_servicio_web
    {
        function op__eco(toba_servicio_web_mensaje $mensaje)
        {
            $array = $mensaje->get_array();
            $payload = array("Clave: {$array['clave']}. Valor: {$array['valor']}");
            return new toba_servicio_web_mensaje($payload);
        }
    }

    ?>
  • Listo. Ya podemos ingresar a http://localhost/proyecto/servicios.php/serv_creditos para ver que el servicio esta disponible

Consumir el servicio

  • En el editor de toba ir a la solapa Datos y abrir la opción Servicios Web Accesibles. Seleccionar Agregar
  • Como identificador podemos poner por ejemplo cli_creditos. La URL solo se define en esta instancia si el servicio tiene una localización determinable durante la programación del sistema. Esto no suele ser asi en los sistemas del SIU, por lo que lo dejariamos vacio. Para el ejemplo utilizar http://localhost/proyecto/servicios.php/serv_creditos
  • Ya es posible utilizar el siguiente codigo desde cualquier .php de la aplicación:
    <?php
            //--1 *Arma el mensaje
            $opciones = array('action' => 'eco');    //En action se detalla la operacion a invocarse
            $mensaje = new toba_servicio_web_mensaje(array('clave' => 'Clave', 'valor' => 'Valor'), $opciones);
        
            //--2 *Arma el servicio
            $opciones = array();
            $servicio = toba::servicio_web('cli_creditos', $opciones);
        
            //- *3  *Muestra la respuesta
            $respuesta = $servicio->request($mensaje);
            toba::notificacion()->info($respuesta->get_payload());
    ?>

Manejo de errores

Tanto en el lado cliente como lado servidor se utiliza la excepcion toba_error_servicio_web que tiene dos parametros:

  • El mensaje legible del error $e->get_mensaje()
  • Un codigo de error opcional $e->get_codigo()

Para lanzar la excepción del lado servidor:

    throw new toba_error_servicio_web("Mensaje legible", "error_alta");

Para atraparlo en el cliente:

    try {
        $respuesta = $servicio->request($mensaje);
    } catch (toba_error_servicio_web $e) {
        toba::notificacion()->info($e->get_mensaje().' (codigo "'.$e->get_codigo().'")');
    }

Debugging

Pasos a seguir:

  1. Para obtener un mayor nivel de verbosidad en los mensajes de logs, desactivar el modo es_produccion en el archivo instalacion/instalacion.ini tanto de cliente como servidor y aumentar el nivel de log de toba a Debug.
  2. WSF tiene un log propio, tanto de cliente como servidor. En sistemas unix se ubica en la carpeta /tmp
  3. ¿Salio el request del cliente?
    1. Ver logs de toba del cliente, allí se indica tanto el Request enviado como el Response recibido. Si no se registra en el log de toba el pedido, seguramente hubo un fatal_error de php. Generalmente se puede ver el motivo en el archivo error.log de apache
    2. Si el mensaje no pudo ser enviado y la librería WSF tira un error interno, se puede obtener más información buscando el archivo de log del cliente en /tmp o desde la operación de auditoría de toba_usuarios (requiere toba 2.4+)
  4. ¿Llego el mensaje al servidor?
    1. Ver si se registro el mensaje en el log de servicios_web de toba_usuarios (requiere toba 2.4+), o el log de aplicación
    2. Si no se registro nada posiblemente la librería WSF a rechazado el pedido, se pueden ver los logs del server en /tmp. Si es un error de certificados probar la misma operación sin seguridad en el envio/recepción para ver si es eso. En caso de ser este el problema puede probar volver a configurar tanto cliente como servidor, ya que debuggear la encripción/firmado puede resultar muy complicado
    3. Si no hay nada en estos logs posiblemente se este apuntando a una URL incorrecta (probar abrir la URL directamente en el navegador, debería tirar la pantalla listando los servicios web disponibles) o un segmentation fault de apache, revisar el error.log del mismo
  5. ¿Llego la respuesta del servidor al cliente?
    1. En el log de servicio web de toba_usuarios se registra
    2. Revisar el Response en el log de aplicación del cliente, para comprobar que llega lo mismo que lo enviado

Si estos archivos de logs no son suficientes, y se duda en definitiva que es lo que efectivamente se envia o recibe, existe la posibilidad muy práctica de usar un sniffer de red estilo wireshark. Allí se puede observar detalladamente el envio y recepción completo del mensaje

A partir de la versión 2.4 en la operación Auditoría > Logs de Servicios Web Ofrecidos de toba_usuarios, que consume los logs generados en la carpeta instalacion/i__desarrollo/p__proyecto/logs/web_services. El nivel de log se configura con la mismas primitivas con la que se configura el log de aplicación de toba. En caso de existir los logs de WSF, esta operación de toba_usuarios también permite descargarlos para su inspeccion