Protocolo de intercambio de información (Web Services)

Transcripción

1 CMT Sistema de Gestión de Datos de Abonado (SGDA) Nº Proyecto: SAT Protocolo de intercambio de información (Web Services) Nivel de seguridad: N1 Versión: /06/2004 Autores Carlos Guardiola Salvador Madrid Aprobación: Eduardo Blanco Avda. de Europa, 34 A Aravaca, Madrid. Tel: (+34) / (+34) Fax: (+34) / (+34)

2 Control de cambios Versión Fecha Revisado Resumen de los cambios producidos 0.1 Borrador inicial /07/2004 Primera versión oficial /07/2004 Actualización de esquemas y definiciones de los webservices asi como modificacion de los diagramas de uso /07/ /09/2004 Actualización de definiciones /09/2004 Actualización de definiciones /02/2005 Actualizacion de esquemas y definiciones asi como explicación de nuevas funcionalidades /03/2006 Nuevos webservices para consulta de operaciones pendientes de cargas y descargas.

3 Índice 1. Introducción Descripción de los Servicios Web Servicio Web: login Función: login Función: logout Definición WSDL Servicio Web: upload Función: operacionespendientes Función: iniciarvolumen Función: enviardatos Función: continuarvolumen Función: anularvolumen Función: anularentrega Función: obtenerestadoentrega Definición WSDL Servicio Web: download Función: operacionespendientes Función: descargardatos Función: obtenerestadodescarga Función: comprobardescarga Definición WSDL Servicio web: Operaciones Pendientes para cargas Funcion: solicitudfranjas Funcion: solicitudarchivos DefinicionWSDL Servicio web: Operaciones Pendientes para descargas Funcion: solicitudfranjas Funcion: solicitudoperadores Funcion: solicitudarchivos DefinicionWSDL Protocolo de Intercambio Upload Subida de datos al sistema Continuar Volumen Otras operaciones Download Descarga de datos Otras operaciones Definiciones y Esquemas Login, Upload y Download ERROR...42 Pág. i

4 4.2. Upload y Download: Utilidades Upload, RESPUESTA_OPERACIONES_PENDIENTES Upload, SOLICITUD_INICIAR_VOLUMEN Upload, RESPUESTA_INICIAR_VOLUMEN Upload, SOLICITUD_ENVIAR_DATOS Upload, RESPUESTA_ENVIAR_DATOS Upload, SOLICITUD_CONTINUAR_VOLUMEN Upload, RESPUESTA_CONTINUAR_VOLUMEN Upload, SOLICITUD_ESTADO_ENTREGA Upload, RESPUESTA_ESTADO_ENTREGA Upload, SOLICITUD_ANULAR_VOLUMEN Upload, RESPUESTA_ANULAR_VOLUMEN Upload, SOLICITUD_ANULAR_ENTREGA Upload, RESPUESTA_ANULAR_ENTREGA Download, RESPUESTA_OPERACIONES_PENDIENTES Download, SOLICITUD_DESCARGAR_DATOS Download, RESPUESTA_DESCARGAR_DATOS Download, SOLICITUD_ESTADO_DESCARGA Download, RESPUESTA_ESTADO_DESCARGA Download, SOLICITUD_COMPROBAR_DESCARGA Download, RESPUESTA_COMPROBAR_DESCARGA Operaciones Pendientes, SOLICITUD_FRANJAS Operaciones Pendientes, RESPUESTA_FRANJAS_UPLOAD Operaciones Pendientes, SOLICITUD_ARCHIVOS_UPLOAD Operaciones Pendientes, RESPUESTA_ARCHIVOS_UPLOAD Operaciones Pendientes, RESPUESTA_FRANJAS_DOWNLOAD Operaciones Pendientes, SOLICITUD_OPERADORES Operaciones Pendientes, RESPUESTA_OPERADORES Operaciones Pendientes, SOLICITUD_ARCHIVOS_DOWNLOAD Operaciones Pendientes, RESPUESTA_ARCHIVOS_DOWNLOAD...65 Apéndice I. Referencias...66 Pág. ii

5 1. Introducción El Sistema de Gestión de Datos de Abonado (SGDA) se define como un Servicio que la CMT ofrece tanto a los Operadores como a las Entidades mediante el cual puedan intercambiar de manera telemática información sobre Datos de Abonado. Dentro del alcance original del proyecto, tal y como se describe en la Circular y en el Pliego, se establece la necesidad de hacer que ciertas operaciones sean accesibles de manera hasta cierto punto automática. La solución propuesta pasa por el intercambio de mensajes en formato XML mediante el protocolo SOAP, utilizando funciones que se definen dentro de una serie de servicios Web. Merece la pena destacar que no se considera adecuado que las operaciones sean completamente automáticas, porque el acceso al sistema se realiza en cualquier caso estableciendo una sesión SSL con el certificado digital de un usuario representante de la Entidad u Operador. Este establecimiento será responsabilidad del programa Cliente (en adelante, el cliente) que deberá tener acceso al certificado personal del representante, junto con su clave privada, para poder establecer al sesión segura con el servidor. Parece por tanto que dejar en un servidor el certificado del represente junto con su clave privada, podría ser una práctica comprometedora desde el punto de vista de la seguridad. Para SGDA, es necesario que la sesión se establezca usando el certificado del usuario; no sólo para garantizar que realmente representa a la Entidad u Operador que dice representar, sino porque además el servidor tiene que realizar operaciones de seguridad que garanticen la integridad de los datos que se suben al sistema. El objetivo de este documento es detallar los servicios Web que se han diseñado para automatizar los procesos de: Carga de datos en el sistema. Descarga de datos del sistema. Establecimiento y cierre de sesión, operaciones comunes a ambos. En cualquier caso, ambos procesos se han diseñado como un reflejo de las funcionalidades que un usuario podría hacer si accediese a la interfaz Web de SGDA. Esto significa que se han diseñado siguiendo los requisitos y las especificaciones funcionales definidos en ARS2_1 y EFS1_2 respectivamente, y por tanto están sometidos a las mismas restricciones. El documento se ha dividido en varias partes; en la primera, se describen los servicios de login, cargas (o uploads), y descargas (o downloads). En cada una de ellas de describirán las funciones: Indicando su sentido desde el punto de vista del servidor y del cliente. Pág. 1 de 49

6 Especificando sus parámetros de entrada y salida. Incluyendo los archivos con las definiciones y esquemas en formato XML de los servicios, funciones, tipos de datos, etc. En la segunda parte se presentan diagramas de intercambio de mensajes, para mayor comprensión de las operaciones descritas. En la tercera, se definen los esquemas XML que regulan el intercambio de información. Pág. 2 de 49

7 2. Descripción de los Servicios Web En este capítulo se detallan los servicios Web que se han diseñado, sus funciones, el sentido de las mismas y sus parámetros de entrada y salida Servicio Web: login Este servicio gestiona las sesiones de los clientes. Aporta las funcionalidades de crear una nueva sesión, cuando el cliente quiera acceder al sistema, y de cerrarla cuando considere oportuno Función: login Descripción Puesto que el servidor de aplicaciones de SGDA sólo es accesible mediante conexiones SSL establecidas con certificado digital de usuario, el cliente deberá implementar los mecanismos que permitan iniciar esta sesión. Internamente existirán unos manejadores que comprobarán que efectivamente el usuario que trata de iniciar la sesión tiene los permisos necesarios. Sólo si se consigue transitar por completo por la cadena de filtros, se invoca realmente la función login; el servidor creará un identificador de sesión e instanciará una serie de objetos que guardará en la sesión, que ayudarán a la gestión de las operaciones del cliente. En cualquier caso, esto es transparente al cliente; la función devuelve el valor con el identificador de la sesión ademas de establecer dicho valor en las cabeceras SOAP del mensaje. Opcionalmente, podrá devolver un mensaje de error cuando no ha sido posible realizar correctamente la operación. Por lo tanto, y a partir de este punto será responsabilidad del cliente mantener este identificador de sesión en todas las cabeceras de los mensajes SOAP que envíe al servidor. De no ser así, el servidor podría detectar el uso de sesiones caducadas o no creadas, lo que implicaría que se descartasen los mensajes Entrada No tiene parámetros de entrada, salvo el parámetro de cabecera del mensaje SOAP con un identificador de sesion aleatorio que no será utilizado. Pág. 3 de 49

8 Salida Devolverá el identificador de la sesión creada tanto en la cabecera SOAP como en el cuerpo del mensaje. Opcionalmente, podrá devolver un mensaje de tipo ERROR si surgieron problemas a la hora de realizar la operación Función: logout Descripción Esta función es la contraria de la anterior, y cierra la sesión que el usuario haya iniciado. No es necesario que el cliente pase como parámetro el identificador de la sesión, puesto que esta forma parte de la cabecera SOAP. Opcionalmente, devolverá un mensaje de tipo ERROR en caso de que se produjese alguno mientras el servidor procesa la respuesta Entrada Además del identificador de la sesión que se ha venido utilizando en la cabecera es necesario enviar el mismo identificador como parte del cuerpo del mensaje Salida Opcionalmente, podrá devolver un mensaje de tipo ERROR Definición WSDL. A continuación se muestra la definición del servicio login en formato WSDL. <definitions xmlns:er=" xmlns=" xmlns:soap=" xmlns:http=" xmlns:xs=" xmlns:soapenc=" xmlns:mime=" xmlns:l=" xmlns:ut=" targetnamespace=" <types> <xs:schema> <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" </xs:schema> </types> <message name="respuestaerror"> <part name="respuesta" type="er:error"/> <message name="session"> <part name="sessionheader" type="ut:sessionid"/> <message name="sessionparam"> <part name="session" type="xs:int"/> Pág. 4 de 49

9 <porttype name="loginservice"> <operation name="login"> <input message="l:session"/> <output message="l:sessionparam"/> <fault name="error" message="l:respuestaerror"/> <operation name="logout"> <input message="l:session"/> <output message="l:sessionparam"/> <fault name="error" message="l:respuestaerror"/> </porttype> <binding name="loginservicesoapbinding" type="l:loginservice"> <soap:binding style="rpc" transport=" <operation name="login"> <soap:operation style="rpc"/> <input> <soap:header message="l:session" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="logout"> <soap:operation style="rpc"/> <input> <soap:header message="l:session" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> </binding> <service name="loginservice"> <port name="loginservice" binding="l:loginservicesoapbinding"> <soap:address location=" </port> </service> </definitions> Tabla 1 login.wsdl Pág. 5 de 49

10 2.2. Servicio Web: upload Este servicio gestiona las operaciones de cargas de ficheros de Datos de Abonado, que los operadores tienen la obligación de incorporar al sistema. La Circular especifica que un mismo archivo de datos de abonado puede incorporarse al sistema mediante un conjunto de volúmenes. Así, al menos un archivo está compuesto de un volumen. Puesto que un volumen en sí es un archivo, y para evitar posibles confusiones, al conjunto de volúmenes que componen un archivo de datos de abonado se le denominará entrega. Hay que destacar que los volúmenes que componen la entrega se subirán por partes, de manera que la interrupción de la transmisión no suponga la subida desde el principio. Esto deberá ser tenido en cuenta por el cliente, siendo responsabilidad suya preparar los datos correctamente del volumen que desea subir. Sin embargo, el control de la transferencia recae en el servidor. Aporta las siguientes funcionalidades: Conocer las operaciones de cargas pendientes dado el día en que se accede al sistema, asi como las fechas de inicio y finalizacion del periodo de carga en el que se encuentra. Caracterizar la entrega de un archivo de datos de abonado. Enviar porciones de datos de un determinado archivo. Retomar una operación de carga que por cualquier motivo se ha pospuesto. Anular un volumen, porque desea subirse desde el principio. Anular una entrega, porque desea caracterizarse desde el principio. Obtener el estado de una entrega. En general, la mayoría de las operaciones reciben entradas y devuelven respuestas de un tipo de datos a medida de la función. Alternativamente, podrían devolver un elemento de tipo ERROR si el servidor detectase un error durante la ejecución de las mismas. Las restricciones de autenticidad y no repudio obligan a que todas las cargas de un mismo volumen sean hechas por un mismo usuario. Sólo si este decidiese anular el volumen podría subirlo otro representante. Indicar también que todas las operaciones que se realicen contra este servicio web estarán firmadas. Por parte del servidor, los mensajes SOAP que se envien estarán firmados con el certificado digital de que dispone SGDA y por parte del cliente los mensajes SOAP que envíe deberan estar firmados con el certificado digital usado para la comunicación SSL con el servidor. Pág. 6 de 49

11 Función: operacionespendientes Descripción Permite que un operador conozca las operaciones pendientes a la fecha del día en que se realiza la consulta. La respuesta vendrá ordenada en primer lugar por operadores a los que representa el usuario, después en función de los ámbitos en los que el Operador está habilitado para dar servicio, y dentro de cada uno de ellos, los archivos (entregas) que está obligado a subir al sistema y el estado de los mismos, si es que hubiese comenzado a subirlos. Puesto que la circular establece que en el ámbito Nacional habrá un archivo para numeración de Directorio, y en el resto de ámbitos provinciales un archivo para Emergencias y Guías; como mucho podrá haber hasta 3 archivos en un mismo ámbito. Dado que se incluye el estado de las transferencias, esta deberá ser la primera operación que un cliente invoque cuando haga uso del servicio de uploads. Por otra parte, el sistema detectará las siguientes condiciones: Si el sistema se encuentra en una ventana de descarga, no se podrán subir archivos en ningún caso. Si el operador se encuentra en una ventana de carga, bien de totales o de actualizaciones, recibirá la lista de archivos que el sistema espera recibir. Si el operador no se encuentra en una ventana de carga ni de descarga, pero se ha dado recientemente de alta en el sistema, el servidor permitirá que se suban archivos de totales. Si el operador no tiene obligación de subir archivos, no devolverá ningún elemento de tipo archivo. Conviene destacar que esta función permite al cliente conocer los identificadores de los archivos (entregas) que mantiene el sistema, así como de los volúmenes que haya comenzado a subir. Estos identificadores deberán usarse en la mayor parte de las funciones del servicio de upload, siendo por tanto responsabilidad del cliente obtenerlos de la respuesta y almacenarlos de la forma que considere oportuna (en la memoria del proceso, o mecanismos similares) Entrada No recibe ningún parámetro de entrada, salvo el identificador de la sesion obtenido del servicio web de Login Salida Un elemento de tipo RESPUESTA_OPERACIONES_PENDIENTES. Pág. 7 de 49

12 Función: iniciarvolumen Descripción Mediante esta operación, un Operador indica al sistema que desea comenzar la carga de uno de los volúmenes que componen una entrega de datos de abonado. Esta función requiere que el cliente aporte información que el sistema a priori desconoce, como la fecha de extracción de los datos, el número total de volúmenes que componen un archivo (entrega), el número de volumen en concreto que se quiere subir, el resumen (hash) del mismo, etc. Estos datos se detallarán en el tipo SOLICITUD_INICIAR_VOLUMEN. El resumen del fichero (HASH) debe estar codificado en hexadecimal. El sistema realizará una serie de comprobaciones, y si el cliente tiene derecho a comenzar la operación que está solicitando, creará un identificador de envío asociado a la transferencia. Este identificador se entrega junto otros datos que forman parte de la respuesta, y será responsabilidad del cliente incluirlo en todas las operaciones de transferencias de datos del volumen. Así mismo, el cliente recibe el número total de bloques de datos y el tamaño de los mismos, que el servidor espera recibir. Será responsabilidad del cliente asegurarse de cumplir estas condiciones, puesto que el servidor podrá rechazar aquellos envíos que no las respeten Entrada Un elemento de tipo SOLICITUD_INICIAR_VOLUMEN Salida Un elemento de tipo RESPUESTA_INICIAR_VOLUMEN Función: enviardatos Descripción Esta es la función que utiliza el cliente para transmitir bloques de un volumen, siempre en formato base64. Por lo tanto, en una misma sesión, el cliente deberá hacer tantas invocaciones a esta función como bloques espere el servidor recibir. Además, deberá usar los identificadores de archivo, envío y bloque que permitan caracterizar la transferencia. Será responsabilidad del cliente cumplir las siguientes condiciones: Enviar los bloques en el orden en que el servidor se los solicita. Componer bloques de información bien codificados y consecutivos, de manera que el servidor reciba todos los datos que le permitan restaurar el archivo. El servidor responderá al cliente con el estado de la recepción. Pág. 8 de 49

13 Es necesario indicar que los identificadores de los bloques empiezan en 0 no 1 y por tanto el identificador del último bloque a enviar será: numero_total_bloques 1 Todos los bloques enviados deben ir codificados en base64 lo cual no quiere decir que se deba codificar todo el fichero y luego recoger el bloque que corresponda enviar del fichero codificado, sino que se debe coger el bloque que corresponda y codificar en base64 solo el bloque. Por tanto, el tamaño del bloque indicado en las operaciones anteriores se corresponde a la cantidad de información que se debe enviar antes de codificarlo en base64 y no a la cantidad de información a enviar al WebService Entrada Un elemento de tipo SOLICITUD_ENVIAR_DATOS Salida Un elemento de tipo RESPUESTA_ENVIAR_DATOS Función: continuarvolumen Descripción Esta operación la debe invocar un cliente solamente cuando se haya interrumpido una sesión de envío, y desee retomar la transferencia en el último bloque que se envió. Deberá indicar el identificar de archivo y volumen, que pueden recuperarse en una llamada a la función operacionespendientes. El servidor responderá con el estado de la transferencia del volumen Entrada Un elemento de tipo SOLICITUD_CONTINUAR_VOLUMEN Salida Un elemento de tipo RESPUESTA_CONTINUAR_VOLUMEN Función: anularvolumen Descripción Un Operador podrá en cualquier momento anular la entrega de un volumen si detectase que por cualquier motivo sus datos estuviesen mal formados, corrompidos, y en general cualquier causa que considerase oportuna. Pág. 9 de 49

14 Para ello deberá indicar al servidor el archivo (entrega) y el volumen del mismo que desea eliminar. El servidor elimina del sistema la información asociada únicamente al volumen indicado, quedando sin modificarse el resto de los posibles volúmenes que compusieran la entrega. Esto implica que si el cliente quisiera volver a intentar la subida del volumen debe volver a caracterizarlo, usando la función empezarvolumen. Invocar a continuarvolumen con un volumen que ha sido anulado dará una respuesta errónea Entrada Un elemento de tipo SOLICITUD_ANULAR_VOLUMEN Salida Un elemento de tipo RESPUESTA_ANULAR_VOLUMEN Función: anularentrega Descripción Esta operación es de mayor alcance que la anterior, ya que permite eliminar toda la información que el sistema almacene sobre una determinada entrega. De esta forma, dado un identificador de archivo, el sistema borrará todos los volúmenes del mismo Entrada Un elemento de tipo SOLICITUD_ANULAR_ENTREGA Salida Un elemento de tipo RESPUESTA_ANULAR_ENTREGA Función: obtenerestadoentrega Descripción Esta operación permite que en cualquier momento un operador pueda conocer el estado particular de una determinado archivo (entrega) a partir del identificador del mismo. El servidor responderá con la información que posee el sistema sobre dicho archivo, y sus volúmenes Entrada Un elemento de tipo SOLICITUD_ESTADO_ENTREGA. Pág. 10 de 49

15 Salida Un elemento de tipo RESPUESTA_ESTADO_ENTREGA Definición WSDL A continuación se muestra la definición en formato WSDL del servicio upload. <definitions xmlns=" xmlns:soap=" xmlns:http=" xmlns:xs=" xmlns:soapenc=" xmlns:mime=" xmlns:u=" xmlns:rop=" xmlns:siv=" xmlns:riv=" xmlns:sed=" xmlns:red=" xmlns:scv=" xmlns:rcv=" xmlns:sav=" xmlns:rav=" xmlns:sae=" xmlns:rae=" xmlns:see=" xmlns:ree=" xmlns:ut=" xmlns:er=" targetnamespace=" <types> <xs:schema> <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" Pág. 11 de 49

16 schemalocation=" <xs:import namespace=" </xs:schema> </types> <message name="respuestaerror"> <part name="respuesta" type="er:error"/> <message name="solicitudoperacionespendientes"> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaoperacionespendientes"> <part name="respuesta" type="rop:operacionespendientes"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudiniciarvolumen"> <part name="solicitud" type="siv:iniciarvolumen"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestainiciarvolumen"> <part name="respuesta" type="ut:volumen"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudenviardatos"> <part name="solicitud" type="sed:enviardatos"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaenviardatos"> <part name="respuesta" type="red:envio"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestacontinuarvolumen"> <part name="respuesta" type="ut:volumen"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudcontinuarvolumen"> <part name="solicitud" type="scv:continuarvolumen"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudanularvolumen"> <part name="solicitud" type="sav:anularvolumen"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaanularvolumen"> <part name="respuesta" type="rav:volumenarchivo"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudanularentrega"> <part name="solicitud" type="sae:anularentrega"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaanularentrega"> <part name="respuesta" type="rae:entrega"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudestadoentrega"> <part name="solicitud" type="see:estadoentrega"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaestadoentrega"> <part name="respuesta" type="ut:archivo"/> <part name="sessionheader" type="ut:sessionid"/> <porttype name="uploadservice"> Pág. 12 de 49

17 <operation name="operacionespendientes"> <input message="u:solicitudoperacionespendientes"/> <output message="u:respuestaoperacionespendientes"/> <fault name="error" message="u:respuestaerror"/> <operation name="iniciarvolumen"> <input message="u:solicitudiniciarvolumen"/> <output message="u:respuestainiciarvolumen"/> <fault name="error" message="u:respuestaerror"/> <operation name="enviardatos"> <input message="u:solicitudenviardatos"/> <output message="u:respuestaenviardatos"/> <fault name="error" message="u:respuestaerror"/> <operation name="continuarvolumen"> <input message="u:solicitudcontinuarvolumen"/> <output message="u:respuestacontinuarvolumen"/> <fault name="error" message="u:respuestaerror"/> <operation name="anularvolumen"> <input message="u:solicitudanularvolumen"/> <output message="u:respuestaanularvolumen"/> <fault name="error" message="u:respuestaerror"/> <operation name="anularentrega"> <input message="u:solicitudanularentrega"/> <output message="u:respuestaanularentrega"/> <fault name="error" message="u:respuestaerror"/> <operation name="estadoentrega"> <input message="u:solicitudestadoentrega"/> <output message="u:respuestaestadoentrega"/> <fault name="error" message="u:respuestaerror"/> </porttype> <binding name="uploadservicesoapbinding" type="u:uploadservice"> <soap:binding style="rpc" transport=" <operation name="operacionespendientes"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudoperacionespendientes" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestaoperacionespendientes" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="iniciarvolumen"> <soap:operation style="rpc"/> <input> Pág. 13 de 49

18 <soap:header message="u:solicitudiniciarvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestainiciarvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="enviardatos"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudenviardatos" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestaenviardatos" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="continuarvolumen"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudcontinuarvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestacontinuarvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> Pág. 14 de 49

19 <operation name="anularvolumen"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudanularvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestaanularvolumen" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="anularentrega"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudanularentrega" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestaanularentrega" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="estadoentrega"> <soap:operation style="rpc"/> <input> <soap:header message="u:solicitudestadoentrega" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="u:respuestaestadoentrega" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" Pág. 15 de 49

20 namespace=" </fault> </binding> <service name="uploadservice"> <port name="uploadservice" binding="u:uploadservicesoapbinding"> <soap:address location=" </port> </service> </definitions> Tabla 2 upload.wsdl Pág. 16 de 49

21 2.3. Servicio Web: download Este servicio gestiona las operaciones de descargas de ficheros de Datos de Abonado, que las entidades tienen la obligación de incorporar al sistema. Del mismo modo que las cargas, los diferentes volúmenes que componen el archivo (entrega) se descargan por partes, de manera que la interrupción de la transmisión no suponga que el archivo se comience a descargar desde el principio. Esto deberá ser tenido en cuenta por el cliente, siendo responsabilidad suya almacenar los datos correctamente en su archivo. Por su parte, el servidor controla el último bloque que se ha entregado al cliente, siendo responsabilidad del cliente en cualquier caso saber si lo ha consolidado bien o no. Por lo tanto, las operaciones de descarga están dirigidas por el cliente, que pide un bloque concreto al servidor. La filosofía consiste en el que el cliente puede solicitar al Web Service cualquier bloque, hasta que considere que finalmente tiene el archivo completo. Será responsabilidad del cliente el planificar la política de reintentos en caso de error en la descarga y la consolidación completa del archivo, de forma que minimize el tráfico con el servidor y el tiempo de descarga. Al final, cuando el cliente considere que dispone del archivo completo, calculará el hash y se lo entregará al servidor para que este disponga de la prueba definitiva de la descarga completa, y pueda modificar el estado del archivo de forma concluyente. Aporta las siguientes funcionalidades: Conocer las operaciones de descargas pendientes dado el día en que se accede al sistema. Recibir porciones de datos de un determinado archivo. Obtener el estado de una descarga. Validar la recepcion de la entrega. En general, la mayoría de las operaciones reciben entradas y devuelven respuestas de un tipo de datos a medida de la función. Alternativamente, podrían devolver un elemento de tipo ERROR si el servidor detectase un error durante la ejecución de las mismas. Las restricciones de autenticidad y no repudio obligan a que un mismo volumen sólo pueda ser descargado por un mismo usuario. Si otro representante iniciase la descarga, deberá hacerlos desde el bloque inicial. Indicar también que todas las operaciones que se realicen contra este servicio web estarán firmadas. Por parte del servidor, los mensajes SOAP que se envien estarán firmados con el certificado digital de que dispone SGDA y por parte del cliente los mensajes SOAP que envíe deberan estar firmados con el certificado digital usado para la comunicación SSL con el servidor. Pág. 17 de 49

22 Función: operacionespendientes Descripción Permite que una entidad conozca las descargas que tiene que bajar del sistema, y el estado de las mismas. Estas se ordenarán de la siguiente forma: Una entidad al menos tendrá un servicio, aunque opcionalmente podría dar los tres servicios que se consideran en el sistema (emergencias, guías o directorio). Dentro de cada servicio, se incluirán todas las ventanas de descarga para las que la entidad puede descargar datos. El sistema impedirá que una entidad descargue datos de una ventana si tiene archivos pendientes de intervalos anteriores, para impedir que una entidad tenga datos inconsistentes. Por ejemplo, los archivos de una actualización de marzo sólo podrán obtenerse cuando se haya completado la descarga de los de la actualización de febrero. Dentro de cada ventana, los archivos se agrupan en ámbitos; serán los ámbitos territoriales en los que la entidad está habilitada. Dentro de cada ámbito, el sistema mostrará los archivos (entregas) junto con sus volúmenes y su estado. Esto incluye el último bloque que el sistema ha entregado al cliente y el número total de bloques del volumen. Por lo tanto, será responsabilidad del cliente mantener el control de los bloques que tiene que solicitar. El servidor además detectará si el sistema se encuentra en una ventana de carga; en este caso, no se podrá realizar ninguna descarga y en la respuesta no habría entradas de tipo ventana. Además, si una entidad se ha dado de alta recientemente, podrá obtener el último archivo de totales y todas las actualizaciones que haya hasta el momento. El servidor no muesra las ventanas de archivos que el cliente ya ha descargado. Conviene destacar que esta función permite al cliente conocer los identificadores de los archivos (entregas) y volúmenes que mantiene el sistema, tanto si ha comenzado o no ha descargarlos. Estos identificadores deberán usarse para la descarga y la consulta, siendo por tanto responsabilidad del cliente obtenerlos de la respuesta y almacenarlos de la forma que considere oportuna Entrada No recibe parámetros, salvo el identificador de la sesión Salida Un elemento del tipo RESPUESTA_OPERACIONES_PENDIENTES. Pág. 18 de 49

23 Función: descargardatos Descripción Permite al cliente solicitar un bloque de datos en formato base64, pertenecientes a un archivo (entrega) y volumen. El cliente debe indicar el bloque que espera recibir, si bien el servidor conoce el último bloque que ha entregado. Es necesario resaltar que el numero del bloque almacenado por el servidor es meramente informativo y que el cliente puede solicitar cualquier bloque (no tienen por que realizarse la solicitud de bloques de forma consecutiva) en cualquier momento. Además, los indices de los bloques empiezan en 0 no en 1 por lo que hy dos formas de saber si se han descargado todos los bloques de una entrega: 1. por el estado de la entrega. 2. por que el último bloque solicitado es: numero_bloques_totales 1. Todos los bloques recibidos iran codificados en base64 lo cual significa que para obtener la información real sera necesario decodificarlos primero. Dicha operación de codificación en el servidor no se hace sobre todo el fichero y luego se recoge el bloque del tamaño indicado en la funcion de operaciones pendientes sino que recoge el bloque indicado y luego es codificado. Por tanto en el cliente será necesario primero decodificar el bloque y luego añadirlo al resto de bloques ya descargados del fichero que se esta descargando Entrada Un elemento del tipo SOLICITUD_DESCARGAR_DATOS Salida Un elemento del tipo RESPUESTA_DESCARGA_DATOS Función: obtenerestadodescarga Descripción Permite al cliente conocer el estado de una descarga, a partir de un identificador de archivo. El servidor responde con la información del archivo y sus volúmenes, y el progreso de la descarga Entrada Un elemento de tipo SOLICITUD_ESTADO_DESCARGA Salida Un elemento de tipo RESPUESTA_ESTADO_DESCARGA Pág. 19 de 49

24 Función: comprobardescarga Descripción Permite al cliente comprobar que la descarga que ha realizado es correcta. Para ello debe enviar un resumen (HASH) de lo que considera que es la entrega al servidor. Alli se compara con el resumen (HASH) que envió la operadora que subió el fichero. En caso de ser iguales se responde al cliente con los datos de la entrega y si resultan diferentes se envia al cliente un mensaje de error. Esta función representa el mecanismo que el servidor tiene para averiguar cuando un cliente se ha descargado un archivo de forma completa y correcta. De esta manera, podrá cualificar el archivo en la base de datos como descargado Entrada Un elemento del tipo SOLICITUD_COMPROBAR_DESCARGA Salida Un elemento del tipo RESPUESTA_COMPROBAR_DESCARGA Definición WSDL A continuación se muestra el servicio download descrito en formato WSDL. <definitions xmlns=" xmlns:soap=" xmlns:http=" xmlns:xs=" xmlns:soapenc=" xmlns:mime=" xmlns:d=" xmlns:ut=" xmlns:er=" xmlns:rop=" xmlns:sed=" xmlns:red=" xmlns:sdd=" xmlns:rdd=" targetnamespace=" xmlns:scd=" xmlns:rcd=" <types> <xs:schema> <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" Pág. 20 de 49

25 <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" <xs:import namespace=" schemalocation=" </xs:schema> </types> <message name="respuestaerror"> <part name="respuesta" type="er:error"/> <message name="solicitudoperacionespendientes"> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaoperacionespendientes"> <part name="respuesta" type="rop:operacionespendientes"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicituddescargardatos"> <part name="solicitud" type="sdd:solicituddescargardatos"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestadescargardatos"> <part name="respuesta" type="rdd:respuestadescargardatos"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudestadodescarga"> <part name="solicitud" type="sed:solicitudestadodescarga"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestaestadodescarga"> <part name="respuesta" type="red:respuestaestadodescarga"/> <part name="sessionheader" type="ut:sessionid"/> <message name="solicitudcomprobardescarga"> <part name="solicitud" type="scd:solicitudcomprobardescarga"/> <part name="sessionheader" type="ut:sessionid"/> <message name="respuestacomprobardescarga"> <part name="respuesta" type="rcd:respuestacomprobardescarga"/> <part name="sessionheader" type="ut:sessionid"/> <porttype name="downloadservice"> <operation name="operacionespendientes"> <input message="d:solicitudoperacionespendientes"/> <output message="d:respuestaoperacionespendientes"/> <fault name="error" message="d:respuestaerror"/> <operation name="descargardatos"> <input message="d:solicituddescargardatos"/> <output message="d:respuestadescargardatos"/> <fault name="error" message="d:respuestaerror"/> <operation name="estadodescarga"> <input message="d:solicitudestadodescarga"/> <output message="d:respuestaestadodescarga"/> <fault name="error" message="d:respuestaerror"/> <operation name="comprobardescarga"> <input message="d:solicitudcomprobardescarga"/> <output message="d:respuestacomprobardescarga"/> Pág. 21 de 49

26 <fault name="error" message="d:respuestaerror"/> </porttype> <binding name="downloadservicesoapbinding" type="d:downloadservice"> <soap:binding style="rpc" transport=" <operation name="operacionespendientes"> <soap:operation style="rpc"/> <input> <soap:header message="d:solicitudoperacionespendientes" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="d:respuestaoperacionespendientes" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="descargardatos"> <soap:operation style="rpc"/> <input> <soap:header message="d:solicituddescargardatos" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="d:respuestadescargardatos" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="estadodescarga"> <soap:operation style="rpc"/> <input> <soap:header message="d:solicitudestadodescarga" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="d:respuestaestadodescarga" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" Pág. 22 de 49

27 namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> <operation name="comprobardescarga"> <soap:operation style="rpc"/> <input> <soap:header message="d:solicitudcomprobardescarga" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </input> <output> <soap:header message="d:respuestacomprobardescarga" part="sessionheader" use="encoded" namespace=" <soap:body use="encoded" namespace=" </output> <fault name="error"> <soap:fault name="error" use="encoded" namespace=" </fault> </binding> <service name="downloadservice"> <port name="downloadservice" binding="d:downloadservicesoapbinding"> <soap:address location=" </port> </service> </definitions> Tabla 3 download.wsdl 2.4. Servicio web: Operaciones Pendientes para cargas Este servicio proporciona otra forma de obtener la lista de operaciones pendientes de carga. El servicio web se encarga de proporcionar la misma información que la función operacionespendientes del servicio web Upload solo que en vez de realizar una sola llamada para obtener toda la información de operaciones pendientes, es necesario hacer sucesivas llamadas a las funciones definidas en el mismo. La razón de proporcionar este nuevo servicio es proporcionar un mecanismo a las operadores que deben cargar muchos ficheros para obtener la informacion de operaciones pendientes de carga de forma escalonada evitando asi tener que procesar un mensaje SOAP que puede llegar a ser excesivamente largo. Pág. 23 de 49