部署数据库连接器

警告：Cloud Search 参考连接器“按原样”提供作为示例代码 以创建您自己的有效连接器。此示例代码需要使用 在用于概念验证或 生产环境如需在生产环境中使用，我们强烈建议您获取帮助 。如需进一步帮助，寻找合适的 搜索网络合作伙伴，请与您的 Google 客户经理联系。

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

重要注意事项

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

系统要求

系统要求
操作系统 Windows 或 Linux
SQL 数据库 具有 JDBC 4.0 或更高版本兼容驱动程序的任何 SQL 数据库，包括：
<ph type="x-smartling-placeholder">
    </ph>
  • MS SQL Server（2008、2012、2014、2016）
  • Oracle（11g、12c）
  • Google 云端 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 选项），请参阅 <ph type="x-smartling-placeholder"></ph> Google 提供的连接器参数。

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

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

以下示例假定所需组件位于本地 目录。

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

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 中），但该列未用于 数据库（位于 db.allRecordsSql 中）。其他错误仅在 连接器在第一次遍历时会尝试访问数据库，例如 SQL 语句语法无效。

配置参数参考

数据源访问参数

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

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

需要使用外部用户和群组作为 ACL。Cloud Search Google Workspace 管理员设置的身份源 ID。
服务账号 api.serviceAccountPrivateKeyFile = path-to-private-key

必需。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 列搭配使用。