PUT _connector/my-azure_blob_storage-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Azure Blob Storage",
  "service_type": "azure_blob_storage",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

配置

edit

以下配置字段是设置连接器所必需的：

Account name: Azure Blob 存储账户的名称。
Account key: 账户密钥用于Azure Blob存储账户。
Blob endpoint: Blob 服务的端点。
Containers: 要索引的容器列表。 * 将索引所有容器。

文档和同步

edit

连接器将获取容器中所有可用的数据。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。 所有文档索引到Elastic部署后将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

内容提取

edit

参见内容提取。

已知问题

edit

此连接器存在以下已知问题：

lease data 和 tier 字段不会在 Elasticsearch 索引中更新

这是因为blob时间戳没有更新。请参阅Github问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.6.0+。要使用此连接器，请满足所有自托管连接器要求。

要创建一个新的 Azure Blob 存储连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Azure Blob 存储 自管理连接器。

使用 API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理的 Azure Blob Storage 自管理连接器。

例如：

PUT _connector/my-azure_blob_storage-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Azure Blob Storage",
  "service_type": "azure_blob_storage"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

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

配置

edit

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

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

以下配置字段是设置连接器所必需的：

account_name: Azure Blob 存储账户的名称。
account_key: 账户密钥用于Azure Blob存储账户。
blob_endpoint: Blob 服务的端点。
containers: 要索引的容器列表。 * 将索引所有容器。
retry_count: 失败调用后的重试次数。默认值是 3。
concurrent_downloads: 获取内容的并发下载数量。默认值是 100。
use_text_extraction_service: 需要单独部署Elastic 文本提取服务。需要确保摄取管道设置禁用文本提取。默认值为 False。

使用 Docker 部署

edit

您可以使用 Docker 将 Azure Blob 存储连接器部署为自托管连接器。请按照以下说明操作。

步骤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: azure_blob_storage
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

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

文档和同步

edit

连接器将获取容器中所有可用的数据。

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。 所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

内容提取

edit

参见内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 Azure Blob 存储连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=azure_blob_storage

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=azure_blob_storage DATA_SIZE=small

已知问题

edit

此连接器存在以下已知问题：

lease data 和 tier 字段不会在 Elasticsearch 索引中更新

这是因为 blob 时间戳没有更新。请参阅 Github issue。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Box 连接器参考

edit

Th Box 连接器是使用 Elastic 连接器框架用 Python 编写的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器自 Elastic 版本 8.14.0 起作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

此连接器处于技术预览阶段，可能会发生变化。设计和代码不如正式的GA功能成熟，并且是按原样提供的，不提供任何保证。技术预览功能不受正式GA功能支持SLA的约束。

创建一个Box连接器

edit

使用界面

edit

要创建一个新的 Box 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的本地 Box 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的本地 Box 连接器。

例如：

PUT _connector/my-box-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Box",
  "service_type": "box",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请从连接器列表中选择Box图块，或使用自定义连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

Box API 授权

edit

Box 免费账户

edit

======= 创建 Box 用户认证（OAuth 2.0）自定义应用

您需要按照以下步骤在Box开发者控制台中创建一个OAuth应用：

在Box开发者控制台中注册一个新应用，选择自定义应用并选择用户身份验证（OAuth 2.0）。
在重定向URI中添加您可以访问的网页URL。
在应用程序范围中勾选“写入存储在Box中的所有文件和文件夹”。
应用创建后，客户端ID和客户端密钥值将在配置选项卡中可用。请妥善保管这些信息。

======= 生成一个刷新令牌

要生成刷新令牌，请按照以下步骤操作：

转到以下URL，将替换为之前保存的客户端ID值。例如：

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=

授予对您的应用程序的访问权限。
您现在将被重定向到您在重定向URI中配置的网页，并且HTTP响应应包含一个授权码，您将使用它来生成刷新令牌。 注意：用于生成刷新令牌的授权码只能使用一次，并且仅在30秒内有效。

在您的终端中，运行以下 curl 命令，将、 和 替换为您之前保存的值：

curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=" \
     -d "client_secret=" \
     -d "code=" \
     -d "grant_type=authorization_code"

保存响应中的刷新令牌。您将需要这个来进行连接器配置。

Box 企业账户

edit

======= 创建 Box 服务器认证（客户端凭证授予）自定义应用

在 Box 开发者控制台中注册一个新应用，选择自定义应用并选择服务器身份验证（客户端凭据授予）。
检查以下权限：
- "写入 Box 中存储的所有文件和文件夹" 在应用程序范围中
- "使用 as-user 标头进行 API 调用" 在高级功能中
在应用访问级别中选择 App + Enterprise Access。
从管理控制台授权您的应用程序。保存 客户端凭据 和 企业 ID。您需要这些来配置连接器。

配置

edit

Box Account (required): 下拉菜单以确定Box账户类型：Box免费账户或Box企业账户。默认值是Box免费账户。
Client ID (required): 用于与 Box 实例进行身份验证的客户端 ID。
Client Secret (required): 用于与 Box 实例进行身份验证的客户端密钥。
Refresh Token (required if Box Account is Box Free): 用于生成访问令牌的刷新令牌。 注意： 如果进程终止，您需要生成一个新的刷新令牌。
Enterprise ID (required if Box Account is Box Enterprise): 用于与 Box 实例进行身份验证的企业 ID。

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

文件
文件夹

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自管理连接器的形式提供。要使用此连接器，请满足所有自管理连接器先决条件。

创建一个Box连接器

edit

使用界面

edit

要创建一个新的 Box 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Box 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自管理 Box 自管理连接器。

例如：

PUT _connector/my-box-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Box",
  "service_type": "box"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请从连接器列表中选择Box图块，或使用自定义连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

Box API 授权

edit

免费账户

edit

======= 创建 Box 用户认证（OAuth 2.0）自定义应用

您需要按照以下步骤在Box开发者控制台中创建一个OAuth应用：

在Box开发者控制台中注册一个新应用，选择自定义应用并选择用户身份验证（OAuth 2.0）。
在重定向URI中添加您可以访问的网页URL。
在应用程序范围中勾选“写入Box中存储的所有文件和文件夹”。
应用创建后，客户端ID和客户端密钥值将在配置选项卡中可用。请妥善保管这些信息。

======= 生成一个刷新令牌

要生成刷新令牌，请按照以下步骤操作：

转到以下URL，将替换为之前保存的客户端ID值。例如：

https://account.box.com/api/oauth2/authorize?response_type=code&client_id=

授予对您的应用程序的访问权限。
您现在将被重定向到您在重定向URI中配置的网页，并且HTTP响应应包含一个授权码，您将使用它来生成刷新令牌。 注意：用于生成刷新令牌的授权码只能使用一次，并且仅在30秒内有效。

在您的终端中，运行以下 curl 命令，将、 和 替换为您之前保存的值：

curl -i -X POST "https://api.box.com/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "client_id=" \
     -d "client_secret=" \
     -d "code=" \
     -d "grant_type=authorization_code"

保存响应中的刷新令牌。您将需要这个来进行连接器配置。

Box 企业账户

edit

======= 创建 Box 服务器认证（客户端凭证授予）自定义应用

在 Box 开发者控制台中注册一个新应用，选择自定义应用并选择服务器身份验证（客户端凭据授予）。
检查以下权限：
- "写入 Box 中存储的所有文件和文件夹" 在应用范围中
- "使用 as-user 标头进行 API 调用" 在高级功能中
在应用访问级别中选择 App + Enterprise Access。
从管理控制台授权您的应用程序。保存 客户端凭据 和 企业 ID。您需要这些来配置连接器。

配置

edit

Box Account (required): 下拉菜单以确定Box账户类型：Box免费账户或Box企业账户。默认值是Box免费账户。
Client ID (required): 用于与 Box 实例进行身份验证的客户端 ID。
Client Secret (required): 用于与 Box 实例进行身份验证的客户端密钥。
Refresh Token (required if Box Account is Box Free): 用于生成访问令牌的刷新令牌。 注意： 如果进程终止，您需要生成一个新的刷新令牌。
Enterprise ID (required if Box Account is Box Enterprise): 用于与 Box 实例进行身份验证的企业 ID。

使用 Docker 部署

edit

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

步骤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: box
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

文件
文件夹

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为Box连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=box

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=box DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Confluence 连接器参考

edit

The Elastic Confluence connector 是一个用于 connector for Atlassian Confluence。这个连接器是用 Python 编写的，使用了 Elastic connector framework。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器自 8.9.1 版本起，在 Elastic Cloud 上作为 托管连接器 提供。

Confluence Data Center 支持在 8.13.0 中以技术预览版形式添加，并可能会有所变化。其设计和代码的成熟度低于正式发布的功能，并且是按原样提供，不提供任何保证。技术预览功能不受正式发布功能的 SLA 支持。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个Confluence连接器

edit

使用用户界面

edit

要创建一个新的Confluence连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Confluence 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Confluence 连接器。

例如：

PUT _connector/my-confluence-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Confluence",
  "service_type": "confluence",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

Confluence Cloud 或 Confluence Server/Data Center 7 或更高版本。

配置

edit

以下配置字段是设置连接器所必需的：

Confluence data source

下拉菜单以确定Confluence平台类型：Confluence Cloud、Confluence Server或Confluence Data Center。默认值是Confluence Server。

Confluence Data Center username

Confluence Data Center 账户的用户名。

Confluence Data Center password

用于Confluence Data Center的账户密码。

Confluence Server username

Confluence 服务器的账户用户名。

Confluence Server password

要用于Confluence Server的账户密码。

Confluence Cloud account email

Confluence Cloud 的账户邮箱。

Confluence Cloud API token

用于与Confluence云进行身份验证的API令牌。

Confluence URL label

Confluence托管的域名。示例：

https://192.158.1.38:8080/
https://test_user.atlassian.net/

Confluence space keys

逗号分隔的空间键列表，用于从Confluence服务器或云中获取数据。如果值为*，连接器将从配置的spaces中存在的所有空间中获取数据。默认值为*。示例：

EC, TP
*

Enable indexing labels

切换以启用从页面同步标签。注意：这将增加对源的网络调用数量，并可能降低性能。

Enable SSL

是否启用SSL验证。默认值是False。

SSL certificate

SSL 证书的内容。注意：如果 ssl_enabled 是 False，此字段中的值将被忽略。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

Enable document level security

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

要在Jira管理中访问用户数据，您创建的账户必须被授予产品访问权限以进行Jira管理。此访问权限需要由Atlassian管理员提供，并且授予的访问级别应为产品管理员。

文档和同步

edit

连接器同步以下Confluence对象类型：

页面
空间
博客文章
附件

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

此连接器支持用于远程过滤的高级同步规则。这些规则涵盖了无法通过<基本同步规则表达的复杂查询和过滤场景。高级同步规则通过特定于源的DSL JSON片段定义。

高级同步规则示例

edit

示例 1: 查询索引数据，该数据位于具有键 DEV 的特定空间中。

[
  {
    "query": "space = DEV"
  }
]

示例 2: 基于 created 和 lastmodified 时间的索引数据查询。

[
  {
    "query": "created >= now('-5w')"
  },
  {
    "query": "lastmodified < startOfYear()"
  }
]

示例 3: 仅在键为 SD 的空间中索引给定类型的查询。

[
  {
    "query": "type in ('page', 'attachment') AND space.key = 'SD'"
  }
]

在使用高级同步规则时，Confluence 中最近创建/更新的项目的同步可能会延迟，因为用于 CQL 查询的搜索端点在响应中返回了陈旧的结果。有关更多详细信息，请参阅 Confluence 文档中的以下问题。

文档级安全

edit

DLS 自 8.9.0 版本起自动适用于 Atlassian Confluence Cloud。 DLS 自 8.14.0 版本起适用于 Confluence Server 和 Confluence Data Center，但需要安装 Extender for Confluence。

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

当data_source设置为Confluence Data Center或Server时，由于所使用的API的限制，连接器将仅获取1000个用户用于访问控制同步。

请参阅搜索应用程序中的DLS，了解如何在构建搜索应用程序时，从启用了DLS的连接器中摄取数据。该示例使用SharePoint Online作为数据源，但相同的步骤适用于每个连接器。

内容提取

edit

参见内容提取。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器作为使用Elastic 连接器框架的自托管连接器提供。此自托管连接器兼容 Elastic 版本8.7.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个Confluence连接器

edit

使用用户界面

edit

要创建一个新的Confluence连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Confluence 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自托管 Confluence 自托管连接器。

例如：

PUT _connector/my-confluence-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Confluence",
  "service_type": "confluence"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

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

兼容性

edit

Confluence Cloud 或 Confluence Server/Data Center 7 或更高版本

配置

edit

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

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

以下配置字段是设置连接器所必需的：

data_source

下拉菜单以确定Confluence平台类型：Confluence Cloud、Confluence Server或Confluence Data Center。默认值是Confluence Server。

data_center_username

Confluence Data Center 账户的用户名。

data_center_password

用于Confluence Data Center的账户密码。

username

Confluence Server 账户的用户名。

password

用于Confluence服务器的账户密码。

account_email

Confluence Cloud 的账户邮箱。

api_token

用于与Confluence Cloud进行身份验证的API令牌。

confluence_url

Confluence实例托管的域名。示例：

https://192.158.1.38:8080/
https://test_user.atlassian.net/

spaces

逗号分隔的 Space Keys 列表，用于从Confluence获取数据。如果值为 *，连接器将从配置的 spaces 中获取所有空间的数据。默认值为 *。示例：

EC, TP
*

index_labels

切换以启用从页面同步标签。注意：这将增加对源的网络调用数量，并可能降低性能。

ssl_enabled

是否启用SSL验证。默认值是False。

ssl_ca

SSL 证书的内容。注意：如果 ssl_enabled 是 False，此字段中的值将被忽略。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

retry_count

请求Confluence失败后的重试次数。默认值是3。

concurrent_downloads

获取附件内容时的并发下载数量。这加快了附件内容的提取速度。默认为 50。

use_document_level_security

切换以启用文档级安全 (DLS)。

启用后，完整同步将获取每个文档的访问控制列表，并将它们存储在_allow_access_control字段中。访问控制同步将获取用户的访问控制列表，并将它们存储在一个单独的索引中。

use_text_extraction_service

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

使用 Docker 部署

edit

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

步骤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: confluence
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器同步以下Confluence对象类型：

页面
空间
博客文章
附件

大于10 MB的文件内容将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则示例

edit

示例 1: 查询索引数据，该数据位于具有键 DEV 的特定空间中。

[
  {
    "query": "space = DEV"
  }
]

示例 2: 基于 created 和 lastmodified 时间的索引数据查询。

[
  {
    "query": "created >= now('-5w')"
  },
  {
    "query": "lastmodified < startOfYear()"
  }
]

示例 3: 仅在键为 SD 的空间中索引给定类型的查询。

[
  {
    "query": "type in ('page', 'attachment') AND space.key = 'SD'"
  }
]

文档级安全

edit

DLS 自 8.9.0 版本起自动适用于 Atlassian Confluence Cloud。 DLS 自 8.14.0 版本起适用于 Confluence Server 和 Confluence Data Center，但需要安装 Extender for Confluence。

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

当data_source设置为Confluence Data Center或Server时，由于所使用的API的限制，连接器将仅获取1000个用户用于访问控制同步。

请参考搜索应用程序中的DLS，了解如何在构建搜索应用程序时，从启用了DLS的连接器中摄取数据。该示例使用SharePoint Online作为数据源，但相同的步骤适用于每个连接器。

内容提取

edit

参见内容提取。

自托管连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为Confluence连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=confluence

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=confluence DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Dropbox 连接器参考

edit

The Elastic Dropbox connector 是一个用于 connector Dropbox 的连接器。这个连接器是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic 版本 8.10.0 及更高版本中作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个Dropbox连接器

edit

使用用户界面

edit

要创建一个新的 Dropbox 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Dropbox 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Dropbox 连接器。

例如：

PUT _connector/my-dropbox-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Dropbox",
  "service_type": "dropbox",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

在配置您的连接器之前，您需要：

Dropbox API 授权

edit

创建 Dropbox OAuth 应用

edit

您需要按照以下步骤在Dropbox平台上创建一个OAuth应用：

在Dropbox 应用控制台中注册一个新应用。选择完整的 Dropbox API 应用并选择以下必需的权限：
- files.content.read
- sharing.read
  
  要使用文档级安全，您还需要以下权限：
- team_info.read
- team_data.member
- team_data.content.read
- members.read
一旦应用创建完成，请记下应用密钥和应用密钥的值，您需要在您的 Elastic 部署上配置 Dropbox 连接器时使用这些值。

生成一个刷新令牌

edit

要生成刷新令牌，请按照以下步骤操作：

转到以下URL，将替换为之前保存的应用密钥值： https://www.dropbox.com/oauth2/authorize?client_id=&response_type=code&token_access_type=offline

HTTP 响应应包含一个授权码，您将使用它来生成一个刷新令牌。授权码只能使用一次来创建一个刷新令牌。
在您的终端中，运行以下 cURL 命令，将、: 替换为您之前保存的值：
```
curl -X POST "https://api.dropboxapi.com/oauth2/token?code=&grant_type=authorization_code" -u ":"
```
将刷新令牌从响应中存储起来，以便在连接器配置中使用。

确保响应包含以下范围的列表：
- account_info.read
- files.content.read
- files.metadata.read
- sharing.read
- team_info.read (如果使用文档级安全)
- team_data.member (如果使用文档级安全)
- team_data.content.read (如果使用文档级安全)
- members.read (如果使用文档级安全)

配置

edit

以下配置字段是设置连接器所必需的：

Path to fetch files/folders: 从Dropbox获取文件/文件夹的文件夹路径。默认值是/。

此字段可以通过高级同步规则绕过。
App key: 用于验证您的Dropbox应用程序的应用密钥。
App secret: 用于验证您的Dropbox应用程序的应用密钥。
Refresh token: 用于验证您的Dropbox应用程序的刷新令牌。
Enable document level security: 切换以启用文档级安全 (DLS)。启用后，完整同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。
Include groups and inherited users: 当启用文档级安全性时出现。在索引权限时包含组和继承的用户。

启用包含组和继承用户会导致显著的性能下降。

文档和同步

edit

连接器同步以下对象和实体：

文件
- 包含元数据，如文件名、路径、大小、内容等。
文件夹

由于Dropbox问题，从Dropbox Paper对Paper文件的元数据更新不会立即反映在Dropbox UI中。这延迟了连接器更新结果的可用性。一旦元数据更改在Dropbox UI中可见，更新就会可用。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
目前，连接器不会从共享的团队文件夹中检索文件。
权限默认不会同步。如果未启用文档级安全 (DLS)，则索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。

Dropbox的高级同步规则允许您根据匹配文件名中字符串的查询来同步Dropbox文件。您可以选择通过file_extensions或file_categories过滤查询结果。当两者都提供时，优先考虑file_categories。我们在下面提供了一些示例以供说明。

======= 示例：仅查询

[
  {
    "query": "confidential"
  },
  {
    "query": "dropbox"
  }
]

======= 示例：使用文件扩展名过滤查询

[
  {
    "query": "dropbox",
    "options": {
      "file_extensions": [
        "txt",
        "pdf"
      ]
    }
  }
]

======= 示例：使用文件类别过滤的查询

[
  {
    "query": "test",
    "options": {
      "file_categories": [
        {
          ".tag": "paper"
        },
        {
          ".tag": "png"
        }
      ]
    }
  }
]

======= 限制

当启用高级同步规则时，不支持提取Dropbox Paper文件的内容。

已知问题

edit

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

查看故障排除以获取所有连接器的故障排除提示列表。

安全性

edit

查看安全以获取所有连接器的安全提示列表。

内容提取

edit

参见内容提取。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。

这个自托管连接器兼容 Elastic 版本 8.9.0+。

要使用此连接器，请满足所有自管理连接器要求。

创建一个Dropbox连接器

edit

使用界面

edit

要创建一个新的 Dropbox 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Dropbox 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自托管 Dropbox 自托管连接器。

例如：

PUT _connector/my-dropbox-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Dropbox",
  "service_type": "dropbox"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

在配置您的连接器之前，您需要：

要使用此连接器作为自管理连接器，请参阅自管理连接器。一旦设置完成，如需进行其他使用操作，请参阅Kibana中的连接器UI。

Dropbox API 授权

edit

创建 Dropbox OAuth 应用

edit

您需要按照以下步骤在Dropbox平台上创建一个OAuth应用：

在Dropbox 应用控制台中注册一个新应用。选择完整的 Dropbox API 应用并选择以下必需的权限：
- files.content.read
- sharing.read
  
  要使用文档级安全，您还需要以下权限：
- team_info.read
- team_data.member
- team_data.content.read
- members.read
一旦应用创建完成，请记下应用密钥和应用密钥值，您需要在您的 Elastic 部署上配置 Dropbox 连接器时使用这些值。

生成一个刷新令牌

edit

要生成刷新令牌，请按照以下步骤操作：

转到以下URL，将替换为之前保存的应用密钥值： https://www.dropbox.com/oauth2/authorize?client_id=&response_type=code&token_access_type=offline

HTTP 响应应包含一个授权码，您将使用它来生成一个刷新令牌。授权码只能使用一次来创建一个刷新令牌。
在您的终端中，运行以下 cURL 命令，将、: 替换为您之前保存的值：
```
curl -X POST "https://api.dropboxapi.com/oauth2/token?code=&grant_type=authorization_code" -u ":"
```
将刷新令牌从响应中存储起来，以便在连接器配置中使用。

确保响应包含以下范围的列表：
- account_info.read
- files.content.read
- files.metadata.read
- sharing.read
- team_info.read (如果使用文档级安全)
- team_data.member (如果使用文档级安全)
- team_data.content.read (如果使用文档级安全)
- members.read (如果使用文档级安全)

配置

edit

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

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

以下配置字段是设置连接器所必需的：

path: 从Dropbox获取文件/文件夹的文件夹路径。默认值是/。
app_key (required): 用于验证您的Dropbox应用程序的应用密钥。
app_secret (required): 用于验证您的Dropbox应用程序的应用密钥。
refresh_token (required): 用于验证您的Dropbox应用程序的刷新令牌。
use_document_level_security: 切换以启用文档级安全 (DLS)。启用后，完整同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。
retry_count: 在请求Dropbox失败后的重试次数。默认值是3。
concurrent_downloads: 获取附件内容时的并发下载数量。这可以帮助加快附件内容的提取速度。默认值为 100。
use_text_extraction_service: 需要单独部署Elastic 文本提取服务。需要确保管道设置禁用文本提取。默认值为False。
use_document_level_security: 切换以启用文档级安全 (DLS)。启用后，完整同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。
include_inherited_users_and_groups: 取决于是否启用了文档级安全。在索引权限时包含组和继承的用户。

启用包含组和继承用户会导致显著的性能下降。

使用 Docker 部署

edit

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

步骤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: dropbox
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器同步以下对象和实体：

文件
- 包含元数据，如文件名、路径、大小、内容等。
文件夹

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
目前，连接器不会从共享的团队文件夹中检索文件。
默认情况下，权限不会同步。如果未启用文档级安全 (DLS)，则索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。

======= 示例：仅查询

[
  {
    "query": "confidential"
  },
  {
    "query": "dropbox"
  }
]

======= 示例：使用文件扩展名过滤查询

[
  {
    "query": "dropbox",
    "options": {
      "file_extensions": [
        "txt",
        "pdf"
      ]
    }
  }
]

======= 示例：使用文件类别过滤器查询

[
  {
    "query": "test",
    "options": {
      "file_categories": [
        {
          ".tag": "paper"
        },
        {
          ".tag": "png"
        }
      ]
    }
  }
]

======= 限制

当启用高级同步规则时，不支持对Dropbox Paper文件的内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为Dropbox连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=dropbox

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=dropbox DATA_SIZE=small

已知问题

edit

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

查看故障排除以获取所有连接器的故障排除提示列表。

安全性

edit

查看安全以获取所有连接器的安全提示列表。

内容提取

edit

参见内容提取。

Elastic GitHub 连接器参考

edit

The Elastic GitHub connector 是一个用于连接器 GitHub。这个连接器是使用 Elastic 连接器框架用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

弹性管理连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自 Elastic 版本 8.11.0 起，此连接器作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 GitHub 连接器

edit

使用界面

edit

要创建一个新的 GitHub 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 GitHub 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 GitHub 连接器。

例如：

PUT _connector/my-github-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from GitHub",
  "service_type": "github",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

GitHub 个人访问令牌

edit

配置一个 GitHub 个人访问令牌以从 GitHub 获取数据。

按照以下步骤生成GitHub个人访问令牌：

前往 GitHub 设置 → 开发者设置 → 个人访问令牌 → 令牌(经典)。
选择 生成新令牌。
添加一个注释并选择以下范围：
- repo
- user
- read:org
选择 生成令牌 并复制令牌。

GitHub 应用

edit

配置一个 GitHub 应用程序以从 GitHub 获取数据。

按照以下步骤创建 GitHub 应用：

前往 GitHub 设置 → 开发者设置 → GitHub 应用。
选择 新建 GitHub 应用。
添加名称和主页 URL，在 Webhook 下取消选择 活跃。
在 权限 下，为 提交状态、内容、问题、元数据 和 拉取请求 选择 只读，在 组织权限 下为 成员 选择 只读。
为 此 GitHub 应用可以安装在哪里？ 选择 任何账户。
点击 创建 GitHub 应用。
向下滚动到 私钥 部分，并点击 生成私钥。
点击左上角的 安装应用，选择您想要在其上安装 GitHub 应用的组织/个人账户，点击 安装。
您可以选择安装在所有仓库或选定的仓库上，然后点击 安装。

兼容性

edit

GitHub 和 GitHub Enterprise 均受支持。

配置

edit

以下配置字段是必需的：

Data source

在 GitHub 云和 GitHub 服务器之间切换。

Server URL

GitHub Server实例的URL。（仅限GitHub Server）

Authentication method

用于验证GitHub实例的方法。在个人访问令牌和GitHub应用之间切换。

Token

GitHub个人访问令牌用于验证GitHub实例。此字段仅适用于个人访问令牌认证方法。

Repository Type

在组织和其他之间切换。请注意，文档级安全（DLS）仅适用于组织仓库。

Organization Name

要从中获取数据的组织名称。仅当认证方法设置为个人访问令牌且仓库类型设置为组织时，此字段才可用。

App ID

GitHub App 的应用 ID。此字段仅在 认证方法 设置为 GitHub App 时可用。

App private key

为 GitHub App 生成的私钥。此字段仅在 认证方法 设置为 GitHub App 时可用。

List of repositories

从GitHub实例获取数据的仓库的逗号分隔列表。如果值为*，连接器将从配置用户帐户中的所有仓库获取数据。

默认值是 *。

示例：

elasticsearch,elastic/kibana
*

仓库所有权

如果省略 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分，它将默认为认证用户的名称。

在提供的示例中：

同步的 elasticsearch 仓库将是 /elasticsearch 仓库
同步的 kibana 仓库将是 Elastic 拥有的仓库

当选择 GitHub App 作为 认证方法 时，必须提供 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分。

此字段可以通过高级同步规则绕过。

Enable SSL

为 GitHub 实例启用 SSL。

SSL certificate

GitHub实例的SSL证书。示例：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

Enable document level security

切换以启用文档级安全 (DLS)。启用后，完整同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。仅当Repository Type设置为Organization时，DLS才可用。

文档和同步

edit

连接器同步以下对象和实体：

仓库
拉取请求
问题
文件和文件夹

仅以下文件扩展名会被处理：

.markdown
.md
.rst

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elasticsearch索引的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

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

以下部分提供了此连接器的高级同步规则示例。

======= 基于通过分支键配置的分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "branch": "sync-rules-feature"
    }
  }
]

======= 基于与问题键相关的错误问题查询索引文档

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug"
    }
  }
]

======= 基于与PR键相关的开放PR查询的索引文档

[
  {
    "repository": "repo_name",
    "filter": {
      "pr": "is:open"
    }
  }
]

======= 基于查询和分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug",
      "pr": "is:open",
      "branch": "sync-rules-feature"
    }
  }
]

由给定规则拉取的所有文档都会被索引，无论该文档是否已被之前的规则索引过。这可能导致文档重复，但索引文档的数量在日志中会有所不同。请检查Elasticsearch索引以获取实际的文档数量。

======= 重叠的高级规则

[
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-20"
    },
    "repository": "repo_name"
  },
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-15"
    },
    "repository": "repo_name"
  }
]

如果选择 GitHub App 作为身份验证方法，则必须提供 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分。

内容提取

edit

参见内容提取。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。

这个自托管连接器兼容 Elastic 版本 8.10.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个 GitHub 连接器

edit

使用界面

edit

要创建一个新的 GitHub 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 GitHub 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自托管 GitHub 自托管连接器。

例如：

PUT _connector/my-github-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from GitHub",
  "service_type": "github"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

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

GitHub 个人访问令牌

edit

配置一个 GitHub 个人访问令牌以从 GitHub 获取数据。

按照以下步骤生成 GitHub 访问令牌：

前往 GitHub 设置 → 开发者设置 → 个人访问令牌 → 令牌(经典)。
选择 生成新令牌。
添加一个注释并选择以下范围：
- repo
- user
- read:org
选择 生成令牌 并复制令牌。

GitHub 应用

edit

配置一个 GitHub 应用程序以从 GitHub 获取数据。

按照以下步骤创建 GitHub 应用：

前往 GitHub 设置 → 开发者设置 → GitHub 应用。
选择 新建 GitHub 应用。
添加名称和主页 URL，在 Webhook 下取消选择 活跃。
在 权限 下，为 提交状态、内容、问题、元数据 和 拉取请求 选择 只读，在 组织权限 下为 成员 选择 只读。
为 此 GitHub 应用可以安装在哪里？ 选择 任何账户。
点击 创建 GitHub 应用。
向下滚动到 私钥 部分，并点击 生成私钥。
点击左上角的 安装应用，选择您想要在其上安装 GitHub 应用的组织/个人账户，点击 安装。
您可以选择安装在所有仓库或选定的仓库上，然后点击 安装。

兼容性

edit

GitHub 和 GitHub Enterprise 均受支持。

配置

edit

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

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

以下配置字段是必需的：

data_source

GitHub 云或 GitHub 服务器。

host

GitHub Server实例的URL。（仅限GitHub Server）

auth_method

用于验证GitHub实例的方法。在个人访问令牌和GitHub应用之间切换。

token

GitHub个人访问令牌用于验证GitHub实例。此字段仅适用于个人访问令牌认证方法。

repo_type

在组织和其他之间切换。请注意，文档级安全（DLS）仅适用于组织仓库。

org_name

要从中获取数据的组织名称。仅当认证方法设置为个人访问令牌且仓库类型设置为组织时，此字段才可用。

app_id

GitHub App 的应用 ID。此字段仅在 认证方法 设置为 GitHub App 时可用。

private_key

为 GitHub App 生成的私钥。此字段仅在 认证方法 设置为 GitHub App 时可用。

repositories

从GitHub实例获取数据的仓库的逗号分隔列表。如果值为*，连接器将从配置用户帐户中的所有仓库获取数据。

默认值是 *。

示例：

elasticsearch,elastic/kibana
*

仓库所有权

如果省略 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分，它将默认为认证用户的名称。

在提供的示例中：

同步的 elasticsearch 仓库将是 /elasticsearch
同步的 kibana 仓库将是 Elastic 拥有的仓库

当选择 GitHub App 作为 认证方法 时，必须提供 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分。

此字段可以通过高级同步规则绕过。

ssl_enabled

是否启用SSL验证。默认值是False。

ssl_ca

SSL 证书的内容。注意：如果 ssl_enabled 是 False，此字段中的值将被忽略。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

use_document_level_security

retry_count

对GitHub请求失败后的重试次数。默认值是3。

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要确保管道设置禁用文本提取。默认值为 False。

使用 Docker 部署

edit

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

步骤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: github
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器同步以下对象和实体：

仓库
拉取请求
问题
文件和文件夹

仅以下文件扩展名会被处理：

.markdown
.md
.rst

大于10 MB的文件内容将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elasticsearch索引的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

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

以下部分提供了此连接器的高级同步规则示例。

======= 基于通过分支键配置的分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "branch": "sync-rules-feature"
    }
  }
]

======= 基于与问题键相关的错误问题查询索引文档

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug"
    }
  }
]

======= 基于与PR键相关的开放PR查询索引文档

[
  {
    "repository": "repo_name",
    "filter": {
      "pr": "is:open"
    }
  }
]

======= 基于查询和分支名称索引文档和文件

[
  {
    "repository": "repo_name",
    "filter": {
      "issue": "is:bug",
      "pr": "is:open",
      "branch": "sync-rules-feature"
    }
  }
]

======= 重叠的高级规则

[
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-20"
    },
    "repository": "repo_name"
  },
  {
    "filter": {
      "pr": "is:pr is:merged label:auto-backport merged:>=2023-07-15"
    },
    "repository": "repo_name"
  }
]

如果选择 GitHub App 作为身份验证方法，则必须提供 "OWNER/REPO" 仓库参数中的 "OWNER/" 部分。

内容提取

edit

参见内容提取。

自托管连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为GitHub连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=github

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=github DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Gmail 连接器参考

edit

The Elastic GMail connector 是一个用于 GMail 的 connector。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic Cloud 中作为 托管连接器（托管服务）提供。

此连接器兼容 Elastic 版本 8.13.0+。

要使用此连接器，请满足所有托管连接器要求。

创建一个Gmail连接器

edit

使用界面

edit

要创建一个新的Gmail连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Gmail 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Gmail 连接器。

例如：

PUT _connector/my-gmail-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Gmail",
  "service_type": "gmail",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中将此连接器用作托管连接器，请在 Kibana UI 中使用 连接器 工作流程。

要创建一个新的Gmail连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
选择 新建原生连接器 按钮。
选择 Gmail 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接器认证前提条件

edit

在从GMail同步任何数据之前，您需要创建一个具有适当访问权限的服务账户，以访问GMail和Google Directory API，后者是Google Admin SDK API的一部分。您还需要启用域范围委派，以模拟您正在获取消息的用户。

要开始使用，请登录到Google Cloud Platform并转到控制台。

创建一个 Google Cloud 项目。 为您的项目命名，更改项目 ID 并点击创建按钮。
启用 Google API。 从左侧菜单中选择 API 和服务并点击 启用 API 和服务。您需要启用 GMail API 和 Google Admin SDK API。
创建一个服务账户。 在 API 和服务 部分，点击 凭据 并点击 创建凭据 来创建一个服务账户。为您的服务账户命名并设置服务账户 ID。这类似于电子邮件地址，将来将用于识别您的服务账户。点击 完成 以完成服务账户的创建。

您的服务帐户需要至少具有以下范围的访问权限：
- https://www.googleapis.com/auth/gmail.readonly
创建一个密钥文件.
- 在 Cloud Console 中，转到 IAM 和管理员 > 服务账户 页面。
- 点击您要为其创建密钥的服务账户的电子邮件地址。
- 点击 密钥 标签。点击 添加密钥 下拉菜单，然后选择 创建新密钥。
- 选择 JSON 作为密钥类型，然后点击 创建。这将下载一个包含服务账户凭据的 JSON 文件。
Google Workspace 域范围的权限委托.

要访问 Google Workspace 域中的用户数据（如消息），您创建的服务账户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围的权限委托。

您需要为您的服务账户授予以下OAuth 范围：
- https://www.googleapis.com/auth/admin.directory.user.readonly
此步骤允许连接器访问您 Google Workspace 组织中的用户数据及其群组成员身份。

配置

edit

以下配置字段是必需的：

GMail service account JSON

从Google Cloud Platform生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。

Google Workspace admin email

Google Workspace 管理员电子邮件。需要启用文档级安全 (DLS)。具有委托权限的服务帐户可以模拟具有访问 Google Workspace 用户数据及其组成员资格权限的管理员用户。有关更多信息，请参阅 Google Cloud 文档。

Google customer ID

谷歌客户ID。获取消息和启用文档级安全（DLS）所必需的。前往 Google Workspace 管理控制台 → 账户 并复制 客户ID 下的值。

Include spam and trash emails

切换以获取垃圾邮件和回收站邮件。也适用于文档级安全（DLS）。

Enable document level security

切换以启用文档级安全 (DLS)。 DLS 支持 GMail 连接器。启用时：

完整同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

文档和同步

edit

连接器将获取服务帐户有权访问的所有用户的所有消息。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

此连接器提供了高级同步规则。该连接器在 messages 字段下支持 GMail 高级搜索语法。

例如：

{
  "messages": [
    "before:2021/10/10",
    "from:amy"
  ]
}

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源代码

edit

此连接器是使用 Elastic 连接器框架在 Python 中构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

自托管连接器参考

edit

查看自托管连接器参考

可用性和前提条件

edit

此连接器作为自托管连接器从Elastic 连接器框架中提供。

这个自托管连接器兼容 Elastic 版本 8.10.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个Gmail连接器

edit

使用界面

edit

要创建一个新的Gmail连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Gmail 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自管理 Gmail 自管理连接器。

例如：

PUT _connector/my-gmail-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Gmail",
  "service_type": "gmail"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请在 Kibana UI 中使用连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接器认证前提条件

edit

在从GMail同步任何数据之前，您需要创建一个具有适当访问权限的服务账户，以访问GMail和Google Directory API，后者是Google Admin SDK API的一部分。您还需要启用域范围的委派，以模拟您正在获取消息的用户。

要开始使用，请登录到Google Cloud Platform并转到控制台。

创建一个 Google Cloud 项目。 为您的项目命名，更改项目 ID 并点击创建按钮。
启用 Google API。 从左侧菜单中选择 API 和服务并点击 启用 API 和服务。您需要启用 GMail API 和 Google Admin SDK API。
创建一个服务账户。 在 API 和服务 部分，点击 凭据 并点击 创建凭据 来创建一个服务账户。为您的服务账户命名并设置服务账户 ID。这类似于电子邮件地址，将来将用于识别您的服务账户。点击 完成 以完成服务账户的创建。

您的服务帐户需要至少具有以下范围的访问权限：
- https://www.googleapis.com/auth/gmail.readonly
创建一个密钥文件.
- 在 Cloud Console 中，转到 IAM 和管理员 > 服务账户 页面。
- 点击您要为其创建密钥的服务账户的电子邮件地址。
- 点击 密钥 标签。点击 添加密钥 下拉菜单，然后选择 创建新密钥。
- 选择 JSON 作为密钥类型，然后点击 创建。这将下载一个包含服务账户凭据的 JSON 文件。
Google Workspace 域范围的权限委托.

要访问 Google Workspace 域中的用户数据（如消息），您创建的服务账户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围的权限委托。

您需要为您的服务账户授予以下OAuth 范围：
- https://www.googleapis.com/auth/admin.directory.user.readonly
此步骤允许连接器访问您 Google Workspace 组织中的用户数据及其群组成员身份。

配置

edit

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

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

以下配置字段是必需的：

GMail service account JSON

从Google Cloud Platform生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。

Google Workspace admin email

Google customer id

谷歌客户ID。获取消息和启用文档级安全（DLS）所必需的。前往 Google Workspace 管理控制台 → 账户 并复制 客户ID 下的值。

Include spam and trash emails

切换以获取垃圾邮件和回收站中的电子邮件。同样适用于DLS。

Enable document level security

切换以启用文档级安全 (DLS)。 DLS 支持 GMail 连接器。启用时：

全量同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

使用 Docker 部署

edit

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

步骤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: gmail
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器将获取服务帐户有权访问的所有用户的所有消息。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

此连接器提供了高级同步规则。该连接器在 messages 字段下支持 GMail 高级搜索语法。

例如：

{
  "messages": [
    "before:2021/10/10",
    "from:amy"
  ]
}

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用 Elastic 连接器框架在 Python 中构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

Google Cloud Storage 连接器

edit

The Elastic Google Cloud Storage connector 是一个用于 connector Google Cloud Storage 数据源的连接器。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自8.12.0版本起，此连接器在Elastic Cloud中已原生可用。要在Elastic Cloud中使用此连接器，请满足所有托管连接器要求。

用法

edit

Google Cloud Storage 服务账号必须拥有（至少）以下范围和角色：

resourcemanager.projects.get
serviceusage.services.use
storage.buckets.list
storage.objects.list
storage.objects.get

Google Cloud Storage 服务帐户凭据存储在 JSON 文件中。

配置

edit

以下配置字段是设置连接器所必需的：

Buckets: 要索引的存储桶列表。 * 将索引所有存储桶。
Google Cloud service account JSON: 从Google Cloud Storage生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。

文档和同步

edit

连接器将获取服务帐户有权访问的所有存储桶和路径。

The Owner 字段未被获取，因为 read_only 范围不允许连接器获取 IAM 信息。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。所有索引到Elastic部署的文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤由摄取管道控制。

内容提取

edit

参见内容提取。

$ make ftest NAME=google_cloud_storage

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=google_cloud_storage DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.6.0+。要使用此连接器，请满足所有自托管连接器要求。

用法

edit

Google Cloud Storage 服务账号必须拥有（至少）以下范围和角色：

resourcemanager.projects.get
serviceusage.services.use
storage.buckets.list
storage.objects.list
storage.objects.get

Google Cloud Storage 服务帐户凭据存储在 JSON 文件中。

配置

edit

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

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

以下配置字段是设置连接器所必需的：

buckets: 要索引的存储桶列表。 * 将索引所有存储桶。
service_account_credentials: 从Google Cloud Storage生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。
retry_count: 对Google Cloud Storage调用失败后的重试次数。默认值是3。

使用 Docker 部署

edit

您可以使用 Docker 将 Google Cloud Storage 连接器部署为自托管连接器。请按照以下说明操作。

步骤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: google_cloud_storage
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器将获取服务帐户有权访问的所有存储桶和路径。

The Owner 字段未被获取，因为 read_only 范围不允许连接器获取 IAM 信息。

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。所有索引到Elastic部署的文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤由摄取管道控制。

内容提取

edit

参见内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 Google Cloud Storage 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=google_cloud_storage

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=google_cloud_storage DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

Elastic Google Drive 连接器参考

edit

The Elastic Google Drive connector 是一个用于 connector Google Drive 的连接器。这个连接器是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自 Elastic 版本 8.11.0 起，此连接器作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接器认证前提条件

edit

在从Google Drive同步任何数据之前，您需要创建一个具有适当访问Google Drive API权限的服务账户。

要开始使用，请登录到Google Cloud Platform并转到控制台。

创建一个Google Cloud项目。 为您的项目命名，更改项目ID并点击创建按钮。
启用Google API。 从左侧菜单中选择API和服务，然后点击启用API和服务。您需要启用Drive API。
创建一个服务账户。 在API 和服务部分，点击凭据并点击创建凭据来创建一个服务账户。为您的服务账户命名并设置服务账户ID。这类似于电子邮件地址，将来将用于识别您的服务账户。点击完成以完成服务账户的创建。您的服务账户需要至少具有以下访问权限：
- https://www.googleapis.com/auth/drive.readonly
创建一个密钥文件.
- 在Cloud Console中，转到IAM和管理 > 服务账户页面。
- 点击您要为其创建密钥的服务账户的电子邮件地址。
- 点击密钥标签。点击添加密钥下拉菜单，然后选择创建新密钥。
- 选择JSON作为密钥类型，然后点击创建。这将下载一个包含服务账户凭据的JSON文件。
[可选] 共享Google Drive文件夹。 如果您使用域范围委派来同步数据，可以跳过此步骤。转到您的Google Drive。右键点击文件夹或共享驱动器，选择共享并将您在步骤3中创建的服务账户的电子邮件地址添加为此文件夹的查看者。

当您授予服务帐户对Google Drive中特定文件夹或共享驱动器的访问权限时，需要注意的是，这些权限会扩展到该文件夹或驱动器内的所有子项。这意味着授予文件夹或驱动器内的任何文件夹或文件将继承与父级相同的访问权限。

域范围委派的额外身份验证前提条件

edit

当启用使用域范围委派进行数据同步或启用文档级安全配置选项时，此步骤是必需的。

启用Google API。

从左侧菜单中选择API和服务，然后点击启用API和服务。您需要启用Admin SDK API和Drive API。
Google Workspace 域范围的权限委托.

要在 Google Workspace 域中访问驱动器和用户数据，您创建的服务帐户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围的权限委托。

您需要为您的服务帐户授予以下OAuth 范围：
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/drive.readonly
- https://www.googleapis.com/auth/drive.metadata.readonly
此步骤允许连接器：
- 访问 Google Workspace 组织中的用户数据及其组成员身份
- 访问与 Google Workspace 成员关联的驱动器中的 Google Drive 数据

配置

edit

以下配置字段是必需的：

Google Drive service account JSON

从Google Cloud Platform生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。

Enable document level security

切换以启用文档级安全 (DLS)。 DLS 支持 Google Drive 连接器。启用时：

完整同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

Google Workspace admin email

Google Workspace 管理员电子邮件。需要启用文档级安全 (DLS) 或域范围委派以进行数据同步。具有委派权限的服务帐户可以模拟具有访问 Google Workspace 用户数据及其组成员资格权限的管理员用户。有关更多信息，请参阅 Google Cloud 文档。

文档和同步

edit

连接器将获取服务帐户有权访问的所有文件和文件夹。

它将尝试从Google Suite文档（Google Docs、Google Sheets和Google Slides）和常规文件中提取内容。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

内容提取

edit

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

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。要使用此连接器，请满足所有自托管连接器要求。

用法

edit

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

连接器认证前提条件

edit

在从Google Drive同步任何数据之前，您需要创建一个具有适当访问Google Drive API权限的服务账户。

要开始使用，请登录到Google Cloud Platform并转到控制台。

创建一个Google Cloud项目。 为您的项目命名，更改项目ID并点击创建按钮。
启用Google API。 从左侧菜单中选择API和服务，然后点击启用API和服务。您需要启用Drive API。
创建一个服务账户。 在API 和服务部分，点击凭据并点击创建凭据来创建一个服务账户。为您的服务账户命名并设置服务账户ID。这类似于电子邮件地址，将来将用于识别您的服务账户。点击完成以完成服务账户的创建。您的服务账户需要至少具有以下访问权限：
- https://www.googleapis.com/auth/drive.readonly
创建一个密钥文件.
- 在Cloud Console中，转到IAM和Admin > 服务账户页面。
- 点击您要为其创建密钥的服务账户的电子邮件地址。
- 点击密钥标签。点击添加密钥下拉菜单，然后选择创建新密钥。
- 选择JSON作为密钥类型，然后点击创建。这将下载一个包含服务账户凭据的JSON文件。
[可选] 共享Google Drive文件夹。 如果您使用域范围委派来同步数据，可以跳过此步骤。转到您的Google Drive。右键点击文件夹或共享驱动器，选择共享并将您在步骤3中创建的服务账户的电子邮件地址添加为此文件夹的查看者。

域范围委派的额外身份验证前提条件

edit

当启用使用域范围委派进行数据同步或启用文档级安全配置选项时，此步骤是必需的。

启用Google API。

从左侧菜单中选择API和服务，然后点击启用API和服务。您需要启用Admin SDK API和Drive API。
Google Workspace 域范围的权限委托.

要在 Google Workspace 域中访问驱动器和用户数据，您创建的服务帐户需要由该域的超级管理员授予访问权限。您可以按照官方文档执行 Google Workspace 域范围的权限委托。

您需要为您的服务帐户授予以下OAuth 范围：
- https://www.googleapis.com/auth/admin.directory.group.readonly
- https://www.googleapis.com/auth/admin.directory.user.readonly
- https://www.googleapis.com/auth/drive.readonly
- https://www.googleapis.com/auth/drive.metadata.readonly
此步骤允许连接器：
- 访问 Google Workspace 组织中的用户数据及其组成员身份
- 访问与 Google Workspace 成员关联的驱动器中的 Google Drive 数据

配置

edit

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

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

以下配置字段是必需的：

service_account_credentials

从Google Cloud Platform生成的服务帐户凭据（JSON字符串）。有关更多信息，请参阅Google Cloud文档。

use_domain_wide_delegation_for_sync

使用域范围委派来自动同步Google工作区中所有共享和个人驱动器的内容。这消除了手动与服务帐户共享Google Drive数据的需要，尽管它可能会增加同步时间。如果禁用，则只会同步手动与服务帐户共享的项目和文件夹。

google_workspace_admin_email_for_data_sync

当启用数据同步的域范围委派时，此项为必填项。此电子邮件用于发现和同步共享驱动器。仅同步此用户有权访问的共享驱动器。

google_workspace_email_for_shared_drives_sync

当启用数据同步的域范围委派时，此项为必需。提供用于发现和同步共享驱动器的 Google Workspace 用户电子邮件。只有该用户有权访问的共享驱动器才会被同步。

use_document_level_security

切换以启用文档级安全 (DLS)。 DLS 支持 Google Drive 连接器。启用时：

完整同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

google_workspace_admin_email

max_concurrency

Google Drive API 的最大并发 HTTP 请求数。增加此值可以提高数据检索速度，但也可能对系统资源和网络带宽提出更高的要求。

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要确保管道设置禁用文本提取。默认值为False。

使用 Docker 部署

edit

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

步骤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: google_drive
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器将获取服务帐户有权访问的所有文件和文件夹。

它将尝试从Google Suite文档（Google Docs、Google Sheets和Google Slides）和常规文件中提取内容。

大于10 MB的文件内容将不会被提取
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

内容提取

edit

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

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。更多详情请参阅连接器测试。

要为 Google Drive 连接器执行端到端测试，请运行以下命令：

make ftest NAME=google_drive

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=google_drive DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic GraphQL 连接器参考

edit

Elastic GraphQL 连接器是使用 Elastic 连接器框架用 Python 编写的。查看此连接器的源代码。

可用性和先决条件

edit

此连接器在 Elastic 8.14.0 中引入，作为 自托管 的自托管连接器提供。

要使用此连接器，请满足所有自我管理连接器的前提条件。重要的是，您必须在您自己的基础设施上部署连接器服务。您有两个部署选项：

从源代码运行连接器服务。如果你熟悉Python并且希望在本地快速迭代，请使用此选项。
在Docker中运行连接器服务。如果你想将连接器部署到服务器，或者使用容器编排平台，请使用此选项。

此连接器处于技术预览阶段，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。技术预览功能不受正式发布功能的SLA支持。

用法

edit

要在用户界面中设置此连接器，请在搜索 → 连接器下创建新连接器时选择GraphQL图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用Docker部署

edit

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

步骤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: graphql
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

配置 GraphQL 连接器

edit

请注意以下配置字段：

http_endpoint (required)

GraphQL 端点的基本 URL。示例: https://api.xyz.com/graphql

http_method (required)

GET 或 POST。

authentication_method(required)

选择 无认证、基本认证 和 Bearer Token。

username

使用基本身份验证时需要。

password

使用基本身份验证时需要。

token

使用承载令牌认证时需要。

graphql_query (required)

用于从源获取数据的查询。可以包含在 graphql_variables 字段中提供的变量。连接器将用 graphql_variables 中的值替换查询中的变量，并向源发出 GraphQL 查询。

示例:

query getUser($id: ID!) {
    user(id: $id) {
        name
        email
    }
}

graphql_variables

包含在GraphQL查询中使用的键/值对的JSON对象。连接器将使用此处提供的值替换查询中的变量，并向源发出GraphQL查询。

示例:

对于GraphQL查询 query getUser($id: ID!) { user(id: $id) { name } }

其中 graphql_variables 的值为 {"id": "123"}
连接器将执行 query getUser { user(id: "123") { name } } 以从源获取数据

graphql_object_to_id_map (required)

GraphQL响应对象与其ID字段之间的JSON映射。连接器将为每个对象（JSON键）获取数据，并使用提供的ID字段（JSON值）将对象索引到Elasticsearch中。连接器将为映射中指定的每个对象索引所有字段。使用点(.)表示法指定从GraphQL响应根到所需对象的完整路径。

示例:

GraphQL 查询 query getUser { organization { users{ user_id name email} } } 从源中获取所有可用用户。要为每个用户索引为一个单独的文档，请按如下方式配置此字段。

{
    "organization.users": "user_id"
}

在这个例子中，user_id 在每个用户文档中是唯一的。因此，我们将 user_id 设置为 organization.users 的值。

此字段中提供的路径应仅包含 JSON 对象，而不包含列表。

headers

包含要与每个GraphQL请求一起发送的自定义标头的JSON对象：

{
    "content-type": "Application/json"
}

pagination_model (required)

此字段指定连接器要使用的分页模型。连接器支持无分页和基于游标的分页分页模型。

对于基于游标的分页，在查询中添加 pageInfo {endCursor hasNextPage} 和 after 参数变量在所需节点（分页键）。使用带有变量的 after 查询参数来遍历页面。此字段的默认值为 无分页。示例：

对于基于游标的分页，查询应类似于以下示例：

query getUsers($cursor: String!) {
    sampleData {
        users(after: $cursor) {
            pageInfo {
                endCursor
                hasNextPage
            }
            nodes {
                first_name
                last_name
                address
            }
        }
    }
}

The value of pagination_key is sampleData.users 所以它必须包含：

pageInfo {endCursor hasNextPage}
使用基于游标的分页时，带有变量的 after 参数

pagination_key (required)

指定用于分页的GraphQL对象。使用.来提供从响应根开始的完整路径。

示例:

organization.users

connection_timeout

指定等待来自GraphQL源的响应的最大时间（以秒为单位）。默认值为 30秒。

文档和同步

edit

连接器根据GraphQL查询和GraphQL对象列表同步对象和实体。

同步类型

edit

全量同步默认支持所有连接器。

此连接器目前不支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

连接器客户端操作

edit

端到端测试

edit

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 GraphQL 源来运行此测试。

更多详情请参阅连接器测试。

要为GraphQL连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=graphql

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=graphql DATA_SIZE=small

默认情况下，DATA_SIZE=MEDIUM。

已知问题

edit

每个文档将在每次同步中更新。
如果不同对象中存在具有不同类型的相同字段名称，连接器可能会引发映射解析器异常。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Jira 连接器参考

edit

The Elastic Jira connector 是一个用于 connector Atlassian Jira 的连接器。该连接器使用 Elastic connector framework 用 Python 编写。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和前提条件

edit

此连接器自 8.9.1 版本起，在 Elastic Cloud 上作为 托管连接器 提供。

Jira Data Center 支持在 8.13.0 中以技术预览版形式添加，并可能会有所变化。其设计和代码不如正式 GA 功能成熟，并且是按原样提供，不提供任何保证。技术预览功能不受正式 GA 功能支持 SLA 的约束。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 Jira 连接器

edit

使用用户界面

edit

要创建一个新的 Jira 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Jira 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Jira 连接器。

例如：

PUT _connector/my-jira-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Jira",
  "service_type": "jira",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

Jira Cloud、Jira Server 和 Jira Data Center 7 或更高版本。

配置

edit

以下配置字段是设置连接器所必需的：

Jira data source

下拉菜单以确定Jira平台类型：Jira Cloud、Jira Server 或 Jira Data Center。默认值是 Jira Cloud。

Jira Data Center username

Jira Data Center 账户的用户名。

Jira Data Center password

用于Jira Data Center的账户密码。

Jira Cloud service account id

用于与 Jira Cloud 进行身份验证的电子邮件地址。示例: jane.doe@example.com

Jira Cloud API token

用于与Jira Cloud进行身份验证的API令牌。

Jira Server username

Jira Server 账户的用户名。

Jira Server password

用于Jira Server的账户密码。

Jira Cloud service account id

Jira Cloud 的账户邮箱。

Jira Cloud API token

用于与Jira Cloud进行身份验证的API令牌。

Jira host url

Jira托管的域名。示例：

Jira project keys

逗号分隔的项目键列表，用于从 Jira 服务器或云端获取数据。如果值为 *，连接器将从配置的项目中存在的所有项目中获取数据。默认值为 *。示例：

EC, TP
*

Enable SSL

是否启用SSL验证。默认值是False。

SSL certificate

SSL证书的内容。注意：如果ssl_enabled为False，则ssl_ca值将被忽略。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

Enable document level security

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

文档和同步

edit

连接器同步以下对象和实体：

项目
- 包括元数据，如描述、项目键、项目类型、负责人姓名等。
问题
- 所有类型的问题，包括任务、错误、子任务、增强、故事等。
- 包括元数据，如问题类型、父问题详情、修复版本、受影响的版本、解决方案、附件、评论、子任务详情、优先级、自定义字段等。
附件

注意： 已归档的项目和问题不会被索引。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

此连接器支持用于远程过滤的高级同步规则。这些规则涵盖了无法通过基本同步规则表达的复杂查询和过滤场景。高级同步规则通过特定于源的DSL JSON片段定义。

高级同步规则示例

edit

示例 1: 根据 Jira 问题的状态查询索引内容。

[
  {
    "query": "project = Collaboration AND status = 'In Progress'"
  },
  {
    "query": "status IN ('To Do', 'In Progress', 'Closed')"
  }
]

示例 2: 根据给定项目的优先级查询索引数据。

[
  {
    "query": "priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)"
  }
]

示例 3: 根据受理人和创建时间查询索引数据。

[
  {
    "query": "assignee is EMPTY and created < -1d"
  }
]

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

当data_source设置为Confluence Data Center或Server时，由于所使用的API的限制，连接器将仅获取1000个用户用于访问控制同步。

内容提取

edit

参见内容提取。

已知问题

edit

启用文档级安全会影响性能。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和前提条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.7.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个Jira连接器

edit

使用用户界面

edit

要创建一个新的 Jira 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Jira 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自托管 Jira 自托管连接器。

例如：

PUT _connector/my-jira-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Jira",
  "service_type": "jira"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

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

兼容性

edit

Jira Cloud、Jira Server 和 Jira Data Center 7 或更高版本。

配置

edit

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

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

以下配置字段是设置连接器所必需的：

data_source

下拉菜单以确定Jira平台类型：Jira Cloud、Jira Server 或 Jira Data Center。默认值是 Jira Cloud。

data_center_username

Jira Data Center 账户的用户名。

data_center_password

用于Jira Data Center的账户密码。

username

Jira Server 账户的用户名。

password

用于Jira Server的账户密码。

account_email

用于与 Jira Cloud 进行身份验证的电子邮件地址。示例: jane.doe@example.com

api_token

用于与Jira Cloud进行身份验证的API令牌。

jira_url

Jira托管的域名。示例：

projects

逗号分隔的项目键列表，用于从 Jira 服务器或云端获取数据。如果值为 *，连接器将从配置的项目中存在的所有项目中获取数据。默认值为 *。示例：

EC, TP
*

此字段可以通过高级同步规则绕过。

ssl_enabled

是否启用SSL验证。默认值是False。

ssl_ca

SSL证书的内容。注意：如果ssl_enabled为False，则ssl_ca值将被忽略。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

retry_count

请求Jira失败后的重试次数。默认值是3。

concurrent_downloads

获取附件内容时的并发下载数量。这加快了附件内容的提取速度。默认为100。

use_document_level_security

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要禁用摄取管道设置中的文本提取。默认值为False。

使用 Docker 部署

edit

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

步骤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: jira
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器同步以下对象和实体：

项目
- 包括元数据，如描述、项目键、项目类型、负责人姓名等。
问题
- 所有类型的问题，包括任务、错误、子任务、增强、故事等。
- 包括元数据，如问题类型、父问题详情、修复版本、受影响的版本、解决方案、附件、评论、子任务详情、优先级、自定义字段等。
附件

注意： 已归档的项目和问题不会被索引。

大于10 MB的文件内容将不会被提取
默认情况下，权限不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则示例

edit

示例 1: 根据 Jira 问题的状态查询索引内容。

[
  {
    "query": "project = Collaboration AND status = 'In Progress'"
  },
  {
    "query": "status IN ('To Do', 'In Progress', 'Closed')"
  }
]

示例 2: 根据给定项目的优先级查询索引数据。

[
  {
    "query": "priority in (Blocker, Critical) AND project in (ProjA, ProjB, ProjC)"
  }
]

示例 3: 根据受理人和创建时间查询索引数据。

[
  {
    "query": "assignee is EMPTY and created < -1d"
  }
]

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

当data_source设置为Confluence Data Center或Server时，由于所使用的API的限制，连接器将仅获取1000个用户用于访问控制同步。

内容提取

edit

参见内容提取。

自托管连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为Jira连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=jira

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=jira DATA_SIZE=small

已知问题

edit

启用文档级安全会影响性能。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Microsoft SQL 连接器参考

edit

The Elastic Microsoft SQL connector 是一个用于 connector Microsoft SQL 数据库的连接器。这个连接器是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic 版本 8.8.0 及更高版本中作为 托管连接器 提供。要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 Microsoft SQL 连接器

edit

使用用户界面

edit

要创建一个新的 Microsoft SQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的本地 Microsoft SQL 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Microsoft SQL 连接器。

例如：

PUT _connector/my-mssql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Microsoft SQL",
  "service_type": "mssql",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请使用连接器工作流。参见Elastic 托管连接器。

用户需要sysadmin服务器角色。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

以下内容与Elastic连接器框架兼容：

微软 SQL Server 2017, 2019 版本
Azure SQL
Amazon RDS for SQL Server

配置

edit

以下配置字段是设置连接器所必需的：

Host

托管 Microsoft SQL Server 的服务器主机地址。默认值是 127.0.0.1。示例：

192.158.1.38
demo.instance.demo-region.demo.service.com

Port

Microsoft SQL Server 所在的主机端口。默认值是 1433。

Username

Microsoft SQL Server 账户的用户名。

Password

要用于Microsoft SQL Server的账户密码。

Database

Microsoft SQL Server 数据库的名称。示例：

employee_database
customer_database

Comma-separated list of tables

表格列表，用逗号分隔。如果值为 *，Microsoft SQL 连接器将从配置的数据库中获取所有表格的数据。默认值为 *。示例：

table_1, table_2
*

此字段可以通过高级同步规则绕过。

Schema

Microsoft SQL Server 架构的名称。默认值是 dbo。

示例：

dbo
custom_schema

Enable SSL

切换以启用SSL验证。默认值是 False。

SSL certificate

SSL 证书的内容。如果 SSL 被禁用，ssl_ca 值将被忽略。

展开查看示例证书

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

Validate host

切换以启用主机验证。默认值是 False。

文档和同步

edit

未定义主键的表将被跳过。
如果sys.dm_db_index_usage_stats表中的last_user_update对于特定表和数据库不可用，则该表中的所有数据将被同步。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档索引到一个Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下是此连接器的一些高级同步规则示例。

展开查看示例数据

employee 表

emp_id	name	age
3	约翰	28
10	简	35
14	亚历克斯	22

* customer 表

c_id	name	age
2	榆树	24
6	松树	30
9	橡树	34

======= 示例：两个查询

这些规则从employee和customer表中获取所有记录。这些表中的数据将分别同步到Elasticsearch。

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

======= 示例：一个 WHERE 查询

此规则仅从 employee 表中获取 emp_id 大于 5 的记录。只有这些筛选后的记录将被同步到 Elasticsearch。

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

======= 示例：一个JOIN查询

此规则通过在employee和customer表之间执行INNER JOIN来获取记录，条件是employee表中的emp_id与customer表中的c_id匹配。此组合数据的结果将被同步到Elasticsearch。

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

在使用高级规则时，查询可以绕过配置字段 tables。如果查询指定的表在配置中没有出现，这种情况就会发生。如果配置指定 * 来获取所有表，而高级同步规则只请求部分表，这种情况也会发生。

已知问题

edit

此连接器没有已知问题。请参阅已知问题以了解影响所有连接器的问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

此连接器使用通用数据库连接器源代码（分支main，兼容Elastic 9.0）。

查看此数据源的特定附加代码（分支main，兼容Elastic 9.0）。

自管理连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。要使用此连接器，请满足所有自托管连接器要求。

创建一个 Microsoft SQL 连接器

edit

使用界面

edit

要创建一个新的 Microsoft SQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Microsoft SQL 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自管理 Microsoft SQL 自管理连接器。

例如：

PUT _connector/my-mssql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Microsoft SQL",
  "service_type": "mssql"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

用户需要sysadmin服务器角色。

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

兼容性

edit

以下内容与Elastic连接器框架兼容：

微软 SQL Server 2017, 2019 版本
Azure SQL
Amazon RDS for SQL Server

配置

edit

在使用自我管理的连接器工作流程时，最初这些字段将使用在连接器源代码中设置的默认配置。请注意，此数据源使用generic_database.py连接器源代码。

请参考mssql.py以获取更多特定于此数据源的代码。这些可配置字段将在Kibana UI中以其各自的标签呈现。一旦连接成功，用户将能够在Kibana中更新这些值。

以下配置字段是设置连接器所必需的：

host

托管 Microsoft SQL Server 的服务器主机地址。默认值是 127.0.0.1。示例：

192.158.1.38
demo.instance.demo-region.demo.service.com

port

Microsoft SQL Server 所在的主机端口。默认值是 9090。

username

Microsoft SQL Server 账户的用户名。

password

要用于Microsoft SQL Server的账户密码。

database

Microsoft SQL Server 数据库的名称。示例：

employee_database
customer_database

tables

逗号分隔的表列表。如果值为 *，Microsoft SQL 连接器将从配置的数据库中存在的所有表中获取数据。默认值为 *。示例：

table_1, table_2
*

此字段可以通过高级同步规则绕过。

fetch_size

每次请求获取的行数。

retry_count

每次请求失败的重试次数。

schema

Microsoft SQL Server 架构的名称。默认值是 dbo。

示例：

dbo
custom_schema

ssl_enabled

SSL 验证启用。默认值是 False。

ssl_ca

SSL 证书的内容。如果 SSL 被禁用，ssl_ca 值将被忽略。

展开查看示例证书

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

validate_host

主机验证启用。默认值是 False。

使用 Docker 部署

edit

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

步骤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: mssql
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

未定义主键的表将被跳过。
如果sys.dm_db_index_usage_stats表中的last_user_update对于特定表和数据库不可用，则该表中的所有数据将被同步。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档 索引到Elastic部署后将对 所有有权访问 该Elastic部署的用户可见。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下是此连接器的一些高级同步规则示例。

展开查看示例数据

employee 表

emp_id	name	age
3	约翰	28
10	简	35
14	亚历克斯	22

* customer 表

c_id	name	age
2	榆树	24
6	松树	30
9	橡树	34

======= 示例：两个查询

这些规则从employee和customer表中获取所有记录。这些表中的数据将分别同步到Elasticsearch。

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

======= 示例：一个WHERE查询

此规则仅从 employee 表中获取 emp_id 大于 5 的记录。只有这些筛选后的记录将被同步到 Elasticsearch。

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

======= 示例：一个JOIN查询

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 Microsoft SQL 连接器执行端到端测试，请运行以下命令：

make ftest NAME=mssql

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=mssql DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。请参阅已知问题以了解影响所有连接器的问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

此连接器使用通用数据库连接器源代码（分支main，兼容Elastic 9.0）。

查看此数据源的特定附加代码（分支main，兼容Elastic 9.0）。

Elastic MongoDB 连接器参考

edit

The Elastic MongoDB connector 是一个用于 connector MongoDB 数据源的连接器。这个连接器是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和前提条件

edit

此连接器在 Elastic 版本 8.5.0 及更高版本中作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

兼容性

edit

此连接器兼容 MongoDB Atlas 和 MongoDB 3.6 及更高版本。

数据源和您的 Elastic 部署必须能够在网络上相互通信。

配置

edit

每次您创建一个由该连接器管理的索引时，您将创建一个新的连接器配置。您将需要关于数据源的一些或全部信息。

Server hostname

MongoDB主机URI。示例：

mongodb+srv://my_username:my_password@cluster0.mongodb.net/mydb?w=majority
mongodb://127.0.0.1:27017

Username

连接器将使用的MongoDB用户名。

用户必须有权访问配置的数据库和集合。您可能希望为每个连接器创建一个专用的只读用户。

Password

连接器将使用的MongoDB密码。

Database

要同步的 MongoDB 数据库。数据库必须可以使用配置的用户名和密码访问。

Collection

要同步的 MongoDB 集合。该集合必须存在于配置的数据库中。必须使用配置的用户名和密码访问该集合。

Direct connection

切换以使用 MongoDB 客户端的直接连接选项。默认情况下禁用。

SSL/TLS Connection

切换以使用SSL/TLS加密建立与MongoDB服务器的安全连接。确保您的MongoDB部署支持SSL/TLS连接。启用如果您的MongoDB集群使用DNS SRV记录（即MongoDB Atlas用户）。

默认情况下禁用。

Certificate Authority (.pem)

指定来自证书颁发机构的根证书。该证书的值用于验证MongoDB实例提供的证书。

Atlas 用户可以留空，因为 Atlas 使用了一个广泛受信任的根 CA。

Skip certificate verification: 跳过各种证书验证（如果启用了SSL）。默认情况下禁用。

我们强烈建议在生产环境中禁用此选项。

创建一个 MongoDB 连接器

edit

使用界面

edit

要创建一个新的 MongoDB 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 MongoDB 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的原生 MongoDB 连接器。

例如：

PUT _connector/my-mongodb-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from MongoDB",
  "service_type": "mongodb",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请使用连接器工作流。参见Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

示例

edit

此连接器有一个示例。请参阅托管连接器教程 (MongoDB)。

已知问题

edit

MongoDB Atlas 必须启用 SSL

edit

在8.12.0中引入的一个错误导致连接器无法同步Mongo Atlas URL（mongo+srv），除非启用了SSL/TLS。

聚合管道中的表达式和变量

edit

在聚合管道中使用诸如 new Date() 这样的表达式是不可能的。这些表达式不会被底层的 MongoDB 客户端评估，而是会作为字符串传递给 MongoDB 实例。一个可能的解决方法是使用聚合变量。

不正确（new Date() 将被解释为字符串）：

{
    "aggregate": {
        "pipeline": [
            {
                "$match": {
                  "expiresAt": {
                    "$gte": "new Date()"
                  }
                }
            }
        ]
    }
}

正确（使用 $$NOW）：

{
  "aggregate": {
    "pipeline": [
      {
        "$addFields": {
          "current_date": {
            "$toDate": "$$NOW"
          }
        }
      },
      {
        "$match": {
          "$expr": {
            "$gte": [
              "$expiresAt",
              "$current_date"
            ]
          }
        }
      }
    ]
  }
}

使用自签名或自定义CA TLS证书进行连接

edit

目前，MongoDB 连接器在连接到您自行管理的 MongoDB 主机时，不支持使用自签名或自定义 CA 证书。

以下解决方法不应在生产环境中使用。

这可以通过在配置的主机上附加某些查询参数在开发环境中解决。

例如，如果你的主机是 mongodb+srv://my.mongo.host.com，附加 ?tls=true&tlsAllowInvalidCertificates=true 将允许禁用 TLS 证书验证。

在这个示例中，完整的主机将如下所示：

mongodb+srv://my.mongo.host.com/?tls=true&tlsAllowInvalidCertificates=true

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

文档和同步

edit

以下描述了此连接器的默认同步行为。使用同步规则和摄取管道来自定义特定索引的同步。

配置的MongoDB数据库和集合中的所有文档都被提取并转换为Elasticsearch索引中的文档。

连接器为配置的数据库和集合中的每个MongoDB文档创建一个Elasticsearch文档。
对于每个文档，连接器将每个MongoDB字段转换为一个Elasticsearch字段。
对于每个字段，Elasticsearch 动态确定数据类型。

这使得Elasticsearch文档与原始MongoDB文档高度匹配。

当创建第一个文档时，Elasticsearch 映射会被创建。

每次同步都是一次“完整”的同步。对于每个发现的MongoDB文档：

如果不存在，则在Elasticsearch中创建文档。
如果它已经存在于Elasticsearch中，则替换Elasticsearch文档并增加版本号。
如果现有的Elasticsearch文档在MongoDB集合中不再存在，则从Elasticsearch中删除它。
嵌入式文档作为父文档中的object字段存储。

这是递归的，因为嵌入的文档本身可以包含嵌入的文档。

大于10 MB的文件将不会被提取
权限不会同步。所有索引到Elastic部署的文档将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

以下部分描述了此连接器的同步规则。

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级规则用于 MongoDB 可以用来表示 find 查询或聚合管道。它们还可以用于调整在执行这些查询/管道时可用的选项。

`find` 查询

edit

您必须在MongoDB集合上创建一个文本索引，以便执行文本搜索。

对于find查询，此JSON DSL的结构应如下所示：

{
	"find":{
		"filter": {
			// find query goes here
		},
		"options":{
			// query options go here
		}
	}
}

例如：

{
	"find": {
		"filter": {
			"$text": {
				"$search": "garden",
				"$caseSensitive": false
			}
		},
		"skip": 10,
		"limit": 1000
	}
}

find 查询还支持其他选项，例如 projection 对象：

{
  "find": {
    "filter": {
      "languages": [
        "English"
      ],
      "runtime": {
        "$gt":90
      }
    },
    "projection":{
      "tomatoes": 1
    }
  }
}

可用的选项包括：

allow_disk_use（true，false）——当设置为true时，服务器可以在执行查找操作时将临时数据写入磁盘。此选项仅在MongoDB服务器版本4.4及更新版本中可用。
allow_partial_results（true，false）——允许查询在某些分片宕机时获取部分结果。
batch_size（整数）——从MongoDB返回的每个结果批次中的文档数量。
filter（对象）——查询的过滤条件。
limit（整数）——从查询返回的最大文档数量。
max_time_ms（整数）——允许查询运行的最长时间，以毫秒为单位。
no_cursor_timeout（true，false）——服务器通常在非活动期间（10分钟）后超时空闲游标，以防止过度内存使用。设置此选项以防止这种情况。
projection（数组，对象）——结果集中每个文档中要包含或排除的字段。如果是一个数组，它应该至少有一个项目。
return_key（true，false）——返回索引键而不是文档。
show_record_id（true，false）——返回结果集中每个文档的$recordId。
skip（整数）——在返回结果之前要跳过的文档数量。

聚合管道

edit

同样地，对于聚合管道，JSON DSL 的结构应如下所示：

{
	"aggregate":{
		"pipeline": [
			// pipeline elements go here
		],
		"options": {
            // pipeline options go here
		}
    }
}

可用的选项包括：

allowDiskUse (true, false) — 如果允许在聚合期间使用磁盘，则设置为true。
batchSize (Integer) — 每批返回的文档数量。
bypassDocumentValidation (true, false) — 是否跳过文档级别的验证。
collation (Object) — 要使用的排序规则。
comment (String) — 用户提供的评论，附加到此命令。
hint (String) — 用于聚合的索引。
let (Object) — 在管道中使用的变量映射。详见服务器文档。
maxTimeMs (Integer) — 允许聚合运行的最长时间（以毫秒为单位）。

从 Ruby 连接器框架迁移

edit

作为8.8.0版本的一部分，MongoDB连接器已从Ruby连接器框架迁移到Elastic连接器框架。

此更改引入了从MongoDB摄取的数据的轻微格式修改：

嵌套对象的ID字段名称已从“_id”更改为“id”。例如，如果您有一个字段“customer._id”，现在将被命名为“customer.id”。
日期格式已从YYYY-MM-DD'T'HH:mm:ss.fff'Z'更改为YYYY-MM-DD'T'HH:mm:ss

如果您在从8.7.x迁移到8.8.x后MongoDB连接器停止工作，请阅读已知问题中概述的解决方法。如果这不起作用，我们建议删除附加到此连接器的搜索索引，并从头重新创建一个MongoDB连接器。

自托管连接器

edit

查看自托管连接器参考

可用性和前提条件

edit

此连接器也可作为自管理连接器从Elastic 连接器框架中获得。要使用此连接器作为自管理连接器，请满足所有自管理连接器要求。

兼容性

edit

此连接器兼容 MongoDB Atlas 和 MongoDB 3.6 及更高版本。

数据源和您的 Elastic 部署必须能够在网络上相互通信。

配置

edit

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

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

以下配置字段是设置连接器所必需的：

host

MongoDB主机URI。示例：

mongodb+srv://my_username:my_password@cluster0.mongodb.net/mydb?w=majority
mongodb://127.0.0.1:27017

user

连接器将使用的MongoDB用户名。

用户必须有权访问配置的数据库和集合。您可能希望为每个连接器创建一个专用的只读用户。

password

连接器将使用的MongoDB密码。

匿名身份验证仅支持用于测试目的，但不应在生产环境中使用。省略用户名和密码，以使用默认值。

database

要同步的 MongoDB 数据库。数据库必须可以使用配置的用户名和密码访问。

collection

要同步的 MongoDB 集合。该集合必须存在于配置的数据库中。必须使用配置的用户名和密码访问该集合。

direct_connection

是否使用MongoDB客户端的直接连接选项。默认值是False。

ssl_enabled

是否使用SSL/TLS加密建立与MongoDB服务器的安全连接。确保您的MongoDB部署支持SSL/TLS连接。启用如果您的MongoDB集群使用DNS SRV记录（即MongoDB Atlas用户）。

默认值为 False。

ssl_ca

指定来自证书颁发机构的根证书。该证书的值用于验证MongoDB实例提供的证书。

Atlas 用户可以留空，因为 Atlas 使用了一个广泛受信任的根 CA。

tls_insecure: 跳过各种证书验证（如果启用了SSL）。默认值是 False。

我们强烈建议在生产环境中禁用此选项。

创建一个 MongoDB 连接器

edit

使用界面

edit

要创建一个新的 MongoDB 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 MongoDB 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自托管 MongoDB 自托管连接器。

例如：

PUT _connector/my-mongodb-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from MongoDB",
  "service_type": "mongodb"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

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

示例

edit

此连接器有一个示例。请参阅托管连接器教程 (MongoDB)。

已知问题

edit

MongoDB Atlas 必须启用 SSL

edit

在8.12.0版本中引入的一个错误导致连接器无法同步Mongo Atlas URL（mongo+srv），除非启用了SSL/TLS。

聚合管道中的表达式和变量

edit

不正确（new Date() 将被解释为字符串）：

{
    "aggregate": {
        "pipeline": [
            {
                "$match": {
                  "expiresAt": {
                    "$gte": "new Date()"
                  }
                }
            }
        ]
    }
}

正确（使用 $$NOW）：

{
  "aggregate": {
    "pipeline": [
      {
        "$addFields": {
          "current_date": {
            "$toDate": "$$NOW"
          }
        }
      },
      {
        "$match": {
          "$expr": {
            "$gte": [
              "$expiresAt",
              "$current_date"
            ]
          }
        }
      }
    ]
  }
}

使用自签名或自定义CA TLS证书进行连接

edit

目前，MongoDB 连接器在连接到您自行管理的 MongoDB 主机时，不支持使用自签名或自定义 CA 证书。

以下解决方法不应在生产环境中使用。

这可以通过在配置的主机上附加某些查询参数在开发环境中解决。

例如，如果你的主机是 mongodb+srv://my.mongo.host.com，附加 ?tls=true&tlsAllowInvalidCertificates=true 将允许禁用 TLS 证书验证。

在这个示例中，完整的主机将如下所示：

mongodb+srv://my.mongo.host.com/?tls=true&tlsAllowInvalidCertificates=true

Docker 镜像在版本 8.12.0 和 8.12.1 中报错

edit

在8.12.0版本中引入的一个错误会导致使用MongoDB作为数据源时，Connectors docker镜像运行出错。命令行将输出错误信息cannot import name 'coroutine' from 'asyncio'。 此问题已在8.12.2和8.13.0版本中修复。 此错误不会影响Elastic托管的连接器。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

使用 Docker 部署

edit

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

步骤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: mongodb
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

以下描述了此连接器的默认同步行为。使用同步规则和摄取管道来自定义特定索引的同步。

配置的MongoDB数据库和集合中的所有文档都被提取并转换为Elasticsearch索引中的文档。

连接器为配置的数据库和集合中的每个MongoDB文档创建一个Elasticsearch文档。
对于每个文档，连接器将每个MongoDB字段转换为一个Elasticsearch字段。
对于每个字段，Elasticsearch 动态确定数据类型。

这使得Elasticsearch文档与原始MongoDB文档高度匹配。

当创建第一个文档时，Elasticsearch 映射会被创建。

每次同步都是一次“完整”的同步。对于每个发现的MongoDB文档：

如果不存在，则在Elasticsearch中创建文档。
如果它已经存在于Elasticsearch中，则替换Elasticsearch文档并增加版本号。
如果现有的Elasticsearch文档在MongoDB集合中不再存在，则从Elasticsearch中删除它。
嵌入式文档作为父文档中的object字段存储。

这是递归的，因为嵌入的文档本身可以包含嵌入的文档。

大于10 MB的文件将不会被提取
权限不会同步。所有索引到Elastic部署的文档将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

以下部分描述了此连接器的同步规则。

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级规则用于 MongoDB 可以用来表示 find 查询或聚合管道。它们还可以用于调整在执行这些查询/管道时可用的选项。

`find` 查询

edit

您必须在MongoDB集合上创建一个文本索引，以便执行文本搜索。

对于find查询，此JSON DSL的结构应如下所示：

{
	"find":{
		"filter": {
			// find query goes here
		},
		"options":{
			// query options go here
		}
	}
}

例如：

{
	"find": {
		"filter": {
			"$text": {
				"$search": "garden",
				"$caseSensitive": false
			}
		},
		"skip": 10,
		"limit": 1000
	}
}

find 查询还支持其他选项，例如 projection 对象：

{
  "find": {
    "filter": {
      "languages": [
        "English"
      ],
      "runtime": {
        "$gt":90
      }
    },
    "projection":{
      "tomatoes": 1
    }
  }
}

可用的选项包括：

allow_disk_use (true, false) — 当设置为true时，服务器可以在执行查找操作时将临时数据写入磁盘。此选项仅在MongoDB服务器版本4.4及更新版本中可用。
allow_partial_results (true, false) — 允许查询在某些分片宕机时获取部分结果。
batch_size (Integer) — 从MongoDB返回的每个批次结果中的文档数量。
filter (Object) — 查询的过滤条件。
limit (Integer) — 从查询中返回的最大文档数量。
max_time_ms (Integer) — 允许查询运行的最长时间，以毫秒为单位。
no_cursor_timeout (true, false) — 服务器通常在非活动期间（10分钟）后超时空闲游标，以防止过度使用内存。设置此选项以防止这种情况。
projection (Array, Object) — 结果集中每个文档中要包含或排除的字段。如果是一个数组，它应该至少有一个项目。
return_key (true, false) — 返回索引键而不是文档。
show_record_id (true, false) — 返回结果集中每个文档的$recordId。
skip (Integer) — 返回结果前要跳过的文档数量。

聚合管道

edit

同样地，对于聚合管道，JSON DSL 的结构应如下所示：

{
	"aggregate":{
		"pipeline": [
			// pipeline elements go here
		],
		"options": {
            // pipeline options go here
		}
    }
}

可用的选项包括：

allowDiskUse（true，false）— 如果在聚合期间允许使用磁盘，则设置为true。
batchSize（整数）— 每批返回的文档数量。
bypassDocumentValidation（true，false）— 是否跳过文档级别的验证。
collation（对象）— 要使用的排序规则。
comment（字符串）— 附加到此命令的用户提供的注释。
hint（字符串）— 用于聚合的索引。
let（对象）— 在管道中使用的变量映射。详情请参阅服务器文档。
maxTimeMs（整数）— 允许聚合运行的最长时间（以毫秒为单位）。

从Ruby连接器框架迁移

edit

作为8.8.0版本的一部分，MongoDB连接器已从Ruby连接器框架迁移到Elastic连接器框架。

此更改引入了从MongoDB摄取的数据的轻微格式修改：

嵌套对象的ID字段名称已从“_id”更改为“id”。例如，如果您有一个字段“customer._id”，现在将被命名为“customer.id”。
日期格式已从YYYY-MM-DD'T'HH:mm:ss.fff'Z'更改为YYYY-MM-DD'T'HH:mm:ss

Elastic MySQL 连接器参考

edit

The Elastic MySQL connector 是一个用于 connector MySQL 数据源的连接器。这个连接器是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和前提条件

edit

此连接器在 Elastic 版本 8.5.0 及更高版本 中作为 托管连接器 提供。要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

除了上述共享要求外，此连接器没有其他额外的前提条件。

兼容性

edit

此连接器兼容 MySQL 5.6 及更高版本。

该连接器也兼容于MariaDB数据库，兼容上述内容。

数据源和您的 Elastic 部署必须能够在网络上相互通信。

创建一个 MySQL 连接器

edit

使用界面

edit

要创建一个新的 MySQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 MySQL 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 MySQL 连接器。

例如：

PUT _connector/my-mysql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from MySQL",
  "service_type": "mysql",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

配置

edit

每次您创建一个由该连接器管理的索引时，您将创建一个新的连接器配置。您将需要关于数据源的一些或全部信息。

Host

MySQL主机（不包括端口）的IP地址或域名。示例：

192.158.1.38
localhost

Port

MySQL 主机的端口。示例：

3306
3307

Username

连接器将使用的MySQL用户名。

用户必须有权访问配置的数据库。您可能希望为每个连接器创建一个专用的只读用户。

Password

连接器将使用的MySQL密码。

Database

要同步的 MySQL 数据库。数据库必须可以使用配置的用户名和密码访问。

示例：

products
orders

Comma-separated list of tables

配置的数据库中要同步的表。一个或多个表名，用逗号分隔。这些表必须可以使用配置的用户名和密码访问。

示例：

furniture, food, toys
笔记本电脑

使用高级同步规则时，可以绕过此字段。

Enable SSL

是否启用SSL验证。默认值是True。

SSL Certificate

SSL证书的内容。如果SSL被禁用，SSL证书的值将被忽略。

展开查看示例证书

已知问题

edit

此连接器存在以下已知问题：

从技术预览连接器（8.7 或更早版本）升级到 8.8 将导致 MySQL 连接器配置无效。

MySQL 连接器在 8.8 之前的版本可能会缺少一些运行连接器所需的配置字段。如果您希望在从 8.7 或更早版本升级后继续使用您的 MySQL 连接器，请运行以下脚本来修复您的连接器配置。这将用缺失的字段填充配置。然后，配置所需的其他信息将由自管理连接器自动添加。

POST /.elastic-connectors/_update/connector_id
{
  "doc" : {
    "configuration": {
      "tables": {
        "type": "list",
        "value": "*"
      },
      "ssl_enabled": {
        "type": "bool",
        "value": false
      },
      "ssl_ca": {
        "type": "str",
        "value": ""
      },
      "fetch_size": {
        "type": "int",
        "value": 50
      },
      "retry_count": {
        "type": "int",
        "value": 3
      }
    }
  }
}

升级到8.8不会迁移MySQL同步规则。

升级后，您必须重新创建同步规则。

查看影响所有连接器的已知问题。

文档和同步

edit

以下描述了此连接器的默认同步行为。使用同步规则和摄取管道来自定义特定索引的同步。

在您的连接器配置中包含的所有MySQL数据库记录都会被提取并转换为您的Elasticsearch索引中的文档。

对于MySQL数据库表中的每一行，连接器会创建一个Elasticsearch文档。
对于每一列，连接器会将该列转换为一个Elasticsearch字段。
Elasticsearch 动态映射 MySQL数据类型为Elasticsearch数据类型。
未定义主键的表将被跳过。
表示其他记录的字段值将被替换为该记录的主键（复合主键使用_连接）。

当创建第一个文档时，Elasticsearch 映射会被创建。

每次同步都是一次“完整”同步。

对于每个发现的MySQL行：

如果不存在，则在Elasticsearch中创建文档。
如果它已经存在于Elasticsearch中，则替换Elasticsearch文档并增加版本号。
如果现有的Elasticsearch文档在MySQL表中不再存在，则从Elasticsearch中删除它。

大于10 MB的文件将不会被提取
默认情况下，权限不会同步。 所有文档 索引到一个Elastic部署将对 所有有权访问 该Elastic部署的用户可见。

同步规则

edit

以下部分描述了此连接器的同步规则。

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级规则可以用于将任意SQL语句传递给MySQL实例。

您需要在“tables”字段中指定自定义查询中使用的表。

例如：

[
    {
        "tables": ["table1", "table2"],
        "query": "SELECT ... FROM ..."
    }
]

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和前提条件

edit

此连接器在 Elastic 版本 8.5.0 及更高版本 中作为 托管连接器 提供。要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

此连接器也可作为自管理连接器从Elastic 连接器框架中获得。要使用此连接器作为自管理连接器，请满足所有自管理连接器要求。

除了上述共享要求外，此连接器没有其他额外的前提条件。

创建一个 MySQL 连接器

edit

使用界面

edit

要创建一个新的 MySQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 MySQL 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 MySQL 自管理连接器。

例如：

PUT _connector/my-mysql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from MySQL",
  "service_type": "mysql"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请使用连接器工作流。参见Elastic 托管连接器。

要使用此连接器作为自管理连接器，请参阅自管理连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

此连接器兼容 MySQL 5.6 及更高版本。

该连接器也兼容于MariaDB数据库，兼容上述内容。

数据源和您的 Elastic 部署必须能够在网络上相互通信。

配置

edit

每次您创建一个由该连接器管理的索引时，您将创建一个新的连接器配置。您将需要关于数据源的一些或全部信息。

Host

MySQL主机（不包括端口）的IP地址或域名。示例：

192.158.1.38
localhost

Port

MySQL 主机的端口。示例：

3306
3307

Username

连接器将使用的MySQL用户名。

用户必须有权访问配置的数据库。您可能希望为每个连接器创建一个专用的只读用户。

Password

连接器将使用的MySQL密码。

Database

要同步的 MySQL 数据库。数据库必须可以使用配置的用户名和密码访问。

示例：

products
orders

Tables

配置的数据库中要同步的表。一个或多个表名，用逗号分隔。这些表必须可以使用配置的用户名和密码访问。

示例：

furniture, food, toys
laptops

Enable SSL

是否启用SSL验证。默认值是True。

SSL Certificate

SSL证书的内容。如果SSL被禁用，SSL证书的值将被忽略。

展开查看示例证书

已知问题

edit

此连接器存在以下已知问题：

从技术预览连接器（8.7 或更早版本）升级到 8.8 将导致 MySQL 连接器配置无效。

POST /.elastic-connectors/_update/connector_id
{
  "doc" : {
    "configuration": {
      "tables": {
        "type": "list",
        "value": "*"
      },
      "ssl_enabled": {
        "type": "bool",
        "value": false
      },
      "ssl_ca": {
        "type": "str",
        "value": ""
      },
      "fetch_size": {
        "type": "int",
        "value": 50
      },
      "retry_count": {
        "type": "int",
        "value": 3
      }
    }
  }
}

升级到8.8不会迁移MySQL同步规则。

升级后，您必须重新创建同步规则。

查看影响所有连接器的已知问题。

文档和同步

edit

以下描述了此连接器的默认同步行为。使用同步规则和摄取管道来自定义特定索引的同步。

在您的连接器配置中包含的所有MySQL数据库记录都会被提取并转换为您的Elasticsearch索引中的文档。

对于MySQL数据库表中的每一行，连接器会创建一个Elasticsearch文档。
对于每一列，连接器会将该列转换为一个Elasticsearch字段。
Elasticsearch 动态映射 MySQL数据类型为Elasticsearch数据类型。
未定义主键的表将被跳过。
表示其他记录的字段值将被替换为该记录的主键（复合主键使用_连接）。

当创建第一个文档时，Elasticsearch 映射会被创建。

每次同步都是一次“完整”同步。

对于每个发现的MySQL行：

如果不存在，则在Elasticsearch中创建文档。
如果它已经存在于Elasticsearch中，则替换Elasticsearch文档并增加版本号。
如果现有的Elasticsearch文档在MySQL表中不再存在，则从Elasticsearch中删除它。

使用 Docker 部署

edit

您可以使用 Docker 将 MySQL 连接器部署为自管理连接器。请按照以下说明操作。

步骤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: mysql
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

同步规则

edit

以下部分描述了此连接器的同步规则。

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级规则可以用于将任意SQL语句传递给MySQL实例。

您需要在“tables”字段中指定自定义查询中使用的表。

例如：

[
    {
        "tables": ["table1", "table2"],
        "query": "SELECT ... FROM ..."
    }
]

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

弹性网络驱动器连接器参考

edit

弹性网络驱动器连接器是一个用于网络驱动器数据源的连接器。该连接器使用Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

弹性管理连接器参考

edit

查看Elastic 托管连接器参考

可用性和前提条件

edit

此连接器自 8.9.1 版本起，在 Elastic Cloud 上作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

配置

edit

以下配置字段是设置连接器所必需的：

Username

网络驱动器的账户用户名。用户必须对提供的文件夹路径至少具有读取权限。

Password

用于爬取网络驱动器的账户密码。

IP address

网络驱动器所在服务器的IP地址。默认值是 127.0.0.1。

Port

网络驱动器服务可用的服务器端口。默认值是 445。

Path

连接器将爬取以获取文件的网络驱动器路径。这是通过SMB共享的文件夹的名称。连接器使用Python smbprotocol库，该库支持SMB v2和v3。
仅接受一个路径——可以指定父文件夹以扩大范围。
驱动路径应使用正斜杠作为路径分隔符。示例：
- admin/bin

Enable document level security

切换以启用文档级安全（DLS）。启用时：

Full syncs will fetch access control lists for each document and store them in the _allow_access_control field.
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。默认值是 false。

有关更多信息，包括先决条件和限制，请参阅文档级安全。

Identity mappings

包含用户和组SIDs的CSV文件路径（适用于Linux网络驱动器）。

文件应按如下格式编排：

字段由分号分隔（;）
每行三个字段：Username;User-SID;Group-SIDs
组-SIDs是以逗号分隔的，并且是可选的。

示例包含一个用户名、用户-sid且没有组：
```
user1;S-1;
```
示例包含一个用户名、用户SID和两个组：
```
user1;S-1;S-11,S-22
```

文档和同步

edit

连接器将文件夹同步为Elasticsearch中的单独文档。以下字段将被添加到文档类型 folder 中：

创建时间
标题
路径
修改
时间
ID

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。 DLS 有助于同步文件夹和文件权限，包括用户和组级别的权限。

注意： 请参考搜索应用程序中的DLS，了解如何在启用DLS的情况下搜索数据，当构建搜索应用程序时。

可用性

edit

当前版本的网络驱动器连接器仅支持Windows网络驱动器的DLS支持。
要在Windows网络驱动器中获取用户和组，连接器配置中添加的账户凭据应有权访问托管网络驱动器的Windows服务器的Powershell。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。此连接器的高级同步规则使用全局模式。

每条规则必须包含一个全局模式。该模式随后会与配置的驱动器路径内的所有可用文件夹路径进行匹配。
模式必须以连接器中配置的drive_path字段开头。
如果模式匹配任何可用的文件夹路径，则将获取这些文件夹内的直接内容。

以下部分提供了此连接器的高级同步规则示例。

======= 递归索引文件夹内的文件和文件夹

[
  {
    "pattern": "Folder-shared/a/mock/**"
  },
  {
    "pattern": "Folder-shared/b/alpha/**"
  }
]

======= 直接在文件夹内索引文件和文件夹

[
  {
    "pattern": "Folder-shared/a/b/test"
  }
]

======= 直接在一组文件夹内索引文件和文件夹

[
  {
    "pattern": "Folder-shared/org/*/all-tests/test[135]"
  }
]

======= 排除匹配模式的文件和文件夹

[
  {
    "pattern": "Folder-shared/**/all-tests/test[!7]"
  }
]

内容提取

edit

参见内容提取。

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器与 Elastic 版本8.6.0+兼容。

要使用此连接器，请满足所有自我管理连接器的要求。

用法

edit

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

配置

edit

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

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

以下配置字段是设置连接器所必需的：

username

网络驱动器的账户用户名。用户必须对提供的文件夹路径至少具有读取权限。

password

用于爬取网络驱动器的账户密码。

server_ip

网络驱动器所在服务器的IP地址。默认值是 127.0.0.1。

server_port

网络驱动器服务可用的服务器端口。默认值是 445。

drive_path

连接器将爬取以获取文件的网络驱动器路径。这是通过SMB共享的文件夹的名称。连接器使用Python smbprotocol库，该库支持SMB v2和v3。
仅接受一个路径——可以指定父文件夹以扩大范围。
驱动路径应使用正斜杠作为路径分隔符。示例：
- admin/bin

use_document_level_security

切换以启用文档级安全（DLS）。启用时：

Full syncs will fetch access control lists for each document and store them in the _allow_access_control field.
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

有关更多信息，包括先决条件和限制，请参阅文档级安全。

drive_type

要爬取的网络驱动器类型。以下选项可供选择：

Windows
Linux

identity_mappings

包含用户和组SIDs的CSV文件路径（适用于Linux网络驱动器）。

文件应按如下格式编排：

字段由分号分隔（;）
每行三个字段：Username;User-SID;Group-SIDs
组-SIDs是以逗号分隔的，并且是可选的。

示例包含一个用户名、用户-sid且没有组：
```
user1;S-1;
```
示例包含一个用户名、用户SID和两个组：
```
user1;S-1;S-11,S-22
```

使用 Docker 部署

edit

您可以使用 Docker 将网络驱动器连接器部署为自托管连接器。请按照以下说明操作。

步骤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: network_drive
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

连接器将文件夹同步为Elasticsearch中的单独文档。以下字段将被添加到文档类型 folder 中：

创建时间
标题
路径
修改
时间
ID

大于10 MB的文件内容将不会被提取
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。 DLS 有助于同步文件夹和文件权限，包括用户和组级别的权限。

注意： 请参考搜索应用程序中的DLS，了解如何在启用DLS的情况下搜索数据，当构建搜索应用程序时。

可用性

edit

网络驱动器自管理连接器为Windows和Linux网络驱动器提供DLS支持。
要在Windows网络驱动器中获取用户和组，连接器配置中添加的账户凭据应具有访问托管网络驱动器的Windows服务器的Powershell的权限。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。此连接器的高级同步规则使用全局模式。

每条规则必须包含一个全局模式。该模式随后会与配置的驱动器路径内的所有可用文件夹路径进行匹配。
该模式必须以连接器中配置的drive_path字段开头。
如果该模式匹配到任何可用的文件夹路径，则这些文件夹内的内容将直接被获取。

以下部分提供了此连接器的高级同步规则示例。

======= 递归索引文件夹内的文件和文件夹

[
  {
    "pattern": "Folder-shared/a/mock/**"
  },
  {
    "pattern": "Folder-shared/b/alpha/**"
  }
]

======= 直接在文件夹内索引文件和文件夹

[
  {
    "pattern": "Folder-shared/a/b/test"
  }
]

======= 直接在一组文件夹内索引文件和文件夹

[
  {
    "pattern": "Folder-shared/org/*/all-tests/test[135]"
  }
]

======= 排除匹配模式的文件和文件夹

[
  {
    "pattern": "Folder-shared/**/all-tests/test[!7]"
  }
]

内容提取

edit

参见内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要执行网络驱动器自管理连接器的功能测试，请运行以下命令：

$ make ftest NAME=network_drive

默认情况下，这将使用中等大小的数据集。为了加快测试速度，请添加DATA_SIZE=small标志：

make ftest NAME=network_drive DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Notion 连接器参考

edit

Notion 连接器是使用 Elastic 连接器框架用 Python 编写的。查看此连接器的 源代码（分支 main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此托管连接器在 Elastic 8.14.0 版本中作为 Elastic Cloud 上的托管服务引入。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

此连接器处于测试版，可能会发生变化。设计和代码不如正式发布的功能成熟，并且是按原样提供的，不提供任何保证。测试版功能不受正式发布功能的SLA支持。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择Notion图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

创建一个 Notion 连接器

edit

使用用户界面

edit

要创建一个新的 Notion 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Notion 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Notion 连接器。

例如：

PUT _connector/my-notion-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Notion",
  "service_type": "notion",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

连接到 Notion

edit

要连接到 Notion，用户需要为其 Notion 工作区创建一个内部集成，该集成可以使用内部集成密钥令牌访问资源。使用以下设置配置集成：

用户必须从功能选项卡中为该集成授予内容、评论和用户功能的READ权限。
用户必须手动将集成添加为连接到工作区中的顶级页面。子页面将自动继承父页面的连接。

配置

edit

请注意以下配置字段：

Notion Secret Key(required)

分配给您的集成用于特定工作区的密钥令牌。示例：

zyx-123453-12a2-100a-1123-93fd09d67394

Databases(required)

要由连接器获取的数据库名称的逗号分隔列表。如果值为 *，连接器将获取工作区中所有可用的数据库。示例：

database1, database2
*

Pages(required)

逗号分隔的页面名称列表，由连接器获取。如果值为*，连接器将获取工作区中所有可用的页面。示例：

*
Page1, Page2

Index Comments

切换以启用从配置的页面、数据库及其相应子块中获取和索引Notion工作区的评论。默认值为False。

启用评论索引可能会由于增加的网络调用而影响连接器性能。因此，默认情况下此值为False。

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

页面
- 包含元数据，如页面名称、id、最后更新时间等。
块
- 包含元数据，如标题、类型、id、内容（如果是文件块）等。
数据库
- 包含元数据，如名称、id、记录、大小等。
用户
- 包含元数据，如名称、id、电子邮件地址等。
评论
- 包含内容和元数据，如id、最后更新时间、创建者等。
- 注意：默认情况下不包含评论。

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问相关Elasticsearch索引的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则，用于在将数据索引到Elasticsearch之前过滤Notion中的数据。高级同步规则通过特定于源的DSL JSON片段定义。

Notion的高级同步规则采用以下参数：

searches: Notion的搜索过滤器，用于按标题搜索。
query: Notion的数据库查询过滤器，用于获取特定数据库。

示例

edit

======= 示例 1

索引每个标题包含 Demo Page 的页面：

  {
    "searches": [
      {
        "filter": {
          "value": "page"
        },
        "query": "Demo Page"
      }
    ]
  }

======= 示例 2

索引每个标题包含Demo Database的数据库：

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    }
  ]
}

======= 示例 3

索引每个标题包含Demo Database的数据库和每个标题包含Demo Page的页面：

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    },
    {
      "filter": {
        "value": "page"
      },
      "query": "Demo Page"
    }
  ]
}

======= 示例 4

索引工作区中的所有页面：

{
  "searches": [
    {
      "filter": {
        "value": "page"
      },
      "query": ""
    }
  ]
}

======= 示例 5

索引所有连接到工作区的页面和数据库：

{
  "searches":[
    {
      "query":""
    }
  ]
}

======= 示例 6

索引数据库中所有行的记录，其中列Task completed的值为true，并且其属性（数据类型）为复选框：

{
  "database_query_filters": [
    {
      "filter": {
          "property": "Task completed",
          "checkbox": {
            "equals": true
          }
      },
      "database_id": "database_id"
    }
  ]
}

======= 示例 7

索引特定数据库的所有行：

{
  "database_query_filters": [
    {
      "database_id": "database_id"
    }
  ]
}

======= 示例 8

索引所有定义在 searches 和 database_query_filters 中的块：

{
  "searches":[
    {
      "query":"External tasks",
      "filter":{
        "value":"database"
      }
    },
    {
      "query":"External tasks",
      "filter":{
        "value":"page"
      }
    }
  ],
  "database_query_filters":[
    {
      "database_id":"notion_database_id1",
      "filter":{
        "property":"Task completed",
        "checkbox":{
          "equals":true
        }
      }
    }
  ]
}

在这个示例中，filter 对象的语法是根据 Notion 文档为 database_query_filters 定义的。

已知问题

edit

新页面的更新可能不会立即反映在Notion API中。

如果在添加页面后立即启动同步，这可能导致这些页面未被连接器索引。为了确保所有页面都被索引，请在向Notion添加页面几分钟后启动同步。
Notion的公共API不支持链接的数据库。

Notion 中的链接数据库是数据库的副本，可以进行过滤、排序和以不同方式查看。要获取链接数据库中的信息，您需要定位原始的源数据库。更多详情请参阅 Notion 文档。
文档的属性对象在详情下被序列化为字符串。

Notion的properties模式不一致，如果将其作为对象索引到Elasticsearch中，可能会导致document_parsing_exceptions。出于这个原因，properties对象被序列化为JSON字符串，并存储在details字段下。如果你需要从properties中搜索子对象，你可能需要在摄取管道中对details字段进行后处理，以提取你想要的子字段。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic 8.13.0 中引入，作为 自托管 的自托管连接器提供。

要使用此连接器，请满足所有自我管理连接器的前提条件。重要的是，您必须在您自己的基础设施上部署连接器服务。您有两个部署选项：

从源代码运行连接器服务。如果你熟悉Python并且希望在本地快速迭代，请使用此选项。
在Docker中运行连接器服务。如果你想将连接器部署到服务器，或者使用容器编排平台，请使用此选项。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择Notion图块。

有关其他操作，请参阅 Kibana 中的连接器 UI。

创建一个 Notion 连接器

edit

使用用户界面

edit

要创建一个新的 Notion 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Notion 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 Notion 自管理连接器。

例如：

PUT _connector/my-notion-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Notion",
  "service_type": "notion"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

连接到 Notion

edit

要连接到 Notion，用户需要为其 Notion 工作区创建一个内部集成，该集成可以使用内部集成密钥令牌访问资源。使用以下设置配置集成：

用户必须从功能选项卡中为该集成授予内容、评论和用户功能的READ权限。
用户必须手动将集成添加为连接到工作区中的顶级页面。子页面将自动继承父页面的连接。

使用 Docker 部署

edit

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

步骤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: notion
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

请注意以下配置字段：

Notion Secret Key(required)

分配给您的集成用于特定工作区的密钥令牌。示例：

zyx-123453-12a2-100a-1123-93fd09d67394

Databases(required)

要由连接器获取的数据库名称的逗号分隔列表。如果值为 *，连接器将获取工作区中所有可用的数据库。示例：

database1, database2
*

Pages(required)

逗号分隔的页面名称列表，由连接器获取。如果值为*，连接器将获取工作区中所有可用的页面。示例：

*
Page1, Page2

Index Comments

切换以启用从配置的页面、数据库及其相应子块的Notion工作区中获取和索引评论。默认值为False。

启用评论索引可能会由于增加的网络调用而影响连接器性能。因此，默认情况下此值为False。

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

页面
- 包含元数据，如页面名称、id、最后更新时间等。
块
- 包含元数据，如标题、类型、id、内容（在文件块的情况下）等。
数据库
- 包含元数据，如名称、id、记录、大小等。
用户
- 包含元数据，如名称、id、电子邮件地址等。
评论
- 包含内容和元数据，如id、最后更新时间、创建者等。
- 注意：默认情况下不包含评论。

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问相关Elasticsearch索引的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则，用于在将数据索引到Elasticsearch之前过滤Notion中的数据。高级同步规则通过特定于源的DSL JSON片段定义。

Notion的高级同步规则采用以下参数：

searches: Notion的搜索过滤器，用于按标题搜索。
query: Notion的数据库查询过滤器，用于获取特定数据库。

示例

edit

======= 示例 1

索引每个标题包含 Demo Page 的页面：

  {
    "searches": [
      {
        "filter": {
          "value": "page"
        },
        "query": "Demo Page"
      }
    ]
  }

======= 示例 2

索引每个标题包含Demo Database的数据库：

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    }
  ]
}

======= 示例 3

索引每个标题包含Demo Database的数据库和每个标题包含Demo Page的页面：

{
  "searches": [
    {
      "filter": {
        "value": "database"
      },
      "query": "Demo Database"
    },
    {
      "filter": {
        "value": "page"
      },
      "query": "Demo Page"
    }
  ]
}

======= 示例 4

索引工作区中的所有页面：

{
  "searches": [
    {
      "filter": {
        "value": "page"
      },
      "query": ""
    }
  ]
}

======= 示例 5

索引所有连接到工作区的页面和数据库：

{
  "searches":[
    {
      "query":""
    }
  ]
}

======= 示例 6

索引数据库中所有行的记录，其中列Task completed的值为true，并且其属性（数据类型）为复选框：

{
  "database_query_filters": [
    {
      "filter": {
          "property": "Task completed",
          "checkbox": {
            "equals": true
          }
      },
      "database_id": "database_id"
    }
  ]
}

======= 示例 7

索引特定数据库的所有行：

{
  "database_query_filters": [
    {
      "database_id": "database_id"
    }
  ]
}

======= 示例 8

索引所有定义在 searches 和 database_query_filters 中的块：

{
  "searches":[
    {
      "query":"External tasks",
      "filter":{
        "value":"database"
      }
    },
    {
      "query":"External tasks",
      "filter":{
        "value":"page"
      }
    }
  ],
  "database_query_filters":[
    {
      "database_id":"notion_database_id1",
      "filter":{
        "property":"Task completed",
        "checkbox":{
          "equals":true
        }
      }
    }
  ]
}

在这个示例中，filter 对象的语法是根据 Notion 文档为 database_query_filters 定义的。

连接器客户端操作

edit

端到端测试

edit

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 Notion 源来运行此测试。

更多详情请参阅连接器测试。

要为 Notion 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=notion

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=notion DATA_SIZE=small

默认情况下，DATA_SIZE=MEDIUM。

已知问题

edit

新页面的更新可能不会立即反映在Notion API中。

如果在添加页面后立即启动同步，这可能导致这些页面未被连接器索引。为了确保所有页面都被索引，请在向Notion添加页面几分钟后启动同步。
Notion的公共API不支持链接的数据库。

Notion 中的链接数据库是数据库的副本，可以进行过滤、排序和以不同方式查看。要获取链接数据库中的信息，您需要定位原始的源数据库。更多详情请参阅 Notion 文档。
文档的属性对象在详情下被序列化为字符串。

Notion的properties模式不一致，如果将其作为对象索引到Elasticsearch中，可能会导致document_parsing_exceptions。出于这个原因，properties对象被序列化为JSON字符串，并存储在details字段下。如果你需要从properties中搜索子对象，你可能需要在摄取管道中对details字段进行后处理，以提取你想要的子字段。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic OneDrive 连接器参考

edit

The Elastic OneDrive connector 是一个用于 OneDrive 的 connector。这个 connector 是使用 Elastic connector framework 用 Python 编写的。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自 Elastic 版本 8.11.0 起，此连接器作为 托管连接器 提供。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个OneDrive连接器

edit

使用用户界面

edit

要创建一个新的 OneDrive 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 OneDrive 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 OneDrive 连接器。

例如：

PUT _connector/my-onedrive-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from OneDrive",
  "service_type": "onedrive",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到OneDrive

edit

要连接到 OneDrive，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。

请按照以下步骤操作：

转到 Azure 门户并使用您的 Azure 账户登录。
导航到 Azure Active Directory 服务。
从左侧菜单中选择 应用注册。
点击 新注册 按钮以注册一个新应用程序。
为您的应用提供一个名称，并可选地选择支持的账户类型（例如，单租户、多租户）。
点击注册按钮以创建应用注册。
注册完成后，您将被重定向到应用的概述页面。请记下 应用程序（客户端）ID 值，因为您稍后会需要它。
向下滚动到 API 权限 部分，然后点击 添加权限 按钮。
在 请求 API 权限 窗格中，选择 Microsoft Graph 作为 API。
选择应用程序权限，并在 应用程序 标签下选择以下权限：User.Read.All, File.Read.All
点击 添加权限 按钮以将所选权限添加到您的应用。最后，点击 授予管理员同意 按钮以授予应用所需的权限。此步骤需要管理员权限。注意：如果您不是管理员，您需要请求管理员通过他们的 Azure 门户授予同意。
点击 证书和密钥 标签。转到客户端密钥。生成一个新的客户端密钥，并记下 Value 列中的字符串。

配置

edit

以下配置字段是必需的：

Azure application Client ID

Azure 应用程序的唯一标识符，可在应用程序的概述页面上找到。示例：

ab123453-12a2-100a-1123-93fd09d67394

Azure application Client Secret

应用程序在请求令牌时用于证明其身份的字符串值，可在 Azure 应用程序菜单的 证书和密钥 选项卡下找到。示例：

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

Azure application Tenant ID

Azure Active Directory 实例的唯一标识符。示例：

123a1b23-12a3-45b6-7c8d-fc931cfb448d

Enable document level security

切换以启用文档级安全。启用时：

完整同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容被检索的速度。

内容提取

edit

更多详情请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

文件
- 包含元数据，如文件名、路径、大小、内容等。
文件夹

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限默认不会同步。您必须首先启用DLS。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。此功能默认情况下适用于OneDrive连接器。请参阅配置以了解如何为此连接器启用DLS。

有关此功能的更多详细信息，请参阅文档级安全。

请参阅搜索应用程序中的DLS，了解在构建搜索应用程序时如何使用启用了DLS的数据进行摄取。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下是此连接器的一些高级同步规则示例。

======= 示例 1

此规则跳过对扩展名为 .xlsx 和 .docx 的文件进行索引。所有其他文件和文件夹将被索引。

[
  {
    "skipFilesWithExtensions": [".xlsx" , ".docx"]
  }
]

======= 示例 2

此规则专注于索引由 user1-domain@onmicrosoft.com 和 user2-domain@onmicrosoft.com 拥有的文件和文件夹，但排除了扩展名为 .py 的文件。

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 3

此规则仅索引根文件夹中直接包含的文件和文件夹，不包括任何.md文件。

[
  {
    "skipFilesWithExtensions": [".md"],
    "parentPathPattern": "/drive/root:"
  }
]

======= 示例 4

此规则索引由 user1-domain@onmicrosoft.com 和 user3-domain@onmicrosoft.com 拥有的文件和文件夹，这些文件和文件夹直接位于 abc 文件夹内，而 abc 文件夹是根目录下 hello 目录中任何文件夹的子文件夹。排除扩展名为 .pdf 和 .py 的文件。

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user3-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".pdf", ".py"],
    "parentPathPattern": "/drive/root:/hello/**/abc"
  }
]

======= 示例 5

此示例包含两条规则。第一条规则索引由user1-domain@onmicrosoft.com和user2-domain@onmicrosoft.com拥有的所有文件和文件夹。第二条规则为所有其他用户索引文件，但跳过具有.py扩展名的文件。

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"]
  },
  {
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 6

此示例包含两条规则。第一条规则索引所有由user1-domain@onmicrosoft.com和user2-domain@onmicrosoft.com拥有的文件，排除.md文件。第二条规则递归索引abc文件夹内的文件和文件夹。

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".md"]
  },
  {
    "parentPathPattern": "/drive/root:/abc/**"
  }
]

内容提取

edit

参见内容提取。

已知问题

edit

启用文档级安全会影响性能。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。

这个自托管连接器兼容 Elastic 版本 8.10.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个OneDrive连接器

edit

使用用户界面

edit

要创建一个新的 OneDrive 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 OneDrive 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 OneDrive 自管理连接器。

例如：

PUT _connector/my-onedrive-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from OneDrive",
  "service_type": "onedrive"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到OneDrive

edit

要连接到 OneDrive，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。

请按照以下步骤操作：

转到 Azure 门户并使用您的 Azure 账户登录。
导航到 Azure Active Directory 服务。
从左侧菜单中选择 应用注册。
点击 新注册 按钮以注册一个新应用程序。
为您的应用提供一个名称，并可选地选择支持的账户类型（例如，单租户、多租户）。
点击注册按钮以创建应用注册。
注册完成后，您将被重定向到应用的概述页面。请记下 应用程序（客户端）ID 值，因为您稍后会需要它。
向下滚动到 API 权限 部分，然后点击 添加权限 按钮。
在 请求 API 权限 窗格中，选择 Microsoft Graph 作为 API。
选择应用程序权限，并在 应用程序 选项卡下选择以下权限：User.Read.All, File.Read.All
点击 添加权限 按钮以将所选权限添加到您的应用。最后，点击 授予管理员同意 按钮以授予应用所需的权限。此步骤需要管理员权限。注意：如果您不是管理员，您需要请求管理员通过他们的 Azure 门户授予同意。
点击 证书和密钥 选项卡。转到客户端密钥。生成一个新的客户端密钥，并记下 Value 列中的字符串。

使用 Docker 部署

edit

自托管连接器运行在您自己的基础设施上。

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

步骤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: onedrive
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

以下配置字段是必需的：

client_id

Azure 应用程序客户端 ID，您的 Azure 应用程序的唯一标识符，可在应用程序的概述页面上找到。示例：

ab123453-12a2-100a-1123-93fd09d67394

client_secret

Azure 应用程序客户端密钥，应用程序在请求令牌时用于证明其身份的字符串值。可在 Azure 应用程序菜单的 证书 & 密钥 选项卡下找到。示例：

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

tenant_id

Azure 应用程序租户 ID：您的 Azure Active Directory 实例的唯一标识符。示例：

123a1b23-12a3-45b6-7c8d-fc931cfb448d

retry_count

请求OneDrive失败后的重试次数。默认值是3。

use_document_level_security

切换以启用文档级安全。启用时：

Full syncs will fetch access control lists for each document and store them in the _allow_access_control field.
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容被检索的速度。

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要禁用摄取管道设置中的文本提取。默认值为False。

内容提取

edit

更多详情请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

文件
- 包含元数据，如文件名、路径、大小、内容等。
文件夹

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
默认情况下，权限不会同步。您必须首先启用DLS。否则，索引到Elastic部署的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。此功能默认情况下适用于OneDrive连接器。请参阅配置以了解如何为此连接器启用DLS。

有关此功能的更多详细信息，请参阅文档级安全。

请参阅搜索应用程序中的DLS，了解在构建搜索应用程序时如何使用启用了DLS的数据进行摄取。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下是此连接器的一些高级同步规则示例。

======= 示例 1

此规则跳过对扩展名为 .xlsx 和 .docx 的文件进行索引。所有其他文件和文件夹将被索引。

[
  {
    "skipFilesWithExtensions": [".xlsx" , ".docx"]
  }
]

======= 示例 2

此规则专注于索引由 user1-domain@onmicrosoft.com 和 user2-domain@onmicrosoft.com 拥有的文件和文件夹，但排除了扩展名为 .py 的文件。

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 3

此规则仅索引根文件夹中直接包含的文件和文件夹，不包括任何.md文件。

[
  {
    "skipFilesWithExtensions": [".md"],
    "parentPathPattern": "/drive/root:"
  }
]

======= 示例 4

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user3-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".pdf", ".py"],
    "parentPathPattern": "/drive/root:/hello/**/abc"
  }
]

======= 示例 5

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"]
  },
  {
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 6

[
  {
    "owners": ["user1-domain@onmicrosoft.com", "user2-domain@onmicrosoft.com"],
    "skipFilesWithExtensions": [".md"]
  },
  {
    "parentPathPattern": "/drive/root:/abc/**"
  }
]

内容提取

edit

参见内容提取。

自托管连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为GitHub连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=onedrive

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=onedrive DATA_SIZE=small

已知问题

edit

启用文档级安全会影响性能。

为您的连接器启用DLS会导致显著的性能下降，因为为此功能所需的向数据源发出的API调用是速率受限的。这会影响您的内容可以被检索的速度。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic OpenText Documentum 连接器参考

edit

此连接器是一个示例连接器，作为自定义化的构建块，并且可能会发生变化。其源代码目前位于一个功能分支上，尚未成为主Elastic连接器代码库的一部分。设计和代码的成熟度低于受支持的功能，并且是按原样提供的，不提供任何保证。此连接器不受支持功能的SLA支持。

Elastic OpenText Documentum 连接器是使用 Elastic 连接器框架编写的 Python 程序。查看此示例连接器的源代码。

可用性和先决条件

edit

这个示例连接器是在Elastic 8.14.0中引入的，作为一个自托管的自托管连接器，仅用于测试和开发目的。

要使用此连接器，请满足所有自我管理连接器的前提条件。重要的是，您必须在您自己的基础设施上部署连接器服务。您有两个部署选项：

从源代码运行连接器服务。如果你熟悉Python并且希望在本地快速迭代，请使用此选项。
在Docker中运行连接器服务。如果你想将连接器部署到服务器，或者使用容器编排平台，请使用此选项。

用法

edit

要在用户界面中设置此连接器，请在搜索 → 连接器下创建新连接器时选择OpenText Documentum图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到OpenText Documentum

edit

基本身份验证用于连接到OpenText Documentum。

配置

edit

配置 OpenText Documentum 连接器

edit

请注意以下配置字段：

OpenText Documentum host url (required)

OpenText Documentum 托管的域。示例: https://192.158.1.38:2099/

Username (required)

连接到OpenText Documentum的账户用户名。

Password (required)

连接到OpenText Documentum的账户密码。

Repositories (optional)

要从 OpenText Documentum 获取数据的存储库的逗号分隔列表。如果值为 *，连接器将从配置用户帐户中的所有存储库获取数据。

默认值是 *。

示例：

elastic, kibana
*

Enable SSL (optional)

为OpenText Documentum实例启用SSL。

SSL Certificate (Required if SSL is enabled)

OpenText Documentum 实例的 SSL 证书。示例：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

仓库
橱柜
文件和文件夹

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后将对所有有权访问目标Elasticsearch索引的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

增量同步在当前版本中不适用于此连接器。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

当前版本中，此连接器不提供高级同步规则。

连接器客户端操作

edit

端到端测试

edit

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 OpenText Documentum 源来运行此测试。

更多详情请参阅连接器测试。

要为 OpenText Documentum 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=opentext_documentum

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=opentext_documentum DATA_SIZE=small

默认情况下，DATA_SIZE=MEDIUM。

已知问题

edit

该连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Oracle 连接器参考

edit

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器自 8.12.0 版本起原生支持 Elastic Cloud。要使用此连接器，请满足所有托管连接器要求。

创建一个Oracle连接器

edit

使用界面

edit

要创建一个新的 Oracle 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Oracle 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Oracle 连接器。

例如：

PUT _connector/my-oracle-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Oracle",
  "service_type": "oracle",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

数据库用户需要CONNECT和DBA权限，并且必须是将被索引的表的所有者。

安全连接

edit

要建立安全连接，必须在运行连接器的系统上安装 Oracle 服务。

请按照以下步骤操作：

设置oracle_home参数为您的Oracle主目录。如果配置文件不在默认位置，请设置wallet_configuration_path参数。
创建一个目录来存储钱包。
```
$ mkdir $ORACLE_HOME/ssl_wallet
```

在$ORACLE_HOME/network/admin目录下创建名为sqlnet.ora的文件，并添加以下内容：

WALLET_LOCATION = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = $ORACLE_HOME/ssl_wallet)))
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_VERSION = 1.0
SSL_CIPHER_SUITES = (SSL_RSA_WITH_AES_256_CBC_SHA)
SSL_SERVER_DN_MATCH = ON

运行以下命令以创建钱包并附加SSL证书。将文件名替换为您的文件名。

$ orapki wallet create -wallet path-to-oracle-home/ssl_wallet -auto_login_only
$ orapki wallet add -wallet path-to-oracle-home/ssl_wallet -trusted_cert -cert path-to-oracle-home/ssl_wallet/root_ca.pem -auto_login_only

有关更多信息，请参阅关于 Oracle SSL 的 Amazon RDS 文档。 Oracle 文档: https://docs.oracle.com/database/121/DBSEG/asossl.htm#DBSEG070。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

此连接器兼容 Oracle 数据库版本 18c、19c 和 21c。

配置

edit

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

Connection source

下拉菜单以确定Oracle源连接：服务名称或SID。默认值是SID。如果连接到可插拔数据库，请选择服务名称选项。

SID

数据库的SID。

Service name

数据库的服务名称。

Host

Oracle 数据库服务器的 IP 地址或主机名。默认值是 127.0.0.1。

Port

Oracle 数据库服务器的端口号。

Username

用于连接到Oracle数据库服务器的用户名。

Password

用于连接到Oracle数据库服务器的密码。

Comma-separated list of tables

逗号分隔的表列表，用于监控更改。默认值是 *。示例：

TABLE_1, TABLE_2
*

文档和同步

edit

未定义主键的表将被跳过。
如果表的系统更改号（SCN）值不在SMON_SCN_TIME表的min(SCN)和max(SCN)值之间，连接器将无法检索最近更新的时间。因此，数据将在每次同步时索引。有关更多详细信息，请参阅以下讨论线程。
不支持sys用户，因为它包含1000多个系统表。如果您需要使用sys用户，请使用sysdba或sysoper，并将其配置为用户名。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档索引到一个Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前，过滤由摄取管道控制。

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

此连接器使用通用数据库连接器源代码（分支main，兼容Elastic 9.0）。

查看此数据源的特定代码（分支main，兼容Elastic 9.0）。

自管理连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.6.0+。要使用此连接器，请满足所有自托管连接器要求。

创建一个 Oracle 连接器

edit

使用界面

edit

要创建一个新的 Oracle 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Oracle 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 Oracle 自管理连接器。

例如：

PUT _connector/my-oracle-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Oracle",
  "service_type": "oracle"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请参阅自管理连接器。

数据库用户需要CONNECT和DBA权限，并且必须是将被索引的表的所有者。

安全连接

edit

要建立安全连接，必须在运行连接器的系统上安装 Oracle 服务。

请按照以下步骤操作：

设置oracle_home参数为您的Oracle主目录。如果配置文件不在默认位置，请设置wallet_configuration_path参数。
创建一个目录来存储钱包。
```
$ mkdir $ORACLE_HOME/ssl_wallet
```

在$ORACLE_HOME/network/admin目录下创建名为sqlnet.ora的文件，并添加以下内容：

WALLET_LOCATION = (SOURCE = (METHOD = FILE) (METHOD_DATA = (DIRECTORY = $ORACLE_HOME/ssl_wallet)))
SSL_CLIENT_AUTHENTICATION = FALSE
SSL_VERSION = 1.0
SSL_CIPHER_SUITES = (SSL_RSA_WITH_AES_256_CBC_SHA)
SSL_SERVER_DN_MATCH = ON

运行以下命令以创建钱包并附加SSL证书。将文件名替换为您的文件名。

$ orapki wallet create -wallet path-to-oracle-home/ssl_wallet -auto_login_only
$ orapki wallet add -wallet path-to-oracle-home/ssl_wallet -trusted_cert -cert path-to-oracle-home/ssl_wallet/root_ca.pem -auto_login_only

有关更多信息，请参阅关于 Oracle SSL 的 Amazon RDS 文档。 Oracle 文档: https://docs.oracle.com/database/121/DBSEG/asossl.htm#DBSEG070。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

Oracle 数据库版本 18c、19c 和 21c 与 Elastic 连接器框架兼容。

配置

edit

在使用自我管理连接器工作流程时，这些字段将使用在连接器源代码中设置的默认配置。请注意，此数据源使用generic_database.py连接器源代码。有关此数据源的特定代码，请参阅oracle.py。

这些可配置的字段将在Kibana UI中以其各自的标签呈现。一旦连接，用户将能够在Kibana中更新这些值。

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

connection_source

确定Oracle源：服务名或SID。默认值为SID。如果连接到可插拔数据库，请选择服务名。

sid

数据库的SID。

service_name

数据库的服务名称。

host

Oracle 数据库服务器的 IP 地址或主机名。默认值是 127.0.0.1。

port

Oracle 数据库服务器的端口号。

username

用于连接到 Oracle 数据库服务器的用户名。

password

用于连接到Oracle数据库服务器的密码。

tables

逗号分隔的表列表，用于监控更改。默认值是 *。示例：

TABLE_1, TABLE_2
*

oracle_protocol

连接器用于建立连接的协议。默认值是 TCP。对于安全连接，使用 TCPS。

oracle_home

用于在安全连接的厚模式下运行连接器的Oracle主目录路径。对于非安全连接，请将此字段留空。

wallet_configuration_path

SSL钱包配置文件的路径。

fetch_size

每次请求获取的行数。默认值是 50。

retry_count

对Oracle数据库请求失败后的重试次数。默认值是3。

使用 Docker 部署

edit

您可以使用 Docker 将 Oracle 连接器部署为自管理连接器。请按照以下说明操作。

步骤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: oracle
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

未定义主键的表将被跳过。
如果表的系统更改号（SCN）值不在SMON_SCN_TIME表的min(SCN)和max(SCN)值之间，连接器将无法检索最近更新的时间。因此，数据将在每次同步时索引。有关更多详细信息，请参阅以下讨论线程。
不支持sys用户，因为它包含1000多个系统表。如果您需要使用sys用户，请使用sysdba或sysoper，并将其配置为用户名。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档索引到一个Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前，过滤由摄取管道控制。

自管理连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要执行Oracle连接器的功能测试，请运行以下命令：

make ftest NAME=oracle

默认情况下，这将使用中等大小的数据集。要使测试更快，请添加 DATA_SIZE=small 参数：

make ftest NAME=oracle DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

此连接器使用通用数据库连接器源代码（分支main，兼容Elastic 9.0）。

查看此数据源的特定代码（分支main，兼容Elastic 9.0）。

Elastic Outlook 连接器参考

edit

Elastic Outlook 连接器是基于 Elastic 连接器框架构建的，并且作为一个自管理的自管理连接器提供。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic Cloud 中作为 托管连接器（托管服务）提供。

此连接器兼容 Elastic 版本 8.13.0+。

要使用此连接器，请满足所有托管连接器要求。

创建一个Outlook连接器

edit

使用用户界面

edit

要创建一个新的 Outlook 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的本地 Outlook 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Outlook 连接器。

例如：

PUT _connector/my-outlook-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Outlook",
  "service_type": "outlook",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中将此连接器用作托管连接器，请在 Kibana UI 中使用 连接器 工作流程。

要创建一个新的Outlook连接器：

Navigate to Search → Connectors page in the Kibana UI.
Select the New Native Connector button.
Select the Outlook connector.

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到Outlook

edit

Outlook 连接器支持云端（Office365 Outlook）和本地（Exchange Server）平台。

连接到Exchange服务器

edit

为了连接到Exchange服务器，连接器借助ldap3 python库获取Active Directory用户。

连接到 Office365 Outlook (Outlook Cloud)

edit

要使用 Azure 与 Outlook 连接器集成，请按照以下步骤创建和配置 Azure 应用程序：

导航到Azure 门户并使用您的凭据登录。
点击应用注册以注册一个新应用程序。
导航到概述选项卡。记下客户端 ID和租户 ID。
点击证书 & 密钥选项卡并创建一个新的客户端密钥。请妥善保管此密钥。
转到API 权限选项卡。
- 点击“添加权限”。
- 选择“我的组织使用的 API”。
- 搜索并选择“Office 365 Exchange Online”。
- 添加full_access_as_app应用程序权限。

您现在可以使用已记录的客户端ID、租户ID和客户端密钥来配置Outlook连接器。

配置

edit

Outlook data source (required)

下拉菜单以确定 Outlook 平台类型：outlook_cloud 或 outlook_server。默认值是 outlook_cloud。

Tenant ID

Required if data source is outlook_cloud. The Tenant ID for the Azure account hosting the Outlook instance.

Client ID

如果数据源是 outlook_cloud，则此项为必填项。用于与 Outlook 实例进行身份验证的客户端 ID。

Client Secret Value

如果数据源是 outlook_cloud，则此项为必填项。用于与 Outlook 实例进行身份验证的客户端密钥值。

Exchange Server

Required if data source is outlook_server. IP address to connect with Exchange server. Example: 127.0.0.1

Active Directory Server

Required if data source is outlook_server. IP address to fetch users from Exchange Active Directory to fetch data. Example: 127.0.0.1

Exchange server username

如果数据源是 outlook_server，则此项为必填项。用于与 Exchange 服务器进行身份验证的用户名。

Exchange server password

如果数据源是 outlook_server，则需要提供。用于与 Exchange 服务器进行身份验证的密码。

Exchange server domain name

如果数据源是 outlook_server，则此项为必填项。 Exchange 服务器用户的域名，例如 gmail.com 或 exchange.local。

Enable SSL

Whether SSL verification will be enabled. Default value is False. Note: This configuration is applicable for Outlook Server only.

SSL certificate

如果启用了ssl，则需要此项。 SSL证书的内容。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

注意： 此配置仅适用于 Outlook Server。

Document level security

切换以启用文档级安全 (DLS)。启用时：

全量同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

邮件
- Inbox Mails
- Sent Mails
- Archive Mails
- Junk Mails
Contacts
Calendar Events
Tasks
附件
- Mail Attachments
- Task Attachments
- Calendar Attachments

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。所有文档索引到Elastic部署后将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

连接器客户端操作

edit

端到端测试

edit

注意： 当前版本的连接器不支持端到端测试。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和来源

edit

此连接器使用 Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

自管理连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自管理连接器的形式提供。要使用此连接器，请满足所有自管理连接器先决条件。

创建一个Outlook连接器

edit

使用用户界面

edit

要创建一个新的Outlook连接器：

Navigate to the Search → Connectors page in the Kibana UI.
Follow the instructions to create a new Outlook self-managed connector.

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 Outlook 自管理连接器。

例如：

PUT _connector/my-outlook-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Outlook",
  "service_type": "outlook"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自托管连接器，请从连接器列表中使用Outlook图块或自定义连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到Outlook

edit

Outlook 连接器支持云端（Office365 Outlook）和本地（Exchange Server）平台。

连接到Exchange服务器

edit

为了连接到Exchange服务器，连接器借助ldap3 python库获取Active Directory用户。

连接到 Office365 Outlook (Outlook Cloud)

edit

要使用 Azure 与 Outlook 连接器集成，请按照以下步骤创建和配置 Azure 应用程序：

导航到Azure 门户并使用您的凭据登录。
点击应用注册以注册一个新应用程序。
导航到概述选项卡。记下客户端 ID和租户 ID。
点击证书 & 密钥选项卡并创建一个新的客户端密钥。请妥善保管此密钥。
转到API 权限选项卡。
- 点击“添加权限”。
- 选择“我的组织使用的 API”。
- 搜索并选择“Office 365 Exchange Online”。
- 添加full_access_as_app应用程序权限。

您现在可以使用已记录的客户端ID、租户ID和客户端密钥来配置Outlook连接器。

配置

edit

data_source

(必填) 下拉菜单以确定 Outlook 平台类型：outlook_cloud 或 outlook_server。默认值是 outlook_cloud。

tenant_id

(如果数据源是outlook_cloud，则为必填项) 托管Outlook实例的Azure账户的租户ID。

client_id

（如果数据源是outlook_cloud，则为必填项）用于与Outlook实例进行身份验证的客户端ID。

client_secret

(如果数据源是outlook_cloud，则为必填项) 用于与Outlook实例进行身份验证的客户端密钥值。

exchange_server

(如果数据源是outlook_server，则为必填项) 用于连接Exchange服务器的IP地址。示例: 127.0.0.1

active_directory_server

(如果数据源是outlook_server，则为必填项) 从Exchange Active Directory获取用户数据的IP地址。示例: 127.0.0.1

username

(如果数据源是outlook_server，则为必填项) 用于与Exchange服务器进行身份验证的用户名。

password

(如果数据源是outlook_server，则为必填项) 用于与Exchange服务器进行身份验证的密码。

domain

(如果数据源是outlook_server，则为必填项) Exchange服务器用户的域名，例如gmail.com或exchange.local。

ssl_enabled

是否启用SSL验证。默认值是False。 注意: 此配置仅适用于Outlook Server。

ssl_ca

（如果启用了ssl，则为必填项） SSL证书的内容。示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

use_text_extraction_service

使用自托管内容提取服务。默认值是 False。

document_level_security

切换以启用文档级安全 (DLS)。启用时：

全量同步将获取每个文档的访问控制列表并将其存储在_allow_access_control字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

注意： 此配置仅适用于 Outlook Server。

使用 Docker 部署

edit

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

步骤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: outlook
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

邮件
- 收件箱邮件
- 已发送邮件
- 归档邮件
- 垃圾邮件
联系人
日历事件
任务
附件
- 邮件附件
- 任务附件
- 日历附件

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级别安全性

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

连接器客户端操作

edit

端到端测试

edit

注意： 当前版本的连接器不支持端到端测试。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器包含在 Elastic 连接器框架中。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

Elastic PostgreSQL 连接器参考

edit

The Elastic PostgreSQL connector 是一个用于 PostgreSQL 的连接器。这个连接器是使用 Elastic 连接器框架用 Python 编写的。

此连接器使用通用数据库连接器源代码（分支main，兼容Elastic 9.0）。查看此连接器的特定源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器（Elastic Cloud）

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic 版本 8.8.0 及更高版本中作为 Elastic 托管连接器 提供。要在 Elastic Cloud 中本机使用此连接器，请满足所有 Elastic 托管连接器要求。

创建一个 PostgreSQL 连接器

edit

使用界面

edit

要创建一个新的 PostgreSQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 PostgreSQL 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的原生 PostgreSQL 连接器。

例如：

PUT _connector/my-postgresql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from PostgreSQL",
  "service_type": "postgresql",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要将此连接器用作Elastic 托管连接器，请使用连接器工作流程。参见Elastic 托管连接器。

用户必须将 track_commit_timestamp 设置为 on。为此，请在 PostgreSQL 服务器中运行 ALTER SYSTEM SET track_commit_timestamp = on;。

有关其他操作，请参阅 <←esconnectors-usage>>。

有关连接器客户端工作流程的端到端示例，请参阅教程。

兼容性

edit

PostgreSQL 版本 11 到 15 与 Elastic 连接器兼容。

配置

edit

设置以下配置字段：

Host

PostgreSQL实例所在的服务器主机地址。示例：

192.158.1.38
demo.instance.demo-region.demo.service.com

Port

PostgreSQL实例所在的主机端口。示例：

5432 (默认)

Username

PostgreSQL 账户的用户名。

Password

PostgreSQL 账户的密码。

Database

PostgreSQL 数据库的名称。示例：

employee_database
customer_database

Schema

PostgreSQL 数据库的架构。

Comma-separated List of Tables

由逗号分隔的表列表。如果值为 *，PostgreSQL 连接器将从配置的数据库中存在的所有表中获取数据。默认值为 *。示例：

table_1, table_2
*

使用高级同步规则时，可以绕过此字段。

Enable SSL

切换以启用SSL验证。默认情况下禁用。

SSL Certificate

SSL 证书的内容。如果 SSL 被禁用，ssl_ca 值将被忽略。

展开查看示例证书

文档和同步

edit

表必须由PostgreSQL用户拥有。
未定义主键的表将被跳过。
要在PostgreSQL中获取最后更新时间，必须将track_commit_timestamp设置为on。否则，所有数据将在每次同步时被索引。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档索引到一个Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

示例数据

edit

以下是将在后续示例中使用的示例数据。

======= employee 表

emp_id	name	age
3	约翰	28
10	简	35
14	亚历克斯	22

======= customer 表

c_id	name	age
2	榆树	24
6	松树	30
9	橡树	34

高级同步规则示例

edit

======= 多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

======= 使用id_columns的多表查询

在8.15.0版本中，我们为PostgreSQL连接器的同步规则添加了一个新的可选字段id_columns。使用id_columns字段来导入没有主键的表。包含唯一字段的名称，以便连接器可以使用它们为文档生成唯一ID。

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee",
    "id_columns": ["emp_id"]
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer",
    "id_columns": ["c_id"]
  }
]

此示例使用 id_columns 字段来分别指定 employee 和 customer 表的唯一字段 emp_id 和 c_id。

======= 使用WHERE子句过滤数据

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

======= JOIN 操作

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。要使用此连接器，请满足所有自托管连接器要求。

创建一个 PostgreSQL 连接器

edit

使用界面

edit

要创建一个新的 PostgreSQL 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 PostgreSQL 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 PostgreSQL 自管理连接器。

例如：

PUT _connector/my-postgresql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from PostgreSQL",
  "service_type": "postgresql"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请参阅自管理连接器。

用户必须将 track_commit_timestamp 设置为 on。为此，请在 PostgreSQL 服务器中运行 ALTER SYSTEM SET track_commit_timestamp = on;。

有关其他操作，请参阅。

有关自管理连接器工作流程的端到端示例，请参阅教程。

兼容性

edit

PostgreSQL 版本 11 到 15 与 Elastic 连接器框架兼容。

配置

edit

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

这些可配置的字段将在Kibana UI中以其各自的标签呈现。一旦连接，用户将能够在Kibana中更新这些值。

设置以下配置字段：

host

PostgreSQL实例所在的服务器主机地址。示例：

192.158.1.38
demo.instance.demo-region.demo.service.com

port

PostgreSQL实例所在的主机端口。示例：

5432
9090

username

PostgreSQL 账户的用户名。

password

PostgreSQL 账户的密码。

database

PostgreSQL 数据库的名称。示例：

employee_database
customer_database

schema

PostgreSQL 数据库的架构。

tables

由逗号分隔的表列表。如果值为 *，PostgreSQL 连接器将从配置的数据库中存在的所有表中获取数据。默认值为 *。示例：

table_1, table_2
*

使用高级同步规则时，可以绕过此字段。

ssl_enabled

是否启用SSL验证。默认值是True。

ssl_ca

SSL证书的内容（如果启用了SSL）。如果禁用了SSL，ssl_ca 值将被忽略。

展开查看示例证书

使用 Docker 部署

edit

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

步骤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: postgresql
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

表必须由PostgreSQL用户拥有。
未定义主键的表将被跳过。
要在PostgreSQL中获取最后更新时间，必须将track_commit_timestamp设置为on。否则，所有数据将在每次同步时被索引。

大于10 MB的文件将不会被提取。
权限不会同步。 所有文档索引到一个Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

高级同步规则

edit

A //连接器-同步-类型-完整，需要完整同步以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

示例数据

edit

以下是将在后续示例中使用的示例数据。

======= employee 表

emp_id	name	age
3	约翰	28
10	简	35
14	亚历克斯	22

======= customer 表

c_id	name	age
2	榆树	24
6	松树	30
9	橡树	34

高级同步规则示例

edit

======== 多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

======== 使用id_columns进行多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee",
    "id_columns": ["emp_id"]
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer",
    "id_columns": ["c_id"]
  }
]

此示例使用 id_columns 字段来分别指定 employee 和 customer 表的唯一字段 emp_id 和 c_id。

======== 使用WHERE子句过滤数据

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

======== JOIN 操作

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 PostgreSQL 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=postgresql

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=postgresql DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Redis 连接器参考

edit

Redis 连接器是使用 Elastic 连接器 Python 框架构建的，并且可以作为自管理的自管理连接器使用。查看此连接器的 源代码（分支 main，与 Elastic 9.0 兼容）。

可用性和先决条件

edit

此连接器在 Elastic 8.13.0 中引入，作为 自托管 的自托管连接器提供。

要使用此连接器，请满足所有自我管理连接器的前提条件。重要的是，您必须在您自己的基础设施上部署连接器服务。您有两个部署选项：

从源代码运行连接器服务。如果你熟悉Python并且希望在本地快速迭代，请使用此选项。
在Docker中运行连接器服务。如果你想将连接器部署到服务器，或者使用容器编排平台，请使用此选项。

用法

edit

要在UI中设置此连接器，请在搜索 → 连接器下创建新连接器时选择Redis图块。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用 Docker 部署

edit

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

步骤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: redis
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

host (required)

您的Redis服务器/云的IP地址。示例：

127.0.0.1
redis-12345.us-east-1.ec2.cloud.redislabs.com

port (required)

Redis 服务器/云实例托管的端口。示例：

6379

username (optional)

Redis服务器/云的用户名。示例：

默认

password (optional)

Redis服务器/云实例的密码。示例：

changeme

database (required)

Redis服务器/云的数据库索引列表。* 将从所有数据库中获取数据。示例：

0,1,2
*

使用高级同步规则时，此字段将被忽略。

ssl_enabled

切换以使用SSL/TLS。默认情况下禁用。

mutual_tls_enabled

切换以使用安全的相互 SSL/TLS。确保您的 Redis 部署支持相互 SSL/TLS 连接。默认情况下禁用。依赖于 ssl_enabled。

tls_certfile

指定来自证书颁发机构的证书。该证书的值用于验证Redis实例提供的证书。依赖于mutual_tls_enabled。

tls_keyfile

指定客户端私钥。该密钥的值用于验证Redis实例中的连接。依赖于mutual_tls_enabled。

文档和同步

edit

连接器同步以下对象和实体：

每个数据库索引的键和值

权限未同步。所有文档索引到Elastic部署后，将对所有有权访问相关Elasticsearch索引的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

高级同步规则是通过特定于源的DSL JSON片段定义的。

使用高级同步规则在Redis源过滤数据，而无需将所有数据索引到Elasticsearch中。

它们接受以下参数：

database: 指定Redis数据库索引为整数值。
key_pattern: 2. key_pattern: 用于在Redis中查找键的模式。
type: Redis的键类型。

支持的值：
- HASH
- LIST
- SET
- STREAM
- STRING
- ZSET

请提供以下至少一项：key_pattern 或 type，或两者都提供。

高级同步规则示例

edit

示例 1

edit

获取数据库记录，其中键以 alpha 开头:

[
  {
    "database": 0,
    "key_pattern": "alpha*"
  }
]

示例 2

edit

通过指定完整键名来获取与数据库记录的精确匹配：

[
  {
    "database": 0,
    "key_pattern": "alpha"
  }
]

示例 3

edit

获取数据库记录，其中键以 test1、test2 或 test3 开头：

[
  {
    "database": 0,
    "key_pattern": "test[123]"
  }

示例 4

edit

排除键以test1、test2 或 test3 开头的数据库记录：

[
  {
    "database": 0,
    "key_pattern": "test[^123]"
  }
]

示例 5

edit

获取所有数据库记录：

[
  {
    "database": 0,
    "key_pattern": "*"
  }
]

示例 6

edit

获取所有类型为SET的数据库记录：

[
  {
    "database": 0,
    "key_pattern": "*",
    "type": "SET"
  }
]

示例 7

edit

获取数据库中类型为SET的记录:

[
  {
    "database": 0,
    "type": "SET"
  }
]

连接器客户端操作

edit

端到端测试

edit

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 Redis 源来运行此测试。

更多详情请参阅连接器测试。

要为 Redis 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=redis

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=redis DATA_SIZE=small

默认情况下，DATA_SIZE=MEDIUM。

已知问题

edit

从Redis数据库检索键/值时，最后修改时间不可用。因此，每次执行高级同步规则查询时，所有对象都会被索引。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic S3 连接器参考

edit

The Elastic S3 connector 是一个用于连接器 Amazon S3 数据源。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和前提条件

edit

此连接器自版本 8.12.0 起在 Elastic Cloud 中本机可用。要使用此连接器，请满足所有托管连接器要求。

创建一个 Amazon S3 连接器

edit

使用界面

edit

要创建一个新的 Amazon S3 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Amazon S3 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用 API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Amazon S3 连接器。

例如：

PUT _connector/my-s3-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Amazon S3",
  "service_type": "s3",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此托管连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

S3用户还需要创建IAM身份

创建一个IAM身份

edit

用户需要创建一个IAM身份以使用此连接器作为自管理连接器。请参阅AWS文档。

与IAM身份关联的策略必须具有以下AWS权限：

ListAllMyBuckets
ListBucket
GetBucketLocation
GetObject

兼容性

edit

目前该连接器不支持S3兼容的供应商。

配置

edit

以下配置字段是设置连接器所必需的：

AWS Buckets

S3 存储桶名称列表。 * 将从所有存储桶中获取数据。示例：

testbucket, prodbucket
testbucket
*

使用高级同步规则时，此字段将被忽略。

AWS Access Key ID: 用于访问存储桶的AWS身份的访问密钥ID。
AWS Secret Key: 用于访问存储桶的AWS身份的秘密访问密钥。

文档和同步

edit

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。 所有文档索引到Elastic部署后将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

使用高级同步规则来过滤要从 Amazon S3 存储桶中获取的数据。它们接受以下参数：

bucket: 规则适用的S3存储桶。
extension（可选）：列出要同步的文件类型。默认同步所有类型。
prefix（可选）：前缀字符串。连接器将获取与该字符串匹配的文件和文件夹数据。默认值为""（同步所有存储桶对象）。

======= 高级同步规则示例

通过前缀递归获取文件和文件夹

示例: 获取 folder1/docs 中的文件/文件夹。

[
  {
    "bucket": "bucket1",
    "prefix": "folder1/docs"
  }

]

示例: 获取以 folder1 开头的文件/文件夹。

[
  {
    "bucket": "bucket2",
    "prefix": "folder1"
  }
]

通过指定扩展名获取文件和文件夹

示例: 获取所有以 abc 开头的对象，然后使用文件扩展名进行过滤。

[
  {
    "bucket": "bucket2",
    "prefix": "abc",
    "extension": [".txt", ".png"]
  }
]

内容提取

edit

参见内容提取。

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

自托管连接器参考

edit

查看自托管连接器参考

可用性和前提条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.6.0+。要使用此连接器，请满足所有自托管连接器要求。

创建一个 Amazon S3 连接器

edit

使用界面

edit

要创建一个新的 Amazon S3 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Amazon S3 自管理连接器。

使用 API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自管理的 Amazon S3 自管理连接器。

例如：

PUT _connector/my-s3-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Amazon S3",
  "service_type": "s3"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请参阅自管理连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

S3用户还需要创建IAM身份

创建IAM身份

edit

用户需要创建一个IAM身份以使用此连接器作为自管理连接器。请参阅AWS文档。

与IAM身份关联的策略必须具有以下AWS权限：

ListAllMyBuckets
ListBucket
GetBucketLocation
GetObject

兼容性

edit

目前该连接器不支持S3兼容的供应商。

配置

edit

在使用自托管连接器工作流程时，这些字段将使用在连接器源代码中设置的默认配置。这些可配置字段将在Kibana UI中以其各自的标签呈现。一旦连接成功，您将能够在Kibana中更新这些值。

以下配置字段是设置连接器所必需的：

buckets

S3 存储桶名称列表。 * 将从所有存储桶中获取数据。示例：

testbucket, prodbucket
testbucket
*

使用高级同步规则时，此字段将被忽略。

aws_access_key_id: 用于访问存储桶的AWS身份的访问密钥ID。
aws_secret_access_key: 用于访问存储桶的AWS身份的秘密访问密钥。
read_timeout: Amazon S3 的 read_timeout。默认值是 90。
connect_timeout: 爬取S3的连接超时时间。默认值是 90。
max_attempts: 最大重试次数。默认值是 5。
page_size: 在 Amazon S3 中迭代存储桶对象的页面大小。默认值是 100。

使用 Docker 部署

edit

您可以使用 Docker 将 Amazon S3 连接器部署为自管理连接器。请按照以下说明操作。

步骤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: s3
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

默认情况下，不会提取大于10 MB的文件内容。您可以使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。 所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

使用高级同步规则来过滤要从 Amazon S3 存储桶中获取的数据。它们接受以下参数：

bucket: 规则适用的S3存储桶。
extension（可选）：列出要同步的文件类型。默认同步所有类型。
prefix（可选）：前缀字符串。连接器将获取与该字符串匹配的文件和文件夹数据。默认值为""（同步所有存储桶对象）。

======= 高级同步规则示例

通过前缀递归获取文件和文件夹

示例: 获取 folder1/docs 中的文件/文件夹。

[
  {
    "bucket": "bucket1",
    "prefix": "folder1/docs"
  }

]

示例: 获取以 folder1 开头的文件/文件夹。

[
  {
    "bucket": "bucket2",
    "prefix": "folder1"
  }
]

通过指定扩展名获取文件和文件夹

示例: 获取所有以 abc 开头的对象，然后使用文件扩展名进行过滤。

[
  {
    "bucket": "bucket2",
    "prefix": "abc",
    "extension": [".txt", ".png"]
  }
]

内容提取

edit

参见内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 Amazon S3 自托管连接器 执行功能测试，请运行以下命令：

make ftest NAME=s3

默认情况下，这将使用中等大小的数据集。要使测试更快，请添加 DATA_SIZE=small 参数：

make ftest NAME=s3 DATA_SIZE=small

已知问题

edit

此连接器没有已知问题。

查看影响所有连接器的已知问题。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

Elastic Salesforce 连接器参考

edit

The Elastic Salesforce connector 是一个用于连接器 Salesforce 数据源。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自 8.12.0 版本起，此连接器在 Elastic Cloud 中作为 托管连接器 提供。要使用此连接器，请满足所有自托管连接器要求。

兼容性

edit

此连接器兼容以下内容：

Salesforce
Salesforce 沙盒

创建一个 Salesforce 连接器

edit

使用用户界面

edit

要创建一个新的 Salesforce 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Salesforce 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Salesforce 连接器。

例如：

PUT _connector/my-salesforce-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Salesforce",
  "service_type": "salesforce",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请在 Kibana UI 中使用连接器工作流程。

有关其他操作，请参阅 connectors usage。

您需要创建一个启用了OAuth2.0的Salesforce连接应用程序，以便与Salesforce进行身份验证。

创建一个Salesforce连接应用

edit

Salesforce 连接器通过一个连接的应用程序进行身份验证。请遵循 Salesforce 官方文档中的为 OAuth 2.0 客户端凭据流配置连接的应用程序。

在创建连接的应用程序时，在标题为 API（启用OAuth设置） 的部分中，确保以下设置已启用：

启用OAuth设置
启用设备流
- 回调URL 应该是Salesforce的虚拟回调URL，https://test.salesforce.com/services/oauth2/success
需要密钥进行Web服务器流
需要密钥进行刷新令牌流
启用客户端凭据流

所有其他选项应被禁用。最后，在选定的OAuth范围部分，包含以下OAuth范围：

通过API管理用户数据 (api)
随时执行请求 (refresh_token, offline_access)

Salesforce 管理员要求

edit

默认情况下，Salesforce 连接器需要全局管理员权限才能访问 Salesforce 数据。展开下面的部分以了解如何创建具有最小权限的自定义 Salesforce 用户。

创建一个具有最小权限的自定义Salesforce用户

通过从设置菜单创建具有足够权限的自定义配置文件，您可以移除从 Salesforce 获取数据所需的系统管理员角色要求。

要创建一个新配置文件：

从Salesforce设置菜单中，转到管理 ⇒ 用户 ⇒ 配置文件。
创建一个新配置文件。
从现有配置文件下拉菜单中选择只读或标准用户。命名配置文件并保存。

默认情况下，只读或标准用户用户具有访问所有标准对象的读取权限。
编辑新创建的配置文件。在对象权限下，为要摄取到Elasticsearch的标准对象和自定义对象分配至少读取访问权限。
确保新创建的配置文件对以下标准对象至少具有读取访问权限：
- 账户
- 活动
- 案例
- 联系人
- 电子邮件消息
- 潜在客户
- 商机
- 用户
  
  如果使用高级同步规则，您需要在配置文件中为该特定对象分配读取权限。
转到用户 ⇒ 配置文件并将新创建的配置文件分配给用户。
转到已连接的应用，选择您的应用，然后选择编辑策略。将客户端凭据流分配给Salesforce中具有自定义配置文件的用户。

现在，可以为此用户配置连接器以获取所有对象记录，而无需系统管理员角色。

配置

edit

以下设置是配置此连接器所必需的：

Domain (required)

您的 Salesforce 账户的域名。这是出现在您的 Salesforce URL 中的子域名。例如，如果您的 Salesforce URL 是 foo.my.salesforce.com，那么您的域名将是 foo。如果您使用的是 Salesforce 沙盒，您的 URL 将包含一个额外的子域名，并且看起来类似于 foo.sandbox.my.salesforce.com。在这种情况下，您的域名将是 foo.sandbox。

Client ID (required)

由您的连接应用程序生成的客户端ID。 Salesforce文档有时也会将此称为消费者密钥

Client Secret (required)

由您的连接应用程序生成的客户端密钥。 Salesforce 文档有时也会将其称为 消费者密钥。

Enable document level security

切换以启用文档级安全性 (DLS)。可选，默认禁用。有关更多信息，包括如何设置各种 Salesforce 权限类型，请参阅 DLS 部分。

当启用时：

完整同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

查找客户端ID和客户端密钥

edit

客户端 ID 和客户端密钥在您创建连接的应用程序后不会自动显示给您。您可以通过以下步骤找到它们：

导航到设置
转到平台工具 > 应用 > 应用管理器
点击您的应用旁边的三角形并选择查看
页面加载后，点击管理消费者详情

您的客户端ID和客户端密钥现在应该在页面顶部可见。

文档级安全 (DLS)

edit

文档级安全 (DLS) 使您能够根据用户的权限限制对文档的访问。此功能默认适用于 Salesforce 连接器，并支持 标准和自定义对象。

Salesforce 允许用户通过以下方式设置权限：

配置文件
权限集
权限集组

有关指导，请参阅这些关于设置 Salesforce 权限的视频教程。

要摄取任何标准或自定义对象，用户必须确保至少授予该对象读取权限。这可以通过以下任何一种设置权限的方法来实现。

使用配置文件设置权限

edit

请参阅Salesforce文档以通过配置文件设置权限。

使用权限集设置权限

edit

请参阅Salesforce 文档以通过权限集设置权限。

使用权限集组设置权限

edit

请参阅Salesforce文档以通过权限集组设置权限。

为用户分配配置文件、权限集和权限集组

edit

一旦权限设置完成，将配置文件、权限集或权限集组分配给用户。请按照以下步骤在 Salesforce 中操作：

导航到用户部分下的管理。
选择用户并选择要设置权限的用户。
设置在之前步骤中创建的配置文件、权限集或权限集组。

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。高级同步规则能够在将数据索引到Elasticsearch之前，对Salesforce中的数据进行过滤。

它们接受以下参数：

query : Salesforce 查询以过滤文档。
language : Salesforce 查询语言。允许的值为 SOQL 和 SOSL。

======= 根据指定的查询和语言获取文档

示例: 使用SOQL查询获取文档

[
  {
    "query": "SELECT Id, Name FROM Account",
    "language": "SOQL"
  }
]

示例: 使用SOSL查询获取文档。

[
  {
    "query": "FIND {Salesforce} IN ALL FIELDS",
    "language": "SOSL"
  }
]

======= 使用SOQL和SOSL查询获取标准和自定义对象

示例: 通过SOQL和SOSL查询获取标准对象的文档。

[
  {
    "query": "SELECT Account_Id, Address, Contact_Number FROM Account",
    "language": "SOQL"
  },
  {
    "query": "FIND {Alex Wilber} IN ALL FIELDS RETURNING Contact(LastModifiedDate, Name, Address)",
    "language": "SOSL"
  }
]

示例: 通过SOQL和SOSL查询获取自定义对象的文档。

[
  {
    "query": "SELECT Connector_Name, Version FROM Connector__c",
    "language": "SOQL"
  },
  {
    "query": "FIND {Salesforce} IN ALL FIELDS RETURNING Connectors__c(Id, Connector_Name, Connector_Version)",
    "language": "SOSL"
  }
]

======= 获取包含标准和自定义字段的文档

示例: 获取包含账户对象的所有标准和自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(ALL) FROM Account",
    "language": "SOQL"
  }
]

示例: 获取Connector对象的所有自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(CUSTOM) FROM Connector__c",
    "language": "SOQL"
  }
]

示例: 获取包含所有标准字段的账户对象文档。

[
  {
    "query": "SELECT FIELDS(STANDARD) FROM Account",
    "language": "SOQL"
  }
]

文档和同步

edit

连接器同步以下 Salesforce 对象：

账户
活动
案例
联系人
内容文档 (上传到 Salesforce 的文件)
潜在客户
机会

连接器将不会摄取任何它没有权限查询的对象。

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
默认情况下，权限不会同步。您必须启用文档级安全。否则，索引到Elastic部署中的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

内容提取

edit

如果您的 Salesforce 来源中的内容文档符合以下条件，连接器将会检索它们：

附加到一个或多个同步的对象
是可提取的文件类型

这意味着连接器不会摄取您拥有的未附加到受支持的 Salesforce 对象的任何内容文档。请参阅文档和同步以获取受支持的对象类型列表。

如果一个内容文档附加到多个支持的对象，只会为其创建一个弹性文档。该文档将在related_ids字段中保留与每个连接对象的链接。

有关内容提取的更多详细信息，请参阅内容提取。

已知问题

edit

目前此连接器没有已知问题。请参阅连接器已知问题以获取所有连接器的已知问题列表。

安全性

edit

请参阅连接器安全性。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.10.0+。要使用此连接器，请满足所有自托管连接器要求。

兼容性

edit

此连接器兼容以下内容：

Salesforce
Salesforce 沙盒

创建一个 Salesforce 连接器

edit

使用用户界面

edit

要创建一个新的 Salesforce 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Salesforce 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自托管 Salesforce 自托管连接器。

例如：

PUT _connector/my-salesforce-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Salesforce",
  "service_type": "salesforce"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请在 Kibana UI 中使用连接器工作流程。

有关其他操作，请参阅 connectors usage。

您需要创建一个启用了OAuth2.0的Salesforce连接应用程序，以便与Salesforce进行身份验证。

创建一个 Salesforce 连接的应用程序

edit

Salesforce 连接器通过一个连接的应用程序进行身份验证。请遵循 Salesforce 官方文档中的为 OAuth 2.0 客户端凭据流配置连接的应用程序。

在创建连接的应用程序时，在标题为 API（启用OAuth设置） 的部分中，确保以下设置已启用：

启用OAuth设置
启用设备流
- 回调URL 应该是Salesforce的虚拟回调URL，https://test.salesforce.com/services/oauth2/success
需要密钥进行Web服务器流
需要密钥进行刷新令牌流
启用客户端凭据流

所有其他选项应被禁用。最后，在选定的OAuth范围部分，包含以下OAuth范围：

通过API管理用户数据 (api)
随时执行请求 (refresh_token, offline_access)

Salesforce 管理员要求

edit

默认情况下，Salesforce 连接器需要全局管理员权限才能访问 Salesforce 数据。展开下面的部分以了解如何创建具有最小权限的自定义 Salesforce 用户。

创建一个具有最小权限的自定义Salesforce用户

通过从设置菜单创建具有足够权限的自定义配置文件，您可以移除从 Salesforce 获取数据所需的系统管理员角色要求。

要创建一个新配置文件：

从Salesforce设置菜单中，转到管理 ⇒ 用户 ⇒ 配置文件。
创建一个新配置文件。
从现有配置文件下拉菜单中选择只读或标准用户。命名配置文件并保存。

默认情况下，只读或标准用户用户具有访问所有标准对象的读取权限。
编辑新创建的配置文件。在对象权限下，为要摄取到Elasticsearch的标准对象和自定义对象分配至少读取访问权限。
确保新创建的配置文件对以下标准对象至少具有读取访问权限：
- 账户
- 活动
- 案例
- 联系人
- 电子邮件消息
- 潜在客户
- 商机
- 用户
  
  如果使用高级同步规则，您需要在配置文件中为该特定对象分配读取权限。
转到用户 ⇒ 配置文件并将新创建的配置文件分配给用户。
转到已连接的应用，选择您的应用，然后选择编辑策略。将客户端凭据流分配给Salesforce中具有自定义配置文件的用户。

现在，可以为此用户配置连接器以获取所有对象记录，而无需系统管理员角色。

使用 Docker 进行部署

edit

自托管连接器运行在您自己的基础设施上。

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

步骤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: salesforce
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

以下设置是配置此连接器所必需的：

domain(required)

您的 Salesforce 账户的域名。这是出现在您的 Salesforce URL 中的子域名。例如，如果您的 Salesforce URL 是 foo.my.salesforce.com，那么您的域名将是 foo。如果您使用的是 Salesforce Sandbox，您的 URL 将包含一个额外的子域名，并且看起来类似于 foo.sandbox.my.salesforce.com。在这种情况下，您的域名将是 foo.sandbox。

client_id(required)

由您的连接应用程序生成的客户端ID。 Salesforce文档有时也会将此称为消费者密钥

client_secret(required)

由您的连接应用程序生成的客户端密钥。 Salesforce 文档有时也会将其称为 消费者密钥。

use_document_level_security

切换以启用文档级安全性 (DLS)。可选，默认禁用。有关更多信息，包括如何设置各种 Salesforce 权限类型，请参阅 DLS 部分。

当启用时：

全量同步将获取每个文档的访问控制列表并将其存储在 _allow_access_control 字段中。
访问控制同步将获取用户的访问控制列表并将其存储在单独的索引中。

查找客户端ID和客户端密钥

edit

客户端 ID 和客户端密钥在您创建连接的应用程序后不会自动显示给您。您可以通过以下步骤找到它们：

导航到设置
转到平台工具 > 应用 > 应用管理器
点击您的应用旁边的三角形并选择查看
页面加载后，点击管理消费者详情

您的客户端ID和客户端密钥现在应该在页面顶部可见。

文档级安全 (DLS)

edit

文档级安全 (DLS) 使您能够根据用户的权限限制对文档的访问。此功能默认适用于 Salesforce 连接器，并支持 标准和自定义对象。

Salesforce 允许用户通过以下方式设置权限：

配置文件
权限集
权限集组

有关指导，请参阅这些关于设置 Salesforce 权限的视频教程。

要摄取任何标准或自定义对象，用户必须确保至少授予该对象读取权限。这可以通过以下任何一种设置权限的方法来实现。

使用配置文件设置权限

edit

请参阅Salesforce文档以通过配置文件设置权限。

使用权限集设置权限

edit

请参阅Salesforce 文档以通过权限集设置权限。

使用权限集组设置权限

edit

请参阅Salesforce文档以通过权限集组设置权限。

为用户分配配置文件、权限集和权限集组

edit

一旦权限设置完成，将配置文件、权限集或权限集组分配给用户。请按照以下步骤在 Salesforce 中操作：

导航到用户部分下的管理。
选择用户并选择要设置权限的用户。
设置在之前步骤中创建的配置文件、权限集或权限集组。

同步规则

edit

基本同步规则对所有连接器都是相同的，并且默认情况下可用。

更多信息请阅读同步规则。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。高级同步规则能够在将数据索引到Elasticsearch之前，对Salesforce中的数据进行过滤。

它们接受以下参数：

query : Salesforce 查询以过滤文档。
language : Salesforce 查询语言。允许的值为 SOQL 和 SOSL。

======= 根据指定的查询和语言获取文档

示例: 使用SOQL查询获取文档

[
  {
    "query": "SELECT Id, Name FROM Account",
    "language": "SOQL"
  }
]

示例: 使用SOSL查询获取文档。

[
  {
    "query": "FIND {Salesforce} IN ALL FIELDS",
    "language": "SOSL"
  }
]

======= 使用SOQL和SOSL查询获取标准和自定义对象

示例: 通过SOQL和SOSL查询获取标准对象的文档。

[
  {
    "query": "SELECT Account_Id, Address, Contact_Number FROM Account",
    "language": "SOQL"
  },
  {
    "query": "FIND {Alex Wilber} IN ALL FIELDS RETURNING Contact(LastModifiedDate, Name, Address)",
    "language": "SOSL"
  }
]

示例: 通过SOQL和SOSL查询获取自定义对象的文档。

[
  {
    "query": "SELECT Connector_Name, Version FROM Connector__c",
    "language": "SOQL"
  },
  {
    "query": "FIND {Salesforce} IN ALL FIELDS RETURNING Connectors__c(Id, Connector_Name, Connector_Version)",
    "language": "SOSL"
  }
]

======= 获取包含标准和自定义字段的文档

示例: 获取包含账户对象的所有标准和自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(ALL) FROM Account",
    "language": "SOQL"
  }
]

示例: 获取Connector对象的所有自定义字段的文档。

[
  {
    "query": "SELECT FIELDS(CUSTOM) FROM Connector__c",
    "language": "SOQL"
  }
]

示例: 获取包含所有标准字段的账户对象文档。

[
  {
    "query": "SELECT FIELDS(STANDARD) FROM Account",
    "language": "SOQL"
  }
]

文档和同步

edit

连接器同步以下 Salesforce 对象：

账户
活动
案例
联系人
内容文档 (上传到 Salesforce 的文件)
潜在客户
机会

连接器将不会摄取它没有权限查询的任何对象。

默认情况下，不会提取大于10 MB的文件内容。使用自管理的本地提取服务来处理较大的二进制文件。
默认情况下，权限不会同步。您必须启用文档级安全。否则，索引到Elastic部署的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

内容提取

edit

连接器将从您的 Salesforce 源中检索内容文档，如果它们满足以下条件：

附加到一个或多个同步的对象
是可提取的文件类型

这意味着连接器不会摄取您拥有的未附加到受支持的 Salesforce 对象的任何内容文档。请参阅文档和同步以获取受支持的对象类型列表。

如果一个内容文档附加到多个支持的对象，只会为其创建一个弹性文档。该文档将在related_ids字段中保留与每个连接对象的链接。

查看内容提取以了解更多关于内容提取的详细信息。

已知问题

edit

目前此连接器没有已知问题。请参阅连接器已知问题以获取所有连接器的已知问题列表。

安全性

edit

请参阅连接器安全性。

框架和源

edit

此连接器是使用Elastic 连接器框架构建的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic ServiceNow 连接器参考

edit

The Elastic ServiceNow connector 是一个用于连接器 ServiceNow。

此连接器使用 Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自8.10.0版本起，ServiceNow连接器在Elastic Cloud中已原生可用。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 ServiceNow 连接器

edit

使用用户界面

edit

要创建一个新的 ServiceNow 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 ServiceNow 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 ServiceNow 连接器。

例如：

PUT _connector/my-servicenow-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from ServiceNow",
  "service_type": "servicenow",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在 Elastic Cloud 中本机使用此连接器，请参阅 Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI

兼容性

edit

ServiceNow 连接器与以下版本的 ServiceNow 兼容：

ServiceNow "东京"
ServiceNow "圣地亚哥"
ServiceNow "罗马"
ServiceNow "犹他"
ServiceNow "温哥华"
ServiceNow "华盛顿"
ServiceNow "世外桃源"

配置

edit

以下配置字段是设置连接器所必需的：

ServiceNow URL

ServiceNow实例的主机URL。

Username

用于ServiceNow的账户用户名。

Password

用于ServiceNow的账户密码。

Comma-separated list of services

从ServiceNow获取数据的逗号分隔的服务列表。如果值为*，连接器将从ServiceNow提供的基本服务列表中获取数据：

用户
事件
请求的项目
知识
变更请求

如果你配置了一个自定义服务，* 值默认不会从上述基本服务中获取数据。在这种情况下，你需要明确提及这些服务名称。

默认值是 *。示例：
User, Incident, Requested Item, Knowledge, Change Request
*

Enable document level security

根据用户的权限限制对文档的访问。有关更多详细信息，请参阅文档级安全。

文档和同步

edit

用户可以访问的所有服务和记录将根据提供的配置进行索引。连接器同步以下ServiceNow对象类型：

记录
附件

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
默认情况下，权限不会同步。有关更多详细信息，请参阅文档级安全。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全 (DLS) 确保在 ServiceNow 中设置的身份和权限在 Elasticsearch 中得到维护。这使您能够限制和个性化用户和组对该索引中文档的读取访问权限。访问控制同步确保此元数据在您的 Elasticsearch 文档中保持最新。

ServiceNow 连接器支持用于访问控制列表 (ACL) 的角色，以在 Elasticsearch 中实现文档级安全。对于默认服务，连接器使用以下角色来查找有权访问文档的用户。

Service	Roles
用户	`管理员`
事件	`admin`, `sn_incident_read`, `ml_report_user`, `ml_admin`, `itil`
请求的项目	`admin`, `sn_request_read`, `asset`, `atf_test_designer`, `atf_test_admin`
知识	`admin`, `knowledge`, `knowledge_manager`, `knowledge_admin`
变更请求	`admin`, `sn_change_read`, `itil`

对于这些默认服务以外的服务，连接器会遍历具有读取操作的访问控制，并找到这些服务的相应角色。

ServiceNow 连接器不支持脚本化和条件权限。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

以下部分提供了此连接器的高级同步规则示例。

======= 基于事件编号为事件服务索引文档

[
  {
    "service": "Incident",
    "query": "numberSTARTSWITHINC001"
  }
]

======= 基于用户活动状态为用户服务索引文档

[
  {
    "service": "User",
    "query": "active=False"
  }
]

======= 基于作者名称为知识服务索引文档

[
  {
    "service": "Knowledge",
    "query": "author.nameSTARTSWITHSystem Administrator"
  }
]

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取影响所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

内容提取

edit

参见内容提取。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

ServiceNow 连接器在 Elastic 版本 8.9.0 中引入。该连接器作为自托管连接器提供。要使用此连接器作为自托管连接器，请满足所有自托管连接器要求。

创建一个 ServiceNow 连接器

edit

使用用户界面

edit

要创建一个新的 ServiceNow 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 ServiceNow 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自托管 ServiceNow 自托管连接器。

例如：

PUT _connector/my-servicenow-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from ServiceNow",
  "service_type": "servicenow"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请使用自定义连接器工作流程。

有关其他操作，请参阅 Usage。

兼容性

edit

ServiceNow 连接器与以下版本的 ServiceNow 兼容：

ServiceNow "东京"
ServiceNow "圣地亚哥"
ServiceNow "罗马"
ServiceNow "犹他"
ServiceNow "温哥华"
ServiceNow "华盛顿"
ServiceNow "世外桃源"

配置

edit

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

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

以下配置字段是设置连接器所必需的：

url

ServiceNow实例的主机URL。

username

ServiceNow 账户的用户名。

password

用于ServiceNow的账户密码。

services

从ServiceNow获取数据的逗号分隔的服务列表。如果值为*，连接器将从ServiceNow提供的基本服务列表中获取数据：

用户
事件
请求的项目
知识
变更请求

如果您配置了自定义服务，* 值默认不会从上述基本服务中获取数据。在这种情况下，您需要明确提及这些服务名称。

默认值为 *。示例：
User, Incident, Requested Item, Knowledge, Change Request
*

retry_count

在请求ServiceNow失败后的重试次数。默认值是3。

concurrent_downloads

获取附件内容时的并发下载数量。这加快了附件内容的提取速度。默认为 10。

use_text_extraction_service

需要单独部署Elastic 文本提取服务。需要禁用摄取管道设置中的文本提取。默认值为False。

use_document_level_security

根据用户的权限限制对文档的访问。有关更多详细信息，请参阅文档级安全。

文档和同步

edit

用户可以访问的所有服务和记录将根据提供的配置进行索引。连接器同步以下ServiceNow对象类型：

记录
附件

大于10 MB的文件内容将不会被提取。使用自管理的本地提取服务来处理较大的二进制文件。
默认情况下，权限不会同步。您必须启用文档级安全。否则，索引到Elastic部署的所有文档将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

Service	Roles
用户	`管理员`
事件	`admin`, `sn_incident_read`, `ml_report_user`, `ml_admin`, `itil`
请求的项目	`admin`, `sn_request_read`, `asset`, `atf_test_designer`, `atf_test_admin`
知识	`admin`, `knowledge`, `knowledge_manager`, `knowledge_admin`
变更请求	`admin`, `sn_change_read`, `itil`

对于这些默认服务以外的服务，连接器会遍历具有读取操作的访问控制，并找到这些服务的相应角色。

ServiceNow 连接器不支持脚本化和条件权限。

使用 Docker 部署

edit

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

步骤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: servicenow
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

高级同步规则通过特定于源的DSL JSON片段定义。

以下部分提供了此连接器的高级同步规则示例。

======= 基于事件编号为事件服务索引文档

[
  {
    "service": "Incident",
    "query": "numberSTARTSWITHINC001"
  }
]

======= 基于用户活动状态为用户服务索引文档

[
  {
    "service": "User",
    "query": "active=False"
  }
]

======= 基于作者名称索引知识服务的文档

[
  {
    "service": "Knowledge",
    "query": "author.nameSTARTSWITHSystem Administrator"
  }
]

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 ServiceNow 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=servicenow

使用以下标志生成性能报告：PERF8=yes。通过参数DATA_SIZE=在SMALL、MEDIUM和LARGE之间切换测试数据集大小。默认情况下，它设置为MEDIUM。

用户不需要拥有正在运行的 Elasticsearch 实例或 ServiceNow 源来运行此测试。 Docker Compose 管理开发环境的完整设置。

已知问题

edit

此连接器没有已知问题。请参阅已知问题以获取影响所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

内容提取

edit

参见内容提取。

Elastic SharePoint Online 连接器参考

edit

寻找 SharePoint Server 连接器？请参阅 SharePoint Server 参考。

The Elastic SharePoint Online connector 是一个用于 connector for Microsoft SharePoint Online。

此连接器使用 Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此连接器在 Elastic 版本 8.9.0 及更高版本 中作为 托管连接器 提供。要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

此连接器需要订阅。查看此功能在 Elastic Search 部分中的要求，位于 Elastic Stack 订阅页面。

用法

edit

要将此连接器用作托管连接器，请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

SharePoint 先决条件

edit

创建 SharePoint OAuth 应用

edit

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

要开始使用，首先登录到SharePoint Online并访问您的管理仪表板。确保您已作为Azure门户的服务账户登录。

请按照以下步骤操作：

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

Sharepoint
- Sites.Read.All
```
使用权限屏幕中的 授予管理员同意 链接 授予管理员同意。
保存 Azure 平台的租户名称（即域名）。

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

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

SharePoint 权限

edit

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

要将 DisableCustomAppAuthentication 设置为 false，请使用 PowerShell 连接到 SharePoint 并运行 set-spotenant -DisableCustomAppAuthentication $false
要在 SharePoint Online 中为租户分配完全权限，请在浏览器中转到租户 URL。 URL 遵循以下模式：https:///_layouts/15/appinv.aspx。这将加载 SharePoint 管理中心页面。
- 在 App ID 框中，输入您之前记录的应用程序 ID，然后点击 Lookup。应用程序名称将出现在标题框中。
- 在 App Domain 框中，输入 .onmicrosoft.com
- 在 应用的权限请求XML 框中，输入以下XML字符串：

Graph API 权限

微软建议使用 Graph API 进行所有与 Sharepoint Online 相关的操作。Graph API 文档齐全且在获取数据方面更为高效，这有助于避免限流。请参阅微软的限流策略以获取更多信息。

以下是我们使用这些Graph API权限的总结：

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

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

兼容性

edit

此连接器与SharePoint Online兼容。

配置

edit

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

Tenant ID

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

Tenant Name

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

Client ID

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

Secret value

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

Comma-separated list of sites

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

collection1
collection1,sub-collection
*

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

Enumerate all sites?

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

Fetch sub-sites of configured sites?

是否应自动获取配置站点下的子站点。此选项仅在未枚举所有站点时可用（见上文）。

Enable document level security

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

一旦启用，将可以使用以下细粒度的权限开关：

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

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

文档和同步

edit

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

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

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

使Sharepoint站点页面Web部件内容可搜索

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

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

限制

edit

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

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。高级同步规则通过特定于源的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中。两天后，这个文档将变成181天。由于这个文档已经被摄取，它不会被修改。因此，内容将不会从索引中移除，遵循增量同步。

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

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"
  }
}

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。此功能默认为此连接器提供。

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

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

内容提取

edit

默认内容提取

edit

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

参见内容提取。

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

edit

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

一个自管理的Elastic文本提取服务部署。
在默认的摄取管道设置中，文本提取将被禁用。

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

已知问题

edit

由于SharePoint文件和文件夹限制而未能同步的文档

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

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

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器可作为自托管连接器使用。要使用此连接器作为自托管连接器，请满足所有自托管连接器要求。

此连接器需要订阅。查看此功能在 Elastic Search 部分中的要求，位于 Elastic Stack 订阅页面。

用法

edit

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

SharePoint 先决条件

edit

创建 SharePoint OAuth 应用

edit

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

要开始使用，首先登录到SharePoint Online并访问您的管理仪表板。确保您已作为Azure门户服务账户登录。

请按照以下步骤操作：

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

Sharepoint
- Sites.Read.All
```
授予管理员同意，使用权限屏幕中的 授予管理员同意 链接。
保存 Azure 平台的租户名称（即域名）。

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

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

SharePoint 权限

edit

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

要将 DisableCustomAppAuthentication 设置为 false，请使用 PowerShell 连接到 SharePoint 并运行 set-spotenant -DisableCustomAppAuthentication $false
要在 SharePoint Online 中为租户分配完全权限，请在浏览器中转到租户 URL。 URL 遵循以下模式：https:///_layouts/15/appinv.aspx。这将加载 SharePoint 管理中心页面。
- 在 App ID 框中，输入您之前记录的应用程序 ID，然后点击 Lookup。应用程序名称将出现在标题框中。
- 在 App Domain 框中，输入 .onmicrosoft.com
- 在应用的权限请求XML框中，输入以下XML字符串：

Graph API 权限

微软建议使用Graph API进行所有与Sharepoint Online相关的操作。Graph API文档齐全，且在获取数据时更为高效，有助于避免限流。请参阅微软的限流策略以获取更多信息。

以下是我们使用这些Graph API权限的原因总结：

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

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

兼容性

edit

此连接器与SharePoint Online兼容。

配置

edit

在使用自我管理连接器工作流程时，最初这些字段将使用在连接器源代码中设置的默认配置。这些设置在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

要从中获取的站点集合名称或路径列表。当枚举所有站点时，这些值应为站点的名称。使用 * 以包含所有可用站点。示例：

collection1
collection1,sub-collection
*

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

enumerate_all_sites

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

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

fetch_subsites

是否应自动获取配置站点下的子站点。此选项仅在未枚举所有站点时可用（见上文）。

use_text_extraction_service

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

use_document_level_security

启用后，将可以使用以下细粒度权限开关：

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

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

使用 Docker 部署

edit

您可以使用 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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

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

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

使Sharepoint站点页面Web部件内容可搜索

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

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

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

限制

edit

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

同步规则

edit

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

高级同步规则

edit

需要进行全量同步，以使高级同步规则生效。

以下部分描述了此连接器的高级同步规则。高级同步规则通过特定于源的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

======== 示例：高级同步规则的边缘情况

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

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"
  }
}

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。此功能默认为此连接器提供。

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

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

内容提取

edit

默认内容提取

edit

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

参见内容提取。

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

edit

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

一个自管理的Elastic文本提取服务部署。
在默认的摄取管道设置中，文本提取将被禁用。

更多信息请参考本地内容提取。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为SharePoint Online连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=sharepoint_online

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=sharepoint_online DATA_SIZE=small

已知问题

edit

由于SharePoint文件和文件夹限制而未能同步的文档

SharePoint 对可以同步的文件和文件夹数量有限制。您可能会遇到类似以下错误，这些错误会写入未能同步的文档正文中： 文件大小超过允许的限制。相关ID: fdb36977-7cb8-4739-992f-49878ada6686, 协调世界时时间: 2022年4月21日下午11:24:22

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

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic SharePoint Server 连接器参考

edit

The Elastic SharePoint Server connector 是一个用于 connector for Microsoft SharePoint Server。

此连接器使用开源代码 Elastic 连接器框架用 Python 编写。查看此连接器的源代码。

寻找 SharePoint Online 连接器？请参阅 SharePoint Online 参考。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

自 Elastic 8.15.0 起，此连接器作为托管服务提供。要使用此连接器，请满足所有托管连接器要求。

此连接器处于测试版，可能会发生变化。测试版功能可能会发生变化，并且不受一般可用（GA）功能支持SLA的保障。 Elastic计划在未来版本中将此功能提升为GA。

创建一个 SharePoint Server 连接器

edit

使用用户界面

edit

要创建一个新的 SharePoint Server 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的本地 SharePoint Server 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的本地 SharePoint Server 连接器。

例如：

PUT _connector/my-sharepoint_server-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from SharePoint Server",
  "service_type": "sharepoint_server",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

请参阅Elastic 托管连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

以下SharePoint Server版本兼容：

SharePoint 2013
SharePoint 2016
SharePoint 2019

配置

edit

以下配置字段是设置连接器所必需的：

username

SharePoint Server实例的账户用户名。

password

账户的密码。

host_url

SharePoint Server实例所在的服务器主机URL。示例：

https://192.158.1.38:8080
https://.sharepoint.com

site_collections

逗号分隔的站点集合列表，用于从SharePoint Server获取数据。示例：

collection1
collection1, collection2

ssl_enabled

是否启用SSL验证。默认值是False。

ssl_ca

SharePoint Server 所需的 SSL 证书内容。如果 ssl_enabled 设置为 False，请保持此字段为空。

示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

retry_count

在请求SharePoint Server实例失败后的重试次数。默认值是 3。

use_document_level_security

启用后，将可以使用以下细粒度权限开关：

获取唯一列表权限: 启用此选项以获取唯一的列表权限。如果此设置被禁用，列表将继承其父站点的权限。
获取唯一列表项权限: 启用此选项以获取唯一的列表项权限。如果此设置被禁用，列表项将继承其父站点的权限。

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

文档和同步

edit

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

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

默认情况下，不会提取大于10 MB的文件内容。使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elasticsearch索引的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

请参阅搜索应用程序中的DLS，了解如何在构建搜索应用程序时，从启用了DLS的连接器中摄取数据。该示例使用SharePoint Online作为数据源，但相同的步骤适用于每个连接器。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

内容提取

edit

参见内容提取。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器使用 Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支 main，兼容 Elastic 9.0）。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自托管连接器的形式提供。此自托管连接器兼容 Elastic 版本 8.9.0+。要使用此连接器，请满足所有自托管连接器要求。

创建一个 SharePoint Server 连接器

edit

使用用户界面

edit

要创建一个新的 SharePoint Server 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 SharePoint Server 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自托管 SharePoint Server 自托管连接器。

例如：

PUT _connector/my-sharepoint_server-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from SharePoint Server",
  "service_type": "sharepoint_server"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请参阅自管理连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

兼容性

edit

以下SharePoint Server版本与Elastic连接器框架兼容：

SharePoint 2013
SharePoint 2016
SharePoint 2019

配置

edit

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

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

以下配置字段是设置连接器所必需的：

username

SharePoint Server实例的账户用户名。

password

账户的密码。

host_url

SharePoint Server实例所在的服务器主机URL。示例：

https://192.158.1.38:8080
https://.sharepoint.com

site_collections

逗号分隔的站点集合列表，用于从SharePoint Server获取数据。示例：

collection1
collection1, collection2

ssl_enabled

是否启用SSL验证。默认值是False。

ssl_ca

SharePoint Server 实例所需的 SSL 证书内容。如果 ssl_enabled 设置为 False，请保持此字段为空。

示例证书：

-----BEGIN CERTIFICATE-----
MIID+jCCAuKgAwIBAgIGAJJMzlxLMA0GCSqGSIb3DQEBCwUAMHoxCzAJBgNVBAYT
...
7RhLQyWn2u00L7/9Omw=
-----END CERTIFICATE-----

retry_count

对SharePoint Server实例请求失败后的重试次数。默认值是3。

use_document_level_security

启用后，将可以使用以下细粒度权限开关：

获取唯一列表权限: 启用此选项以获取唯一的列表权限。如果此设置被禁用，列表将继承其父站点的权限。
获取唯一列表项权限: 启用此选项以获取唯一的列表项权限。如果此设置被禁用，列表项将继承其父站点的权限。

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

使用 Docker 部署

edit

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

步骤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_server
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

文档和同步

edit

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

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

默认情况下，不会提取大于10 MB的文件内容。使用自管理的本地提取服务来处理较大的二进制文件。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elasticsearch索引的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步，但此功能目前默认情况下是禁用的。请参阅相关文档以启用增量同步。

文档级安全

edit

文档级安全（DLS）使您能够根据用户的权限限制对文档的访问。请参阅本页上的配置，了解如何为此连接器启用DLS。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则在当前版本中不适用于此连接器。目前过滤是通过摄取管道控制的。

内容提取

edit

参见内容提取。

自管理连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为sharepoint连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=sharepoint_server

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=sharepoint_server DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

框架和源

edit

此连接器使用 Elastic 连接器框架用 Python 编写。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic Slack 连接器参考

edit

Slack 连接器是使用 Elastic 连接器框架用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此托管连接器在 Elastic 8.14.0 版本中作为 Elastic Cloud 上的托管服务引入。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 Slack 连接器

edit

使用用户界面

edit

要创建一个新的 Slack 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Slack 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Slack 连接器。

例如：

PUT _connector/my-slack-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Slack",
  "service_type": "slack",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择Notion图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

您需要创建一个 Slack 应用程序以与 Slack 进行身份验证。

创建一个 Slack 应用程序

edit

当创建时，您将收到连接器用于身份验证的凭据。同时也会创建一个新的Bot用户。

连接器只会同步来自Bot用户所在频道的消息。

要创建应用程序，请按照以下步骤操作：

前往 https://api.slack.com/apps 并点击“创建新应用”。
选择“从头开始”。
为应用命名，并选择您希望从中同步的工作区。根据工作区的设置，您可能会收到关于需要管理员批准的警告。这将在稍后处理。
导航到侧边栏中的“OAuth & 权限”。
向下滚动到“范围”部分并添加这些范围：
- channels:history
- channels:read
- users:read。
  
  可选地，如果您希望应用机器人能够自动加入公共频道，您也可以添加channels:join。
向上滚动到“您工作区的OAuth令牌”并安装应用程序。您的工作区可能需要您获得管理员批准。如果是这样，请现在请求批准，并在批准后返回下一步。
复制并保存新的“Bot User OAuth Token”。此凭据将在配置连接器时使用。

配置

edit

以下设置是配置此连接器所必需的：

token(required): 通过创建和安装您的 Slack 应用程序生成的 Bot 用户 OAuth 令牌。
fetch_last_n_days(required): 从 Slack 获取历史记录的天数。这必须是一个正数，以获取从那一天开始回溯的数据子集。如果设置为 0，它将获取自工作区开始以来的所有数据。默认值是 180 天。
auto_join_channels(required): 连接器是否应自动将应用的机器人用户邀请到所有公共频道。连接器只会同步机器人用户所在的频道的消息。默认情况下，机器人不会邀请自己加入任何频道，并且必须手动邀请到您希望同步的每个频道。如果启用此设置，您的应用必须具有channels.join范围。
sync_users(required): 是否应为每个Slack用户索引一个文档。默认情况下，连接器只会为频道和消息创建文档。然而，无论此设置的值如何，Slack应用程序确实需要users.read范围，并将发出请求以枚举工作区的所有用户。这允许消息被丰富为人类可读的用户名，而不依赖于不可读的用户UID。因此，禁用此设置不会导致速度提升，而只会减少Elasticsearch中的总体存储量。

同步规则

edit

基本同步规则对所有连接器都是相同的，并且默认情况下可用。

当前版本中，此连接器不提供高级同步规则。

更多信息请阅读同步规则的类型。

内容提取

edit

此连接器目前不支持处理 Slack 附件或其他二进制文件。

文档和同步

edit

连接器同步以下对象和实体：

频道
消息
用户 (可配置)

仅同步公共频道及其中的消息。
不同步权限。所有文档 索引到 Elastic 部署后，将对 所有有权访问 该 Elastic 部署的用户可见。

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器作为自托管连接器从Elastic 连接器框架中提供。

这个自托管连接器兼容 Elastic 版本 8.10.0+。

要使用此连接器，请满足所有自我管理连接器的要求。

创建一个 Slack 连接器

edit

使用界面

edit

要创建一个新的 Slack 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Slack 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的自管理 Slack 自管理连接器。

例如：

PUT _connector/my-slack-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Slack",
  "service_type": "slack"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自管理连接器，请在 Kibana UI 中使用连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

您需要创建一个 Slack 应用程序以与 Slack 进行身份验证。

创建一个 Slack 应用程序

edit

当创建时，您将收到连接器用于身份验证的凭据。同时也会创建一个新的Bot用户。

连接器只会从机器人用户所在的频道同步消息。

要创建应用程序，请按照以下步骤操作：

前往 https://api.slack.com/apps 并点击“创建新应用”。
选择“从头开始”。
为应用命名，并选择您希望从中同步的工作区。根据工作区的设置，您可能会收到关于需要管理员批准的警告。这将在稍后处理。
导航到侧边栏中的“OAuth & 权限”。
向下滚动到“范围”部分并添加这些范围：
- channels:history
- channels:read
- users:read。
  
  可选地，如果您希望应用机器人能够自动加入公共频道，您也可以添加channels:join。
向上滚动到“您工作区的OAuth令牌”并安装应用程序。您的工作区可能需要您获得管理员批准。如果是这样，请现在请求批准，并在批准后返回下一步。
复制并保存新的“Bot用户OAuth令牌”。此凭据将在配置连接器时使用。

使用 Docker 部署

edit

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

步骤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: slack
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

配置

edit

以下设置是配置此连接器所必需的：

token(required): 通过创建和安装您的 Slack 应用程序生成的 Bot 用户 OAuth 令牌。
fetch_last_n_days(required): 从 Slack 获取历史记录的天数。这必须是一个正数，以获取从那一天开始回溯的数据子集。如果设置为 0，它将获取自工作区开始以来的所有数据。默认值是 180 天。
auto_join_channels(required): 连接器是否应自动将应用的机器人用户邀请到所有公共频道。连接器只会同步机器人用户所在的频道的消息。默认情况下，机器人不会邀请自己加入任何频道，并且必须手动邀请到您希望同步的每个频道。如果启用此设置，您的应用必须具有channels.join范围。
sync_users(required): 是否应为每个Slack用户索引一个文档。默认情况下，连接器只会为频道和消息创建文档。然而，无论此设置的值如何，Slack应用程序确实需要users.read权限，并将发出请求以枚举工作区的所有用户。这允许消息使用人类可读的用户名进行丰富，而不依赖于不可读的用户UID。因此，禁用此设置不会导致速度提升，而只会减少Elasticsearch中的总体存储量。

同步规则

edit

基本同步规则对所有连接器都是相同的，并且默认情况下可用。

当前版本中，此连接器不提供高级同步规则。

更多信息请阅读同步规则的类型。

内容提取

edit

此连接器目前不支持处理 Slack 附件或其他二进制文件。

文档和同步

edit

连接器同步以下对象和实体：

频道
消息
用户 (可配置)

仅同步公共频道和公共频道的消息。
不同步权限。 所有文档 索引到Elastic部署后将对 所有有权访问 该Elastic部署的用户可见。

自托管连接器操作

edit

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为GitHub连接器执行E2E测试，请运行以下命令：

$ make ftest NAME=slack

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=slack DATA_SIZE=small

已知问题

edit

目前此连接器没有已知问题。请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Microsoft Teams 连接器参考

edit

Microsoft Teams 连接器是使用 Elastic 连接器框架用 Python 编写的。

查看此连接器的源代码（分支main，兼容 Elastic 9.0）。

Elastic 托管连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此托管连接器在 Elastic 8.14.0 版本中作为 Elastic Cloud 上的托管服务引入。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个 Microsoft Teams 连接器

edit

使用用户界面

edit

要创建一个新的 Microsoft Teams 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Microsoft Teams 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Microsoft Teams 连接器。

例如：

PUT _connector/my-microsoft_teams-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Microsoft Teams",
  "service_type": "microsoft_teams",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择团队图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到 Microsoft Teams

edit

要连接到 Microsoft Teams，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。请按照以下步骤操作：

转到 Azure 门户并使用您的 Azure 账户登录。
导航到 Azure Active Directory 服务。
从左侧菜单中选择 应用注册。
点击 新注册 按钮以注册一个新应用程序。
为您的应用提供一个名称，并可选选择支持的账户类型（例如，单租户、多租户）。
点击注册按钮以创建应用注册。
注册完成后，您将被重定向到应用的概述页面。请记下 应用程序（客户端）ID 值，因为您稍后会需要它。
向下滚动到 API 权限 部分，然后点击“添加权限”按钮。
在“请求 API 权限”窗格中，选择“Microsoft Graph”作为 API。
选择以下权限：
- TeamMember.Read.All (Delegated)
- Team.ReadBasic.All (Delegated)
- TeamsTab.Read.All (Delegated)
- Group.Read.All (Delegated)
- ChannelMessage.Read.All (Delegated)
- Chat.Read (Delegated) & Chat.Read.All (Application)
- Chat.ReadBasic (Delegated) & Chat.ReadBasic.All (Application)
- Files.Read.All (Delegated and Application)
- Calendars.Read (Delegated and Application)
点击 添加权限 按钮以将所选权限添加到您的应用。
点击 授予管理员同意 按钮以授予应用所需的权限。此步骤需要管理员权限。如果您不是管理员，您需要请求管理员通过他们的 Azure 门户授予同意。
在“证书和密钥”选项卡下，转到 客户端密钥。生成一个新的客户端密钥，并记下 Value 列下的字符串。

完成后，使用以下配置参数来配置连接器。

配置

edit

以下配置字段是必需的：

client_id (required)

Azure 应用程序的唯一标识符，可在应用程序的概述页面上找到。示例：

ab123453-12a2-100a-1123-93fd09d67394

secret_value (required)

应用程序在请求令牌时用于证明其身份的字符串值，可在 Azure 应用程序菜单的 证书和密钥 选项卡下找到。示例：

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

tenant_id (required)

Azure Active Directory 实例的唯一标识符，可在应用的概述页面上找到。示例：

123a1b23-12a3-45b6-7c8d-fc931cfb448d

username (required)

您的Azure应用程序的用户名。示例：

dummy@3hmr2@onmicrosoft.com

password (required)

Azure 应用程序的密码。示例：

changeme

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

用户聊天消息
用户聊天标签
用户聊天附件
用户聊天会议记录
用户会议
团队
团队频道
频道标签
频道消息
频道会议
频道附件
日历事件

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

已知问题

edit

与自己聊天用户的个人聊天消息不会通过Graph API获取。因此，这些消息不会被索引到Elasticsearch中。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自管理连接器的形式提供。要使用此连接器，请满足所有自管理连接器先决条件。

创建一个 Microsoft Teams 连接器

edit

使用用户界面

edit

要创建一个新的 Microsoft Teams 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Microsoft Teams 自管理连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自管理 Microsoft Teams 自管理连接器。

例如：

PUT _connector/my-microsoft_teams-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Microsoft Teams",
  "service_type": "microsoft_teams"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要使用此连接器作为自托管连接器，请从连接器列表中使用Microsoft Teams磁贴的自定义连接器工作流程。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到 Microsoft Teams

edit

要连接到 Microsoft Teams，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。请按照以下步骤操作：

转到 Azure 门户并使用您的 Azure 账户登录。
导航到 Azure Active Directory 服务。
从左侧菜单中选择 应用注册。
点击 新注册 按钮以注册一个新应用程序。
为您的应用提供一个名称，并可选选择支持的账户类型（例如，单租户、多租户）。
点击注册按钮以创建应用注册。
注册完成后，您将被重定向到应用的概览页面。请记下 应用程序（客户端）ID 值，因为您稍后会需要它。
向下滚动到 API 权限 部分，然后点击“添加权限”按钮。
在“请求 API 权限”窗格中，选择“Microsoft Graph”作为 API。
选择以下权限：
- TeamMember.Read.All (Delegated)
- Team.ReadBasic.All (Delegated)
- TeamsTab.Read.All (Delegated)
- Group.Read.All (Delegated)
- ChannelMessage.Read.All (Delegated)
- Chat.Read (Delegated) & Chat.Read.All (Application)
- Chat.ReadBasic (Delegated) & Chat.ReadBasic.All (Application)
- Files.Read.All (Delegated and Application)
- Calendars.Read (Delegated and Application)
点击 添加权限 按钮以将所选权限添加到您的应用。
点击 授予管理员同意 按钮以授予应用所需的权限。此步骤需要管理员权限。如果您不是管理员，您需要请求管理员通过他们的 Azure 门户授予同意。
在“证书和密钥”选项卡下，转到 客户端密钥。生成一个新的客户端密钥，并记下 Value 列下的字符串。

完成后，使用以下配置参数来配置连接器。

配置

edit

以下配置字段是必需的：

client_id (required)

Azure 应用程序的唯一标识符，可在应用程序的概述页面上找到。示例：

ab123453-12a2-100a-1123-93fd09d67394

secret_value (required)

应用程序在请求令牌时用于证明其身份的字符串值，可在 Azure 应用程序菜单的 证书和密钥 选项卡下找到。示例：

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

tenant_id (required)

Azure Active Directory 实例的唯一标识符，可在应用的概述页面上找到。示例：

123a1b23-12a3-45b6-7c8d-fc931cfb448d

username (required)

您的Azure应用程序的用户名。示例：

dummy@3hmr2@onmicrosoft.com

password (required)

Azure 应用程序的密码。示例：

changeme

使用 Docker 部署

edit

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

步骤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: microsoft_teams
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

用户聊天消息
用户聊天标签
用户聊天附件
用户聊天会议记录
用户会议
团队
团队频道
频道标签
频道消息
频道会议
频道附件
日历事件

大于10 MB的文件将不会被提取。
权限不会同步。所有文档索引到Elastic部署后，将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

端到端测试

edit

连接器框架使操作员能够针对真实数据源运行功能测试。有关更多详细信息，请参阅连接器测试。

要为 Teams 连接器执行端到端测试，请运行以下命令：

$ make ftest NAME=microsoft_teams

为了加快测试速度，添加 DATA_SIZE=small 标志：

make ftest NAME=microsoft_teams DATA_SIZE=small

已知问题

edit

与自己聊天用户的单聊消息不会通过Graph API获取。因此，这些消息不会被索引到Elasticsearch中。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

Elastic Zoom 连接器参考

edit

Zoom 连接器是使用 Elastic 连接器框架用 Python 编写的。

查看此连接器的源代码（分支main，兼容Elastic 9.0）。

弹性管理连接器参考

edit

查看Elastic 托管连接器参考

可用性和先决条件

edit

此托管连接器在 Elastic 8.14.0 版本中作为 Elastic Cloud 上的托管服务引入。

要在 Elastic Cloud 中本机使用此连接器，请满足所有托管连接器要求。

创建一个Zoom连接器

edit

使用用户界面

edit

要创建一个新的 Zoom 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的原生 Zoom 连接器。

有关其他操作，请参阅 Kibana 中的连接器 UI。

使用API

edit

您可以使用 Elasticsearch 的 Create connector API 来创建一个新的原生 Zoom 连接器。

例如：

PUT _connector/my-zoom-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Zoom",
  "service_type": "zoom",
  "is_native": "true"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中的 id 和 encoded 返回值：

POST /_security/api_key
{
  "name": "my-connector-api-key",
  "role_descriptors": {
    "my-connector-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "my-index_name",
            ".search-acl-filter-my-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

使用 encoded 值来存储连接器密钥，并注意此响应返回的 id 值：
```
POST _connector/_secret
{
  "value": "encoded_api_key"
}
```

使用 API 密钥 id 和连接器密钥 id 来更新连接器：

PUT /_connector/my_connector_id>/_api_key_id
{
  "api_key_id": "API key_id",
  "api_key_secret_id": "secret_id"
}

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择Zoom图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到Zoom

edit

要连接到 Zoom，您需要创建一个 Server-to-Server OAuth 应用程序，以便访问资源。请按照以下步骤操作：

前往 Zoom 应用市场并使用您的 Zoom 账户登录。
导航到“开发”服务。
从下拉菜单中选择“构建应用”。
点击“服务器到服务器 OAuth”按钮以注册一个新应用程序。
为您的应用提供一个名称。
点击“创建”按钮以创建应用注册。
注册完成后，您将被重定向到应用的概览页面。请记下“应用凭证”值，因为您稍后会需要它。
导航到“范围”部分并点击“添加范围”按钮。

以下细粒度范围需要添加到应用程序中。

user:read:list_users:admin
meeting:read:list_meetings:admin
meeting:read:list_past_participants:admin
cloud_recording:read:list_user_recordings:admin
team_chat:read:list_user_channels:admin
team_chat:read:list_user_messages:admin

连接器需要的最小范围是 user:read:list_users:admin 才能将数据导入 Elasticsearch。

+ 10. 点击“完成”按钮以将所选范围添加到您的应用中。 11. 导航到“激活”部分并输入必要的信息以激活应用。

完成后，使用以下配置参数来配置连接器。

配置

edit

以下配置字段是必需的：

Zoom application Account ID

(必填) "账户ID" 是与Zoom平台中特定Zoom账户相关联的唯一标识符，可在应用的概览页面上找到。示例：

KVx-aQssTOutOAGrDfgMaA

Zoom application Client ID

(必填) "客户端ID" 是指与Zoom平台集成的应用程序的唯一标识符，可以在应用程序的概览页面上找到。示例：

49Z69_rnRiaF4JYyfHusw

Zoom application Client Secret

(必需) “客户端密钥”是指开发者在Zoom开发者门户上注册应用程序以与Zoom平台集成时生成的一条机密信息，可以在应用程序的概览页面上找到。示例：

eieiUJRsiH543P5NbYadavczjkqgdRTw

Recording Age Limit (Months)

(必需) 从Zoom请求录音的时间范围。超过此时间范围的录音将不会被索引。此配置参数允许您定义一个时间限制，以月为单位，用于索引录音。

Fetch past meeting details

获取有关以前会议的更多信息，包括详细信息和参与者。默认值为False。启用此选项以获取过去的会议详细信息。此设置可能会增加同步时间。

内容提取

edit

请参阅内容提取。

文档和同步

edit

连接器同步以下对象和实体：

用户
实时会议
即将举行的会议
过去的会议
录音
频道
聊天消息
聊天文件

大于10 MB的文件内容将不会被提取。（自托管连接器可以使用自托管本地提取服务来处理较大的二进制文件。）
权限不会同步。所有文档索引到Elastic部署后将对所有有权访问该Elastic部署的用户可见。

同步类型

edit

全量同步默认支持所有连接器。

此连接器还支持增量同步。

同步规则

edit

基本同步规则对于所有连接器都是相同的，并且默认情况下可用。

高级同步规则

edit

当前版本中，此连接器不提供高级同步规则。

已知问题

edit

会议: 用户只能索引不到一个月的会议。
聊天消息和文件: 用户只能索引不到6个月的聊天记录和文件。

请参阅已知问题以获取所有连接器的已知问题列表。

故障排除

edit

参见故障排除。

安全性

edit

参见安全。

自托管连接器参考

edit

查看自托管连接器参考

可用性和先决条件

edit

此连接器以自管理连接器的形式提供。要使用此连接器，请满足所有自管理连接器先决条件。

创建一个Zoom连接器

edit

使用界面

edit

要创建一个新的 Zoom 连接器：

导航到 Kibana UI 中的 搜索 → 连接器 页面。
按照说明创建一个新的 Zoom 自托管连接器。

使用API

edit

您可以使用 Elasticsearch 的创建连接器 API 来创建一个新的自托管 Zoom 自托管连接器。

例如：

PUT _connector/my-zoom-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from Zoom",
  "service_type": "zoom"
}

您还需要为连接器创建一个API密钥。

用户需要集群权限 manage_api_key、manage_connector 和 write_connector_secrets 才能以编程方式生成 API 密钥。

要为连接器创建API密钥：

运行以下命令，替换指示的值。注意响应中encoded返回值：

POST /_security/api_key
{
  "name": "connector_name-connector-api-key",
  "role_descriptors": {
    "connector_name-connector-role": {
      "cluster": [
        "monitor",
        "manage_connector"
      ],
      "indices": [
        {
          "names": [
            "index_name",
            ".search-acl-filter-index_name",
            ".elastic-connectors*"
          ],
          "privileges": [
            "all"
          ],
          "allow_restricted_indices": false
        }
      ]
    }
  }
}

更新你的config.yml文件，使用API密钥encoded值。

有关所有可用连接器API的详细信息，请参阅Elasticsearch API 文档。

用法

edit

要在用户界面中使用此连接器，请在搜索 → 连接器下创建新连接器时选择团队图块。

如果你已经熟悉连接器的工作原理，你也可以使用连接器API。

有关其他操作，请参阅 Kibana 中的连接器 UI。

连接到Zoom

edit

要连接到 Zoom，您需要创建一个 Server-to-Server OAuth 应用程序，以便访问资源。请按照以下步骤操作：

前往 Zoom 应用市场并使用您的 Zoom 账户登录。
导航到“开发”服务。
从下拉菜单中选择“构建应用”。
点击“服务器到服务器 OAuth”按钮以注册一个新应用程序。
为您的应用提供一个名称。
点击“创建”按钮以创建应用注册。
注册完成后，您将被重定向到应用的概览页面。请记下“应用凭证”值，因为您稍后会需要它。
导航到“范围”部分并点击“添加范围”按钮。

以下细粒度范围需要添加到应用程序中。

user:read:list_users:admin
meeting:read:list_meetings:admin
meeting:read:list_past_participants:admin
cloud_recording:read:list_user_recordings:admin
team_chat:read:list_user_channels:admin
team_chat:read:list_user_messages:admin

连接器需要的最小范围是 user:read:list_users:admin 才能将数据导入 Elasticsearch。

+ 10. 点击“完成”按钮以将所选范围添加到您的应用中。 11. 导航到“激活”部分并输入必要的信息以激活应用。

完成后，使用以下配置参数来配置连接器。

配置

edit

以下配置字段是必需的：

Zoom application Account ID

(必填) "账户ID" 是与Zoom平台中特定Zoom账户相关联的唯一标识符，可在应用的概览页面上找到。示例：

KVx-aQssTOutOAGrDfgMaA

Zoom application Client ID

(必填) "Client ID" 指的是与 Zoom 平台集成的应用程序的唯一标识符，可以在应用程序的概览页面上找到。示例：

49Z69_rnRiaF4JYyfHusw

Zoom application Client Secret

(必需) “客户端密钥”是指开发者在Zoom开发者门户上注册应用程序以与Zoom平台集成时生成的一条机密信息，可以在应用程序的概览页面上找到。示例：

eieiUJRsiH543P5NbYadavczjkqgdRTw

Recording Age Limit (Months)

(必需) 从Zoom请求录制文件的时间范围。早于此时间的录制文件将不会被索引。此配置参数允许您定义一个时间限制，以月为单位，用于索引录制文件。

Fetch past meeting details

获取有关以前会议的更多信息，包括详细信息和参与者。默认值为False。启用此选项以获取过去的会议详细信息。此设置可能会增加同步时间。

使用 Docker 部署

edit

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

步骤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: zoom
    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实例。

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

第三步：运行 Docker 镜像

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

docker run \
-v ~/connectors-config:/config \
--network "elastic" \
--tty \
--rm \
docker.elastic.co/integrations/elastic-connectors:9.0.0-beta1.0 \
/app/bin/elastic-ingest \
-c /config/config.yml

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

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