Implementar un conector de base 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 sus propios conectores funcionales. Este código de muestra requiere una personalización y pruebas sustanciales antes de usarse en entornos de producción o de prueba de concepto. Para uso en producción, recomendamos obtener ayuda de uno de nuestros socios de Cloud Search. Para obtener más ayuda para encontrar un socio adecuado de Cloud Search, comuníquese con su administrador de cuentas de Google.

Puede configurar Google Cloud Search para descubrir e indexar datos de las bases de datos de su organización mediante el conector de base de datos de Google Cloud Search.

Consideraciones importantes

Puede instalar y ejecutar el conector de base de datos de Cloud Search en casi cualquier entorno donde se puedan ejecutar aplicaciones 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 SQL con un controlador compatible con JDBC 4.0 o posterior, incluidos los siguientes:
Software Controlador JDBC para que el conector lo use para acceder a la base de datos (descargado e instalado por separado)

Implementar el conector

Los siguientes pasos describen cómo instalar el conector y configurarlo para indexar las bases de datos especificadas y devolver los resultados a los usuarios de Cloud Search.

requisitos previos

Antes de implementar el conector de base de datos de Cloud Search, recopile la siguiente información:

Paso 1. Descargue y cree el software del conector de la base de datos

  1. Clone el repositorio del conector de GitHub.
    $ git clone https://github.com/google-cloudsearch/database-connector.git
    $ cd database-connector
  2. Consulte la versión deseada del conector:
    $ git checkout tags/v1-0.0.3
  3. Construya el conector.
    $ mvn package
    Para omitir las pruebas al compilar el conector, use mvn package -DskipTests .
  4. Copie el archivo zip del conector en su directorio de instalación local y descomprímalo:
    $ 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. Configure el conector de la base de datos

  1. Cree un archivo de texto y asígnele el nombre connector-config.properties (predeterminado) o similar. Google recomienda nombrar los archivos de configuración con la extensión .properties o .config y mantener el archivo en el mismo directorio que el conector. Si usa un nombre o ruta diferente, debe especificar la ruta cuando ejecute 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 SQL transversal completa de la base de datos, un título de campo de contenido y definiciones de columna. También puede configurar otro comportamiento 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, vaya a la referencia de parámetros de configuración al final de este artículo.

    Para obtener más información sobre los parámetros que son 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, vaya a Parámetros de conector proporcionados por Google .

    Si corresponde, especifique las propiedades del objeto de esquema en los parámetros de consulta de SQL transversal. Por lo general, puede agregar alias a la declaración SQL. Por ejemplo, si tiene una base de datos de películas y el esquema de la fuente de datos contiene una definición de propiedad llamada "Nombre del actor", una instrucción SQL podría tener la forma: SELECT …, last_name AS ActorName, … FROM … .

Paso 3. Ejecute el conector de la base de datos

El siguiente ejemplo asume que los componentes requeridos están ubicados en el directorio local en un sistema Linux.

Para ejecutar el conector desde la línea de comando, ingrese 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:

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

Referencia de parámetros de configuración

Parámetros de acceso a la fuente de datos

Ajuste Parámetro
ID de la fuente de datos api.sourceId = source-ID

Requerido. El ID de origen de Cloud Search que configuró el administrador de Google Workspace.

ID de fuente de identidad api.identitySourceId = identity-source-ID

Requerido para usar usuarios y grupos externos para ACL. El ID de fuente de identidad de Cloud Search que configuró el administrador de Google Workspace.

cuenta de servicio api.serviceAccountPrivateKeyFile = path-to-private-key

Requerido. La ruta al archivo de claves de la cuenta del servicio de Cloud Search que creó el administrador de Google Workspace.

Parámetros de acceso a la base de datos

Ajuste Parámetro
URL de la base de datos db.url = database-URL

Requerido. La ruta completa de la base de datos a la que se 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

Requerido. Un nombre de usuario y una contraseña válidos que utiliza el conector para acceder a la base de datos. Este usuario de la base de datos debe tener acceso de lectura a los registros relevantes de la base de datos que se está leyendo.

controlador JDBC db.driverClass = oracle.jdbc.OracleDriver

Requerido solo si el controlador JDBC 4.0 aún no está especificado en la ruta de clase.

Parámetros de consulta de SQL transversal

El conector atraviesa los registros de la base de datos con consultas SQL SELECT en el archivo de configuración. Debe configurar una consulta transversal completa; las consultas para recorridos incrementales son opcionales.

Un recorrido completo lee todos los registros de la base de datos configurados para la indexación. Se requiere un recorrido completo para indexar nuevos registros para 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, su base de datos debe contener campos de marca de tiempo para indicar registros modificados.

El conector ejecuta estos recorridos de acuerdo con las programaciones definidas en los parámetros de programación de recorridos .

Ajuste Parámetro
Consulta transversal completa db.allRecordsSql = SELECT column-1 [, column-2 ,...] FROM database-name

Requerido. La consulta se ejecuta para cada recorrido completo.

Cada nombre de columna que usará el conector en cualquier capacidad (contenido, ID único, ACL) debe estar presente en esta consulta. El conector realiza algunas verificaciones preliminares al inicio para detectar errores y omisiones. Por este motivo, no utilice una consulta general " SELECT * FROM … ".

Paginación transversal completa db.allRecordsSql.pagination = {none | offset}

El valor puede ser:

Consulta transversal incremental db.incrementalUpdateSql = SELECT column-1 [, column-2 ,...] FROM database-name WHERE last_update_time > ?

Obligatorio si programa recorridos incrementales .

Los "?" en la consulta es un marcador de posición obligatorio para un valor de marca de tiempo. El conector utiliza la marca de tiempo para realizar un seguimiento de las modificaciones entre las consultas SQL transversales incrementales.

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

Para el primer recorrido incremental, el conector utiliza 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 utilizada para identificar las adiciones de nuevos registros o los 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 SQL transversales

Parámetros de definición de columna

Los siguientes parámetros especifican las columnas que usa en las instrucciones transversales y para identificar de forma única cada registro.

Ajuste Parámetro
Todas las columnas db.allColumns = column-1 , column-2 , ... column-N

Requerido. Identifica todas las columnas que se requieren en una consulta SQL al acceder a la base de datos. Las columnas definidas con este parámetro deben estar explícitamente referenciadas 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 clave únicas db.uniqueKeyColumns = column-1 [, column-2 ]

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

Cloud Search requiere que cada documento que se pueda buscar tenga un identificador único dentro de una fuente de datos. Debe poder definir una ID única para cada registro de la base de datos a partir de los valores de columna. Si ejecuta varios conectores en bases de datos separadas pero indexa en un conjunto de datos común, asegúrese de especificar una ID única en todos los documentos.

Ejemplos:

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
columna de enlace URL url.columns = column-1 [, column-2 ]

Requerido. Especifica uno o más nombres definidos y válidos de las columnas utilizadas para la URL utilizada para un resultado de 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 usar un enlace 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 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 se refieren a las columnas especificadas en db.columns , en orden, comenzando con cero.

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

Los ejemplos siguen esta tabla.

Columnas codificadas en porcentaje para URL url.columnsToEscape = column-1 [, column-2 ]

Especifica columnas de db.columns cuyos valores se codificarán en porcentaje antes de incluirlos en la cadena de URL formateada.

Ejemplos de columnas de URL

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

campos de contenido

Utilice las opciones de contenido para definir qué valores de registro deben formar parte del contenido de búsqueda.

Ajuste Parámetro
Columna de búsqueda de la más alta calidad contentTemplate.db.title = column-name

Requerido. 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 ...]

Designe columnas de contenido (excepto la columna configurada para contentTemplate.db.title ) como campos de calidad de búsqueda alta, media o baja. Las columnas no especificadas tienen un valor predeterminado bajo.

Columnas de datos de contenido db.contentColumns = column-1 [, column-2 ...]

Especifique columnas de contenido en la base de datos. Estos se formatean y cargan en Cloud Search como contenido de documento que se puede buscar.

Si no especifica un valor, el valor predeterminado es " * ", lo que indica que se deben usar todas las columnas para el contenido.

columna de blobs db.blobColumn = column-name

Especifique el nombre de una única columna de blob que se usará para 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 columnas de contenido. Sin embargo, las definiciones de columnas de metadatos y datos estructurados aún se permiten junto con las columnas de blobs.