resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
    is_native=True,
)
print(resp)

const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
  is_native: true,
});
console.log(response);

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返回值

resp = client.security.create_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
                }
            ]
        }
    },
)
print(resp)

const response = await client.security.createApiKey({
  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,
        },
      ],
    },
  },
});
console.log(response);

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返回值

resp = client.connector.secret_post(
    body={
        "value": "encoded_api_key"
    },
)
print(resp)

const response = await client.connector.secretPost({
  body: {
    value: "encoded_api_key",
  },
});
console.log(response);

POST _connector/_secret
{
  "value": "encoded_api_key"
}

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

resp = client.connector.update_api_key_id(
    connector_id="my_connector_id>",
    api_key_id="API key_id",
    api_key_secret_id="secret_id",
)
print(resp)

const response = await client.connector.updateApiKeyId({
  connector_id: "my_connector_id>",
  api_key_id: "API key_id",
  api_key_secret_id: "secret_id",
});
console.log(response);

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

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

用法

编辑

要在 Elastic Cloud 中原生使用此连接器，请参见Elastic 托管连接器。

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

连接到 OneDrive

编辑

要连接到 OneDrive，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。

请按照以下步骤操作

转到Azure 门户并使用您的 Azure 帐户登录。
导航到Azure Active Directory服务。
从左侧菜单中选择应用程序注册。
单击新建注册按钮以注册新的应用程序。
为您的应用程序提供名称，并可以选择支持的帐户类型（例如，单租户、多租户）。
单击注册按钮以创建应用程序注册。
注册完成后，您将被重定向到应用程序的概述页面。记下应用程序（客户端）ID值，以后您将需要它。
向下滚动到API 权限部分，然后单击添加权限按钮。
在请求 API 权限窗格中，选择Microsoft Graph作为 API。
选择应用程序权限，并在应用程序选项卡下选择以下权限：User.Read.All、File.Read.All
单击添加权限按钮，将选定的权限添加到您的应用程序。最后，单击授予管理员同意按钮，向应用程序授予所需的权限。此步骤需要管理员权限。注意：如果您不是管理员，则需要请求管理员通过他们的 Azure 门户授予同意。
单击证书和密钥选项卡。转到客户端密钥。生成一个新的客户端密钥，并记下Value列下的字符串。

配置

编辑

以下配置字段是必需的

Azure 应用程序客户端 ID

Azure 应用程序的唯一标识符，位于应用程序的概述页面。示例

ab123453-12a2-100a-1123-93fd09d67394

Azure 应用程序客户端密钥

应用程序在请求令牌时用于证明其身份的字符串值，可在 Azure 应用程序菜单的证书和密钥选项卡下找到。示例

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

Azure 应用程序租户 ID

Azure Active Directory 实例的唯一标识符。示例

123a1b23-12a3-45b6-7c8d-fc931cfb448d

启用文档级安全性

切换以启用文档级安全性。启用后

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

为您的连接器启用 DLS 将导致明显的性能下降，因为此功能所需的对数据源的 API 调用受到速率限制。这会影响检索内容的速度。

内容提取

编辑

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

文档和同步

编辑

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

文件
- 包括文件名称、路径、大小、内容等元数据。
文件夹

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

同步类型

编辑

默认情况下，所有连接器都支持完全同步。

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

文档级安全性

编辑

文档级安全性 (DLS) 使您可以根据用户的权限限制对文档的访问。此功能默认情况下适用于 OneDrive 连接器。有关如何为此连接器启用 DLS，请参阅配置。

有关此功能的更多详细信息，请参阅文档级安全性。

请参阅搜索应用程序中的 DLS，了解如何在构建搜索应用程序时摄取启用 DLS 的数据。

同步规则

编辑

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

高级同步规则

编辑

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

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

以下是一些此连接器高级同步规则的示例。

======= 示例 1

此规则跳过对扩展名为.xlsx和.docx的文件的索引。所有其他文件和文件夹都将被索引。

[
  {
    "skipFilesWithExtensions": [".xlsx" , ".docx"]
  }
]

======= 示例 2

此规则专注于索引[email protected]和[email protected]拥有的文件和文件夹，但排除扩展名为.py的文件。

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 3

此规则仅索引根文件夹内的文件和文件夹，排除任何.md文件。

[
  {
    "skipFilesWithExtensions": [".md"],
    "parentPathPattern": "/drive/root:"
  }
]

======= 示例 4

此规则索引由[email protected]和[email protected]拥有的文件和文件夹，这些文件和文件夹直接位于根目录下hello目录的任何子目录下的abc文件夹内。扩展名为.pdf和.py的文件将被排除。

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".pdf", ".py"],
    "parentPathPattern": "/drive/root:/hello/**/abc"
  }
]

======= 示例 5

此示例包含两条规则。第一条规则索引由[email protected]和[email protected]拥有的所有文件和文件夹。第二条规则索引所有其他用户的文件，但跳过扩展名为.py的文件。

[
  {
    "owners": ["[email protected]", "[email protected]"]
  },
  {
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 6

此示例包含两条规则。第一条规则索引由[email protected]和[email protected]拥有的所有文件，排除.md文件。第二条规则递归地索引abc文件夹内的文件和文件夹。

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".md"]
  },
  {
    "parentPathPattern": "/drive/root:/abc/**"
  }
]

内容提取

编辑

参见内容提取。

已知问题

编辑

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

为您的连接器启用 DLS 将导致明显的性能下降，因为此功能所需的对数据源的 API 调用受到速率限制。这会影响检索内容的速度。

请参考已知问题，了解所有连接器的已知问题列表。

故障排除

编辑

参见故障排除。

安全

编辑

参见安全。

自管理连接器

编辑

查看自管理连接器参考

可用性和先决条件

编辑

此连接器作为自管理自管理连接器提供。

此自管理连接器与 Elastic 版本8.10.0+兼容。

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

创建 OneDrive 连接器

编辑

使用 UI

编辑

要创建一个新的 OneDrive 连接器

在 Kibana UI 中，从主菜单导航到搜索 → 内容 → 连接器页面，或使用全局搜索字段。
按照说明创建新的OneDrive自管理连接器。

使用 API

编辑

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

例如

resp = client.connector.put(
    connector_id="my-{service-name-stub}-connector",
    index_name="my-elasticsearch-index",
    name="Content synced from {service-name}",
    service_type="{service-name-stub}",
)
print(resp)

const response = await client.connector.put({
  connector_id: "my-{service-name-stub}-connector",
  index_name: "my-elasticsearch-index",
  name: "Content synced from {service-name}",
  service_type: "{service-name-stub}",
});
console.log(response);

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值

resp = client.security.create_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
                }
            ]
        }
    },
)
print(resp)

const response = await client.security.createApiKey({
  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,
        },
      ],
    },
  },
});
console.log(response);

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
        }
      ]
    }
  }
}

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

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

用法

编辑

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

连接到 OneDrive

编辑

要连接到 OneDrive，您需要创建一个可以访问资源的 Azure Active Directory 应用程序和服务主体。

请按照以下步骤操作

转到Azure 门户并使用您的 Azure 帐户登录。
导航到Azure Active Directory服务。
从左侧菜单中选择应用程序注册。
单击新建注册按钮以注册新的应用程序。
为您的应用程序提供名称，并可以选择支持的帐户类型（例如，单租户、多租户）。
单击注册按钮以创建应用程序注册。
注册完成后，您将被重定向到应用程序的概述页面。记下应用程序（客户端）ID值，以后您将需要它。
向下滚动到API 权限部分，然后单击添加权限按钮。
在请求 API 权限窗格中，选择Microsoft Graph作为 API。
选择应用程序权限，并在应用程序选项卡下选择以下权限：User.Read.All、File.Read.All
单击添加权限按钮，将选定的权限添加到您的应用程序。最后，单击授予管理员同意按钮，向应用程序授予所需的权限。此步骤需要管理员权限。注意：如果您不是管理员，则需要请求管理员通过他们的 Azure 门户授予同意。
单击证书和密钥选项卡。转到客户端密钥。生成一个新的客户端密钥，并记下Value列下的字符串。

使用 Docker 部署

编辑

自管理连接器在您自己的基础设施上运行。

您可以使用 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

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

# 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 实例进行身份验证。

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

步骤 3：运行 Docker 镜像

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

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

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

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

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

配置

编辑

以下配置字段是必需的

client_id

Azure 应用程序客户端 ID，Azure 应用程序的唯一标识符，可在应用程序的概述页面上找到。示例

ab123453-12a2-100a-1123-93fd09d67394

client_secret

Azure 应用程序客户端密钥，应用程序在请求令牌时用于证明其身份的字符串值。可在 Azure 应用程序菜单的Certificates & Secrets选项卡下找到。示例

eyav1~12aBadIg6SL-STDfg102eBfCGkbKBq_Ddyu

tenant_id

Azure 应用程序租户 ID：Azure Active Directory 实例的唯一标识符。示例

123a1b23-12a3-45b6-7c8d-fc931cfb448d

retry_count

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

use_document_level_security

切换以启用文档级安全性。启用后

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

为您的连接器启用 DLS 将导致明显的性能下降，因为此功能所需的对数据源的 API 调用受到速率限制。这会影响检索内容的速度。

use_text_extraction_service

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

内容提取

编辑

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

文档和同步

编辑

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

文件
- 包括文件名称、路径、大小、内容等元数据。
文件夹

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

同步类型

编辑

默认情况下，所有连接器都支持完全同步。

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

文档级安全性

编辑

文档级安全性 (DLS) 使您可以根据用户的权限限制对文档的访问。此功能对于 OneDrive 连接器默认可用。有关如何为此连接器启用 DLS 的信息，请参见配置。

有关此功能的更多详细信息，请参阅文档级安全性。

请参阅搜索应用程序中的 DLS，了解如何在构建搜索应用程序时摄取启用 DLS 的数据。

同步规则

编辑

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

高级同步规则

编辑

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

以下是一些此连接器高级同步规则的示例。

======= 示例 1

此规则跳过对扩展名为.xlsx和.docx的文件的索引。所有其他文件和文件夹都将被索引。

[
  {
    "skipFilesWithExtensions": [".xlsx" , ".docx"]
  }
]

======= 示例 2

此规则专注于索引[email protected]和[email protected]拥有的文件和文件夹，但排除扩展名为.py的文件。

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 3

此规则仅索引根文件夹内的文件和文件夹，排除任何.md文件。

[
  {
    "skipFilesWithExtensions": [".md"],
    "parentPathPattern": "/drive/root:"
  }
]

======= 示例 4

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".pdf", ".py"],
    "parentPathPattern": "/drive/root:/hello/**/abc"
  }
]

======= 示例 5

[
  {
    "owners": ["[email protected]", "[email protected]"]
  },
  {
    "skipFilesWithExtensions": [".py"]
  }
]

======= 示例 6

[
  {
    "owners": ["[email protected]", "[email protected]"],
    "skipFilesWithExtensions": [".md"]
  },
  {
    "parentPathPattern": "/drive/root:/abc/**"
  }
]

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

要对 GitHub 连接器执行端到端测试，请运行以下命令

$ make ftest NAME=onedrive

为了更快地进行测试，请添加DATA_SIZE=small标志

make ftest NAME=onedrive DATA_SIZE=small

已知问题

编辑

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

为您的连接器启用 DLS 将导致明显的性能下降，因为此功能所需的对数据源的 API 调用受到速率限制。这会影响检索内容的速度。

请参考已知问题，了解所有连接器的已知问题列表。

故障排除

编辑

参见故障排除。

安全

编辑

参见安全。

« Elastic Notion 连接器参考 Elastic OpenText Documentum 连接器参考 »

Elastic OneDrive 连接器参考