部署 Microsoft Windows 文件系统连接器

本指南专供 Google Cloud Search 文件系统连接器管理员(即负责下载、配置、运行和监控该连接器的任何人员)参考使用,其中介绍了如何执行与 Microsoft Windows 文件系统连接器部署相关的关键任务:

  • 下载 Google Cloud Search 文件系统连接器软件
  • 配置连接器以便与特定的文件系统数据源搭配使用
  • 部署并运行该连接器

建议您熟悉 G Suite 和 Microsoft Windows 文件系统的基础知识,以便于理解本文档中所提及的概念。

Google Cloud Search 文件系统连接器概览

借助 Google Cloud Search 文件系统连接器,Google Cloud Search 能够从 Microsoft Windows 共享中查找内容,并通过 Cloud Search 的 Indexing API 将内容编入 Cloud Search 的索引。成功编入索引后,Microsoft Windows 共享中的内容便可通过 Cloud Search 的客户端或 Cloud Search 的 Query API 搜索。

单个连接器实例可以支持多个 Microsoft Windows 共享。该连接器支持 DFS 命名空间和链接。但它仅支持 DFS 命名空间中的 DFS 链接,而不支持 DFS 命名空间中的常规文件夹。

配置属性文件

为使该连接器能够在文件系统中查找内容并将其上传到 Indexing API,连接器管理员必须按照部署步骤中的说明创建一个配置文件,以将设置提供给 Windows 文件系统连接器。

除了本文档中介绍的文件系统连接器参数之外,Google 还提供了适用于所有 Cloud Search 连接器的配置参数。如需了解详情,请参阅 Google 提供的连接器参数

连接器所需的 Microsoft Windows 帐号权限

运行连接器的 Microsoft Windows 帐号必须具有足够的权限才能执行以下操作:

  • 列出文件夹的内容
  • 读取文档的内容
  • 读取文件的属性和文件夹的属性
  • 读取对文件和文件夹的权限 (ACL)
  • 写入基本特性权限

在抓取期间读取文档内容后,连接器会尝试恢复文档的上次访问日期。要将上次访问日期恢复为读取内容之前的原始值,运行连接器所用的用户帐号需要具有写入文档的权限。如果该帐号具有只读权限而没有写入权限,则文档的上次访问日期会因为连接器在抓取期间读取文档内容而发生变化。

以下某个群组中的成员可为 Windows 帐号授予连接器所需的足够权限:

  • 管理员
  • 高级用户
  • 打印操作员
  • 服务器操作员

持续自动更新

默认情况下,该连接器会在启动时开始监控起始路径(fs.src 中的值),这些路径可以是文件共享或 DFS 链接。如果起始路径是 DFS 命名空间,则该连接器会为这个命名空间中的每个链接启动一个监控器。该连接器启动时,如果这些监控器没有启动,则系统会在执行轮询请求后将 Cloud Search 索引中已有的起始路径或 DFS 链接返回给该连接器时,启动这些监控器。您可以按照 connector-config.properties 变量中的说明,在连接器配置选项 fs.monitorForUpdates 中设置相应的值以停用/启用此功能。

DFS 访问控制

DFS 系统在导航其链接时会采用访问控制机制,通常每个 DFS 链接都有自己的 ACL。此系统采用的机制之一是基于访问权限的枚举 (ABE)。部署 ABE 后,用户可能只会看到一部分 DFS 链接;当 ABE 用于隔离托管主目录时,用户可能只会看到一个 DFS 链接。遍历 DFS 系统时,该连接器除了提供目标的共享 ACL 以外,还会提供 DFS 链接 ACL 作为在抓取 DFS 链接时指定的资源。在这种情况下,共享 ACL 继承自 DFS ACL。

支持的操作系统

仅支持在以下 Windows 操作系统中安装 Cloud Search 文件系统连接器:

  • Windows Server 2016
  • Windows Server 2012
  • Windows Server 2008 R2

Cloud Search 文件系统连接器无法在 Linux 上运行。

支持的文件系统协议

下表列出了用来与文件共享通信的文件系统协议,并指出了该连接器是否支持这些协议。

文件系统协议 与共享通信时所在的操作系统 是否受支持?
服务器消息块 (SMB) - SMB1 Windows Server 2016
Windows Server 2012
Windows Server 2008 R2
服务器消息块 (SMB) - SMB2 Windows Server 2016
Windows Server 2012
Windows Server 2008 R2
分布式文件系统 (DFS) Windows Server 2016
Windows Server 2012
Windows Server 2008 R2
本地 Windows 文件系统 Windows Server 2016
Windows Server 2012
Windows Server 2008 R2
Sun 网络文件系统 (NFS) 2.0
Sun 网络文件系统 (NFS) 3.0
本地 Linux 文件系统

已知限制

  • 文件系统:此版本的文件系统连接器不支持映射驱动器和本地驱动器。
  • 分布式文件系统:映射到 UNC DFS 的驱动器无法正常工作。系统无法正确读取某些 ACL。

前提条件

在部署 Cloud Search 文件系统连接器之前,请确保您的环境已具备以下所有必备组件:

  • Java JRE 1.8(已安装在运行该连接器的计算机上)。
  • 在 Google Cloud Search 和数据源之间建立关系所需的 G Suite 信息:

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

  • 确保 Windows 帐号具有足够的权限,如以下部分所述。

  • 从 Windows 平台共享某个文件夹时,可以在该文件夹的共享 ACL 和 NTFS ACL 中授予权限。这两个 ACL 都需要为该连接器授予适当的访问权限。该连接器也会同时读取这两个 ACL。管理员可以将 fs.skipShareAccessControl 配置选项设置为 true,以跳过尝试读取共享 ACL。

部署步骤

要部署 Google Cloud Search 文件系统连接器,请按照以下步骤操作:

  1. 安装 Cloud Search 文件系统连接器
  2. 指定文件系统连接器配置
  3. 配置对 Google Cloud Search 数据源的访问权限
  4. 配置对文件系统的访问权限
  5. 配置路径分隔符
  6. 配置连接器行为控制
  7. 配置上次访问控制
  8. 限制对已抓取文档和文件夹的访问权限
  9. 跳过文件共享访问控制
  10. 启用日志记录
  11. 配置 mime-type.properties

1. 安装 Cloud Search 文件系统连接器

  1. 从 GitHub 克隆连接器代码库。

    $ git clone https://github.com/google-cloudsearch/windows-filesystems-connector.git
        $ cd windows-filesystems-connector
  2. 检出所需的连接器版本:

    $ git checkout tags/v1-0.0.3
  3. 构建该连接器。

    $ mvn package

    要在构建该连接器时跳过测试,请运行 mvn package -DskipTests 而不是 mvn package

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

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

2. 指定文件系统连接器配置

为使该连接器能够正确访问文件系统并将相关内容编入索引,您必须先创建连接器配置文件。您可以通过在文件系统连接器配置文件中定义参数来控制该连接器的行为和特性。可配置的参数可控制以下行为:

  • 对数据源的访问权限
  • 对文件系统的访问权限
  • 与该连接器对文件系统的访问权限相关的元数据

    另请参阅 Google 提供的连接器参数

要创建配置文件,请执行以下操作:

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

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 文件系统连接器所需的 Google Cloud Search 服务帐号密钥文件。
身份源 ID api.identitySourceId=x0987654321
必填。由 G Suite 管理员设置的 Cloud Search 身份源 ID,用于通过 GCDS 同步 Active Directory 身份。

4. 配置对文件系统的访问权限

您必须先配置对源文件系统的访问权限,这样该连接器才能访问文件系统并从中提取数据,以便编入索引。请使用以下参数,将源路径信息添加到配置文件。

设置 参数
源文件系统 fs.src=path1,path2
您可以通过提供一系列 UNC 源(用由 fs.src.separator 配置的分隔符进行分隔),在 fs.src 属性中指定多个源文件系统。如果使用未包含在 Latin1 中的字符,请使用 Java Unicode 转义符对其进行编码。

5. 配置路径分隔符

请使用以下参数将分隔符信息添加到配置文件中。

设置 参数
路径分隔符 fs.src.separator=,
默认分隔符为“;”(类似于用户在设置 PATHCLASS_PATH 环境变量时采用的方式)。但是,如果您指定的源路径包含英文分号,则可以配置与路径中的字符没有冲突并且没有被属性文件语法本身预留的其他分隔符。

如果 fs.src.separator 设置为空字符串,则 fs.src 值会被视为单个路径名。

6. 配置连接器行为控制机制

请使用以下参数将有关连接器行为的信息添加到配置文件中。

设置 参数
Windows 网域 fs.supportedDomain=domain

如要允许使用 GCDS 设置的用户通过 Cloud Search 访问文档,则此为必填参数。请将此参数指定为单个 NetBIOS 域名。

在 ACL 中添加帐号 fs.supportedAccounts=BUILTIN\\Administrators,\\Everyone,BUILTIN\\Users

无论 supportedAccounts 中的帐号是否为内置帐号,都会添加到 ACL 中。

默认值为 BUILTIN\\Administrators,Everyone,BUILTIN\\Users, \ BUILTIN\\Guest,NT AUTHORITY\\INTERACTIVE, \ NT AUTHORITY\\Authenticated Users

从 ACL 中排除内置帐号 fs.builtinGroupPrefix=BUILTIN\\

内置帐号会从推送到编制索引 API 的 ACL 中排除。以此前缀开头的帐号会被视为内置帐号,将会从 ACL 中排除。

默认值为 BUILTIN\\

允许或禁止将隐藏文件和隐藏文件夹编入索引 fs.crawlHiddenFiles=true

隐藏文件和隐藏文件夹的定义取决于平台。在 Windows 文件系统上,如果设置了 DOS 隐藏属性,则认为文件或文件夹是隐藏的。默认情况下,隐藏文件未编入索引,隐藏文件夹的内容也未编入索引。如果将 fs.crawlHiddenFiles 设置为 true,则允许连接器抓取隐藏文件和隐藏文件夹。

默认值为 false

允许或禁止将抓取的文件夹列表和 DFS 命名空间枚举编入索引 fs.indexFolders=false

在抓取文件夹时,该连接器会创建一个 CONTAINER_ITEM 对象。如果 indexFolders 设置为 false,则该连接器会改为创建一个 VIRTUAL_CONTAINER_ITEM 对象。

默认值为 true

启用/停用文件系统更改监控功能 fs.monitorForUpdates=false

停用监控功能时,如果请求重新抓取,则对内容或访问控制进行的更新和更改不会立即发送到 Indexing API。停用监控功能可显著减少连接器的资源用量。

默认值为 true

设置目录缓存的大小上限 fs.directoryCacheSize=25000

设置遇到的目录缓存的大小上限。此缓存当前用于标识隐藏文件夹或非隐藏文件夹,以避免将祖先文件夹为隐藏状态的文件和文件夹编入索引。如果设置了 DOS 隐藏属性,则文件夹会被视为隐藏状态。

默认缓存大小上限为 50000 个条目,通常占用 10-15 MB RAM。

7. 配置上次访问控制

请使用以下参数将有关已抓取文件和文件夹的上次访问信息添加到配置文件中。

设置 参数
保留上次访问时间戳 fs.preserveLastAccessTime=NEVER

此配置属性控制已抓取文件和文件夹的上次访问时间戳的强制保留级别。如果没有保留上次访问时间,则备份和归档系统会误认为最近有人访问过相应文件或文件夹,从而妨碍将最近使用最少的项转移到辅助存储空间。

如果连接器无法恢复文件的上次访问时间,原因可能是遍历用户的权限不足,无法写入该文件的属性。为保险起见,该连接器会拒绝文件系统的抓取请求,以避免更改数量可能高达数千个文件的上次访问时间戳。

fs.preserveLastAccessTime 属性有以下三个可用的值:

  • ALWAYS:该连接器将尝试保留所有已抓取文件和文件夹的上次访问时间。如果第一次尝试保留失败,则系统会强制连接器拒绝文件系统的所有后续抓取请求,以避免更改数量可能高达数千个文件的上次访问时间戳。
  • IF_ALLOWED:虽然可能有些时间戳未能保留,但该连接器会尝试保留所有已抓取文件和文件夹的上次访问时间。
  • NEVER:该连接器不会尝试保留已抓取文件和文件夹的上次访问时间。上次访问时间戳的默认强制保留级别为 ALWAYS
禁止抓取上次访问时间早于特定日期的文件 fs.lastAccessedDate=2010-01-01

截止日期以 ISO 8601 日期格式 YYYY-MM-DD 指定。

如果将 fs.lastAccessedDate 设置为 2010-01-01,则系统只会抓取自 2010 年 1 月 1 日以来访问过的内容。 您只能指定 fs.lastAccessedDatefs.lastAccessedDays 中的一个。 默认值为 disabled

禁止抓取在指定的天数内未访问过的文件 fs.lastAccessedDays=365

fs.lastAccessedDate 使用的绝对截止日期不同,此属性可以用来使先前已编入索引且在一段时间内未访问过的内容失效。 到期时间以正整数(代表天数)指定。如果将 fs.lastAccessedDays 设置为 365,则系统只会抓取此前一年内被访问过的内容。 您只能指定 fs.lastAccessedDatefs.lastAccessedDays 中的一个。 默认值为 disabled

8. 限制对已抓取文档和文件夹的访问权限

请使用以下参数,将有关限制对已抓取文件和文件夹的访问权限的信息添加到配置文件中。

设置 参数
禁止抓取上次访问时间早于特定日期的文件 fs.lastModifiedDate=2010-01-01

截止日期以 ISO 8601 日期格式 YYYY-MM-DD 指定。

如果将 fs.lastModifiedDate 设置为 2010-01-01,则系统只会抓取自 2010 年 1 月 1 日以来修改过的内容。 您只能指定 fs.lastModifiedDatefs.lastModifiedDays 中的一个。 默认值为 disabled

禁止抓取在指定的天数内未修改过的文件 fs.lastModifiedDays=365

fs.lastModifiedDate 使用的绝对截止日期不同,此属性可以用来使先前已编入索引且在一段时间内未修改过的内容失效。到期时间以正整数(代表天数)指定。 如果将 fs.lastModifiedDays 设置为 365,则系统只会抓取此前一年内被修改过的内容。 您只能指定 fs.lastModifiedDatefs.lastModifiedDays 中的一个。 默认值为 disabled

9. 跳过文件共享访问控制

将访问控制列表 (ACL) 发送到 Indexing API 时,该连接器会尝试保留访问控制的完整性。通常,只有有权访问文件共享的用户才有权访问保留在该共享上的文件,因此连接器会将该共享的 ACL 包含在发送到 Indexing API 的 ACL 中。但是,在某些配置中,连接器的权限可能不足,无法读取该共享的 ACL。在这些情况下,这个“损坏”的共享 ACL 将阻止搜索结果显示该文件共享上保留的所有文件。如果连接器无法读取该共享 ACL,则管理员可以将 fs.skipShareAccessControl 配置选项设置为 true,让连接器跳过尝试读取该共享 ACL。这样就可以为 Indexing API 提供一个完全能够访问的共享 ACL,而不是实际的共享 ACL。

请使用以下参数将有关跳过文件共享访问控制的信息添加到配置文件中。

设置 参数
跳过文件共享访问控制 fs.skipShareAccessControl=true

此布尔型配置属性允许或禁止将文件共享的访问控制列表 (ACL) 发送到 Indexing API。

默认值为 false(共享 ACL 会发送到 Indexing API)

示例:配置文件

以下示例配置文件显示了定义示例连接器行为的参数“键=值”对。

api.serviceAccountPrivateKeyFile=/path/to/file.json
    api.sourceId=0123456789abcde
    api.identitySourceId=a1b1c1234567
    traverse.abortAfterExceptions=500
    fs.src=\\\\host\\share;\\\\dfshost\\dfsnamespace;\\\\dfshost\\dfsnamespace\\link
    fs.monitorForUpdates = true
    fs.preserveLastAccessTime = IF_ALLOWED
    

10. 启用日志记录功能

在包含连接器二进制文件的同一目录中创建一个名为 logs 的文件夹。在同一目录中创建一个名为 logging.properties 的 ASCII 或 UTF-8 文件,并添加以下内容:

handlers = java.util.logging.ConsoleHandler,java.util.logging.FileHandler
    # Default log level
    .level = WARNING
    com.google.enterprise.cloudsearch.level = INFO
    com.google.enterprise.cloudsearch.fs.level = INFO

    # uncomment line below to increase logging level to enable API trace
    #com.google.api.client.http.level = FINE
    java.util.logging.ConsoleHandler.level = INFO
    java.util.logging.FileHandler.pattern=logs/connector-fs.%g.log
    java.util.logging.FileHandler.limit=10485760
    java.util.logging.FileHandler.count=10
    java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
    

11. 配置 mime-type.properties

(可选)您可以在连接器目录中创建一个名为 mime-type.properties 的 ASCII 或 UTF-8 文件。在此文件中,请为每种文件类型指定多用途互联网邮件扩展 (MIME) 类型。如果不指定 MIME 类型,则连接器将尝试检测每个文件的 MIME 类型。连接器依赖于 JDK 提供的 MIME 类型检测功能。在 Microsoft Windows 上,JDK 依赖于 Windows 注册表来确定文件的 MIME 类型。如果缺少注册表条目,可能会导致某些文件的 MIME 类型为 null。

标准应用具有其标准 MIME 类型。mime-type.properties 的用途只是用来覆盖您希望更改的任何绑定。mime-type.properties 文件应与 connector-config.propertieslogging.properties 位于同一个顶层目录中。规范的格式为:文件扩展名加上其 MIME 类型。例如:

xlsx=application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
    one=application/msonenote
    

示例:MIME 类型文件

以下示例显示了 MIME 类型文件。

txt=text/plain
    pdf=application/pdf
    

运行 Cloud Search 文件系统连接器

安装 Cloud Search 文件系统连接器后,您可以使用类似以下示例的命令在主机上运行该连接器:

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