« Elastic Azure Blob 存储连接器参考 Elastic Confluence 连接器参考 »
Elastic 文档 ›Elasticsearch 指南 [8.17] ›使用 Elastic 连接器提取内容 ›连接器参考

Elastic Box 连接器参考

编辑

Elastic Box 连接器参考

编辑

Box 连接器使用 Python 编写，并使用 Elastic 连接器框架。

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

Elastic 托管连接器参考

编辑
查看Elastic 托管连接器参考
可用性和先决条件
编辑

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

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

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

创建 Box 连接器
编辑

使用 UI

编辑

要创建新的 Box 连接器

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

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

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API来创建新的原生 Box 连接器。

例如

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-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 密钥

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

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

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

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

用法
编辑

要将此连接器用作自托管连接器，请使用连接器列表中的Box磁贴或自定义连接器工作流程。

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

Box API 授权
编辑
Box 免费帐户
编辑

创建 Box 用户身份验证 (OAuth 2.0) 自定义应用程序

您需要在 Box 开发人员控制台中创建一个 OAuth 应用程序，请按照以下步骤操作

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

生成刷新令牌

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

  1. 转到以下 URL，将 <CLIENT_ID> 替换为之前保存的客户端 ID 值。例如

    https://account.box.com/api/oauth2/authorize?response_type=code&client_id=<CLIENT_ID>
  2. 授予对您应用程序的访问权限。
  3. 您现在将被重定向到您在 重定向 URI 中配置的网页，并且 HTTP 响应应包含一个授权代码，您将使用该代码生成刷新令牌。注意： 用于生成刷新令牌的授权代码只能使用一次，且仅在 30 秒内有效。

  4. 在您的终端中，运行以下 curl 命令，将 <AUTHORIZATION_CODE>、<CLIENT_ID> 和 <CLIENT_SECRET> 替换为您之前保存的值

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

    从响应中保存刷新令牌。您将需要在连接器配置中使用它。

Box 企业帐户
编辑

创建 Box 服务器身份验证（客户端凭据授权）自定义应用程序

  1. 在Box 开发控制台中使用自定义应用程序注册新应用程序，并选择服务器身份验证（客户端凭据授权）。

  2. 选中以下权限

    • “应用程序范围”中的“写入 Box 中存储的所有文件和文件夹”
    • “高级功能”中的“使用 as-user 标头进行 API 调用”
  3. 在“应用程序访问级别”中选择 应用程序 + 企业访问。
  4. 从管理控制台授权您的应用程序。保存客户端凭据和企业 ID。您将需要这些来配置连接器。
配置
编辑
Box 帐户 (必需)
用于确定 Box 帐户类型的下拉列表：Box 免费帐户或Box 企业帐户。默认值为 Box 免费帐户。
客户端 ID (必需)
用于使用 Box 实例进行身份验证的客户端 ID。
客户端密钥 (必需)
用于使用 Box 实例进行身份验证的客户端密钥。
刷新令牌 (如果 Box 帐户为 Box 免费帐户，则为必需)
用于生成访问令牌的刷新令牌。注意：如果进程终止，您将需要生成新的刷新令牌。
企业 ID (如果 Box 帐户为 Box 企业帐户，则为必需)
用于使用 Box 实例进行身份验证的企业 ID。
内容提取
编辑

请参阅内容提取。

文档和同步
编辑

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

  • 文件
  • 文件夹
  • 不会提取大于 10 MB 的文件。
  • 不会同步权限。所有文档索引到 Elastic 部署后，将对所有具有访问权限的用户可见。
同步类型
编辑

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

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

同步规则
编辑

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

高级同步规则
编辑

此连接器在当前版本中不可用高级同步规则。

已知问题
编辑

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

故障排除
编辑

请参阅故障排除。

安全性
编辑

请参阅安全性。

自托管连接器参考

编辑
查看自托管连接器参考
可用性和先决条件
编辑

此连接器作为自托管自托管连接器提供。要使用此连接器，请满足所有自托管连接器先决条件。

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

创建 Box 连接器
编辑

使用 UI

编辑

要创建新的 Box 连接器

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

使用 API

编辑

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

例如

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-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 密钥

  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
        }
      ]
    }
  }
}
  2. 使用 API 密钥 encoded 值更新您的 config.yml 文件。

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

用法
编辑

要将此连接器用作自托管连接器，请使用连接器列表中的Box磁贴或自定义连接器工作流程。

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

Box API 授权
编辑
Box 免费帐户
编辑

创建 Box 用户身份验证 (OAuth 2.0) 自定义应用程序

您需要在 Box 开发人员控制台中创建一个 OAuth 应用程序，请按照以下步骤操作

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

生成刷新令牌

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

  1. 转到以下 URL，将 <CLIENT_ID> 替换为之前保存的客户端 ID 值。例如

    https://account.box.com/api/oauth2/authorize?response_type=code&client_id=<CLIENT_ID>
  2. 授予对您应用程序的访问权限。
  3. 您现在将被重定向到您在 重定向 URI 中配置的网页，并且 HTTP 响应应包含一个授权代码，您将使用该代码生成刷新令牌。注意： 用于生成刷新令牌的授权代码只能使用一次，且仅在 30 秒内有效。

  4. 在您的终端中，运行以下 curl 命令，将 <AUTHORIZATION_CODE>、<CLIENT_ID> 和 <CLIENT_SECRET> 替换为您之前保存的值

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

    从响应中保存刷新令牌。您将需要在连接器配置中使用它。

Box 企业帐户
编辑

创建 Box 服务器身份验证（客户端凭据授权）自定义应用程序

  1. 在Box 开发控制台中使用自定义应用程序注册新应用程序，并选择服务器身份验证（客户端凭据授权）。

  2. 选中以下权限

    • “应用程序范围”中的“写入 Box 中存储的所有文件和文件夹”
    • “高级功能”中的“使用 as-user 标头进行 API 调用”
  3. 在“应用程序访问级别”中选择 应用程序 + 企业访问。
  4. 从管理控制台授权您的应用程序。保存客户端凭据和企业 ID。您将需要这些来配置连接器。
配置
编辑
Box 帐户 (必需)
用于确定 Box 帐户类型的下拉列表：Box 免费帐户或Box 企业帐户。默认值为 Box 免费帐户。
客户端 ID (必需)
用于使用 Box 实例进行身份验证的客户端 ID。
客户端密钥 (必需)
用于使用 Box 实例进行身份验证的客户端密钥。
刷新令牌 (如果 Box 帐户为 Box 免费帐户，则为必需)
用于生成访问令牌的刷新令牌。注意：如果进程终止，您将需要生成新的刷新令牌。
企业 ID (如果 Box 帐户为 Box 企业帐户，则为必需)
用于使用 Box 实例进行身份验证的企业 ID。
使用 Docker 部署
编辑

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

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

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

内容提取
编辑

请参阅内容提取。

文档和同步
编辑

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

  • 文件
  • 文件夹
  • 不会提取大于 10 MB 的文件。
  • 不会同步权限。所有文档索引到 Elastic 部署后，将对所有具有访问权限的用户可见。
同步类型
编辑

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

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

同步规则
编辑

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

高级同步规则
编辑

此连接器在当前版本中不可用高级同步规则。

端到端测试
编辑

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

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

$ make ftest NAME=box

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

make ftest NAME=box DATA_SIZE=small
已知问题
编辑

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

故障排除
编辑

请参阅故障排除。

安全性
编辑

请参阅安全性。

« Elastic Azure Blob 存储连接器参考 Elastic Confluence 连接器参考 »