部署 CSV 连接器

本指南适用于 Google Cloud Search CSV（逗号分隔值）连接器管理员，即负责下载、配置、运行和监控连接器的所有人员。

本指南介绍了如何执行与 CSV 连接器部署相关的关键任务：

• 下载 Google Cloud Search CSV 连接器软件
• 配置连接器，以用于特定的 CSV 数据源
• 部署并运行连接器

要了解本文档中的概念，您应该熟悉 Google Workspace、CSV 文件和访问权限控制列表 (ACL) 的基础知识。

Google Cloud Search CSV 连接器概览

Cloud Search CSV 连接器可处理任何逗号分隔值 (CSV) 文本文件。CSV 文件用于存储表格数据，文件的每一行就是一条数据记录。

Google Cloud Search 的 CSV 连接器从 CSV 文件中提取单个行，并通过 Cloud Search 的 Indexing API 将其编入 Cloud Search 的索引。成功编入索引后，CSV 文件中的各行即可通过 Cloud Search 的客户端或 Cloud Search 的 Query API 进行搜索。另外，CSV 连接器还支持使用 ACL 来控制用户对搜索结果中内容的访问权限。

Google Cloud Search CSV 连接器可以安装在 Linux 或 Windows 上。在部署 Google Cloud Search CSV 连接器之前，请确保您拥有以下必需的组件：

• Java JRE 1.8（安装在运行 Google Cloud Search CSV 连接器的计算机上）

• 在 Google Cloud Search 和数据源之间建立关系所需的 Google Workspace 信息：

  • Google Workspace 私钥（包含服务账号 ID）
  • Google Workspace 数据源 ID

  一般来说，网域的 Google Workspace 管理员可以为您提供这些凭据。

部署步骤

要部署 Google Cloud Search CSV 连接器，请按以下步骤操作：

1. 安装 Google Cloud Search CSV 连接器软件
2. 指定 CSV 连接器配置
3. 配置对 Google Cloud Search 数据源的访问权限
4. 配置 CSV 文件的访问权限
5. 指定要编入索引的列名、唯一键列和日期时间列
6. 指定要在可点击搜索结果网址中使用的列
7. 指定元数据信息、列格式
8. 安排数据遍历
9. 指定访问控制列表 (ACL) 选项

1. 安装 SDK

将 SDK 安装到本地 Maven 代码库中。

1. 从 GitHub 克隆 SDK 代码库。

   $ git clone https://github.com/google-cloudsearch/connector-sdk.git
   $ cd connector-sdk/csv

2. 获取所需的 SDK 版本：

   $ git checkout tags/v1-0.0.3

3. 构建连接器：

   $ mvn package

4. 将连接器 zip 文件复制到本地安装目录：

   $ cp target/google-cloudsearch-csv-connector-v1-0.0.3.zip installation-dir
   $ cd installation-dir
   $ unzip google-cloudsearch-csv-connector-v1-0.0.3.zip
   $ cd google-cloudsearch-csv-connector-v1-0.0.3

2. 指定 CSV 连接器配置

作为连接器管理员，您可以控制 CSV 连接器的行为和属性，只需在连接器的配置文件中定义参数即可。可配置的参数包括：

• 访问数据源
• CSV 文件的位置
• CSV 列定义
• 定义唯一 ID 的列
• 遍历选项
• 限制数据访问权限的 ACL 选项

要使连接器能够正确访问 CSV 文件，并将相关内容编入索引，您必须先创建连接器的配置文件。

要创建配置文件，请按下列步骤操作：

1. 打开您选择的文本编辑器，并指定配置文件的名称。
   将键=值对添加到文件内容中，如以下部分所述。
2. 保存并命名配置文件。
   Google 建议您将配置文件命名为 connector-config.properties，这样无需其他命令行参数即可运行连接器。

因为您可以在命令行中指定配置文件路径，所以不需要标准文件位置。但是，请将配置文件保存在连接器所在的同一目录中，以简化跟踪和运行连接器的操作。

要确保连接器能识别您的配置文件，请在命令行中指定其路径。否则，连接器将使用本地目录中的 connector-config.properties 作为默认文件名。如需了解如何在命令行中指定配置路径，请参阅运行 Cloud Search CSV 连接器。

3. 配置对 Google Cloud Search 数据源的访问权限

每个配置文件首先必须指定访问 Cloud Search 数据源所必需的参数，如下表所示。通常，要配置连接器对 Cloud Search 的访问权限，您需要数据源 ID、服务账号 ID 和服务账号私钥文件的路径。管理第三方数据源中描述了设置数据源所需的步骤

4. 配置 CSV 文件参数

您必须先确定 CVS 文件的路径，这样连接器才能遍历文件并从中提取数据，以便编入索引。您还可以指定文件格式和文件编码类型。 添加以下参数以在配置文件中指定 CSV 文件属性。

5. 指定要编入索引的列名和唯一键列

要使连接器能够访问 CSV 文件并将其编入索引，您必须在配置文件中提供有关列定义的信息。如果配置文件不包含指定要编入索引的列名称和唯一键列的参数，系统将使用默认值。

6. 指定要在可点击搜索结果网址中使用的列

当用户使用 Google Cloud Search 进行搜索时，系统会显示一个结果页面，其中包含每个结果的可点击网址。要启用此功能，您必须将下表中显示的参数添加到配置文件。

7. 指定元数据信息、列格式、搜索质量

您可以在配置文件中添加参数，以指定下列各项：

• 元数据配置参数
• 列格式
• 搜索质量

元数据配置参数

元数据配置参数描述用于填充内容元数据的 CSV 列。如果配置文件不包含这些参数，系统将使用默认值。下表显示了这些参数。

日期时间格式

日期时间格式指定元数据属性预计使用的格式。如果配置文件不包含此参数，系统将使用默认值。下表显示了此参数。

列格式

列格式指定了应纳入可搜索内容的列的信息。如果配置文件不包含这些参数，系统将使用默认值。下表显示了这些参数。

搜索质量

借助 Cloud Search CSV 连接器，您可以自动对数据字段进行 HTML 格式设置。当连接器开始运行时，会定义数据字段，并使用内容模板来设置每个数据记录的格式，然后再将其上传到 Cloud Search。

内容模板定义了每个字段值对于搜索的重要性。标题字段为必需字段，并被定义为最高优先级。您可以为其他所有内容字段指定搜索质量重要性级别，即高、中或低。未定义为特定类别的任何内容字段均默认为低优先级。下表显示了这些参数。

8. 安排数据遍历

遍历是指连接器从数据源（在本例中为 CSV 文件）中发现内容的过程。当 CSV 连接器运行时，将遍历 CSV 文件的行，并通过 Indexing API 将每一行编入 Cloud Search 索引。

如果进行完整遍历，则会将文件中的所有列编入索引。增量遍历仅将上次遍历以来添加或修改的列编入索引。CSV 连接器仅执行完全遍历，而不执行增量遍历。

时间安排参数用于确定连接器在两次遍历之间等待的频率。如果配置文件不包含时间安排参数，系统将使用默认值。下表显示了这些参数。

9. 指定访问权限控制列表 (ACL) 选项

Google Cloud Search CSV 连接器通过 ACL 支持权限，以控制对搜索结果中 CSV 文件内容的访问权限。您可以使用多个 ACL 选项来保护用户对已编入索引的记录的访问权限。

如果您的代码库包含与每个文档关联的单独 ACL 信息，请上传所有 ACL 信息，以控制 Cloud Search 中的文档访问权限。如果您的代码库提供部分 ACL 信息或不提供此类信息，您可以在以下参数中提供默认 ACL 信息，然后 SDK 会将相应信息提供给连接器。

连接器依赖于配置文件中启用的默认 ACL。如需启用默认 ACL，请将 defaultAcl.mode 设置为除 none 以外的任何模式，并使用 defaultAcl.* 进行配置

架构定义

Cloud Search 允许将结构化和非结构化内容编入索引，并提供这些内容。为支持对您的数据进行结构化数据查询，您需要为数据源设置架构。

定义后，CSV 连接器可以引用已定义的架构来构建编入索引请求。为了提供说明，我们以一个包含有关电影信息的 CSV 文件为例。

假设输入 CSV 文件具有以下内容。

1. movieId
2. movieTitle
3. description
4. year
5. releaseDate
6. actors（用英文逗号 (,) 分隔多个值）
7. genre（多个值）
8. ratings

基于上述数据结构，您可以为要将其中 CSV 文件的数据编入索引的数据源定义架构。

{
  "objectDefinitions": [
    {
      "name": "movie",
      "propertyDefinitions": [
        {
          "name": "actors",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "textPropertyOptions": {
            "operatorOptions": {
              "operatorName": "actor"
            }
          }
        },
        {
          "name": "releaseDate",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "datePropertyOptions": {
            "operatorOptions": {
              "operatorName": "released",
              "lessThanOperatorName": "releasedbefore",
              "greaterThanOperatorName": "releasedafter"
            }
          }
        },
        {
          "name": "movieTitle",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": false,
          "textPropertyOptions": {
            "retrievalImportance": {
              "importance": "HIGHEST"
            },
            "operatorOptions": {
              "operatorName": "title"
            }
          }
        },
        {
          "name": "genre",
          "isReturnable": true,
          "isRepeatable": true,
          "isFacetable": true,
          "enumPropertyOptions": {
            "operatorOptions": {
              "operatorName": "genre"
            },
            "possibleValues": [
              {
                "stringValue": "Action"
              },
              {
                "stringValue": "Documentary"
              },
              {
                "stringValue": "Drama"
              },
              {
                "stringValue": "Crime"
              },
              {
                "stringValue": "Sci-fi"
              }
            ]
          }
        },
        {
          "name": "userRating",
          "isReturnable": true,
          "isRepeatable": false,
          "isFacetable": true,
          "integerPropertyOptions": {
            "orderedRanking": "ASCENDING",
            "maximumValue": "10",
            "operatorOptions": {
              "operatorName": "score",
              "lessThanOperatorName": "scorebelow",
              "greaterThanOperatorName": "scoreabove"
            }
          }
        }
      ]
    }
  ]
}

示例配置文件

以下示例配置文件显示了定义示例连接器行为的参数 key=value 对。

# data source access
api.sourceId=1234567890abcd
api.serviceAccountPrivateKeyFile=./PrivateKey.json

# CSV data structure
csv.filePath=./movie_content.csv
csv.csvColumns=movieId,movieTitle,description,releaseYear,genre,actors,ratings,releaseDate
csv.skipHeaderRecord=true
url.format=https://mymoviesite.com/movies/{0}
url.columns=movieId
csv.datetimeFormat.releaseDate=yyyy-mm-dd
csv.multiValueColumns=genre,actors
csv.multiValue.genre=;
contentTemplate.csv.title=movieTitle

# metadata structured data and content
itemMetadata.title.field=movieTitle
itemMetadata.createTime.field=releaseDate
itemMetadata.contentLanguage.defaultValue=en-US
itemMetadata.objectType.defaultValue=movie
contentTemplate.csv.quality.medium=description
contentTemplate.csv.unmappedColumnsMode=IGNORE

#ACLs
defaultAcl.mode=fallback
defaultAcl.public=true

如需了解每个参数的详细说明，请参阅“配置参数参考”。

运行 Cloud Search CSV 连接器

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

$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config

默认情况下，标准输出中提供了连接器日志。您可以通过指定 logging.properties，将数据记录到文件中。