CURL llega a N1QL: Consulta de datos JSON externos

JSON es una forma útil de transmitir datos. Ahora, N1QL puede consultarlo gracias a una actualización de CURL en Couchbase 5.0. Mira cómo conectarte a varios endpoints para hacerlo.

N1QL tiene muchas funciones que te permiten realizar una operación específica. Una de estas funciones que se ha añadido en el nuevo Couchbase 5.0 DP es CURL.

CURL le permite utilizar N1QL para interactuar con puntos finales JSON externos; es decir, API Rest que devuelven resultados y datos en formato JSON. Esta función permitirá a N1QL tener un conjunto conservador de funcionalidad curl incorporado en el lenguaje. La interacción consiste principalmente en la transferencia de datos hacia y desde un servidor utilizando los protocolos http y https. En resumen, la función CURL en N1QL le proporciona a usted, el usuario, un subconjunto de la funcionalidad estándar de curl (https://curl.haxx.se/docs/manpage.html) dentro de un lenguaje de consulta.

Para recuperar datos de diferentes servidores (como Google Maps, Yahoo Finanzas, etc.), podemos realizar peticiones GET o HTTP POST utilizando la función CURL. Esto se ve en el siguiente diagrama.

Definición de la función

CURL (URL, [opciones])

El primer argumento es la URL, que representa cualquier URL que apunte a un punto final JSON. Sólo se admiten URL con el protocolo http:// o https://. La redirección está desactivada.

Los argumentos de entrada de la función CURL() pueden ser tanto valores estáticos como expresiones N1QL evaluables.

Más adelante en el artículo veremos ejemplos que consultan desde la API de Google Geocode, la API de Yahoo Finanzas, la búsqueda de texto completo de Couchbase y la API de Github. El segundo argumento es una lista de opciones. Se trata de un objeto JSON que contiene una lista de opciones de curl y sus valores correspondientes.

Soportamos una variedad de opciones que le permiten interactuar con cualquier punto final de manera efectiva. En general, se pueden clasificar en opciones relacionadas con la seguridad y opciones generales. Al final del artículo se incluye una tabla con las opciones soportadas.

Funciones y mejoras de seguridad para CURL

Con la incorporación de la función CURL, para evitar vulnerabilidades de seguridad y controlar y minimizar los riesgos asociados a ella, se han implementado múltiples medidas de seguridad.

Uso de certificados CA con la función CURL de N1QL

Los certificados utilizados por la función N1QL CURL deben almacenarse en cada nodo de consulta dentro del clúster en el directorio n1qlcerts. La ubicación donde este directorio debe ser creado por el usuario depende de la ubicación de la instalación couchbase. (Es específico del sistema operativo). A continuación se asume la ubicación de instalación por defecto y se muestra dónde se ha creado el directorio n1qlcerts.

Para ubicaciones de instalación no predeterminadas, es necesario crear la ruta relativa - "../var/lib/couchbase/n1qlcerts directory" desde el directorio bin desde el que se ejecuta cbq-engine.

Este directorio debe crearse para cada nodo de consulta.

Una vez creado este directorio, añade aquí el certificado que CURL va a utilizar. Para usar este certificado, usamos la opción cacert y pasamos el nombre del certificado.

Por ejemplo, si n1qlcerts/usuario1.pem es el nombre del certificado, utilice la opción cacert -.

"cacert": "usuario1.pem"

Sólo son válidos los nombres, las rutas no son válidas y pasar una de ellas provocará un error. CURL() lanza un error en el caso de certificados inválidos y caducados.

NOTA: El directorio n1qlcerts y su contenido deben replicarse en cada nodo de consulta del clúster.

Cabeceras y agente de usuario personalizados

CURL() se ejecuta en el nodo de consulta dentro de un clúster. Esto permite a la función acceder a todos los puntos finales REST accesibles a través del servicio de consulta (ya que es ahí donde se ejecuta la función). Para evitar el acceso a dichos puntos finales inseguros, se añade una cabecera personalizada, que no puede ser modificada por el usuario, a todas las peticiones enviadas utilizando la función curl N1QL. Tiene el formato "X-N1QL-User-Agent: couchbase/n1ql/1.7.0-N1QL".

También se establece siempre un user-agent por defecto. Se puede restablecer con la opción -user-agent. El valor por defecto es "couchbase/n1ql/1.7.0-N1QL".

Ambos valores están diseñados para permitir que los puntos finales internos y externos comprueben la cabecera/agente-usuario y no permitan el acceso en su código y denieguen el acceso a la función. La única advertencia al usar esto, sin embargo, es que todavía no podemos proteger contra cualquier software que no compruebe esta cabecera y las versiones existentes de software instalado localmente (tanto Couchbase como software que no sea Couchbase). Para estos casos, se ha añadido la función de curl whitelist (ver más abajo).

Creación de una lista blanca para restringir el acceso a CURL.

Una lista blanca es un documento JSON que enumera los puntos finales REST permitidos y las URL a las que puede acceder la función CURL(). Las propias URL deben coincidir con un prefijo. El documento de la lista blanca se crea dentro del directorio n1qlcerts (para ver la ubicación, consulte más arriba) y se denomina curl_whitelist.json (este nombre es fijo y el usuario no puede cambiarlo). El archivo (curl_whitelist.json) debe ser creado por el administrador (o un usuario con acceso a la máquina donde está instalado couchbase).

Si la lista blanca no está configurada (..../n1qlcerts/curl_whitelist.json no existe) o si existe pero está vacía, la función CURL no se puede utilizar.

Cualquier lista blanca necesita tener los siguientes campos -

Si el campo all_access es false, entonces el uso de la función CURL ha sido completamente restringido. Para poder usar CURL() con cualquier endpoint en N1QL, el administrador necesita establecer allowed_urls y disallowed_urls en consecuencia. Para permitir el acceso a todas las urls, podemos establecer all_access a true. Esto esencialmente nos da acceso completo a CURL.

Digamos, por ejemplo, que deseamos permitir el acceso a todos los endpoints de la api de google maps pero restringir el acceso a todos los demás endpoints. Lo siguiente será el contenido de la lista blanca.

Curl_whitelist.json

Cualquier url en CURL() prefijada por https://maps.googleapis.com/ se permitirá.

NOTA: La lista blanca debe replicarse en cada nodo de consulta del clúster.

Acceso basado en roles a la función CURL

Algo importante que vale la pena mencionar aquí es que CURL está diseñado para que no pueda ser invocado arbitrariamente. Para evitar la inyección de datos desde una fuente externa mediante la sentencia UPDATE, se ha añadido un nuevo rol QUERY_EXTERNAL_ACCESS. Sólo un usuario que tenga asignado este rol tiene acceso a la función CURL. Por defecto, este rol está vacío. Sólo puede acceder a la función CURL un FULL_ADMIN o cualquier usuario al que el FULL_ADMIN haya asignado el rol QUERY_EXTERNAL_ACCESS. Para versiones anteriores de couchbase que no soportan el control de acceso basado en roles, se puede utilizar un bucket protegido por contraseña. También para la funcionalidad CURL(), internamente se soporta un conjunto específico de cifrados SSL (MEDIUM o HIGH). Esto depende de COUCHBASE_SSL_CIPHER_LIST.

Restricción del tamaño de los resultados de CURL()

Un problema importante al utilizar la función CURL() es cuando un usuario crea un archivo realmente largo, de más de 64 MB, e intenta leerlo. Dado que los datos se cargan en memoria, si no se limita el tamaño del resultado, el servicio de consulta podría bloquearse. Debido a esta posibilidad, el tamaño máximo del resultado para los datos que puede devolver CURL() es de 64 MB (67 108 864 bytes). El usuario puede restringir la cantidad de memoria para los resultados CURL utilizando el parámetro resultado-cap El valor mínimo (por defecto) de la opción result-cap es 20MB ( 20 971 520 bytes).

Por ejemplo, si la consulta fija el límite de resultado en 20 MB - "result-cap":20971520, cualquier respuesta que tenga un tamaño superior devolverá un error.

Interacción con diferentes puntos finales

Veamos como consultar diferentes endpoints usando la función CURL en N1QL.

API de geocodificación de Google Maps

La API de geocodificación de Google Maps permite convertir direcciones estáticas en coordenadas y viceversa mediante una solicitud HTTP. (Para más información, consulte https://developers.google.com/maps/documentation/geocoding/intro )

Supongamos que quieres buscar Santa Cruz en España utilizando tu clave API de Google Dev. Para ello, puede utilizar la siguiente consulta:

Solicitud de rizos

Consulta correspondiente

Esta consulta recupera la dirección y los límites de localización geográfica de la dirección, Santa Cruz, ES. Utilizamos la dirección, los componentes y los parámetros clave de la API REST de geocodificación de Google Maps. La opción "data" representa la opción data de curl que representa datos HTTP POST. Sin embargo, dado que se trata de una solicitud get, establecemos la opción "get" en true. Puedes proporcionar valores a todos los parámetros REST dentro de la opción "data".

Ahora busquemos Half Moon Bay

API de Yahoo Finanzas

La API de Yahoo Finanzas le permite utilizar el Lenguaje de consulta de Yahoo (YQL) para obtener cotizaciones bursátiles (como se ve en http://meumobi.github.io/stocks%20apis/2016/03/13/get-realtime-stock-quotes-yahoo-finance-api.html ). A continuación se muestra la sentencia YQL SELECT para acceder a las acciones de Hortonworks Inc (HDP).

Para obtener los resultados en JSON puede utilizar la siguiente URL:

https://query.yahooapis.com/v1/public/yql?q=select%20*%20from%20yahoo.finance.quotes%20where%20symbol%20in%20(%22HDP%22)&format=json&diagnostics=true&env=store%3A%2F%2Fdatatables.org%2Falltableswithkeys&callback=

Solicitud de rizos

Consulta correspondiente

Para esta consulta, el valor de la opción data contiene los parámetros REST de Yahoo, q (para la consulta YQL), format (para devolver los datos en JSON) y algunos otros parámetros.

Búsqueda de texto completo en Couchbase

La búsqueda de texto completo de Couchbase permite aplicar búsquedas difusas a los datos almacenados en Couchbase. Para más información https://www.couchbase.com/blog/couchbase-4.5-developer-preview-couchbase-fts/.

Supongamos que creas un índice FTS llamado beers en el bucket beer-sample en Couchbase. Ahora puedes buscar cerveza tipo pale ale utilizando este índice, usando la función CURL en N1QL. Es importante tener en cuenta que FTS actualmente acepta HTTP POST en lugar de GET. Para especificar explícitamente el método de petición POST, utilice la opción request.

Solicitud de rizos

Consulta correspondiente

Damos múltiples opciones en esta consulta. La opción header permite pasar una cabecera personalizada al servidor. Content-Type : application/json indica al servidor que los datos se proporcionan en formato JSON. Si tenemos un bucket protegido por contraseña en Couchbase, entonces necesitamos pasar sus credenciales con la consulta. La opción user se puede utilizar para pasar un nombre de usuario y una contraseña separados por dos puntos. La opción request especifica que se utiliza el método POST.

Si desea recuperar sólo los documentos de muestra-cerveza que devuelve la búsqueda anterior, puede escribir una consulta N1QL JOIN de la siguiente manera.

Esto recuperará los ids de los documentos devueltos por la consulta FTS que busca pale ale, junto con el total de aciertos y todos los detalles del documento correspondiente en beer-sample.

API de Github

La API de Github es un poco diferente de las anteriores, ya que devuelve múltiples resultados en forma de una matriz JSON de valores de resultado. Consulte la documentación de la API de Github en https://developer.github.com/v3/ para más detalles sobre lo que se puede consultar.

Digamos que quieres averiguar todos los repositorios vinculados a una cuenta de Github. La siguiente consulta lo hace

Solicitud de rizos

Consulta correspondiente

Si la cuenta tiene tres repositorios, la consulta devuelve tres resultados (aquí he añadido el límite 1). La palabra clave RAW se utiliza para devolver el array de documentos que devuelve la consulta, sin un objeto envoltorio. Un punto que notarás es que la opción de cabecera contiene el User-Agent con un nombre de usuario de github. Esto es ahora obligatorio para todas las peticiones a la API de Github.

Ahora, a partir de esta lista, digamos que le gustaría saber cuál es la url de clonación para cada uno de estos repos. La siguiente consulta logra esto

Resumen

Como puedes ver con los ejemplos anteriores, usando la función CURL, los usuarios de N1QL pueden ahora interactuar con cualquier API externa que devuelva resultados en formato JSON. Esto abre muchas posibilidades. Por ejemplo, si Couchbase contiene datos correspondientes a diferentes hoteles, entonces puedes utilizar la API de Google Maps para encontrar ubicaciones cercanas a cada uno de los hoteles correspondientes.

Para disponer de un entorno seguro con la incorporación de CURL() se han añadido múltiples mejoras de seguridad. La siguiente es una breve lista

• CURL se ejecuta en el nodo de consulta dentro de un clúster.
• La función CURL está desactivada por defecto.
• CURL sólo admite HTTP y HTTPS. Todos los demás protocolos están desactivados.
• No se permite la redirección de URL.
• El encabezado personalizado para N1QL CURL es "X-N1QL-User-Agent: couchbase/n1ql/1.7.0-N1QL".
• El User-Agent es "couchbase/n1ql/1.7.0-N1QL".
• Restringir la cantidad de memoria para los resultados CURL utilizando result-cap. El límite mínimo será de 20 MB y el máximo de 64 MB.
• El rol FULL_ADMIN permitirá el acceso a CURL. El rol QUERY_EXTERNAL_ACCESS puede ser asignado a un usuario por el FULL ADMIN. Esto permitirá al usuario utilizar la funcionalidad CURL.
• Los certificados deben almacenarse en la máquina local - cada nodo de consulta dentro de un cluster. Utilice ..../Couchbase/var/lib/couchbase/n1qlcerts para almacenar los certificados.Utilice cacert para pasar el "nombre" del certificado a utilizar. Sólo son válidos los nombres, las rutas no son válidas. (Pasar una ruta provocará un error).
• CURL lanza un error en caso de certificados inválidos/expirados.
• El usuario tiene la posibilidad de poner puntos finales en la "lista blanca".

La implementación N1QL de CURL utiliza la API golang libcurl - https://github.com/andelf/go-curl

Lista de opciones disponibles

Opciones de seguridad

Otras opciones relacionadas con las transferencias