在配置连接器之前，你必须在 SharePoint Online 平台中创建一个 OAuth 应用程序。你的连接器将以注册的 OAuth 应用程序/客户端的身份验证到 SharePoint。在此过程中，你将收集值（客户端 ID、租户 ID 和 客户端密钥），这些值在你需要在 Kibana 中执行配置步骤时使用。

要开始，请首先登录到 SharePoint Online 并访问你的管理仪表板。请确保你以 Azure 门户 服务帐户的身份登录。

请按照以下步骤操作

登录到 https://portal.azure.com/ 并单击Azure Active Directory。
找到 应用注册，然后单击新注册。
为你的应用命名，例如“搜索”。
暂时将重定向 URI留空。
注册该应用程序。
找到并保留 应用程序（客户端）ID 和 目录（租户）ID 以便使用。
通过导航到客户端凭据：证书和密钥来查找密钥。
选择新建客户端密钥
为你的客户端密钥选择一个名称。选择一个过期日期。（在此过期日期，你将需要生成一个新密钥并更新你的连接器配置。）
- 在离开此屏幕之前，保存客户端密钥密钥 ID。
- 在离开此屏幕之前，保存客户端密钥值。
设置 OAuth 应用程序将从 Azure 门户服务帐户请求的权限。
- 导航到API 权限，然后单击添加权限。
- 添加应用程序权限，直到列表如下所示
```
Graph API
- Sites.Selected
- Files.Read.All
- Group.Read.All
- User.Read.All

Sharepoint
- Sites.Selected
```
  如果 站点逗号分隔列表 配置设置为 *，或者用户启用切换按钮 枚举所有站点，则连接器需要 Sites.Read.All 权限。
使用权限屏幕中的 授予管理员同意 链接授予管理员同意。
保存 Azure 平台的租户名称（即域名）。

连接器需要应用程序权限。它不支持委派的权限（范围）。

连接器在可能的情况下使用 Graph API（稳定的 v1.0 API）从 Sharepoint Online 获取数据。当实体无法通过 Graph API 获取时，连接器会回退到使用 Sharepoint REST API。

SharePoint 权限

编辑

有关设置 SharePoint 权限，请参阅以下文档。

要将 DisableCustomAppAuthentication 设置为 false，请使用 PowerShell 连接到 SharePoint 并运行 set-spotenant -DisableCustomAppAuthentication $false
要在 SharePoint Online 中为租户分配完全权限，请在浏览器中转到租户 URL。URL 遵循以下模式：https://<office_365_admin_tenant_URL>/_layouts/15/appinv.aspx。这将加载 SharePoint 管理中心页面。
- 在 应用程序 ID 框中，输入你之前记录的应用程序 ID，然后单击查找。应用程序名称将显示在标题框中。
- 在应用程序域框中，键入 <tenant_name>.onmicrosoft.com
- 在 应用程序的权限请求 XML 框中，键入以下 XML 字符串
```
<AppPermissionRequests AllowAppOnlyPolicy="true">
<AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
<AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />
</AppPermissionRequests>
```

Graph API 权限

Microsoft 建议对 SharePoint Online 的所有操作使用 Graph API。Graph API 有完善的文档，并且在获取数据方面效率更高，这有助于避免限制。有关详细信息，请参阅 Microsoft 的限制策略。

以下是我们使用这些 Graph API 权限的原因摘要

Sites.Selected 用于获取站点及其元数据
Files.Read.All 用于获取站点驱动器和这些驱动器中的文件
Groups.Read.All 用于获取文档级权限的组
User.Read.All 用于获取文档级权限的用户信息

由于 Graph API 的设计方式，这些权限是“全部或全无”的 - 目前无法限制对这些资源的访问。

兼容性

编辑

此连接器与 SharePoint Online 兼容。

配置

编辑

使用以下配置字段来设置连接器

租户 ID

托管 Sharepoint Online 实例的 Azure 帐户的租户 ID。

租户名称

托管 Sharepoint Online 实例的 Azure 帐户的租户名称。

客户端 ID

用于使用 SharePoint Online 进行身份验证的客户端 ID。

密钥值

用于使用 SharePoint Online 进行身份验证的密钥值。

站点逗号分隔列表

要从 SharePoint 获取的站点集名称或路径列表。枚举所有站点时，这些值应为站点的名称。使用 * 来包括所有可用站点。示例

collection1
collection1,sub-collection
*

当不枚举所有站点时，这些值应为站点的路径（/sites/ 之后的 URL）。示例
collection1
collection1,collection1/sub-collection

枚举所有站点？

如果启用，则将从 API 中批量获取所有站点的完整列表，并对其进行筛选以匹配配置的站点名称列表。如果禁用，则将从 API 中单独获取配置的站点路径列表中的每个路径。禁用时，* 不是 站点逗号分隔列表的有效配置。在同步大量（超过总数的 200 个）站点时，启用此配置最有用。这是因为，在高容量时，批量获取站点效率更高。在同步较少站点时，禁用此配置可以提高性能。这是因为，在低容量时，仅获取你需要的站点效率更高。

获取已配置站点的子站点？

是否应自动获取已配置站点的子站点。仅当不枚举所有站点时，此选项才可用（请参阅上文）。

启用文档级安全性

切换以启用文档级安全性 (DLS)。启用后，完全和增量同步将获取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。访问控制同步将获取用户的访问控制列表，并将其存储在单独的索引中。

启用后，以下精细权限切换将可用

获取驱动器项目权限：启用此选项以获取特定于驱动器项目的权限。
获取唯一页面权限：启用此选项以获取唯一页面权限。如果禁用此设置，页面将从其父站点继承权限。
获取唯一列表权限：启用此选项以获取唯一列表权限。如果禁用此设置，列表将从其父站点继承权限。
获取唯一列表项权限：启用此选项以获取唯一列表项权限。如果禁用此设置，列表项将从其父站点继承权限。

如果留空，则这些精细权限切换将使用默认值 true。请注意，这些设置可能会增加同步时间。

文档和同步

编辑

连接器同步以下 SharePoint 对象类型

站点（和子站点）
列表
列表项和附件内容
文档库和附件内容（包括网页）

不会提取大于 10 MB 的文件的内容。（自管理连接器可以使用自管理本地提取服务来处理更大的二进制文件。）
默认情况下，权限不会同步。启用文档级安全 (DLS)以同步权限。

使 SharePoint 网站页面 Web 部件内容可搜索

如果您在 SharePoint 网站页面上使用 Web 部件，并希望使此内容可搜索，则需要查阅官方文档。

我们建议对于所有需要可搜索的 Web 部件，将 isHtmlString 设置为True。

限制

编辑

该连接器目前不从连接到 Teams 的站点同步内容。

同步规则

编辑

基本同步规则对于所有连接器都是相同的，并且默认可用。有关更多信息，请阅读同步规则类型。

高级同步规则

编辑

需要完全同步才能使高级同步规则生效。

以下部分介绍了此连接器的高级同步规则。高级同步规则通过特定于源的 DSL JSON 片段定义。

SharePoint Online 连接器的高级规则使您可以避免提取和同步可能不再与搜索相关的旧数据。

示例

{
	"skipExtractingDriveItemsOlderThan": 60
}

此规则将不会提取任何 60 天或更长时间未修改的驱动器项目（文档库中的文件）的内容。

增量同步的同步规则的限制

在使用增量同步时，在 SharePoint Online 内容已索引后更改同步规则可能会带来意外结果。

增量同步确保来自第三方系统的更新，但不会修改索引中的现有文档。

为避免这些问题，请在更改同步规则（基本或高级）后运行完全同步。

让我们看看几个示例，其中增量同步可能会导致索引上的数据不一致。

示例：在完全同步后添加了限制性基本同步规则

假设您的 SharePoint Online 驱动器包含以下驱动器项目

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

同步后，所有这些驱动器项目都将存储在您的 Elasticsearch 索引中。让我们添加一个基本同步规则，按路径过滤文件

Exclude WHERE path CONTAINS "Documents"

这些过滤规则将排除路径中带有“Documents”的所有文件，只留下 /Presentations 目录中的文件

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

如果没有更改文件，增量同步将不会收到来自 SharePoint Online 的更改信息，并且无法删除任何文件，从而使索引保持与同步之前相同的状态。

在完全同步之后，索引将更新，并且将删除被同步规则排除的文件。

示例：在完全同步后删除了限制性基本同步规则

假设 SharePoint Online 驱动器具有以下驱动器项目

/Documents/Report.doc
/Documents/Spreadsheet.xls
/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls
/Personal/Documents/Sales.xls

在进行同步之前，我们添加一个限制性的基本过滤规则

Exclude WHERE path CONTAINS "Documents"

在完全同步后，索引将仅包含 /Presentations 目录中的文件

/Presentations/Q4-2020-Report.pdf
/Presentations/Q4-2020-Report-Data.xls

之后，我们可以删除过滤规则并运行增量同步。如果文件没有发生任何更改，增量同步将不会在 Elasticsearch 索引中反映这些更改，因为 SharePoint Online 不会报告对项目的任何更改。只有完全同步才会包含之前被同步规则忽略的项目。

示例：高级同步规则的极端情况

可以应用高级同步规则来限制将提取内容的文档。例如，可以设置一个规则，使 180 天之前的文档不会提取内容。

但是，存在一种极端情况。假设一个文档有 179 天的历史，它的内容被提取并索引到 Elasticsearch 中。2 天后，该文档将有 181 天的历史。由于该文档已被提取，因此它不会被修改。因此，按照增量同步，内容不会从索引中删除。

在这种情况下，如果您希望删除旧文档，则需要手动清理索引。例如，您可以手动运行一个 Elasticsearch 查询，删除早于 180 天的驱动器项目内容

resp = client.update_by_query(
    index="INDEX_NAME",
    conflicts="proceed",
    query={
        "bool": {
            "filter": [
                {
                    "match": {
                        "object_type": "drive_item"
                    }
                },
                {
                    "exists": {
                        "field": "file"
                    }
                },
                {
                    "range": {
                        "lastModifiedDateTime": {
                            "lte": "now-180d"
                        }
                    }
                }
            ]
        }
    },
    script={
        "source": "ctx._source.body = ''",
        "lang": "painless"
    },
)
print(resp)

const response = await client.updateByQuery({
  index: "INDEX_NAME",
  conflicts: "proceed",
  query: {
    bool: {
      filter: [
        {
          match: {
            object_type: "drive_item",
          },
        },
        {
          exists: {
            field: "file",
          },
        },
        {
          range: {
            lastModifiedDateTime: {
              lte: "now-180d",
            },
          },
        },
      ],
    },
  },
  script: {
    source: "ctx._source.body = ''",
    lang: "painless",
  },
});
console.log(response);

POST INDEX_NAME/_update_by_query?conflicts=proceed
{
  "query": {
    "bool": {
      "filter": [
        {
          "match": {
            "object_type": "drive_item"
          }
        },
        {
          "exists": {
            "field": "file"
          }
        },
        {
          "range": {
            "lastModifiedDateTime": {
              "lte": "now-180d"
            }
          }
        }
      ]
    }
  },
  "script": {
    "source": "ctx._source.body = ''",
    "lang": "painless"
  }
}

文档级安全

编辑

文档级安全 (DLS) 使您可以根据用户的权限限制对文档的访问。此功能对于此连接器默认可用。

请参阅此页面上的配置，了解如何为此连接器启用 DLS。

请参阅搜索应用程序中的 DLS，了解在构建搜索应用程序时，如何在启用 DLS 的情况下从 SharePoint Online 提取数据。

内容提取

编辑

默认内容提取

编辑

默认内容提取服务由企业搜索默认提取管道提供支持。（请参阅搜索索引的提取管道。）

请参阅内容提取。

本地内容提取（对于大文件）

编辑

SharePoint Online 自管理连接器支持大文件内容提取（> 100MB）。这需要

Elastic Text Extraction Service 的自管理部署。
在默认提取管道设置中，文本提取必须禁用。

有关更多信息，请参阅本地内容提取。

已知问题

编辑

由于 SharePoint 文件和文件夹限制导致同步失败的文档

SharePoint 对可以同步的文件和文件夹数量有限制。您可能会遇到以下错误，该错误写入到未能同步的文档正文中：文件大小超过允许的限制。CorrelationId: fdb36977-7cb8-4739-992f-49878ada6686, UTC DateTime: 4/21/2022 11:24:22 PM

有关这些限制的更多信息，请参阅SharePoint 文档。
- 同步大量文件
  
  连接器将无法从包含 5000 多个文件的文件夹中下载文件。列表视图阈值（默认为 5000）是一个限制，用于防止对 SharePoint Online 环境产生高性能影响的操作。
  
  解决方法： 减小批处理大小以避免此问题。
- 同步大文件
  
  SharePoint 有文件大小限制，但是这些限制是可配置的。
  
  解决方法： 增大文件大小限制。有关更多信息，请参阅SharePoint 文档。
- 在增量同步期间，删除的文档计数器不会更新
  
  如果启用了配置 Enumerate All Sites?，则增量同步可能无法按预期工作。在增量同步之间删除的驱动器项目文档可能不会被检测为已删除。
  
  解决方法：禁用 Enumerate All Sites?，并为所有所需的站点配置完整站点路径。

有关所有连接器的已知问题列表，请参阅已知问题。

故障排除

编辑

请参阅故障排除。

安全

编辑

请参阅安全。

自管理连接器

编辑

查看自管理连接器参考

可用性和先决条件

编辑

此连接器可用作自管理的自管理连接器。要将此连接器用作自管理连接器，请满足所有自管理连接器要求。

此连接器需要订阅。请在 Elastic Stack 订阅页面的 Elastic Search 部分下查看此功能的要求。

使用

编辑

要将此连接器用作自管理连接器，请参阅自管理连接器。有关其他操作，请参阅Kibana 中的连接器 UI。

SharePoint 先决条件

编辑

创建 SharePoint OAuth 应用

编辑

在配置连接器之前，您必须在 SharePoint Online 平台中创建一个OAuth 应用。您的连接器将以注册的 OAuth 应用程序/客户端的身份向 SharePoint 进行身份验证。在此过程中，您将收集一些值（客户端 ID、租户 ID 和 客户端密钥），这些值在 Kibana 中的配置步骤中需要用到。

要开始，请首先登录到 SharePoint Online 并访问你的管理仪表板。请确保你以 Azure 门户 服务帐户的身份登录。

请按照以下步骤操作

登录到 https://portal.azure.com/ 并单击Azure Active Directory。
找到 应用注册，然后单击新注册。
为你的应用命名，例如“搜索”。
暂时将重定向 URI留空。
注册该应用程序。
找到并保留 应用程序（客户端）ID 和 目录（租户）ID 以便使用。
通过导航到客户端凭据：证书和密钥来查找密钥。
选择新建客户端密钥
为你的客户端密钥选择一个名称。选择一个过期日期。（在此过期日期，你将需要生成一个新密钥并更新你的连接器配置。）
- 在离开此屏幕之前，保存客户端密钥密钥 ID。
- 在离开此屏幕之前，保存客户端密钥值。
设置 OAuth 应用程序将从 Azure 门户服务帐户请求的权限。
- 导航到API 权限，然后单击添加权限。
- 添加应用程序权限，直到列表如下所示
```
Graph API
- Sites.Selected
- Files.Read.All
- Group.Read.All
- User.Read.All

Sharepoint
- Sites.Selected
```
  如果 站点逗号分隔列表 配置设置为 *，或者用户启用切换按钮 枚举所有站点，则连接器需要 Sites.Read.All 权限。
使用权限屏幕中的 授予管理员同意 链接授予管理员同意。
保存 Azure 平台的租户名称（即域名）。

连接器需要应用程序权限。它不支持委派的权限（范围）。

SharePoint 权限

编辑

有关设置 SharePoint 权限，请参阅以下文档。

要将 DisableCustomAppAuthentication 设置为 false，请使用 PowerShell 连接到 SharePoint 并运行 set-spotenant -DisableCustomAppAuthentication $false
要在 SharePoint Online 中为租户分配完全权限，请在浏览器中转到租户 URL。URL 遵循以下模式：https://<office_365_admin_tenant_URL>/_layouts/15/appinv.aspx。这将加载 SharePoint 管理中心页面。
- 在 应用程序 ID 框中，输入你之前记录的应用程序 ID，然后单击查找。应用程序名称将显示在标题框中。
- 在应用程序域框中，键入 <tenant_name>.onmicrosoft.com
- 在 应用程序的权限请求 XML 框中，键入以下 XML 字符串
```
<AppPermissionRequests AllowAppOnlyPolicy="true">
<AppPermissionRequest Scope="http://sharepoint/content/tenant" Right="FullControl" />
<AppPermissionRequest Scope="http://sharepoint/social/tenant" Right="Read" />
</AppPermissionRequests>
```

Graph API 权限

以下是我们使用这些 Graph API 权限的原因摘要

Sites.Selected 用于获取站点及其元数据
Files.Read.All 用于获取站点驱动器和这些驱动器中的文件
Groups.Read.All 用于获取文档级权限的组
User.Read.All 用于获取文档级权限的用户信息

由于 Graph API 的设计方式，这些权限是“全部或全无”的 - 目前无法限制对这些资源的访问。

兼容性

编辑

此连接器与 SharePoint Online 兼容。

配置

编辑

当使用自托管连接器工作流程时，这些字段最初将使用连接器源代码中设置的默认配置。这些配置在 get_default_configuration 函数定义中设置。

这些可配置的字段将在 Kibana UI 中以各自的标签呈现。连接后，您可以在 Kibana 中更新这些值。

使用以下配置字段来设置连接器

tenant_id

托管 Sharepoint Online 实例的 Azure 帐户的租户 ID。

tenant_name

托管 Sharepoint Online 实例的 Azure 帐户的租户名称。

client_id

用于使用 SharePoint Online 进行身份验证的客户端 ID。

secret_value

用于使用 SharePoint Online 进行身份验证的密钥值。

site_collections

要从 SharePoint 获取的站点集名称或路径列表。枚举所有站点时，这些值应为站点的名称。使用 * 来包括所有可用站点。示例

collection1
collection1,sub-collection
*

当不枚举所有站点时，这些值应为站点的路径（/sites/ 之后的 URL）。示例
collection1
collection1,collection1/sub-collection

enumerate_all_sites

如果启用，将从 API 中批量获取所有站点的完整列表，并将其过滤以匹配配置的站点名称列表。如果禁用，将从 API 中单独获取配置的站点路径列表中的每个路径。当同步大量站点（超过 total/200）时，启用此配置最有用。这是因为，在高容量下，批量获取站点更有效。当同步较少站点时，禁用此配置可以提高性能。这是因为，在低容量下，仅获取您需要的站点更有效。

禁用时，* 不是 站点列表（逗号分隔）的有效配置。

fetch_subsites

是否应自动获取已配置站点的子站点。仅当不枚举所有站点时，此选项才可用（请参阅上文）。

use_text_extraction_service

切换以启用文档的本地文本提取服务。需要单独部署Elastic 文本提取服务。需要摄取管道设置禁用文本提取。默认值为 False。

use_document_level_security

启用后，以下精细权限切换将可用

获取驱动器项目权限：启用此选项以获取特定于驱动器项目的权限。
获取唯一页面权限：启用此选项以获取唯一页面权限。如果禁用此设置，页面将从其父站点继承权限。
获取唯一列表权限：启用此选项以获取唯一列表权限。如果禁用此设置，列表将从其父站点继承权限。
获取唯一列表项权限：启用此选项以获取唯一列表项权限。如果禁用此设置，列表项将从其父站点继承权限。

如果留空，则这些精细权限切换将使用默认值 true。请注意，这些设置可能会增加同步时间。

使用 Docker 部署

编辑

您可以使用 Docker 将 SharePoint Online 连接器部署为自托管连接器。请按照以下说明进行操作。

步骤 1：下载示例配置文件

下载示例配置文件。您可以手动下载，也可以运行以下命令

curl https://raw.githubusercontent.com/elastic/connectors/main/config.yml.example --output ~/connectors-config/config.yml

如果您的目录名称不同，或者您想使用不同的配置文件名，请记得更新 --output 参数值。

步骤 2：更新自托管连接器的配置文件

更新配置文件，使其包含以下与您的环境匹配的设置

elasticsearch.host
elasticsearch.api_key
connectors

如果您针对 Docker 化的 Elasticsearch 和 Kibana 版本运行连接器服务，您的配置文件将如下所示

# When connecting to your cloud deployment you should edit the host value
elasticsearch.host: http://host.docker.internal:9200
elasticsearch.api_key: <ELASTICSEARCH_API_KEY>

connectors:
  -
    connector_id: <CONNECTOR_ID_FROM_KIBANA>
    service_type: sharepoint_online
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

推荐使用 elasticsearch.api_key 作为身份验证方法。但是，您也可以使用 elasticsearch.username 和 elasticsearch.password 来向您的 Elasticsearch 实例进行身份验证。

注意：您可以通过简单地取消注释配置文件中的特定设置并修改其值来更改其他默认配置。

步骤 3：运行 Docker 镜像

使用以下命令使用连接器服务运行 Docker 镜像

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/enterprise-search/elastic-connectors:8.17.0.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

有关更多详细信息，请参阅 elastic/connectors 仓库中的 DOCKER.md。

在官方注册表中查找所有可用的 Docker 镜像。

我们还提供了一个使用 Docker Compose 的快速启动自托管选项，因此您可以一次启动所有必需的服务：Elasticsearch、Kibana 和连接器服务。有关更多信息，请参阅 elastic/connectors 仓库中的此 README。