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

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 托管连接器。

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

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

Dropbox API 授权

编辑

创建 Dropbox OAuth 应用程序

编辑

您需要在 Dropbox 平台中按照以下步骤创建 OAuth 应用程序

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

生成刷新令牌

编辑

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

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

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

确保响应具有以下范围列表
- account_info.read
- files.content.read
- files.metadata.read
- sharing.read
- team_info.read（如果使用文档级安全性）
- team_data.member（如果使用文档级安全性）
- team_data.content.read（如果使用文档级安全性）
- members.read（如果使用文档级安全性）

配置

编辑

需要以下配置字段来设置连接器

要获取文件/文件夹的路径: 从 Dropbox 中获取文件/文件夹的文件夹路径。默认值为 /。

可以通过高级同步规则绕过此字段。
应用程序密钥: 用于验证您的 Dropbox 应用程序的应用程序密钥。
应用程序机密: 用于验证您的 Dropbox 应用程序的应用程序机密。
刷新令牌: 用于验证您的 Dropbox 应用程序的刷新令牌。
启用文档级安全性: 切换以启用文档级安全性 (DLS)。启用后，完全同步将获取每个文档的访问控制列表，并将它们存储在 _allow_access_control 字段中。访问控制同步将获取用户的访问控制列表，并将它们存储在单独的索引中。
包括组和继承用户: 当启用文档级安全性时出现。索引权限时包括组和继承用户。

启用 包括组和继承用户 将导致性能显著下降。

文档和同步

编辑

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

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

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

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

同步类型

编辑

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

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

同步规则

编辑

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

高级同步规则

编辑

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

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

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 文件的内容提取。

已知问题

编辑

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

故障排除

编辑

有关所有连接器的故障排除提示列表，请参阅故障排除。

安全

编辑

有关所有连接器的安全提示列表，请参阅安全。

内容提取

编辑

请参阅内容提取。

自托管连接器

编辑

查看自托管连接器参考

可用性和先决条件

编辑

此连接器可用作自托管自托管连接器。

此自托管连接器与 Elastic 版本 8.9.0+ 兼容。

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

创建 Dropbox 连接器

编辑

使用 UI

编辑

创建新的 Dropbox 连接器

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

使用 API

编辑

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

例如

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

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。

Dropbox API 授权

编辑

创建 Dropbox OAuth 应用程序

编辑

您需要在 Dropbox 平台中按照以下步骤创建 OAuth 应用程序

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

生成刷新令牌

编辑

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

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

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

确保响应具有以下范围列表
- account_info.read
- files.content.read
- files.metadata.read
- sharing.read
- team_info.read（如果使用文档级安全性）
- team_data.member（如果使用文档级安全性）
- team_data.content.read（如果使用文档级安全性）
- members.read（如果使用文档级安全性）

配置

编辑

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

这些可配置字段将在 Kibana UI 中使用它们各自的标签进行呈现。连接后，您将能够在 Kibana 中更新这些值。

需要以下配置字段来设置连接器

路径: 从 Dropbox 中获取文件/文件夹的文件夹路径。默认值为 /。
app_key（必需）: 用于验证您的 Dropbox 应用程序的应用程序密钥。
app_secret（必需）: 用于验证您的 Dropbox 应用程序的应用程序机密。
refresh_token（必需）: 用于验证您的 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 部署

编辑

您可以使用 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 实例进行身份验证。

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

步骤 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 镜像。