部署 Microsoft SharePoint Online 连接器

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

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

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

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

Google Cloud Search SharePoint Online 连接器概览

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

配置属性文件

要让连接器能够在 SharePoint Online 中查找内容并将内容上传到用于编制索引的 API,连接器管理员必须按照部署步骤中所述的步骤创建一个配置文件,以将设置提供给 SharePoint Online 连接器。

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

支持的操作系统

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

将未发布的文档编入索引

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

支持的身份验证机制

Cloud Search SharePoint Online 连接器支持实时身份验证。

已知的连接器限制

  • 连接器实例只能将单个网站集中的内容编入索引。 您需要分别使用多个连接器实例才能将多个网站集中的内容编入索引。
  • 在每个网站集的 ACL 中使用的唯一身份用户和群组的数量将影响内存消耗。
  • 当前版本的连接器不会生成即时删除通知。
  • 连接器依赖于将内容重新编入索引来识别源代码库中删除的内容。对于以前编入索引的内容,删除检测延迟时间可能超过 4 小时。

前提条件

Google Cloud Search SharePoint Online 连接器可以安装在 Linux 或 Windows 上。在部署 Google Cloud Search SharePoint Online 连接器之前,请确保您拥有以下必备组件:

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

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

  • 连接器的用户帐号。此帐号必须具有网站集管理员权限。

部署步骤

要部署 Google Cloud Search SharePoint Online 连接器,请按照以下步骤操作:

  1. 安装 Google Cloud Search SharePoint Online 连接器软件。
  2. 指定 SharePoint Online 连接器配置
  3. 配置对 Google Cloud Search 数据源的访问权限
  4. 配置对 SharePoint Online 的访问权限
  5. 配置 SharePoint 与 Google Cloud Search 的身份映射
  6. 配置对 SharePoint 列表项的 HTML 内容生成和结构化数据支持。
  7. 配置 O365 与 Google Cloud Search 的身份映射
  8. 启用日志记录

1. 安装 Google Cloud Search SharePoint Online 连接器软件

  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 Online 连接器配置

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

  • 对数据源的访问权限
  • 对 SharePoint Online 的访问权限

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

  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 SharePoint Online 连接器所需的 Google Cloud Search 服务帐号密钥文件。
身份源 ID api.identitySourceId=x0987654321
必需。由 G Suite 管理员设置的 Cloud Search 身份源 ID。

4. 配置对 SharePoint Online 的访问权限

要让连接器能够访问 SharePoint Online 并从中提取数据以编入索引,您必须先配置对 SharePoint Online 的访问权限。请使用以下参数将访问权限信息添加到配置文件中。

设置 参数
SharePoint 网站集的完全限定域名 sharepoint.server=http://yoursharepoint.example.com/
必需。如果域名不是完全限定的,您必须在连接器主机上设置 DNS 替换值。
仅限网站集模式 sharepoint.siteCollectionOnly=true
必需。对于 SharePoint Online,请始终将此参数设置为 true。
SharePoint 用户名 sharepoint.username=username
必需。用于访问 SharePoint Online 的帐号的用户名。
SharePoint 密码 sharepoint.password=user_password
必需。用于访问 SharePoint Online 的帐号的密码。
身份验证模式 sharepoint.formsAuthenticationMode=LIVE
必需。对于 SharePoint Online,请将此参数设置为 LIVE。
部署类型 sharepoint.deploymentType=ONLINE
必需。对于 SharePoint Online,请将此参数设置为 ONLINE。

5. 配置 SharePoint 与 Google Cloud Search 的身份映射

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

SharePoint Online 连接器支持以下身份:

  • Office 365 / Azure AD 用户
  • Office 365 / Azure AD 安全群组
  • SharePoint 本地群组(成员包括 O365 用户和群组)

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

  • 使用 SharePoint 身份连接器同步 SharePoint 本地群组。
  • 使用 O365 身份连接器同步 O365 身份。

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

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

必需。由 G Suite 管理员设置的 Google Cloud Search 源 ID,如添加要搜索的数据源中所述。

引用身份源 api.referenceIdentitySources=defaultIdentitySource
必需。对于 SharePoint Online,请使用固定值 defaultIdentitySource。
引用身份源 ID api.referenceIdentitySource.defaultIdentitySource.id=112233abcd
必需。用于同步 O365 身份的身份源 ID。

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

要将 SharePoint 列表项的其他元数据编入索引,请配置连接器以支持 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。如果设置为 IGNORE,则连接器仅使用映射列生成 HTML。 要在生成的 HTML 内容中包含未映射的字段(不属于高、中、低配置),请将此参数设置为 APPEND。

结构化数据支持

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

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

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

  • 连接器将 SharePoint 属性名称映射到属性定义。

7. 配置 O365 与 Google Cloud Search 的身份映射

要根据 O365 身份为 SharePoint 内容应用适当的安全调整,您需要配置与 SharePoint Online 连接器软件包捆绑的 O365 身份连接器。

构建 Office 365 身份连接器

如果尚未安装 SDK,请将 SDK 安装到本地 Maven 代码库中:

  1. 从 GitHub 克隆 SDK 代码库。

    $ git clone https://github.com/google-cloudsearch/connector-sdk.git
        $ cd connector-sdk
  2. 获取所需的 SDK 版本:

    git checkout tags/v1-0.0.3
        
  3. 安装 SDK 组件:

    mvn install
        

构建连接器:

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

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

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

    mvn package
        

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

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

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

获取 O365 凭据

要使用 O365 身份连接器,您必须为其设置凭据,以从 O365 帐号读取用户和群组。

请参照 Microsoft 的说明创建 Azure Active Directory 应用,以支持 O365 身份连接。在设置该应用时,请执行以下操作:

  1. 为该应用指定一个描述性的名称,例如“gcs-o365-identity-connector”。
  2. 添加权限。该应用需要“Group.Read.All”和“User.Read.All”权限。
  3. 请记录好以下信息,以在下一步中使用:
    • 应用 ID
    • 租户
    • 客户端密钥

连接器配置

设置 参数
身份源 ID api.identitySourceId=1234567890abcdef
必需。用于同步 O365 身份的身份源 ID。

由 G Suite 管理员设置的 Google Cloud Search 源 ID,如添加要搜索的数据源中所述。 此值应与 SharePoint Online 连接器中的“defaultIdentitySource”配置匹配。

Google 客户 ID api.customerId=c1b1d1e1
必需。与您的 Google 网域相关联的客户 ID。

要获取客户 ID,请按照此处的说明操作。

O365 应用 ID o365.clientId=a63c6eb3-29e7-486

必需。O365 应用设置的应用 ID。

O365 租户 o365.tenant=185ef9ed-29e7-486

必需。您的 O365 帐号的租户。

O365 客户端密钥 o365.clientSecret=raHJN15vRLBKs

必需。来自 O365 应用设置的凭据密钥。

连接器日志

在包含连接器二进制文件的同一目录中创建一个名为 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 O365 APIs
    #com.google.enterprise.cloudsearch.o365.level=FINE

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

运行 O365 身份连接器

如需运行连接器,请输入以下命令:

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

8. 启用日志记录

在包含连接器二进制文件的同一目录中创建一个名为 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
    

示例:配置文件

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

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

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

    sharepoint.server=https://mydomain.onmicrosoft.com
    sharepoint.siteCollectionOnly=true
    sharepoint.username=admin@mydomain.onmicrosoft.com
    sharepoint.password=pa$sw0rd
    sharepoint.formsAuthenticationMode=LIVE
    sharepoint.deploymentType=ONLINE

    api.referenceIdentitySources=defaultIdentitySource
    api.referenceIdentitySource.defaultIdentitySource.id=08ef8becd116faa5d3783f8c5a80e5aa
    

运行 SharePoint Online 身份连接器

要让用户能够在 Cloud Search 搜索用户有权访问的 SharePoint 内容以后获取结果,您必须首先将 O365 和 SharePoint 网站集中的主帐号映射到 Google Cloud Identity 服务中的身份。此同步操作通过 O365 身份连接器和 SharePoint Online 身份连接器完成。在 O365 连接器同步用户和群组后,请运行 SharePoint Online 身份连接器(如下所述)以同步 SharePoint 网站集群组。

身份连接器使用一个类似于将内容编入索引的配置文件。下面给出了一个示例:

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

    sharepoint.server=https://mydomain.onmicrosoft.com
    sharepoint.siteCollectionOnly=true
    sharepoint.username=admin@mydomain.onmicrosoft.com
    sharepoint.password=pa$sw0rd
    sharepoint.formsAuthenticationMode=LIVE
    sharepoint.deploymentType=ONLINE

    api.referenceIdentitySources=defaultIdentitySource
    api.referenceIdentitySource.defaultIdentitySource.id=08ef8becd116faa5d3783f8c5a80e5aa
    

请注意,上述示例添加了 api.customerId 属性。要获取 customerId,请按照此处的说明操作。

用于将内容编入索引的 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 Online 连接器

如需运行 SharePoint Online 连接器,请输入以下命令:

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

高级主题

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

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

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