部署 Microsoft SharePoint On-Prem 连接器

本指南专供 Google Cloud Search SharePoint On-Prem 连接器管理员(即负责下载、配置、运行和监控该连接器的任何人员)参考使用。

本指南包含执行与 SharePoint On-Prem 连接器部署相关的关键任务的说明:

  • 下载 Google Cloud Search SharePoint On-Prem 连接器软件
  • 配置连接器以用于本地 SharePoint Server 数据源
  • 部署并运行连接器

要理解本文档中的概念,您应该熟悉 G Suite 和本地 SharePoint Server 的基础知识。

概览

默认情况下,Google Cloud Search 可从 Google 文档和 Gmail 等 G Suite 数据中查找内容、将内容编入索引以及提供内容。您可以使用 Sharepoint On-Prem 连接器扩展 Google Cloud Search 的功能,以便为您的用户提供 SharePoint On-Prem 内容。

配置属性文件

要使连接器能够从本地 SharePoint 查找内容并将其上传到索引 API,您必须创建配置文件向连接器提供特定信息。在执行部署步骤中描述的配置步骤时,您可以通过添加参数来构建配置文件。

除了本文档介绍的 SharePoint On-Prem 连接器参数之外,Google 还提供了供所有 Cloud Search 连接器使用的配置参数。如需了解详细信息,请参阅 Google 提供的连接器参数

支持的操作系统

  • Windows Server 2016
  • Ubuntu
  • Red Hat Enterprise Linux 5.0
  • SUSE Enterprise Linux 10(64 位)

支持的 SharePoint 版本

  • SharePoint Server 2016
  • SharePoint Server 2013

将未发布的文档编入索引

Cloud Search SharePoint On-Prem 连接器始终遵循 SharePoint 上的“搜索可见性”设置(您无法替换此设置)。对于草稿文档,能否编入索引取决于为连接器用户帐号授予的权限。如果连接器用户仅具有“完全读取”权限,则连接器将遵循 SharePoint 上的所有“草稿内容可见性”设置。

支持的身份验证机制

  • NTLM
  • Kerberos
  • HTTP 基本身份验证
  • ADFS

已知的连接器限制

  • 内容数据库的数量将影响文档更改检测的延迟时间。
  • 在每个网站集的 ACL 中使用的唯一身份用户和群组的数量将影响内存消耗。
  • 当前版本的连接器仅支持来自一个 Active Directory 域的身份。
  • 当前版本的连接器不支持常见的 Active Directory 和 Windows 主帐号,例如 Everyone, BUILTIN\Users, All Authenticated Users
  • 当前版本的连接器不会生成即时删除通知。
  • 当前版本的连接器依赖于将内容重新编入索引来识别源代码库中删除的内容。对于以前编入索引的内容,删除检测延迟时间可能超过 4 小时。

部署 Cloud Search SharePoint On-Prem 连接器前的准备工作

在部署 Google Cloud Search SharePoint On-Prem 连接器之前,请确保您拥有以下必需组件:

  • 支持的操作系统Sharepoint Server
  • Java JRE 1.8,安装在运行 Google Cloud Search SharePoint On-Prem 连接器的计算机上
  • 在 Google Cloud Search 和数据源之间建立关系所需的 G Suite 信息:

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

  • 连接器的用户帐号,其用户规范中包含对 SharePoint Web 应用的完全读取权限

  • 确保 Web 应用已创建根网站集。此连接器不支持将没有根网站集的 Web 应用中的内容编入索引。

  • 如果存在任何写入锁定的网站集,请在安装连接器之前使用具有管理员权限的帐号在 SharePoint 上运行 PrepareWriteLockedSitesForAdaptor.ps1 脚本。

  • 要获得配置此连接器的协助,请使用服务器农场管理员权限登录 SharePoint 服务器并运行 diagnose_sp.ps1

    此命令的输出(包括 Web 应用数、文档数和用户群组成员数)有助于估计所需的连接器实例数、内存要求和预期文档数。

部署步骤

要部署 Google Cloud Search SharePoint On-Prem 连接器,请按照下列步骤操作:

  1. 安装 Google Cloud Search SharePoint On-Prem 连接器软件。
  2. 指定 SharePoint On-Prem 连接器配置。
  3. 配置对 Google Cloud Search 数据源的访问权限。
  4. 配置对 SharePoint On-Prem 的访问权限。
  5. 将 SharePoint 添加为可信主机。
  6. 配置网站集。
  7. 启用日志记录。
  8. 配置 SharePoint 与 Google Cloud Search 的身份映射。
  9. 配置 Active Directory 查询。
  10. 配置 HTML 生成和结构化数据支持

1. 安装 Google Cloud Search SharePoint On-Prem 连接器软件。

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

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

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

    $ mvn package

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

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

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

2.指定 SharePoint On-Prem 连接器配置

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

  • 访问数据源
  • 访问 SharePoint On-Prem 服务器
  • 将 SharePoint On-Prem 服务器编入网站集索引

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

  • 打开您选择的文本编辑器并命名配置文件。
  • “键=值”对添加到文件内容中,如以下部分所述。
  • 保存并命名配置文件。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 SharePoint On-Prem 连接器所需的 Google Cloud Search 服务帐号密钥文件。

身份源 ID api.identitySourceId=x0987654321

必需。由 G Suite 管理员设置的 Cloud Search 身份源 ID。

4. 配置对 SharePoint On-Prem 的访问权限

要使连接器可以访问 SharePoint On-Prem 并从中提取数据以编入索引,您必须配置对 SharePoint 服务器的访问权限。请使用以下参数将访问权限信息添加到配置文件中。

设置 参数
SharePoint 服务器的完全限定域名 sharepoint.server=http://yoursharepoint.example.com/

必填。如果域名不是完全限定的,则必须在连接器主机上设置 DNS 覆盖。

SharePoint 用户名 sharepoint.username=YOURDOMAIN\\ConnectorUser

在 Linux 上或不属于 SharePoint Server AD 域的 Windows 机器上运行连接器时必需。

SharePoint 密码 sharepoint.password=user_password

在 Linux 上或不属于 SharePoint Server AD 域的 Windows 机器上运行连接器时必需。

使用实时身份验证连接到 SharePoint sharepoint.username=AdaptorUser Live Authentication Id

sharepoint.password uS3R_passWoRD

sharepoint.formsAuthenticationMode=LIVE

使用 ADFS 身份验证连接到 SharePoint sharepoint.username=AdaptorUser@yourdomain.com

sharepoint.password=uS3R_passWoRD

sharepoint.sts.endpoint=https://adfs.example.com/adfs/services/trust/2005/usernamemixed

sharepoint.sts.realm=urn:myserver:sharepointhttps://yoursharepoint.example.com/_trust

sharepoint.formsAuthenticationMode=ADFS

5. 将 SharePoint 添加为可信主机

如果 SharePoint 配置为使用 HTTPS,请执行以下步骤获取 SharePoint 证书,将其添加为连接器的可信主机:

  • 在浏览器中导航到 SharePoint。 此时将显示一个警告页面,其中会包含一条类似于“此连接不受信任”的消息。显示此消息是因为该证书采用自签名,而非由受信任的证书授权机构签名。点击我了解此风险添加例外
  • 等到浏览按钮可点击时,点击该按钮。
  • 切换到“详细信息”标签页,然后点击“导出”。
  • 将证书保存在连接器的目录中,名称设为 sharepoint.crt
  • 点击关闭,然后点击取消以关闭窗口。
  • 要允许连接器信任 SharePoint,请打开命令提示符并输入以下命令:

    $ keytool -importcert -keystore cacerts.jks -storepass changeit -file sharepoint.crt -alias sharepoint

    当看到“是否信任此证书?”的提示时,输入 yes

6. 配置网站集

(可选)您可以配置连接器以将 SharePoint 服务器编入网站集索引。

设置 参数
sharepoint.server 是否为网站集,而非虚拟服务器 sharepoint.siteCollectionOnly=true

默认为自动检测。如果为 true,则连接器将 sharepoint.server 编入网站集索引。

7. 启用日志记录

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

handlers = java.util.logging.ConsoleHandler,java.util.logging.FileHandler
    # Default log level
    .level = INFO
    # uncomment line below to increase logging level for SharePoint APIsa
    #com.google.enterprise.cloudsearch.sharepoint.level=FINE

    # 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-sharepoint.%g.log
    java.util.logging.FileHandler.limit=10485760
    java.util.logging.FileHandler.count=10
    java.util.logging.FileHandler.formatter=java.util.logging.SimpleFormatter
    

Google Cloud Search 允许其客户对搜索结果应用 ACL 调整。您可以使用 Google 主帐号和外部主帐号定义这些 ACL。

典型的 SharePoint On-Prem 设置涉及以下 3 个主帐号。

  • Active Directory 用户
  • Active Directory 群组
  • SharePoint 本地群组(成员包括 Active Directory 用户和群组)

要为 SharePoint 内容应用适当的安全调整,您还需要将以下外部身份与 Google 保持同步:

  • 使用 Google Cloud Directory Sync 工具(添加了对身份映射群组的支持)来同步 Active Directory 用户和群组。
  • 使用 SharePoint 身份连接器来同步 SharePoint 本地群组。

要支持此类设置,您需要创建 2 个身份源。

  • 一个用于同步 Active Directory 用户和群组的身份源。
  • 一个用于同步 SharePoint 本地群组的身份源
设置 参数
身份源 ID api.identitySourceId=1234567890abcdef

用于同步 SharePoint 本地群组的身份源 ID。必填。由 G Suite 管理员设置的 Google Cloud Search 来源 ID,如添加可供搜索的数据源中所述。

引用身份源 api.referenceIdentitySources=CONTOSO,contoso

Activity Directory 主帐号的引用身份源列表。此值应与要引用的 Activity Directory 主帐号的 Active Directory NETBIOS 名称匹配。

引用身份源 ID api.referenceIdentitySource.CONTOSO.id=112233abcd

必填。用于同步网域 CONTOSO 的 Active Directory 主帐号的身份源 ID。

9. 配置 Active Directory 查询

虽然其他连接器依靠 Google Cloud Directory Sync 来同步 Active Directory 用户和群组,但 SharePoint 连接器需要执行 AD 查询以获取有关正在同步的主帐号的其他信息。使用场景包括:

  • 将网域群组的 SID 映射到相应的 sAMAccountName。
  • 将用户 sAMAccountName 映射到 SharePoint 本地群组成员身份的电子邮件地址。
设置 参数
Active Directory 主机 adLookup.host=dc.contoso.com

必填。Active Directory 的主机名或 IP 地址。

Active Directory 查询端口 adLookup.port=389

可选。默认值为 389。SSL 使用 686。

Active Directory 查询方法 adLookup.method=standard

可选。默认为标准方法。进行安全连接时使用“SSL”。

Active Directory 查询用户 adLookup.username=CONTOSO\user1

必填。有权执行 Active Directory 查询的用户。

Active Directory 查询密码 adLookup.passowrd=password123

必填。由 adLookup.user 指定的用户密码。

10. 为 SharePoint 列表项配置结构化数据支持和 HTML 内容生成

要将 SharePoint 列表项的其他元数据编入索引,请配置连接器以支持 HTML 内容生成和/或结构化数据。

HTML 内容生成

请使用下表中的参数配置 HTML 内容生成。如需了解可选的 HTML 内容生成参数,请参阅“HTML 内容生成”。

设置 参数
HTML 模板标题字段 contentTemplate.sharePointItem.title=Title

用作生成的 HTML“标题”的 SharePoint 字段。

HTML 内容高搜索质量字段 contentTemplate.sharePointItem.quality.high=highField1,highField2…

要作为高质量字段包含在生成的 HTML 中的字段。这些字段中的搜索查询字词匹配排序将靠前。

HTML 内容中等搜索质量字段 contentTemplate.sharePointItem.quality.medium=mediumField1, mediumField2…

要在生成的 HTML 中包含为中等质量字段的字段。

HTML 内容低搜索质量字段 contentTemplate.sharePointItem.quality.low=lowField1, lowField2…

要在生成的 HTML 中包含为低质量字段的字段。

HTML 内容未映射列 contentTemplate.sharepointItem.unmappedColumnsMode=APPEND

默认值为 APPEND。如果要在生成的 HTML 内容中包含未映射的字段(不属于高、中、低配置),请将此参数设置为 APPEND。如果设置为 IGNORE,则仅使用映射列生成 HTML。

结构化数据支持

如果使用以下准则定义数据源的架构,则连接器会为 SharePoint 列表项填充结构化数据:

  • 连接器根据 Cloud Search API 定义的规范来标准化 SharePoint 内容类型名称,以将 SharePoint 内容类型名称映射到相应的对象定义。Cloud Search API 仅支持 A-Z、a-z 和 0-9 作为对象定义的有效字符。连接器通过排除不支持的字符来标准化内容类型名称。例如,内容类型“Announcements”映射到对象定义“Announcements”,而内容类型“News Article”映射到“NewsArticle”。

  • 连接器还支持使用 itemMetadata.objectType 来配置后备对象类型。如果架构中没有与 SharePoint 内容类型对应的对象定义,则连接器会使用后备对象类型。

  • 连接器对 SharePoint 列的显示名称进行标准化,将 SharePoint 属性名称映射到属性定义。

示例:配置文件

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

api.sourceId=08ef8becd116faa4546b8ca2c84b2879
    api.serviceAccountPrivateKeyFile=service_account.json
    api.identitySourceId=08ef8becd116faa475de26d9b291fed9

    # Optional
    contentTemplate.sharepointItem.title=Title
    contentTemplate.sharepointItem.unmappedColumnsMode=APPEND

    sharepoint.server=http://sp-2016:32967/sites/doc-center-site-collection
    sharepoint.siteCollectionOnly=true
    sharepoint.username=contoso\\admin
    sharepoint.password=pa$sw0rd
    sharepoint.stripDomainInUserPrincipals=true

    adLookup.host=dc.contoso.com
    adLookup.port=389
    adLookup.username=contoso\\admin
    adLookup.password=pa$sw0rd

    api.referenceIdentitySources=CONTOSO,contoso
    api.referenceIdentitySource.contoso.id=08ef8becd116faa5d3783f8c5a80e5aa
    api.referenceIdentitySource.CONTOSO.id=08ef8becd116faa5d3783f8c5a80e5aa
    

运行 SharePoint On-Prem 身份连接器

要使用户能够在 Cloud Search 搜索结果中获取其有权访问的 SharePoint 内容,您必须首先将本地 Active Directory 和 SharePoint 网站集中的主帐号映射到 Google Cloud Identity 服务中的身份。此同步由 Google Cloud Directory Sync (GCDS) 应用和 SharePoint On-Prem 身份连接器完成。 要了解使用 GCDS 的步骤,请参阅 Google Directory Sync 简介。要详细了解如何启用身份映射群组,请参阅将群组同步到 Cloud Search 身份源

在 GCDS 同步 Active Directory 中的用户和群组后,运行 SharePoint On-Prem 身份连接器(如下所述)以同步 SharePoint 网站集群组。

身份连接器使用一个类似于将内容编入索引时所用的配置文件。以下是身份连接器配置文件的示例:

api.customerId=C05d3djk8
    api.serviceAccountPrivateKeyFile=service_account.json
    api.identitySourceId=08ef8becd116faa475de26d9b291fed9

    sharepoint.server=http://sp-2016:32967/sites/doc-center-site-collection
    sharepoint.siteCollectionOnly=true
    sharepoint.username=contoso\\admin
    sharepoint.password=pa$sw0rd
    sharepoint.stripDomainInUserPrincipals=true

    adLookup.host=dc.contoso.com
    adLookup.port=389
    adLookup.username=contoso\\admin
    adLookup.password=pa$sw0rd

    api.referenceIdentitySources=CONTOSO,contoso
    api.referenceIdentitySource.contoso.id=08ef8becd116faa5d3783f8c5a80e5aa
    api.referenceIdentitySource.CONTOSO.id=08ef8becd116faa5d3783f8c5a80e5aa
    

请注意,此文件包含 api.customerId 属性。此属性包含您的 G Suite 帐号 ID。要了解如何生成 customerID,请参阅在 Cloud Search 中映射用户身份

用于将内容编入索引的 JAR 文件也包含身份连接器。要运行它,请在包含该配置文件的目录中执行以下命令。用当前版本号替换代码中的“version”,您可以在 GitHub 版本页面上找到这个版本号。

java -Djava.util.logging.config.file=logging.properties -cp "google-cloudsearch-sharepoint-connector-version.jar" com.google.enterprise.cloudsearch.sharepoint.SharePointIdentityConnector

运行 SharePoint On-Prem 连接器

在主机上使用 cmd.exe 运行连接器:

$ java -Djava.util.logging.config.file=logging.properties -jar google-cloudsearch-sharepoint-connector-v1-0.0.3.jar

若要针对采用 HTTPS 协议访问的 SharePoint 网站运行连接器,请将 SharePoint 添加为可信主机,如上所述。

$ java -Djavax.net.ssl.trustStore=cacerts.jks -Djavax.net.ssl.trustStoreType=jks -Djavax.net.ssl.trustStorePassword=changeit -Djava.util.logging.config.file=logging.properties -jar google-cloudsearch-sharepoint-connector-v1-0.0.3.jar

高级主题

本部分中的信息属于 SharePoint 连接器基本配置以外的内容。

多租户配置

多租户 SharePoint 部署通常在同一 Web 应用下托管多个客户网站。客户仅获取其各自网站集的权限。在这种情况下,您无法按 SharePoint On-Prem 连接器的要求获取 SharePoint Web 应用的完全读取权限。

此类多租户配置通过“仅限网站集”模式获得支持。要支持多租户配置,必须使用 connector-config.properties 文件中的 sharepoint.siteCollectionOnly 配置选项启用网站集模式。

要在仅限网站集模式下将根网站集编入索引,您需要明确将 sharepoint.siteCollectionOnly 设置为 true。

连接器会将网站集及其子项编入索引。因此,SharePoint 上的连接器用户帐号需要具有网站集管理员权限。

如果要在多租户环境中将多个网站集编入索引,则需要为每个网站集配置一个连接器实例。

要在仅限网站集模式下配置 SharePoint On-Prem 连接器,请执行以下操作:

  • sharepoint.server 指定为网站集的网址,例如 http://sharepoint.example.com/sites/sitecollection

  • 如果网站集的网址为根网站集(例如 http://sharepoint.example.com),则应明确设置 sharepoint.siteCollectionOnly=true

仅限网站集模式中的非规范网址

SharePoint On-Prem 连接器允许在仅限网站集模式下存在非规范网址。也就是说,由 connector-config.properties 文件中的 sharepoint.server 配置选项指定的连接器网址不必与 SharePoint 完全相同。

替换 Microsoft Outlook .msg 文件的内容类型

如果连接器在抓取内容时遇到 Outlook .msg 文件,它会替换此类文件的内容类型并以 application/vnd.ms-outlook 形式将此类文件编入索引。