本指南适用于 Google Cloud Search CSV（逗号分隔值）连接器管理员，即负责下载、配置、运行和监控连接器的所有人员。
本指南介绍了如何执行以下关键任务：
- 下载 Cloud Search CSV 连接器软件。
- 为特定的 CSV 数据源配置连接器。
- 部署并运行连接器。
为了便于您理解本文档中提及的概念，建议您先熟悉 Google Workspace、CSV 文件和访问权限控制列表 (ACL)。
Cloud Search CSV 连接器概览
Cloud Search CSV 连接器可处理任何逗号分隔值 (CSV) 文本文件。CSV 文件用于存储表格数据，其中每一行都是一条数据记录。
连接器会从 CSV 文件中提取行，并使用 Indexing API 将这些行编入 Cloud Search 索引。编入索引后，可以通过 Cloud Search 客户端或 Query API 搜索相应行。该连接器还支持使用 ACL 来控制用户对内容的访问权限。
您可以在 Linux 或 Windows 上安装连接器。在部署之前，请确保您已准备好以下组件：
- Java JRE 1.8（已安装在运行该连接器的计算机上）。
- 用于建立连接的 Google Workspace 信息：
- Google Workspace 私钥（包含服务账号 ID）。
- Google Workspace 数据源 ID。
通常，网域的 Google Workspace 管理员会提供这些凭据。
部署步骤
请按照以下步骤部署 Cloud Search CSV 连接器：
- 安装连接器软件
- 指定连接器配置
- 配置对 Cloud Search 数据源的访问权限
- 配置 CSV 文件访问权限
- 指定列名称、唯一键和日期时间列
- 指定可点击搜索结果网址的列
- 指定元数据和列格式
- 安排数据遍历
- 指定 ACL 选项
1. 安装 SDK
将 SDK 安装到本地 Maven 代码库中。
从 GitHub 克隆 SDK 代码库。
$ git clone https://github.com/google-cloudsearch/connector-sdk.git $ cd connector-sdk/csv
查看所选版本：
$ git checkout tags/v1-0.0.3
构建连接器：
$ mvn package
提取并安装连接器：
$ 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 文件位置和定义。
- 唯一 ID 列。
- 遍历和 ACL 选项。
要创建配置文件，请执行以下操作：
- 打开文本编辑器，并将文件命名为
connector-config.properties。 - 以
key=value对的形式添加配置参数，每对参数各占一行。如需查看配置文件示例，请参阅配置文件示例。
请将配置文件保存在连接器所在的同一目录中，以简化跟踪。为确保连接器能够识别您的文件，请在命令行中指定其路径。否则，连接器将默认使用本地目录中的 connector-config.properties。请参阅运行连接器。
3. 配置对 Cloud Search 数据源的访问权限
配置文件必须指定用于访问 Cloud Search 数据源的参数。您需要数据源 ID、服务账号 ID 和服务账号私钥文件的路径。
| 设置 | 参数 |
| 数据源 ID | api.sourceId=1234567890abcdef
必需。由 Google Workspace 管理员设置的 Cloud Search 源 ID。 |
| 服务账号私钥的路径 | api.serviceAccountPrivateKeyFile=./PrivateKey.json
必需。用于访问连接器的服务账号密钥文件。 |
| 身份源 ID | api.identitySourceId=x0987654321
如使用外部用户和组，则为必需参数。由 Google Workspace 管理员设置的身份源 ID。 |
4. 配置 CSV 文件参数
确定文件的路径、格式和编码。
| 设置 | 参数 |
| CSV 文件的路径 | csv.filePath=./movie_content.csv
必需。要编入索引的文件的路径。 |
| 文件格式 | csv.format=DEFAULT
文件的格式。Apache Commons CSV CSVFormat 类可为此参数提供可能的值。 格式值包括： |
| 文件格式修饰符 | csv.format.withMethod=value
用于指定 Cloud Search 如何处理文件的修饰符。Apache Commons CSV CSVFormat 类可为此参数提供可能的方法，包括接受单个字符、字符串或布尔值的方法。 例如，要将分号指定为分隔符，请使用 |
| 文件编码类型 | csv.fileEncoding=UTF-8
要使用的 Java 字符集。默认为平台字符集。 |
5. 指定要编入索引的列名和唯一键列
在配置文件中提供列信息。
| 设置 | 参数 |
| 要编入索引的列 | csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...
CSV 文件中要编入索引的列名称。默认情况下，CSV 的第一行用作标题。如果指定了 |
| 唯一键列 | csv.uniqueKeyColumns=movieId
用于生成唯一 ID 的列。默认值为记录的哈希码。 |
6. 指定可点击搜索结果网址的列
为搜索结果启用可点击的网址。
| 设置 | 参数 |
| 搜索结果网址格式 | url.format=https://mymoviesite.com/movies/{0}
必需。用于构造视图网址的格式。 |
| 网址参数 | url.columns=movieId
必需。CSV 列名称，其值将用于生成记录的查看网址。 |
| 要转义的搜索结果网址参数 | url.columnsToEscape=movieId
可选。CSV 列名称，其值将进行网址转义，以生成有效的视图网址。 |
7. 指定元数据、列格式和搜索质量
您可以在配置文件中添加参数，以指定下列各项：
元数据配置参数
这些参数描述了用于填充内容元数据的列。
| 设置 | 参数 |
| 标题 | 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 文件中的列。
| 设置 | 参数 |
| 跳过标题 | csv.skipHeaderRecord=true
忽略第一行。默认值为 false。 |
| 多值列 | csv.multiValueColumns=genre,actors
具有多个值的列名称。 |
| 多值列的分隔符 | csv.multiValue.genre=;
多值列的分隔符。默认分隔符为英文逗号。 |
搜索质量
连接器使用内容模板来设置记录格式。标题字段的优先级最高。您可以为其他字段分配优先级（高、中、低）。
| 设置 | 参数 |
| 内容标题 |
contentTemplate.csv.title=movieTitle
内容标题是最高搜索质量字段。 |
| 与高搜索质量对应的内容字段 |
contentTemplate.csv.quality.high=actors
具有高搜索质量值的内容字段。默认为空字符串。 |
| 与低搜索质量对应的内容字段 |
contentTemplate.csv.quality.low=genre
具有低搜索质量值的内容字段。默认为空字符串。 |
| 与中等搜索质量对应的内容字段 |
contentTemplate.csv.quality.medium=description
具有中等搜索质量值的内容字段。默认为空字符串。 |
| 未指定的内容字段 |
contentTemplate.csv.unmappedColumnsMode=IGNORE
连接器处理未指定内容字段的方式。有效值包括：
默认值为 APPEND。 |
8. 安排数据遍历
遍历是指发现内容的过程。连接器会遍历 CSV 行，并使用 Indexing API 将其编入索引。CSV 连接器仅执行完全遍历。
| 设置 | 参数 |
| 遍历间隔 | schedule.traversalIntervalSecs=7200
完整遍历之间的时间间隔（以秒为单位）。默认值为 86400（一天）。 |
| 启动时遍历 | schedule.performTraversalOnStart=false
连接器在启动时执行遍历，而不会等待第一个时间间隔到期。默认值为 |
9. 指定 ACL 选项
连接器使用 ACL 来控制访问权限。如果您的代码库提供 ACL，请上传这些 ACL。否则，请配置默认 ACL。将 defaultAcl.mode 设置为 none 以外的值。
| 设置 | 参数 |
| ACL 模式 | defaultAcl.mode=fallback
必需。连接器仅支持后备模式。 |
| 默认 ACL 名称 | defaultAcl.name=VIRTUAL_CONTAINER_FOR_CONNECTOR_1
可选。替换连接器用于默认 ACL 的虚拟容器名称。默认值为 |
| 默认公共 ACL | defaultAcl.public=true
将整个代码库设置为公共网域访问权限。默认值为 false。 |
| 公共 ACL 组读取者 | defaultAcl.readers.groups=google:group1, group2
|
| 公共 ACL 读取者 | defaultAcl.readers.users=user1, user2, google:user3
|
| 遭到公共 ACL 拒绝的组读取者 | defaultAcl.denied.groups=group3
|
| 遭到常规 ACL 拒绝的读取者 | defaultAcl.denied.users=user4, user5
|
| 整个网域访问权限 | 如需指定网域中的每个用户都可以公开访问每个已编入索引的记录，请将以下两个选项设置为相应的值：
|
| 已定义的公共 ACL | 如需为每条记录定义一个通用 ACL，请设置以下参数：
除非前缀为“ 默认用户或组为空字符串。仅当 如果 |
架构定义
为支持结构化数据查询，请为数据源设置架构。
例如，假设有一个 CSV 文件包含以下电影信息：
- movieId
- movieTitle
- description
- year
- releaseDate
- actors（用英文逗号 (,) 分隔多个值）
- genre（多个值）
- 评分
根据此结构，您可以为数据源定义以下架构：
{
"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
运行该连接器
如需从命令行运行连接器，请执行以下操作：
$ java -jar google-cloudsearch-csv-connector-v1-0.0.3.jar -Dconfig=my.config
默认情况下，标准输出中提供了连接器日志。您可以通过指定 logging.properties，将数据记录到文件中。