本指南适用于 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 连接器，请按以下步骤操作：
- 安装 Google Cloud Search CSV 连接器软件
- 指定 CSV 连接器配置
- 配置对 Google Cloud Search 数据源的访问权限
- 配置 CSV 文件访问权限
- 指定要编入索引的列名、唯一键列和日期时间列
- 指定要在可点击的搜索结果网址中使用的列
- 指定元数据信息、列格式
- 安排数据遍历
- 指定访问控制列表 (ACL) 选项
1. 安装 SDK
将 SDK 安装到本地 Maven 代码库中。
从 GitHub 克隆 SDK 代码库。
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
获取所需的 SDK 版本：
$ git checkout tags/v1-0.0.3构建连接器：
$ mvn package将连接器 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 文件，并将相关内容编入索引，您必须先创建连接器的配置文件。
要创建配置文件，请按下列步骤操作：
- 打开您选择的文本编辑器，并指定配置文件的名称。
将“键=值”对添加到文件内容中，如以下部分所述。 - 保存并命名配置文件。
Google 建议您将配置文件命名为connector-config.properties，这样运行连接器便不再需要其他命令行参数。
因为您可以在命令行中指定配置文件路径，所以不需要标准文件位置。但是，请将配置文件保存在连接器所在的同一目录中，以简化跟踪和运行连接器的操作。
要确保连接器能识别您的配置文件，请在命令行中指定其路径。否则，连接器将使用本地目录中的 connector-config.properties 作为默认文件名。如需了解如何在命令行中指定配置路径，请参阅运行 Cloud Search CSV 连接器。
3. 配置对 Google Cloud Search 数据源的访问权限
每个配置文件首先必须指定访问 Cloud Search 数据源所必需的参数，如下表所示。通常，要配置连接器对 Cloud Search 的访问权限，您需要数据源 ID、服务账号 ID 和服务账号私钥文件的路径。管理第三方数据源中描述了设置数据源所需的步骤
| 设置 | 参数 |
| 数据源 ID | api.sourceId=1234567890abcdef
必需。由 Google Workspace 管理员设置的 Google Cloud Search 来源 ID，如管理第三方数据源中所述。 |
| 服务账号私钥文件路径 | api.serviceAccountPrivateKeyFile=./PrivateKey.json
必需。为配置 Google Cloud Search CSV 连接器的访问权限而创建 Google Cloud Search 服务账号密钥文件。 |
| 身份源 ID | api.identitySourceId=x0987654321
如使用外部用户和组，则为必需参数。由 Google Workspace 管理员设置的 Google Cloud Search 身份源 ID。 |
4. 配置 CSV 文件参数
您必须先确定 CVS 文件的路径，这样连接器才能遍历文件并从中提取数据，以便编入索引。您还可以指定文件格式和文件编码类型。 添加以下参数，在配置文件中指定 CSV 文件属性。
| 设置 | 参数 |
| CSV 文件的路径 | csv.filePath=./movie_content.csv
必需。要访问并从中提取数据，以编入索引的 CSV 文件的路径。 |
| 文件格式 | csv.format=DEFAULT
文件的格式。Apache Commons CSV CSVFormat 类可为此参数提供可能的值。 格式值包括： |
| 文件格式修饰符 | csv.format.withMethod=value
用于指定 Cloud Search 如何处理文件的修饰符。Apache Commons CSV CSVFormat 类可为此参数提供可能的方法，包括接受单个字符、字符串或布尔值的方法。 例如，如需指定分号作为分隔符，请使用 |
| 文件编码类型 | csv.fileEncoding=UTF-8
在 Cloud Search 读取文件时使用的 Java 字符集。如果未指定，Cloud Search 将使用平台默认字符集。 |
5. 指定要编入索引的列名和唯一键列
要使连接器能够访问 CSV 文件并将其编入索引，您必须在配置文件中提供有关列定义的信息。如果配置文件不包含指定要编入索引的列名称和唯一键列的参数，系统将使用默认值。
| 设置 | 参数 |
| 要编入索引的列 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV 文件中要编入索引的列名称。如果未设置 |
| 唯一键列 | csv.uniqueKeyColumns=movieId
CSV 列，其值将用于生成每条记录的唯一 ID。如果未指定，则应将 CSV 记录的哈希值用作其唯一键。默认值为记录的哈希码。 |
6. 指定要在可点击搜索结果网址中使用的列
当用户使用 Google Cloud Search 进行搜索时，系统会显示一个结果页面，其中包含每个结果的可点击网址。要启用此功能，您必须将下表中显示的参数添加到配置文件。
| 设置 | 参数 |
| 搜索结果网址格式 | url.format=https://mymoviesite.com/movies/{0}
必需。构造 CSV 内容的视图网址的格式。 |
| 搜索结果网址参数。 | url.columns=movieId
必需。CSV 列名称，其值将用于生成记录的视图网址。 |
| 要转义的搜索结果网址参数 | url.columnsToEscape=movieId
可选。CSV 列名称，其值将进行网址转义，以生成有效的视图网址。 |
7. 指定元数据信息、列格式、搜索质量
您可以在配置文件中添加参数，以指定下列各项：
元数据配置参数
元数据配置参数描述用于填充内容元数据的 CSV 列。如果配置文件不包含这些参数，系统将使用默认值。下表显示了这些参数。
| 设置 | 参数 |
| 标题 | itemMetadata.title.field=movieTitle
itemMetadata.title.defaultValue=Gone with the Wind
元数据属性，包含与文档标题对应的值。默认值为空字符串。 |
| 网址 | itemMetadata.sourceRepositoryUrl.field=url
itemMetadata.sourceRepositoryUrl.defaultValue=https://www.imdb.com/title/tt0031381/
包含搜索结果的文档网址值的元数据属性。 |
| 创建时间戳 | itemMetadata.createTime.field=releaseDate
itemMetadata.createTime.defaultValue=1940-01-17
包含文档创建时间戳值的元数据属性。 |
| 上次修改时间 | itemMetadata.updateTime.field=releaseDate
itemMetadata.updateTime.defaultValue=1940-01-17
包含文档上次修改时间戳值的元数据属性。 |
| 文档语言 | itemMetadata.contentLanguage.field=languageCode
itemMetadata.contentLanguage.defaultValue=en-US
待索引文档的内容语言。 |
| 架构对象类型 | itemMetadata.objectType.field=typeitemMetadata.objectType.defaultValue=movie
连接器使用的对象类型，定义请参见架构。如果未指定此属性，连接器不会将任何结构化数据编入索引。 |
日期时间格式
日期时间格式指定元数据属性预计使用的格式。如果配置文件不包含此参数，系统将使用默认值。下表显示了此参数。
| 设置 | 参数 |
| 其他日期时间格式 | structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
其他 java.time.format.DateTimeFormatter 格式的列表（以英文分号分隔）。在解析元数据或架构中的任何日期或日期时间字段的字符串值时，系统将使用这些格式。默认值为空列表，但始终支持 RFC 3339 和 RFC 1123 格式。 |
列格式
列格式指定了应纳入可搜索内容的列的信息。如果配置文件不包含这些参数，系统将使用默认值。下表显示了这些参数。
| 设置 | 参数 |
| 跳过标题 | csv.skipHeaderRecord=true
布尔值。忽略 CSV 文件中的标题记录（第一行）。如果您设置了 |
| 多值列 | csv.multiValueColumns=genre,actors
CSV 文件中具有多个值的列名称。默认值为空字符串。 |
| 多值列的分隔符 | csv.multiValue.genre=;
多值列的分隔符。默认分隔符为英文逗号。 |
搜索质量
Cloud Search CSV 连接器允许为数据字段自动设置 HTML 格式。您的连接器会在连接器执行开始时定义数据字段，然后使用内容模板来设置每条数据记录的格式，然后再将其上传到 Cloud Search。
内容模板定义了每个字段值对于搜索的重要性。标题字段为必填字段，并被定义为最高优先级。您可以为其他所有内容字段指定搜索质量重要性级别，即高、中或低。未定义为特定类别的任何内容字段均默认为低优先级。下表显示了这些参数。
| 设置 | 参数 |
| 内容标题 | contentTemplate.csv.title=movieTitle
内容标题是最高搜索质量字段。 |
| 与高搜索质量对应的内容字段 | contentTemplate.csv.quality.high=actors
具有高搜索质量值的内容字段。默认值为空字符串。 |
| 与低搜索质量对应的内容字段 | contentTemplate.csv.quality.low=genre
具有低搜索质量值的内容字段。默认值为空字符串。 |
| 与中等搜索质量对应的内容字段 | contentTemplate.csv.quality.medium=description
具有中等搜索质量值的内容字段。默认值为空字符串。 |
| 未指定的内容字段 | contentTemplate.csv.unmappedColumnsMode=IGNORE 连接器处理未指定内容字段的方式。有效值包括：
|
8. 安排数据遍历
遍历是指连接器从数据源（在本例中为 CSV 文件）中发现内容的过程。当 CSV 连接器运行时，将遍历 CSV 文件的行，并通过 Indexing API 将每一行编入 Cloud Search 索引。
如果进行完整遍历，则会将文件中的所有列编入索引。增量遍历仅将上次遍历以来添加或修改的列编入索引。CSV 连接器仅执行完全遍历，而不执行增量遍历。
时间安排参数用于确定连接器在两次遍历之间等待的频率。如果配置文件不包含时间安排参数，系统将使用默认值。下表显示了这些参数。
| 设置 | 参数 |
| 在一段时间间隔后执行完全遍历 | schedule.traversalIntervalSecs=7200
连接器会在指定的时间间隔后执行完全遍历。指定各次遍历之间的时间间隔，以秒为单位。默认值为 86400（一天的总秒数）。 |
| 连接器启动时执行完全遍历 | schedule.performTraversalOnStart=false
连接器会在启动时执行完全遍历，而不会等待第一个时间间隔到期。默认值为 true。 |
9. 指定访问权限控制列表 (ACL) 选项
Google Cloud Search CSV 连接器通过 ACL 支持权限，以控制对搜索结果中 CSV 文件内容的访问权限。您可以使用多个 ACL 选项来保护用户对已编入索引的记录的访问权限。
如果您的代码库包含与每个文档关联的单独 ACL 信息，请上传所有 ACL 信息，以控制 Cloud Search 中的文档访问权限。如果您的代码库提供部分 ACL 信息或不提供此类信息，您可以在以下参数中提供默认 ACL 信息，然后 SDK 会将相应信息提供给连接器。
连接器依赖于配置文件中启用的默认 ACL。如需启用默认 ACL，请将 defaultAcl.mode 设置为 none 以外的任何模式，并使用 defaultAcl.* 进行配置
| 设置 | 参数 |
| ACL 模式 | defaultAcl.mode=fallback
必需。CSV 连接器依赖于默认的 ACL 功能。连接器仅支持回退模式。 |
| 默认 ACL 名称 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
可选。允许替换连接器用于设置默认 ACL 的虚拟容器名称。默认值为“DEFAULT_ACL_VIRTUAL_CONTAINER”。如果多个连接器正在将同一数据源中的内容编入索引，您可能需要替换此值。 |
| 默认公共 ACL | defaultAcl.public=true
用于整个代码库的默认 ACL 设置为公共网域访问权限。默认值为 false。 |
| 公共 ACL 组读取者 | defaultAcl.readers.groups=defaultAcl.readers.groups |
| 公共 ACL 读取者 | defaultAcl.readers.users=user1, user2, google:user3 |
| 遭到公共 ACL 拒绝的组读取者 | defaultAcl.denied.groups=group3 |
| 遭到常规 ACL 拒绝的读取者 | defaultAcl.denied.users=user4, user5 |
| 整个网域访问权限 | 如要指定网域中的每个用户均可公开访问已编入索引的每条记录，请将以下两个选项的值设为：
|
| 已定义的公共 ACL | 要为数据存储区的每条记录指定一个 ACL，请设置以下所有参数值：
|
架构定义
Cloud Search 允许将结构化和非结构化内容编入索引和提供这些内容。 为支持对数据进行结构化数据查询，您需要为数据源设置架构。
定义后，CSV 连接器可以引用已定义的架构来构建索引请求。为了提供说明，我们以一个包含有关电影信息的 CSV 文件为例。
假设输入 CSV 文件具有以下内容。
- movieId
- movieTitle
- 说明
- year
- releaseDate
- actors（用英文逗号 (,) 分隔多个值）
- genre（多个值）
- 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 将数据记录到文件中。