New

The executive guide to generative AI

Read more
About usPartnersSupport|Login
« Elastic Notion 连接器参考 Elastic OpenText Documentum 连接器参考 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›使用 Elastic 连接器摄取内容 ›连接器参考

Elastic OneDrive 连接器参考

编辑

Elastic OneDrive 连接器参考

编辑

Elastic OneDrive 连接器是 OneDrive 的一个连接器。 此连接器使用 Elastic 连接器框架以 Python 编写。

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

选择您的连接器参考

您是在 Elastic Cloud 上使用托管连接器还是使用自托管连接器？根据您的部署方法展开文档。

Elastic 托管连接器参考

编辑
查看Elastic 托管连接器参考

可用性和先决条件

编辑

此连接器从 Elastic 版本 8.11.0 开始作为托管连接器提供。

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

创建 OneDrive 连接器

编辑

使用 UI

编辑

要创建新的 OneDrive 连接器

  1. 在 Kibana UI 中，从主菜单导航至搜索 → 内容 → 连接器页面，或使用全局搜索字段。
  2. 按照说明创建新的原生 OneDrive 连接器。

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

使用 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}",
    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
}
Copy as curlTry in Elastic 
您还需要创建一个 API 密钥供连接器使用。

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

要为连接器创建 API 密钥

  1. 运行以下命令，替换指示的值。请注意响应返回的 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
        }
      ]
    }
  }
}
    Copy as curlTry in Elastic 

  2. 使用 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"
}
    Copy as curlTry in Elastic 

  3. 使用 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"
}
    Copy as curlTry in Elastic 

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

用法

编辑

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

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

连接到 OneDrive

编辑

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

请按照以下步骤操作

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

配置

编辑

以下配置字段是必需的

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

此规则侧重于索引 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/**"
  }
]

内容提取

编辑

请参阅内容提取。

已知问题

编辑

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

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

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

自管理连接器

编辑
查看 自管理连接器 参考

可用性和先决条件

编辑

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

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

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

创建 OneDrive 连接器

编辑

使用 UI

编辑

要创建新的 OneDrive 连接器

  1. 在 Kibana UI 中，从主菜单导航至搜索 → 内容 → 连接器页面，或使用全局搜索字段。
  2. 按照说明创建新的 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"
}
Copy as curlTry in Elastic 
您还需要创建一个 API 密钥供连接器使用。

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

要为连接器创建 API 密钥

  1. 运行以下命令，替换指示的值。请注意响应中返回的 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
        }
      ]
    }
  }
}
    Copy as curlTry in Elastic 
  2. 使用 API 密钥 encoded 值更新您的 config.yml 文件。

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

用法

编辑

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

连接到 OneDrive

编辑

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

请按照以下步骤操作

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

使用 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

如果您针对 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 实例。

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

步骤 3：运行 Docker 镜像

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

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

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

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

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

配置

编辑

以下配置字段是必需的

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

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

  • 完整同步将获取每个文档的访问控制列表，并将其存储在 _allow_access_control 字段中。

  • 访问控制同步将获取用户的访问控制列表，并将其存储在单独的索引中。

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

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

内容提取

编辑

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

文档和同步

编辑

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

  • 文件

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

同步类型

编辑

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

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

文档级安全性

编辑

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

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

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

同步规则

编辑

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

高级同步规则

编辑

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

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

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

示例 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/**"
  }
]

内容提取

编辑

请参阅内容提取。

自管理连接器操作

编辑

端到端测试

编辑

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

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

$ make ftest NAME=onedrive

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

make ftest NAME=onedrive DATA_SIZE=small

已知问题

编辑

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

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

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

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