部署数据库连接器

警告：Cloud Search 参考连接器“按原样”提供，作为示例代码提供，供您创建自己的有效连接器时使用。此示例代码需要进行重大自定义和测试，然后才能用于概念验证或生产环境。在生产环境中，我们强烈建议您向我们的 Cloud Search 合作伙伴寻求帮助。如需进一步帮助寻找合适的 Cloud Search 合作伙伴，请与您的 Google 客户经理联系。

您可以将 Google Cloud Search 设置为使用 Google Cloud Search 数据库连接器发现贵组织的数据库中的数据并将其编入索引。

重要注意事项

只要 Cloud Search 数据库连接器可以访问互联网和数据库，您几乎可以在任何能够运行 Java 应用的环境中安装并运行该连接器。

系统要求

系统要求
操作系统 Windows 或 Linux
SQL 数据库 具有兼容 JDBC 4.0 或更高版本的驱动程序的任何 SQL 数据库，包括：
  • MS SQL Server（2008、2012、2014、2016）
  • Oracle（11g、12c）
  • Google Cloud SQL
  • MySQL
软件 用于访问数据库的连接器的 JDBC 驱动程序（单独下载和安装）

部署连接器

以下步骤介绍了如何安装连接器并将其配置为将指定的数据库编入索引并将结果返回给 Cloud Search 用户。

前提条件

在部署 Cloud Search 数据库连接器之前，请收集以下信息：

第 1 步：下载和构建数据库连接器软件

  1. 从 GitHub 克隆连接器代码库。 
    $ git clone https://github.com/google-cloudsearch/database-connector.git
$ cd database-connector
  2. 查看所需的连接器版本：
    $ git checkout tags/v1-0.0.3
  3. 构建连接器。 
    $ mvn package
    如需在构建连接器时跳过测试，请使用 mvn package -DskipTests。
  4. 将连接器 zip 文件复制到本地安装目录并解压缩： 
    $ 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

第 2 步：配置数据库连接器

  1. 创建一个文本文件，并将其命名为 connector-config.properties（默认）或类似名称。Google 建议您使用 .properties 或 .config 扩展名来命名配置文件，并将文件保存在连接器所在的同一目录中。如果使用其他名称或路径，则必须在运行连接器时指定路径。
  2. 以键值对的形式将参数添加到文件内容中。配置文件必须指定数据源访问、数据库访问、数据库完全遍历 SQL 语句、内容字段标题和列定义的参数。您还可以使用可选参数来配置其他连接器行为。例如： 
    # 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

    如需详细了解数据库专用参数，请参阅本文末尾的 配置参数参考。

    如需了解所有 Cloud Search 连接器通用的参数（例如元数据配置、日期时间格式和 ACL 选项），请参阅 Google 提供的连接器参数。

    如果适用，请在遍历 SQL 查询参数中指定架构对象的属性。通常，您可以向 SQL 语句添加别名。例如，如果您有一个电影数据库，并且数据源架构包含一个名为“ActorName”的属性定义，则 SQL 语句的格式为：SELECT …, last_name AS ActorName, … FROM … 。

第 3 步：运行数据库连接器

以下示例假定所需组件位于 Linux 系统的本地目录中。

要使用命令行运行该连接器，请输入以下命令：

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]

其中：

  • google-cloud-search-database-connector-v1-0.0.3.jar 是数据库连接器 .jar 文件
  • mysql-connector-java-5.1.41-bin.jar 是用于访问数据库的 JDBC 驱动程序
  • mysql.config 是自定义命名的配置文件。为确保连接器能识别您的配置文件，请在命令行中指定其路径。否则，连接器将使用本地目录中的 connector-config.properties 作为默认文件名。

连接器会在检测到配置错误时报告错误。在连接器初始化时，系统会报告一些错误，例如数据库列被定义为记录内容的一部分（在 db.allColumns 中），但该列并未用于数据库的遍历 SQL 查询（在 db.allRecordsSql 中）。其他错误仅在连接器尝试访问数据库进行第一次遍历时才会检测和报告，例如 SQL 语句语法无效。

配置参数参考

数据源访问参数

设置 参数
数据源 ID api.sourceId = source-ID

必需。Google Workspace 管理员设置的 Cloud Search 来源 ID。
身份源 ID api.identitySourceId = identity-source-ID

如果要为 ACL 使用外部用户和群组，则必须选择此项。Google Workspace 管理员设置的 Cloud Search 身份源 ID。
服务账号 api.serviceAccountPrivateKeyFile = path-to-private-key

必需。Google Workspace 管理员创建的 Cloud Search 服务帐号密钥文件的路径。

数据库访问参数

设置 参数
数据库网址 db.url = database-URL

必需。要访问的数据库的完整路径，例如 jdbc:mysql://127.0.0.1/dbname。
数据库用户名和密码 db.user = username
db.password = password

必需。连接器用于访问数据库所需的有效用户名和密码。此数据库用户必须具有对正在读取的数据库的相关记录的读取访问权限。
JDBC 驱动程序 db.driverClass = oracle.jdbc.OracleDriver

仅在类路径中尚未指定 JDBC 4.0 版驱动程序时才属于必填项。

遍历 SQL 查询参数

连接器使用配置文件中的 SQL SELECT 查询遍历数据库记录。您必须配置完全遍历查询；增量遍历查询是可选的。

完全遍历会读取配置为编入索引的每个数据库记录。若要将 Cloud Search 的新记录编入索引以及将所有现有记录重新编入索引，则需要执行完全遍历。

增量遍历仅读取新修改的数据库记录以及最近加入的数据库条目，并将其重新编入索引。增量遍历比完全遍历更高效。如需使用增量遍历，您的数据库必须包含时间戳字段来指示已修改的记录。

连接器根据您在 遍历时间表参数中定义的时间表执行这些遍历。

设置 参数
完全遍历查询 db.allRecordsSql = SELECT column-1[, column-2,...] FROM database-name

必需。每次完全遍历时都会运行的查询。

无论容量如何（内容、唯一 ID、ACL），连接器将使用的每个列名称都必须包含在此查询中。连接器在启动时会执行一些初步验证，以检测是否存在错误和遗漏。因此，请勿使用常规的“SELECT * FROM ...”查询。
完全遍历分页 db.allRecordsSql.pagination = {none | offset}

可能的值包括：

  • none：不使用分页
  • offset：按行偏移量使用分页

    如需按偏移量使用分页，SQL 查询必须有一个占位符问号 (?) 表示行偏移量（从零开始）。在每次完全遍历中，都会重复执行查询，直到不返回任何结果。
增量遍历查询 db.incrementalUpdateSql = SELECT column-1[, column-2,...] FROM database-name WHERE last_update_time > ?

如果您安排增量遍历，则此选项是必需的。

查询中的“?”是时间戳值的必要占位符。连接器使用时间戳跟踪增量遍历 SQL 查询之间的修改。

如需跟踪上次更新时间的数据库时间戳列，请将 timestamp_column 别名添加到 SQL 语句；否则，请使用连接器遍历的当前时间戳。

对于第一次增量遍历，连接器会使用连接器的开始时间。第一次增量遍历之后，Cloud Search 会存储该时间戳，以便连接器重新启动后能够访问之前的增量遍历时间戳。
数据库时区 db.timestamp.timezone = America/Los_Angeles

指定用于数据库时间戳的时区。数据库时间戳，用于标识新增记录或最近修改的数据库记录。默认值是连接器运行的本地时区。

遍历 SQL 查询示例

  • 基本的完全遍历查询，用于读取员工数据库中感兴趣的每条记录以编制索引： 
    db.allRecordsSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field \
    FROM employee
  • 按偏移量指定分页，并将完全遍历分解为多个查询。

    对于 SQL Server 2012 或 Oracle 12c（标准 SQL 2008 语法）：

    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

    或者，对于 MySQL 或 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
  • 通过别名应用各个 ACL 的完全遍历查询： 
    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
  • 基本增量遍历查询： 
    db.incrementalUpdateSql = SELECT customer_id, first_name, last_name, employee_id, interesting_field, last_update_time \
     FROM employee \
     WHERE last_update_time > ?
  • 通过别名应用各个 ACL 的增量遍历查询： 
    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 > ?
  • 使用数据库时间戳而不是当前时间的增量遍历查询： 
    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 > ?

列定义参数

以下参数指定您在遍历语句中使用的列，它们用于唯一标识每条记录。

设置 参数
所有列 db.allColumns = column-1, column-2, ...column-N

必需。标明访问数据库时 SQL 查询所需的所有列。查询必须显式引用此参数定义的列。所有其他列定义参数都将与这一组列进行比较。

例如：

db.allColumns = customer_id, first_name, last_name, phone, change_timestamp
唯一键列 db.uniqueKeyColumns = column-1[, column-2]

必需。列出包含唯一值的单个数据库列，或列出其值共同定义了唯一 ID 的多个列。

Cloud Search 要求每个可搜索的文档在数据源中具有唯一标识符。您必须能够根据列值为每条数据库记录定义唯一 ID。如果您在单独的数据库上运行多个连接器，但索引会编入一个通用数据集，请确保在所有文档中指定一个唯一 ID。

示例：

db.uniqueKeyColumns = customer_id
# or
db.uniqueKeyColumns = last_name, first_name
“网址链接”列 url.columns = column-1[, column-2]

必需。为用于可点击搜索结果的网址指定一个或多个有效的已定义名称。如果数据库没有与每条数据库记录关联的相关网址，则可以为每个记录使用一个静态链接。

但是，如果列值确实为每个记录定义了有效链接，则应指定视图网址列和格式配置值。
网址格式 url.format = https://www.example.com/{0}

定义视图网址的格式。带编号的参数按顺序引用 db.columns 中指定的列（从零开始）。

如果未指定，则默认值为“”。{0}

下表中附上了相关示例。
网址经过百分比编码的列 url.columnsToEscape = column-1[, column-2]

指定 db.columns 中的列，其值将进行百分比编码，然后添加到格式化的网址字符串中。

网址列示例

要指定遍历查询中使用的列以及视图网址格式，请执行以下操作：

  • 如需使用不使用任何数据库记录值的静态网址，请执行以下操作： 
    url.format = https://www.example.com
  • 如需使用单个列值（即视图网址），请执行以下操作： 
    url.format = {0}
url.columns = customer_id
  • 如需使用替换到视图网址中位于 {0} 位置处的单个列值，请使用以下代码： 
    url.format = https://www.example.com/customer/id={0}
url.columns = customer_id
url.columnsToEscape = customer_id
  • 如需使用多个列值构建视图网址（列按顺序排列），请执行以下操作： 
    url.format = {1}/customer={0}
url.columns = customer_id, linked_url
url.columnsToEscape = customer_id

内容字段

可使用内容选项来定义哪些记录值应成为可搜索的内容。

设置 参数
质量最高的搜索列 contentTemplate.db.title = column-name

必需。用于搜索索引和搜索结果优先级的最高列。
搜索的列优先级 contentTemplate.db.quality.high = column-1[, column-2...]
contentTemplate.db.quality.medium = column-1[, column-2...]
contentTemplate.db.quality.low = column-1[, column-2...]

将内容列（为 contentTemplate.db.title 设置的列除外）指定为高、中或低搜索质量字段。未指定的列默认为低值。
内容数据列 db.contentColumns = column-1[, column-2...]

指定数据库中的内容列。系统会对其进行格式化，并作为可搜索的文档内容上传到 Cloud Search。

如果您未指定值，则默认值为“*”，表示所有列都应用于内容。*
Blob 列 db.blobColumn = column-name

指定要用于文档内容（而不是内容列组合）的单个 blob 列的名称。

如果指定了 blob 列，同时又定义内容列会被视为错误。但是，仍然允许元数据和结构化数据列定义与 blob 列搭配使用。