Visión General

Este artículo presenta un conjunto de funciones definidas por usuario (UDFs) para DB2 que permiten que las aplicaciones consuman servicios basados en REST desde SQL. Se cubrirán los siguientes temas:

• Introducción
• UDFs REST básicas escalares
  • Enviando valores de encabezado HTTP personalizados
  • Combinando funciones XML con las UDFs REST al recuperar una transferencia de noticias de la BBC
  • Uniendo los resultados de la UDF REST con una tabla relacional
  • Seguridad— autenticación y cifrado
• Funciones de ayuda
  • Codificación/decodificación de URL
  • Codificación/decodificación Base64

Volver arriba

Introducción

El HTTP se definió hace más de 20 años cuando el último cambio significativo (HTTP 1.1) se implementó en 1999 (vea RFC2616). La longevidad del HTTP es un indicador de que es un estado estable. El HTTP es el protocolo más popular en la Web. Con el tiempo han surgido protocolos y patrones de uso adicionales como REST y WebDAV, sobre el HTTP. Muchos sitios Web y aplicaciones ofrecen interfaces basadas en HTTP para accesar a la información.

Muchos formatos de mensaje (la mayoría basados en XML) han evolucionado con el tiempo y se utilizan para intercambiar datos en conjunto don el HTTP como una capa de transporte — por ejemplo, SOAP, RSS o Atom.

Los sistemas de administración de bases de datos relacionales (RDBMS) también han evolucionado, introduciendo funcionalidades de procesamiento y almacenamiento más allá de solo datos relacionales y SQL, como el soporte nativo de XML, por ejemplo.

En este artículo presentamos extensiones hacia SQL en forma de funciones definidas por usuario (UDFs) que accesen a recursos direccionables por URL mediante HTTP directamente desde enunciados SQL. Las UDFs son llamadas REST UDFs o funciones REST. Con las nuevas funciones se pueden usar capacidades adicionales que ya están disponibles en RDBMS — como agregación SQL o acceso XPath — para manipular y almacenar datos recuperados desde la web. Con las funciones REST, se pueden emitir solicitudes HTTP GET o POST simples.

También hay firmas más complejas (minuciosas) para las funciones REST, permitiendo la inspección de códigos de respuesta HTTP y valores de encabezado, lo cual es útil en para la depuración. Las funciones REST minuciosas no se tratan en este artículo, pero usted puede dar un vistazo a las muestras en sample_tableUDF_Queries.txt para tener una idea de cómo se pueden utilizar las funciones.

Las funciones REST pueden tratar la información ingresada vía HTTP como datos binarios o textuales. Las versiones binarias accesen a información como imágenes, sonidos, y otros formatos binarios de datos, mientras que las versiones textuales se encargan de páginas HTML y otra información basada en texto convirtiendo automáticamente los datos de/hacia la página de código de base de datos usado. Los datos textuales en Internet normalmente son Unicode, mientras que los datos en bases de datos relacionales a menudo tienen otras codificaciones.

Al seguir los pasos en este artículo y en la descarga que lo acompaña, usted puede recuperar datos de la web y unirlos con datos relacionales almacenados localmente. Además, podrá aplicar capacidades de almacenamiento XML nativo en DB2 para procesar, almacenar y transformar datos basados en XML (p. ej., utilizando la función XMLTABLE para generar un conjunto de datos relacionales a partir de un documento XML).

Este artículo da inicio presentando las UDFs REST. Luego pasará a proporcionar ejemplos que manipulan información textual y binaria en la web. Se describe la personalización de solicitudes REST mediante la configuración de encabezados HTTP. Un ejemplo basado en el acceso a feeds RSS ilustra la integración de datos web y de base de datos. También se cubre el manejo de la autenticación y codificación HTTP. El artículo termina con ejemplos de funciones de ayuda para efectuar codificación UR y codificación Base64. El artículo incluye un apéndice con todo el conjunto de parámetros de función REST.

A este artículo lo acompaña una descarga que incluye las UDFs REST para DB2 para LUW y DB2 para z/OS, y varias muestras. El paquete de descarga proporciona un conjunto de escalares básicos, así como algunas funciones de ayuda.

Volver arriba

Funciones escalares REST básicas

Las funciones escalares básicas proporcionan acceso al contenido en la web. Las funciones REST están disponibles para los cuatro verbos HTTP más comunes: GET, POST, PUT y DELETE. Hay dos métodos disponibles: uno para manejar contenido binario y otro para contenido basado en texto. El esquema DB2 para las funciones es DB2XML.

Todas las funciones REST básicas son funciones escalares que retornan el contenido del mensaje HTTP de respuesta como BLOB (binario) o CLOB (textual). Las firmas de función siguen este patrón:

DB2XML.HTTP<method><type>(url, httpHeader <,
input>)

Hay un método adicional disponible para efectuar una solicitud HTTP HEAD . Esta no envía ni recupera datos. Recupere el sitio web IBM vía HTTP GET:

SELECT 
   DB2XML.HTTPGETCLOB('http://www.ibm.com','') 
FROM SYSIBM.SYSDUMMY1

El resultado es el texto HTML de la página web de IBM como datos de texto CLOB.

Enviando valores personalizados de encabezado HTTP

Arriba proporcionamos una cadena de caracteres vacía para los valores de encabezado HTTP, lo que significa que se están usando valores predeterminados cuando se emite el mensaje de solicitud. Podría ser necesario proporcionar información de encabezado personalizada con una solicitud (p. ej., para cambiar el tipo de contenido o para establecer un campo de encabezado "SOAPAction" adicional cuando se invoca el servicio web SOAP).

Con cada método se puede especificar un documento XML de encabezado HTTP que permita establecer valores de encabezado HTTP adicionales. El documento de encabezado XML debe cumplir con el siguiente formato:

			
<httpHeader connectionTimeout="10" follwRedirects="true">
	<header name="Accept" value="text/plain,application/xml,*/*;q=0.8" />
	<header name="Accept-Language" value="en-us,en;q=0.5" />
</httpHeader>

Cada campo de encabezado personalizado está representado por un elemento <header> que tiene unname y un value . El elemento raíz <httpHeader> permite especificar algunas opciones adicionales de solicitud mediante atributos.

El documento de encabezado XML se puede suministrar como un valor CLOB o XML nativo (DB2 LUW únicamente).

			
SELECT DB2XML.HTTPPOSTCLOB('http://www.webservicex.net//stockquote.asmx',
CAST ('<httpHeader>
       <header name="Content-Type" value="text/xml;charset=utf-8"/>
       <header name="SOAPAction" value="&quot;http://www.webserviceX.NET/GetQuote&quot;"/>
       </httpHeader>' AS CLOB(1K)),
 CAST('<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
          <soap:Body>
             <GetQuote xmlns="http://www.webserviceX.NET/">
                <symbol>IBM</symbol>
             </GetQuote>
          </soap:Body>
       </soap:Envelope>' AS CLOB(10K))
) FROM SYSIBM.SYSDUMMY1;

El resultado es el mensaje de respuesta del servicio web SOAP como datos de texto CLOB.

Combinando funciones XML con las UDFs REST al recuperar una transferencia de noticias de la BBC

Este ejemplo demuestra cómo usted puede recuperar fácilmente una transferencia de noticias de la BBC y transformarla en un conjunto de datos relacionales usando la función XMLTABLE del DB2.

Primero, observemos el feed RSS de la BBC usando el siguiente enunciado:

SELECT DB2XML.HTTPGETCLOB('http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk','') 
       FROM SYSIBM.SYSDUMMY1;

Ahora podemos envolver un llamado de función XMLTABLE alrededor para transformar el formato XML RSS retornado, en un conjunto de resultado relacional.

				
SELECT *
   FROM XMLTABLE('$result/rss/channel/item' 
      PASSING XMLPARSE(
         DOCUMENT 
           DB2XML.HTTPGETBLOB('http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk','')
      ) as "result"
         COLUMNS 
            title VARCHAR(128) PATH 'title',
            description VARCHAR(1024) PATH 'description',
            link VARCHAR(255) PATH 'link',
			pubDate VARCHAR(20) PATH 'substring(pubDate, 1, 16)'
   ) AS RESULT;

El conjunto resultante tiene cuatro columnas: TITLE que contiene el título del elemento feed, DESCRIPTION con la descripción del feed, LINK con el URL hacia el documento de noticias efectivo, y PUBDATE.

Se pueden encontrar más ejemplos en el paquete de descarga que viene con este artículo.

Uniendo los resultados UDF REST a una tabla relacional

En la sección anterior, la función XMLTABLE se utilizó para desmenuzar los datos XML retornados por la UDF REST. En esta sección, el ejemplo se lleva un paso más allá. El conjunto desmenuzado resultante se une a una tabla de noticias existente, con las cuatro columnas encajando en el título de la noticia.

			
   SELECT DB2XML.NEWS.*
   FROM XMLTABLE('$result/rss/channel/item' 
      PASSING XMLPARSE(
         DOCUMENT 
           DB2XML.HTTPGETBLOB('http://feeds.bbci.co.uk/news/world/rss.xml?edition=uk','')
      ) as "result"
         COLUMNS 
            title VARCHAR(128) PATH 'title'
   ) AS RESULT, DB2XML.NEWS
   WHERE RESULT.TITLE = DB2XML.NEWS.TITLE;

Seguridad— Autenticación y cifrado

Las funciones REST soportan autenticación HTTP básica, así como codificación SSL usando HTTPS.

El siguiente ejemplo muestra cómo se pueden recuperar mensajes no leídos de su cuenta Google Mail, y analizarlos en un conjunto de resultados relacional usando XMLTABLE.

El acceso a Gmail está cifrado por SSL y asegurado usando autenticación básica HTTP (en el URL se utiliza $quot;https"). Gmail retorna los encabezados de los mensajes no leídos como feeds Atom, y nosotros usamos la función XMLTABLE en este ejemplo para retornar el resultado como un conjunto de datos relacional.

SELECT *
  FROM XMLTABLE('$result/*[local-name()=''feed'']/*[local-name()=''entry'']' 
    PASSING  
       XMLPARSE(DOCUMENT 
 DB2XML.HTTPGETBLOB('https://<username>:<password>@mail.google.com/mail/feed/atom/','')) 
AS "result"
  COLUMNS 
    title VARCHAR(128) PATH '*[local-name()=''title'']',
    summary VARCHAR(1024) PATH '*[local-name()=''summary'']',
    author_name VARCHAR(255) PATH '*[local-name()=''author'']/*[local-name()=''name'']',
    author_email VARCHAR(255) PATH '*[local-name()=''author'']/*[local-name()=''email'']'
) AS RESULT;

El conjunto de resultados consiste de cuatro columnas: TITLE, SUMMARY, AUTHOR_NAME y AUTHOR_EMAIL.

Volver arriba

Funciones de ayuda

Además de las funciones REST, usted puede encontrar funciones de ayuda para efectuar codificación/decodificación URL, así como codificación y decodificación Base64.

Codificación/decodificación de URL

La especificación URL (RFC1738) define un conjunto de caracteres especiales que necesitan ser reemplazados con secuencias de escape (p. ej., si se usan en la cadena de caracteres de consulta de un URL). El paquete de funciones incluye dos funciones para efectuar la codificación y decodificación URL. El primer parámetro de la función urlEncode es la cadena de caracteres plana; el primer parámetro de la función urlDecode es la cadena de caracteres URL codificada. El segundo parámetro opcional de ambas funciones es la codificación del conjunto de caracteres a utilizarse. Si se ingresa NULL, se utiliza UTF-8, como se recomienda en la RFC3986.

SELECT DB2XML.URLENCODE(
     'Please send and email to report our % earnings to Mark & Lisa at marklisa@xyz.com'
	 , NULL) 
       FROM SYSIBM.SYSDUMMY1

Result:	   
--------------------------------------------------------------------
Please+send+and+email+to+report+our+%25+earnings+to+Mark+%26+Lisa+at+marklisa%40xyz.com

SELECT DB2XML.URLDECODE(
'Please+send+and+email+to+report+our+%25+earnings+to+Mark+%26+Lisa+at+marklisa%40xyz.com'
, NULL) 
FROM SYSIBM.SYSDUMMY1

Result:	   
----------------------------------------------------------------------
Please send and email to report our % earnings to Mark & Lisa at marklisa@xyz.com

Codificación/decodificación Base64

La codificación Base64 es ampliamente utilizada en la web para representar datos binarios como cadenas de caracteres (p. ej., cuando se envían claves hash). El paquete para descargar incluye dos funciones para efectuar codificación Base64 y decodificación.

SELECT DB2XML.BASE64ENCODE(
 CAST(
 'Please send and email to report our % earnings to Mark & Lisa at marklisa@xyz.com' 
 AS VARCHAR(100) FOR BIT DATA)) 
 FROM SYSIBM.SYSDUMMY1

Result:
-----------------------------------------------------------------------
UGxlYXNlIHNlbmQgYW5kIGVtYWlsIHRvIHJlcG9ydCBvdXIgJSBlYXJuaW5ncyB0byBNYXJrICYgTGlzYSBhdCBtY
XJrbGlzYUB4eXouY29t

SELECT 
CAST(
   DB2XML.BASE64DECODE(
'UGxlYXNlIHNlbmQgYW5kIGVtYWlsIHRvIHJlcG9ydCBvdXIgJSBlYXJuaW5ncyB0byBNYXJrICYgTGlzYSBhdCBtY
XJrbGlzYUB4eXouY29t') AS VARCHAR(100) FOR MIXED DATA) 
FROM SYSIBM.SYSDUMMY1

Result:
-----------------------------------------------------------------------
Please send and email to report our % earnings to Mark & Lisa at marklisa@xyz.com

Volver arriba

Conclusión

Las funciones DB2 REST ofrecen una forma fácil y segura para accesar a recursos en la web desde dentro de un enunciado SQL. a pesar de la simplicidad de las funciones, estas son lo suficientemente versátiles para accesar y consumir datos de muchas fuentes. Las funciones REST presentadas se mezclan sin problemas con las capacidades DB2 pureXML gracias al amplio uso de XML como formato de mensajes en la web. Este artículo explica el uso básico de las funciones REST y cómo integrar datos web con datos de bases de datos. También explica el uso de la autenticación y el cifrado. También se describen funciones de ayuda para ayudar en la codificación con URL y con Base64.

Volver arriba

Reconocimientos

Los autores del presente artículo agradecen a Ling Ling por revisarlo y por comprobar sus instrucciones.

Apéndice

DB2 para LUW únicamente: El documento httpHeader XML también puede proporcionarse como valor XML nativo en lugar de usar CLOB.

Volver arriba

Descargar

Información sobre métodos de descarga

Recursos

Aprender

• "XMLTABLE by example" es una introducción a la función XMLTABLE. Este ofrece varios ejemplos sobre cómo recuperar datos XML en un formato relacional.
  
  
• "Invoking Web services from SQL" describe un conjunto de funciones que ya existe en DB2, que permiten invocar servicios web basados e n SOAP sobre HTTP.
  
  
• La RFC 1738 y la RFC 3986 describen la sintaxis de los Uniform Resource Identifiers (URIs), incluyendo las reglas de codificación URL.
  
  
• La RFC 2616 es la especificación para HTTP 1.1.
  
  
• Consulte los especificación REST.
  
  
• Lea una descripción sobre feeds RSS.
  
  
• Aprenda sobre el estándar Atom.
  
  
• Visite los recursos developerWorks para DB2 para Linux, UNIX y Windows para leer artículos y tutoriales y para conectarse con otros recursos para expandir sus habilidades DB2.
  
  
• Conozca sobre DB2 Express-C, la versión sin costo del DB2 Express Edition para la comunidad.
  
  
• Consulte los IBM DB2 e=kit for database professionals: Conozca cuán fácil es capacitarse y certificarse en DB2 para Linux, UNIX y Windows.
  
  
• Aprenda más sobre Administración de la Información en la zona developerWorks Information Management. Encuentre documentación técnica, artículos "cómo hacer", educación, descargas, información de productos y más.
  
  
• Permanezca actualizado(a) con los Eventos técnicos y webcasts de developerWorks.
  
  
• Siga a developerWorks en Twitter.
  
  

Obtener los productos y tecnologías

• Descargue una versión de prueba gratuita de DB2 para Linux, UNIX y Windows.
  
  
• Ahora usted puede utilizar DB2 gratuitamente. Descargue DB2 Express-C, una versión gratuita del DB2 Express Edition para la comunidad, que ofrece los mismos recursos esenciales de datos que el DB2 Express Edition y que proporciona una base sólida para construir e implementar aplicaciones.
  
  
• Construya su próximo proyecto de desarrollo con software de prueba IBM, disponible para descarga directamente de developerWorks.
  
  

Comentar

• Participar en el foro de debate.
  
  
• Consulte los blogs de developerWorks y participe en la comunidad developerWorks.
  
  

Sobre los autores

Michael Schenker tiene más de siete años de experiencia laboral con IBM, tras unirse a la compañía como empleado de tiempo completo hacia finales del 2003. Durante su carrera, Michael ha trabajado en varios productos relacionados con bases de datos, comenzando como practicante en la Integración de Información DB2 con énfasis en fuentes de datos no relacionales. En 2006, Michael se unió a la organización de herramientas de bases de datos y trabajó en la funcionalidad de proveedor de servicio web DB2 en IBM Data Studio Developer. Duran te ese tiempo, ha acumulado gran experiencia en SOA y en tecnologías web. Desde el 2008, Michael ha sido parte del equipo optimizador del DB2 para z/OS, trabajando en la selección del plan de acceso y en herramientas para pruebas de optimización.

Susan Malaika es miembro sénior del personal técnico del IBM Information Management Group (parte del IBM Software Group). Sus especialidades incluyen XML, la Web y bases de datos. Ha desarrollado estándares para soportar datos en entornos de cuadrícula, en el Global Grid Forum. Adicional a su trabajo como desarrolladora de software de producto IBM, también ha trabajado como especialista en Internet, analista de datos y como diseñadora y desarrolladora de aplicaciones. También es coautora de un libro en la Web y ha publicado artículos sobre procesamiento de transacciones y XML. Es miembro de la Academia de Tecnología IBM.

Califique este artículo

Comentario

Volver arriba

Tabla de contenidos

• Visión General
• Introducción
• Funciones escalares REST básicas
• Funciones de ayuda
• Conclusión
• Reconocimientos
• Apéndice
• Descargar
• Recursos
• Sobre los autores
• Comentarios