部署 CSV 连接器

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

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

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

要了解本文档中的概念,您应该熟悉 G Suite、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 和数据源之间建立关系所需的 G Suite 信息:

    一般来说,G Suite 网域管理员可以为您提供这些凭据。

部署步骤

要部署 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 和服务帐号私钥文件的路径。管理第三方数据源中描述了设置数据源所需的步骤

设置 参数
数据源 ID api.sourceId=1234567890abcdef

必需。由 G Suite 管理员设置的 Google Cloud Search 源 ID,如管理第三方数据源中所述。

服务帐号私钥文件路径 api.serviceAccountPrivateKeyFile=./PrivateKey.json

必需。为配置 Google Cloud Search CSV 连接器的访问权限而创建 Google Cloud Search 服务帐号密钥文件。

身份源 ID api.identitySourceId=x0987654321

如使用外部用户和组,则为必需参数。由 G Suite 管理员设置的 Cloud Search 身份源 ID。

4.配置 CSV 文件参数

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

设置 参数
CSV 文件的路径 csv.filePath=./movie_content.csv

必需。要访问并从中提取数据,以编入索引的 CSV 文件的路径。

文件格式 csv.format=DEFAULT

文件的格式。Apache Commons CSV CSVFormat 类可为此参数提供可能的值。

格式值包括:DEFAULTEXCELINFORMIX_UNLOADINFORMIX_UNLOAD_CSVMYSQLRFC4180ORACLEPOSTGRESQL_CSVPOSTGRESQL_TEXTTDF。如果未指定,则 Cloud Search 使用 DEFAULT

文件格式修饰符 csv.format.withMethod=value

用于指定 Cloud Search 如何处理文件的修饰符。Apache Commons CSV CSVFormat 类可为此参数提供可能的方法,包括接受单个字符、字符串或布尔值的方法。

例如,要将分号指定为分隔符,请使用 csv.format.withDelimiter=;。要忽略空行,则使用 csv.format.withIgnoreEmptyLines=true

文件编码类型 csv.fileEncoding=UTF-8

在 Cloud Search 读取文件时使用的 Java 字符集。如果未指定任何值,Cloud Search 会使用平台默认字符集。

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

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

设置 参数
要编入索引的列 csv.csvColumns=movieId,movieTitle,description,actors,releaseDate,year,userratings...

CSV 文件中要编入索引的列名称。如果未设置 csv.csvColumns,则 CSV 文件的第一行将用作标题。如果设置了 csv.csvColumns,该值将优先于 CSV 的第一行。如果设置了 csv.csvColumns 并且 CSV 文件的第一行是列名称列表,则需要设置 csv.skipHeaderRecord=true,以避免尝试将第一行作为数据编入索引。默认值是文件中标题行中的列。

唯一键列 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=type
itemMetadata.objectType.defaultValue=movie

连接器使用的对象类型,定义请参见架构。 如果未指定此属性,连接器不会将任何结构化数据编入索引。

日期时间格式

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

设置 参数
其他日期时间格式 structuredData.dateTimePatterns=MM/dd/uuuu HH:mm:ssXXX
一个以英文分号分隔的其他 java.time.format.DateTimeFormatter 格式的列表。在解析元数据或架构中的任何日期或日期时间字段的字符串值时,系统将使用这些格式。默认值为空列表,但始终支持 RFC 3339 和 RFC 1123 格式。

列格式

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

设置 参数
跳过标题 csv.skipHeaderRecord=true

布尔值。忽略 CSV 文件中的标题记录(第一行)。如果您已设置 csv.csvColumns 并且 CSV 文件有标题行,则必须设置 skipHeaderRecord=true。这样可以防止将文件中的第一行作为数据编入索引。如果 CSV 文件没有标题行,请设置 skipHeaderRecord=false。默认值为 false。

多值列 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

连接器处理未指定内容字段的方式。有效值包括:

  • APPEND - 将未指定的内容字段附加到模板
  • IGNORE - 忽略未指定的内容字段

    默认值为 APPEND

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=google:group1, group2
公共 ACL 读取者 defaultAcl.readers.users=user1, user2, google:user3
遭到公共 ACL 拒绝的组读取者 defaultAcl.denied.groups=group3
遭到常规 ACL 拒绝的读取者 defaultAcl.denied.users=user4, user5
整个网域访问权限 要指定每个已编入索引的记录都可由网域中的每个用户公开访问,请将以下两个选项设置为所示的值:
  • defaultAcl.mode=fallback
  • defaultAcl.public=true
公共定义 ACL 要为数据代码库的每个记录指定一个 ACL,请设置以下所有参数值:
  • defaultAcl.mode=fallback
  • defaultAcl.public=false
  • defaultAcl.readers.groups=google:group1, group2
  • defaultAcl.readers.users=user1, user2, google:user3
  • defaultAcl.denied.groups=group3
  • defaultAcl.denied.users=user4, user5

    除非前缀为“google:”(字面常量),否则假定每个指定的用户和组都是本地网域定义的用户/组。

    默认用户或组为空字符串。 仅当 defaultAcl.public 设置为 false 时才提供用户和组选项。要列出多个组和用户,请使用英文逗号分隔列表。

    如果 defaultAcl.mode 设置为 none,且未定义单个 ACL,那么记录将无法被搜索到。

架构定义

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": "Documentry"
                  },
                  {
                    "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,将数据记录到文件中。