Implementa un conector de bases de datos

Advertencia: Los conectores de referencia de Cloud Search se proporcionan "tal cual" como código de muestra para usarlos en la creación de tus propios conectores que funcionen. Este código de muestra requiere una personalización y pruebas sustanciales antes de usarse en entornos de prueba de concepto o de producción. Para el uso en producción, te recomendamos que obtengas ayuda de uno de nuestros socios de Cloud Search. Si deseas obtener más ayuda para encontrar un socio de Cloud Search adecuado, comunícate con tu administrador de cuentas de Google.

Puedes configurar Google Cloud Search para que descubra e indexe datos de las bases de datos de la organización mediante el conector de bases de datos de Google Cloud Search.

Consideraciones importantes

Puedes instalar y ejecutar el conector de bases de datos de Cloud Search en casi cualquier entorno en el que se puedan ejecutar las apps de Java, siempre que el conector tenga acceso a Internet y a la base de datos.

Requisitos del sistema

Requisitos del sistema
Sistema operativo Windows o Linux
Base de datos SQL Cualquier base de datos de SQL con un controlador compatible con JDBC 4.0 o posterior, incluidos los siguientes:
  • MS SQL Server (2008, 2012, 2014, 2016)
  • Oracle (11g, 12c)
  • Google Cloud SQL
  • MySQL
Software Controlador JDBC para que el conector lo use a fin de acceder a la base de datos (se descarga e instala por separado)

Implementa el conector

En los siguientes pasos, se describe cómo instalar el conector y configurarlo para indexar las bases de datos especificadas y mostrar los resultados a los usuarios de Cloud Search.

Requisitos previos

Antes de implementar el conector de bases de datos de Cloud Search, recopila la siguiente información:

Paso 1: Descarga y compila el software del conector de bases de datos

  1. Clona el repositorio del conector desde GitHub. 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. Consulta la versión deseada del conector:
    $ git checkout tags/v1-0.0.3
  3. Compila el conector. 
    $ mvn package
    Para omitir las pruebas durante la compilación del conector, usa mvn package -DskipTests.
  4. Copia el archivo ZIP del conector en el directorio de instalación local y descomprímelo: 
    $ cp target/google-cloudsearch-database-connector-v1-0.0.3.zip installation-dir
$ cd installation-dir
$ unzip google-cloudsearch-database-connector-v1-0.0.3.zip
$ cd google-cloudsearch-database-connector-v1-0.0.3

Paso 2: Configura el conector de bases de datos

  1. Crea un archivo de texto y asígnale el nombre connector-config.properties (predeterminado) o uno similar. Google recomienda que les asignes un nombre a los archivos de configuración con la extensión .properties o .config y que mantengas el archivo en el mismo directorio que el conector. Si usas un nombre o una ruta de acceso diferentes, debes especificar la ruta de acceso cuando ejecutes el conector.
  2. Agregue parámetros como pares clave-valor al contenido del archivo. El archivo de configuración debe especificar los parámetros para el acceso a la fuente de datos, el acceso a la base de datos, una instrucción de SQL de recorrido completo de la base de datos, un título de campo de contenido y las definiciones de columnas. También puedes configurar otros comportamientos del conector con parámetros opcionales. Por ejemplo: 
    # Required parameters for data source access
api.sourceId=1234567890abcdef
api.identitySourceId=0987654321lmnopq
api.serviceAccountPrivateKeyFile=./PrivateKey.json
#
# Required parameters for database access
db.url=jdbc:mysql://localhost:3306/mysql_test
db.user=root
db.password=passw0rd
#
# Required full traversal SQL statement parameter
db.allRecordsSql=select customer_id, first_name, last_name, phone, change_timestamp from address_book
#
# Required parameters for column definitions and URL format
db.allColumns=customer_id, first_name, last_name, phone, change_timestamp
db.uniqueKeyColumns=customer_id
url.columns=customer_id
#
# Required content field parameter
contentTemplate.db.title=customer_id
#
# Optional parameters to set ACLs to "entire domain" access
defaultAcl.mode=fallback
defaultAcl.public=true
#
# Optional parameters for schedule traversals
schedule.traversalIntervalSecs=36000
schedule.performTraversalOnStart=true
schedule.incrementalTraversalIntervalSecs=3600

    Para obtener descripciones detalladas de los parámetros específicos de la base de datos, consulta la referencia de los parámetros de configuración al final de este artículo.

    Para obtener información sobre los parámetros comunes a todos los conectores de Cloud Search, como la configuración de metadatos, los formatos de fecha y hora y las opciones de LCA, ve a Parámetros de conectores proporcionados por Google.

    Si corresponde, especifica las propiedades del objeto de esquema en los parámetros de consulta de SQL del recorrido. Por lo general, puedes agregar alias a la instrucción de SQL. Por ejemplo, si tienes una base de datos de películas y el esquema de fuente de datos contiene una definición de propiedad llamada “ActorName”, una instrucción de SQL podría tener la forma: SELECT …, last_name AS ActorName, … FROM … .

Paso 3: Ejecuta el conector de bases de datos

En el siguiente ejemplo, se da por sentado que los componentes obligatorios están ubicados en el directorio local en un sistema Linux.

Para ejecutar el conector desde la línea de comandos, ingresa el siguiente comando: 

java \
   -cp "google-cloudsearch-database-connector-v1-0.0.3.jar:mysql-connector-java-5.1.41-bin.jar" \
   com.google.enterprise.cloudsearch.database.DatabaseFullTraversalConnector \
   [-Dconfig=mysql.config]

Donde:

  • google-cloud-search-database-connector-v1-0.0.3.jar es el archivo .jar del conector de bases de datos.
  • mysql-connector-java-5.1.41-bin.jar es el controlador de JDBC que se usa para acceder a la base de datos.
  • mysql.config es un archivo de configuración con nombre personalizado. Para asegurarte de que el conector reconozca tu archivo de configuración, especifica su ruta de acceso en la línea de comandos. De lo contrario, el conector usa connector-config.properties en tu directorio local como nombre de archivo predeterminado.

El conector informa los errores de configuración a medida que los detecta. Algunos errores se informan cuando se inicializa el conector, como cuando se define una columna de base de datos como parte del contenido del registro (en db.allColumns), pero la columna no se usa en la consulta de SQL de recorrido de la base de datos (en db.allRecordsSql). Otros errores solo se detectan y se informan cuando el conector intenta acceder a la base de datos para el primer recorrido, como la sintaxis de una instrucción de SQL no válida.

Referencia de los parámetros de configuración

Parámetros de acceso a la fuente de datos

Parámetro de configuración Parámetro
ID de la fuente de datos api.sourceId = source-ID

Obligatorio. El ID de la fuente de Cloud Search que configuró el administrador de Google Workspace.
ID de la fuente de identidad api.identitySourceId = identity-source-ID

Es obligatorio utilizar grupos y usuarios externos para las LCA. El ID de la fuente de identidad de Cloud Search que configuró el administrador de Google Workspace.
Cuenta de servicio api.serviceAccountPrivateKeyFile = path-to-private-key

Obligatorio. Es la ruta de acceso al archivo de claves de la cuenta de servicio de Cloud Search que creó el administrador de Google Workspace.

Parámetros de acceso a la base de datos

Parámetro de configuración Parámetro
URL de la base de datos db.url = database-URL

Obligatorio. Es la ruta de acceso completa de la base de datos a la que se debe acceder, como jdbc:mysql://127.0.0.1/dbname.
Nombre de usuario y contraseña de la base de datos db.user = username
db.password = password

Obligatorio. Un nombre de usuario y una contraseña válidos que el conector utiliza para acceder a la base de datos. El usuario de la base de datos debe tener acceso de lectura a los registros relevantes de la base de datos que se lee.
Controlador JDBC db.driverClass = oracle.jdbc.OracleDriver

Solo es obligatorio si el controlador JDBC 4.0 aún no está especificado en la ruta de clase.

Parámetros de consulta de SQL transversales

El conector recorre los registros de la base de datos con consultas de SQL SELECT en el archivo de configuración. Debes configurar una consulta de recorrido completo. Las consultas de recorridos incrementales son opcionales.

Un recorrido completo lee cada registro de base de datos configurado para la indexación. Se requiere un recorrido completo para indexar registros nuevos en Cloud Search, y también para volver a indexar todos los registros existentes.

Un recorrido incremental lee y vuelve a indexar solo los registros de la base de datos recién modificados y las entradas recientes a la base de datos. Los recorridos incrementales pueden ser más eficientes que los recorridos completos. Para usar recorridos incrementales, tu base de datos debe contener campos de marca de tiempo para indicar los registros modificados.

El conector ejecuta estos recorridos según las programaciones que defines en los parámetros de programación de recorrido.

Parámetro de configuración Parámetro
Consulta de recorrido completo db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

Obligatorio. La consulta se ejecuta para cada recorrido completo.

Cada nombre de columna que el conector va a usar en cualquier capacidad (contenido, ID único, LCA) debe estar presente en esta consulta. El conector realiza algunas verificaciones preliminares en el inicio para detectar errores y omisiones. Por este motivo, no utilices una consulta general "SELECCIONAR * DESDE…".
Paginación de recorrido completo db.allRecordsSql.pagination = {none | offset}

El valor puede ser:

  • none: no se debe usar paginación
  • offset: se debe usar la paginación por desplazamiento de fila

    Para usar la paginación por desplazamiento, la consulta de SQL debe tener un signo de interrogación de marcador de posición (?) para un desplazamiento de fila, que comience con cero. En cada recorrido completo, la consulta se ejecuta de manera repetida hasta que no se muestran resultados.
Consulta de recorrido incremental db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

Obligatorio si programas recorridos incrementales.

El signo "?" de la consulta es un marcador de posición obligatorio para un valor de marca de tiempo. El conector usa la marca de tiempo para realizar un seguimiento de las modificaciones entre las consultas de SQL del recorrido incremental.

Para realizar un seguimiento de la columna de marca de tiempo de la base de datos por la última hora de actualización, agrega el alias timestamp_column a la instrucción de SQL; de lo contrario, usa la marca de tiempo actual del recorrido del conector.

Para el primer recorrido incremental, el conector usa la hora de inicio del conector. Después del primer recorrido incremental, Cloud Search almacena la marca de tiempo para que los reinicios del conector puedan acceder a la marca de tiempo del recorrido incremental anterior.
Zona horaria de la base de datos db.timestamp.timezone = America/Los_Angeles

Especifica la zona horaria que se usará para las marcas de tiempo de la base de datos. La marca de tiempo de la base de datos que se usa para identificar nuevas adiciones de registros o registros de la base de datos recién modificados. El valor predeterminado es la zona horaria local donde se ejecuta el conector.

Ejemplos de consultas de SQL transversales

  • Consulta básica de recorrido completo que lee cada registro de interés en una base de datos de empleados para la indexación: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • Especifica la paginación por desplazamiento y divide un recorrido completo en varias consultas.

    Para Oracle 12c o SQL Server 2012 (sintaxis de SQL 2008 estándar), usa lo siguiente:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id OFFSET ? ROWS FETCH FIRST 1000 ROWS ONLY
db.allRecordsSql.pagination = offset

    o para MySQL o Google Cloud SQL:

    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee \
    ORDER BY customer_id LIMIT 1000 OFFSET ?
db.allRecordsSql.pagination = offset
  • Consulta de recorrido completo que aplica LCA individuales con alias: 
    db.allRecordsSql = SELECT customer_id, first_name, last_name,  employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee
  • Consulta de recorrido incremental básica: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • Consulta de recorrido incremental que aplica LCA individuales con alias: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time, \
     permitted_readers AS readers_users, \
     denied_readers AS denied_users, \
     permitted_groups AS readers_groups, \
     denied_groups AS denied_groups \
     FROM employee \
     WHERE last_update_time > ?
  • Consulta de recorrido incremental que usa la marca de tiempo de la base de datos en lugar de la hora actual: 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, \
     last_update_time AS timestamp_column \
     FROM employee \
     WHERE last_update_time > ?

Parámetros de definición de columna

Los siguientes parámetros especifican las columnas que usas en las instrucciones de recorrido y para identificar de manera única cada registro.

Parámetro de configuración Parámetro
Todas las columnas db.allColumns = column-1, column-2, ...column-N

Obligatorio. Identifica todas las columnas que se requieren en una consulta de SQL cuando se accede a la base de datos. Se debe hacer referencia explícitamente a las columnas definidas con este parámetro en las consultas. Todos los demás parámetros de definición de columna se comparan con este conjunto de columnas.

Ejemplo:

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
Columnas de clave única db.uniqueKeyColumns = column-1[, column-2]

Obligatorio. Enumera una sola columna de base de datos que contiene valores únicos o una combinación de columnas cuyos valores definen un ID único.

Cloud Search requiere que cada documento que se puede buscar tenga un identificador único dentro de una fuente de datos. Debes poder definir un ID único para cada registro de la base de datos a partir de los valores de la columna. Si ejecutas varios conectores en bases de datos distintas, pero indexas en un conjunto de datos común, asegúrate de especificar un ID único en todos los documentos.

Ejemplos:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
Columna de vínculo de URL url.columns = column-1[, column-2]

Obligatorio. Especifica uno o más nombres definidos y válidos de las columnas utilizadas para la URL utilizada en un resultado de la búsqueda en el que se puede hacer clic. Para las bases de datos que no tienen una URL relevante asociada con cada registro de la base de datos, se puede utilizar un vínculo estático para cada registro.

Sin embargo, si los valores de las columnas definen un vínculo válido para cada registro, se deben especificar las columnas de la URL de vista y los valores de configuración de formato.
Formato de URL url.format = https://www.example.com/{0}

Define el formato de la URL de vista. Los parámetros numerados hacen referencia a las columnas especificadas en db.columns, en orden, a partir de cero.

Si no se especifica, el valor predeterminado es “{0}.”

Puedes encontrar ejemplos en esta tabla.
Columnas con codificación porcentual para la URL url.columnsToEscape = column-1[, column-2]

Especifica las columnas de db.columns cuyos valores se codificarán en porcentajes antes de incluirlos en una string de URL con formato.

Ejemplos de columnas de URL

Para especificar las columnas utilizadas en las consultas de recorrido y el formato de la URL de vista:

  • Para usar una URL estática que no use ningún valor de registro de la base de datos, haz lo siguiente: 
    url.format = https://www.example.com
  • Para usar un solo valor de columna que sea la URL de vista, haz lo siguiente: 
    url.format = {0}
url.columns = customer_id
  • Para utilizar un solo valor de columna que se reemplace en la URL de vista en la posición {0}: 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • Para usar varios valores de columna a fin de compilar la URL de vista (las columnas dependen del orden): 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

Campos de contenido

Utiliza las opciones de contenido para definir qué valores de los registros deben formar parte del contenido de búsqueda.

Parámetro de configuración Parámetro
Columna de búsqueda de mejor calidad contentTemplate.db.title = column-name

Obligatorio. La columna de mayor calidad para la indexación de búsquedas y la priorización de resultados.
Priorización de columnas para la búsqueda contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

Designa las columnas de contenido (excepto el conjunto de columnas para contentTemplate.db.title) como campos de calidad de búsqueda alta, media o baja. El valor predeterminado de las columnas sin especificar es bajo.
Columnas de datos de contenido db.contentColumns = column-1[, column-2...]

Especifica las columnas de contenido en la base de datos. Se les da formato y se suben a Cloud Search como contenido de documentos que se puede buscar.

Si no especificas un valor, el valor predeterminado es "*", lo que indica que todas las columnas deben utilizarse para el contenido.
Columna de BLOB db.blobColumn = column-name

Especifica el nombre de una sola columna de BLOB para usar en el contenido del documento en lugar de una combinación de columnas de contenido.

Si se especifica una columna de BLOB, se considera un error si también se definen las columnas de contenido. Sin embargo, las definiciones de columnas de datos estructurados y metadatos todavía se permiten junto con las columnas de BLOB.