Suscripción a un servicio web en 4D

4D le permite suscribirse a servicios web; es decir, llamar servicios web externos desde el interior de sus bases de datos.

Utilizando los servicios web disponibles en Internet, puede añadir fácilmente numerosas funciones adicionales a sus bases, tales como información del mercado de valores, seguimiento de entrega de paquetes, ejecución de cálculos complejos, etc. La multitud de servicios web disponibles en Internet puede suplir la mayoría de las necesidades.

Igualmente puede suscribirse a los servicios web que usted ha publicado en otras bases y de esta forma permitir que varias bases de datos se comuniquen entre ellas mismas.

Toda base 4D puede suscribirse a un servicio web; simplemente necesita estar conectada a Internet.

Por lo general, para poder llamar un servicio web, debe seguir los siguientes pasos: 

1. Encuentre el URL del Servicio Web al cual quiere suscribirse.
   Para hacer esto, puede utilizar los sitios web que hacen un inventario de los servicios web publicados en Internet (por ejemplo www.xmethods.net) o directorios como el UDDI. En la mayoría de los casos, debe obtener el URL del archivo WSDL para el servicio web.
   Nota: 4D puede utilizar servicios web publicados en modo RPC o DOC (ver Compatibilidad de RPC, DOC y tipos Complejos).
2. Utilizando el asistente de servicios web, analice el contenido del WSDL del servicio web a utilizar y genere el método proxy correspondiente.
   El método proxy es el método de proyecto local encargado de interrogar el servicio web y de recuperar los valores devueltos. Este paso se describe en la sección a continuación.
   Notas:
   
   • Es posible crear métodos proxy en el asistente de servicios web sin utilizar el archivo WSDL (simplemente introduzca manualmente los parámetros a utilizar).
   • También es posible crear métodos proxy en el editor de métodos, sin utilizar el asistente de servicios web (usuarios avanzados).
3. En el código de su base, llame el método proxy cada vez que lo necesite pasándole los parámetros apropiados.
   Este paso se describe en Llamar un método proxy.

El método proxy maneja la conexión al servicio web:

La suscripción a un servicio web desde una aplicación 4D está a cargo completamente del asistente de servicios web. Este asistente efectúa automáticamente:

• el análisis de archivos WSDL de los servicios web a utilizar,
• la definición de los parámetros de los métodos proxy a crear,
• la creación de los métodos proxy.

Para abrir la ventana del asistente de servicios web, elija el comando Asistente servicios Web... en el menú Diseño de 4D. Aparece la ventana del asistente:

tNota: también es posible mostrar el asistente de servicios web desde el menú de opciones de la página Métodos del Explorador (ver ).

Esta ventana incluye tres áreas:

• el área “URL:” permite introducir o seleccionar el URL del archivo WSDL para el servicio web seleccionado. Esta área es un combo box que almacena los valores previamente introducidos en forma de lista desplegable.
• el área central muestra los resultados del análisis de contenido del archivo WSDL: nombres de los servicios y de los métodos publicados.
• el área inferior (“Parámetros avanzados”, oculta por defecto) muestra los parámetros del método seleccionado en el área central.

El botón Descubrir activa el análisis del archivo WSDL designado y el llenado de las áreas de información.
El botón Examinar... muestra una caja de diálogo estándar de abrir archivos, permitiendo seleccionar un archivo WSDL almacenado localmente. Su ruta de acceso, comienza por “file://”, se muestra en el
área “URL:” (es posible introducir manualmente la ruta de acceso en esta área).
El botón Crear permite generar el método proxy correspondiente al servicio web seleccionado.
El botón Cerrar cierra la caja de diálogo del asistente de servicios web.

El uso típico del asistente de servicios web consiste en analizar un archivo WSDL y luego generar el o los método(s) proxy correspondientes. Esta operación estándar es totalmente automática y
no necesita de programación o de otro conocimiento particular por parte del usuario.

Para analizar un archivo WSDL y generar el método proxy:

1. En el área “URL:”, introduzca o pegue el URL del archivo WSDL del servicio web a utilizar:
   
   Este URL puede provenir, por ejemplo, de un “directorio” de servicios web o haberse comunicado directamente por el servidor del servicio web.
   Igualmente puede especificar un URL local, es decir, la dirección de un archivo WSDL almacenado en su disco duro. Para hacer esto, haga clic en el botón Examinar... y elija el archivo WSDL local, o introduzca directamente su ruta de acceso en el área “URL:”. La ruta de acceso del archivo local comienza por “file://” luego utiliza el separador de carpetas del sistema. Debe pasar una ruta de acceso absoluta.
2. Haga clic en el botón Descubrir para que 4D analice el contenido del archivo WSDL.
   Después de un momento, el área central muestra los resultados del análisis del archivo: el (los) nombre(s) del servicio(s) web como también el (los) método(s) publicado(s) aparecen en forma de lista jerárquica.
   
   Nota: puede mostrar directamente el código fuente XML del archivo WSDL en su navegador web por defecto manteniendo presionada la tecla Mayús al hacer clic en el botón Descubrir.
   Al hacer clic en un servicio web se muestra su documentación (si la hay) al lado derecho de la ventana. De lo contrario, aparecerá la indicación “No documentación”.
   De la misma forma, la documentación (si existe) para cada método aparece cuando selecciona su nombre:
   
   Nota: si el análisis del archivo WSDL revela la presencia de parámetros de tipo complejo, el asistente muestra una bandera amarilla junto al método concerniente .
3. Seleccione el método servicio web que quiere utilizar luego haga clic en el botón Crear.
   4D genera instantáneamente el método proxy correspondiente y lo muestra en una ventana del editor de métodos:
   
   El nombre del método proxy está definido por la concatenación del prefijo por defecto “proxy_” y el nombre del método servicio web. El prefijo por defecto puede modificarse en la Página Web/Web Services de las Propiedades de la base. El nombre del método proxy también puede modificarse después de su creación; esto no influencia el funcionamiento del método.

Los métodos proxy generados por el asistente de servicios web a partir del análisis de un archivo WSDL son inmediatamente operacionales y pueden utilizarse tal cual (modo estándar).

Sin embargo, usted puede modificar los parámetros resultantes del análisis del WSDL. Por ejemplo, es posible renombrar el método proxy.

Igualmente puede utilizar el asistente de servicios web para crear un método proxy para el cual usted ha introducido manualmente los parámetros. En este caso, no utilice el analizador WSDL.
No es obligatorio introducir todos los parámetros para poder crear un método.  Incluso es posible no introducir ningún parámetro con el fin de crear una “plantilla” de método proxy que luego puede llenar utilizando el lenguaje de programación de 4D.

En estos modos no estándar, debe utilizar los parámetros avanzados del asistente de servicios web. Para mostrar estos parámetros, haga clic en el botón ubicado en la parte inferior izquierda de la ventana del asistente. Aparecen los campos de los parámetros avanzados. Si un método está seleccionado, los campos muestran sus parámetros actuales:

Todos los parámetros son modificables. Note, sin embargo, que la modificación de los parámetros resultantes del análisis WSDL (excepto el nombre del método) debe ser efectuada con precaución porque el funcionamiento del servicio web puede afectarse como consecuencia.

Esta es una descripción de los parámetros avanzados:

• Nombre del método: nombre que el asistente dará al método proxy a crear. Por defecto, este nombre está formado por el prefijo “proxy_” (modificable en las Preferencias) seguido del nombre del método seleccionado. Este nombre puede modificarse libremente (por ejemplo, si ya existe en la base de datos) sin que esto influya en el funcionamiento del servicio web.
• URL de acceso: URL al cual el método proxy envía las solicitudes SOAP.
• Acción Soap: contenido del campo SOAPAction. Este campo contiene generalmente el valor “NombreServicio#NombreMetodo.”
• Espacio de nombres: namespace del servicio web (para mayor información, consulte Personalizar un espacio de nombres).
• Parámetros: esta tabla lista los parámetros del método publicado.
  
  Cada línea de la tabla describe un parámetro:
  
  • la primera columna indica si el parámetro es de entrada (“in”) o de salida (“out”). Esta característica es evaluada desde el punto de vista del método proxy y no del método publicado.
  • la segunda columna indica el nombre del parámetro.
  • la tercera columna indica el tipo de SOAP del parámetro. Los diferentes tipos de SOAP aceptados por 4D pueden ser visualizados en el menú Tipo ubicado en el área Propiedades. El Asistente de servicios web será el responsable de asociar los tipos SOAP con los tipos 4D correspondientes en el método proxy.
    La siguiente tabla describe los tipos de valores SOAP aceptados y los tipos 4D correspondientes:
    

    Tipo SOAP	Tipo 4D correspondiente
    boolean	Booleano
    int	Entero largo
    time	Hora
    float	Real
    double	Real
    date	Fecha
    string	Texto
    base64Binary	BLOB
    ArrayOfBoolean	Array booleano
    ArrayOfInt	Array entero largo
    ArrayOfTime	Array entero largo
    ArrayOfFloat	Array real
    ArrayOfDate	Array fecha
    ArrayOfString	Array texto
    AsXML	BLOB

           
    Nota: El tipo AsXML no es un tipo SOAP, estrictamente hablando, pero se utiliza para soportar tipos XML complejos (ver [#title id="1221" anchor="503589"/]).
    El área Propiedades muestra las características del parámetro seleccionado en la tabla. El asistente de servicios web le permite modificar los parámetros existentes o añadir parámetros, por ejemplo si el archivo WSDL no está actualizado.
    
    • Para modificar un parámetro, selecciónelo y luego efectúe las modificaciones en el área Propiedades.
    • Para añadir un parámetro, haga clic en el botón Añadir luego defina sus características en el área Propiedades.
    •  Para borrar un parámetro, selecciónelo en la lista y luego haga clic en el botón Suprimir.
    Nota: las modificaciones efectuadas en los parámetros avanzados sólo se tendrán en cuenta si un método proxy es efectivamente creado con la ayuda del botón Create

Para llamar un método proxy en su código, simplemente escriba su nombre y pase los parámetros requeridos. Estos parámetros se declaran en el área de encabezado del método proxy por el Asistente de servicios web. Conforme a la sintaxis estándar para pasar parámetros entre métodos en 4D, son llamados $0, $1, $2... Pueden visualizarse en los parámetros avanzados de la descripción del método publicado (ver Uso de parámetros avanzados) y a veces se describen en su documentación. 

Por ejemplo, en el caso de un método llamado WS_EuroConverter, el método proxy puede llamarse de esta forma:

Después de la ejecución del método, aparece la siguiente alerta:

4D le permite utilizar servicios web publicados en modo RPC o DOC, incluyendo tipos complejos (ver Compatibilidad de RPC, DOC y tipos Complejos).

Nota: a pesar del hecho de ser tipos XML complejos, los arrays de datos son manejados por 4D como tipos simples.

Los métodos proxy generados por el asistente de servicios web que incluyen tipos complejos (es decir, publicados en modo RPC con tipos complejos o en modo DOC) son similares a los métodos proxy estándar. Sin embargo, notará que en ciertos casos con estos servicios web, el comando WEB SERVICE CALL incluye, como un parámetro, una constante que contiene la palabra manual. 

De hecho, el uso de tales servicios web requiere un proceso adicional. La principal razón es que los tipos complejos son intercambiados en forma de documentos o elementos XML. Esto significa que para extraer o incluir información en estos parámetros SOAP, es necesario un análisis XML previo, mientras en el caso de los tipos simples, los valores de los parámetros se pueden leer directamente.

• Uso de tipos simples (RPC)
  

• Uso de tipos compuestos (DOC)
  

Sólo las tablas y los datos de tipo complejo en un nivel (un solo nivel jerárquico en la solicitud SOAP) son totalmente soportados por el asistente de servicios web. Si se encuentran elementos más complejos en la solicitud, el asistente lo indicará con una bandera desplegada junto al nombre del método. El soporte de este tipo de servicio web generalmente requiere de procesos personalizados por parte del desarrollador.

En 4D, los parámetros de tipo complejo (excepto tablas) son manejados en forma de BLOBs. Los comandos XML de 4D permiten tratar el contenido de estos BLOBs. Para mayor información, consulte los temasServicios Web (Cliente) y XML DOM del manual de Lenguaje 4D.