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

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。

S3 用户还需要创建 IAM 身份

创建 IAM 身份

编辑

用户需要创建一个 IAM 身份才能将此连接器用作自管理连接器。请参阅AWS 文档。

与 IAM 身份关联的策略必须具有以下AWS 权限

ListAllMyBuckets
ListBucket
GetBucketLocation
GetObject

兼容性

编辑

当前，该连接器不支持与 S3 兼容的供应商。

配置

编辑

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

AWS 存储桶

S3 存储桶名称列表。* 将从所有存储桶中提取数据。例如

testbucket, prodbucket
testbucket
*

使用高级同步规则时，将忽略此字段。

AWS 访问密钥 ID: 将用于存储桶访问的 AWS 身份的访问密钥 ID。
AWS 密钥: 将用于存储桶访问的 AWS 身份的密钥。

文档和同步

编辑

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

同步规则

编辑

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

高级同步规则

编辑

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

高级同步规则通过特定于源的 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"]
  }
]

内容提取

编辑

请参阅内容提取。

已知问题

编辑

此连接器没有已知问题。

有关影响所有连接器的任何问题，请参阅已知问题。

故障排除

编辑

请参阅故障排除。

安全

编辑

请参阅安全。

框架和源代码

编辑

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

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

自管理连接器参考

编辑

查看自管理连接器参考

可用性和先决条件

编辑

此连接器作为自管理自管理连接器提供。此自管理连接器与 Elastic 版本 8.6.0+ 兼容。要使用此连接器，请满足所有自管理连接器要求。

创建 Amazon S3 连接器

编辑

使用 UI

编辑

要创建新的 Amazon S3 连接器

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

使用 API

编辑

您可以使用 Elasticsearch 创建连接器 API 来创建新的自管理 Amazon S3 自管理连接器。

例如

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

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。

S3 用户还需要创建 IAM 身份

创建 IAM 身份

编辑

用户需要创建一个 IAM 身份才能将此连接器用作自管理连接器。请参阅AWS 文档。

与 IAM 身份关联的策略必须具有以下AWS 权限

ListAllMyBuckets
ListBucket
GetBucketLocation
GetObject

兼容性

编辑

当前，该连接器不支持与 S3 兼容的供应商。

配置

编辑

当使用自管理连接器工作流时，这些字段将使用连接器源代码中设置的默认配置。这些可配置字段将在 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 部署

编辑

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

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

步骤 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 部署的文档对于所有有权访问该 Elastic 部署的用户都是可见的。

同步规则

编辑

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

高级同步规则

编辑

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

高级同步规则通过特定于源的 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"]
  }
]

内容提取

编辑

请参阅内容提取。

端到端测试

编辑

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

要为 Amazon S3 自托管连接器执行功能测试，请运行以下命令：

make ftest NAME=s3

默认情况下，这将使用中等大小的数据集。要加快测试速度，请添加 DATA_SIZE=small 参数

make ftest NAME=s3 DATA_SIZE=small

已知问题

编辑

此连接器没有已知问题。

有关影响所有连接器的任何问题，请参阅已知问题。

问题排查

编辑

请参阅故障排除。

安全性

编辑

请参阅安全。

框架和源代码

编辑

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

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

« Redis 连接器参考 Elastic Salesforce 连接器参考 »