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-postgresql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from PostgreSQL",
  "service_type": "postgresql",
  "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 托管的连接器，请使用 连接器 工作流。请参阅Elastic 托管的连接器。

用户必须将 track_commit_timestamp 设置为 on。为此，请在 PostgreSQL 服务器中运行 ALTER SYSTEM SET track_commit_timestamp = on;。

有关其他操作，请参阅 <←esconnectors-usage>>。

有关连接器客户端工作流的端到端示例，请参阅教程。

兼容性

编辑

PostgreSQL 版本 11 至 15 与 Elastic 连接器兼容。

配置

编辑

设置以下配置字段

主机

托管 PostgreSQL 实例的服务器主机地址。示例

192.158.1.38
demo.instance.demo-region.demo.service.com

端口

托管 PostgreSQL 实例的端口。示例

5432（默认）

用户名

PostgreSQL 帐户的用户名。

密码

PostgreSQL 帐户的密码。

数据库

PostgreSQL 数据库的名称。示例

employee_database
customer_database

架构

PostgreSQL 数据库的架构。

逗号分隔的表列表

以逗号分隔的表列表。如果该值为 *，则 PostgreSQL 连接器将从配置的数据库中提取所有表中的数据。默认值为 *。示例

table_1, table_2
*

使用高级同步规则时，可以绕过此字段。

启用 SSL

切换以启用 SSL 验证。默认情况下禁用。

SSL 证书

SSL 证书的内容。如果禁用 SSL，则会忽略 ssl_ca 值。

展开以查看证书示例

文档和同步

编辑

表必须由 PostgreSQL 用户拥有。
将跳过未定义主键的表。
要获取 PostgreSQL 中上次更新的时间，必须将 track_commit_timestamp 设置为 on。否则，所有数据将在每次同步中编制索引。

不会提取大于 10 MB 的文件。
不会同步权限。索引到 Elastic 部署的所有文档对于所有有权访问该 Elastic 部署的用户可见。

同步规则

编辑

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

高级同步规则

编辑

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

高级同步规则通过特定于源的 DSL JSON 代码段定义。

示例数据

编辑

以下是在以下示例中将使用的一些示例数据。

employee 表

emp_id	name	age
3	John	28
10	Jane	35
14	Alex	22

customer 表

c_id	name	age
2	Elm	24
6	Pine	30
9	Oak	34

高级同步规则示例

编辑

多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

带有 id_columns 的多表查询

在 8.15.0 中，我们在 PostgreSQL 连接器的高级同步规则中添加了一个新的可选 id_columns 字段。使用 id_columns 字段来摄取没有主键的表。包括唯一字段的名称，以便连接器可以使用它们为文档生成唯一 ID。

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee",
    "id_columns": ["emp_id"]
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer",
    "id_columns": ["c_id"]
  }
]

此示例使用 id_columns 字段分别指定 employee 和 customer 表的唯一字段 emp_id 和 c_id。

使用 WHERE 子句筛选数据

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

JOIN 操作

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

使用高级规则时，查询可以绕过配置字段 tables。如果查询指定了未出现在配置中的表，则会发生这种情况。如果配置指定 * 以提取所有表，而高级同步规则仅请求表的子集，也会发生这种情况。

已知问题

编辑

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

自管理连接器

编辑

查看 自管理连接器 参考

可用性和先决条件

编辑

此连接器作为自管理的自管理连接器提供。要使用此连接器，请满足所有自管理连接器要求。

创建 PostgreSQL 连接器

编辑

使用 UI

编辑

要创建新的 PostgreSQL 连接器

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

使用 API

编辑

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

例如

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-postgresql-connector
{
  "index_name": "my-elasticsearch-index",
  "name": "Content synced from PostgreSQL",
  "service_type": "postgresql"
}

您还需要为连接器创建一个 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 文档。

用法

编辑

要将此连接器用作 自管理连接器，请参阅自管理连接器。

用户必须将 track_commit_timestamp 设置为 on。为此，请在 PostgreSQL 服务器中运行 ALTER SYSTEM SET track_commit_timestamp = on;。

有关其他操作，请参阅。

有关自管理连接器工作流的端到端示例，请参阅教程。

兼容性

编辑

PostgreSQL 版本 11 至 15 与 Elastic 连接器框架兼容。

配置

编辑

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

这些可配置字段将在 Kibana UI 中以其各自的标签呈现。连接后，用户将能够在 Kibana 中更新这些值。

设置以下配置字段

主机

托管 PostgreSQL 实例的服务器主机地址。示例

192.158.1.38
demo.instance.demo-region.demo.service.com

端口

托管 PostgreSQL 实例的端口。示例

5432
9090

用户名

PostgreSQL 帐户的用户名。

密码

PostgreSQL 帐户的密码。

数据库

PostgreSQL 数据库的名称。示例

employee_database
customer_database

架构

PostgreSQL 数据库的架构。

表

以逗号分隔的表列表。如果该值为 *，则 PostgreSQL 连接器将从配置的数据库中提取所有表中的数据。默认值为 *。示例

table_1, table_2
*

使用高级同步规则时，可以绕过此字段。

ssl_enabled

是否启用 SSL 验证。默认值为 True。

ssl_ca

SSL 证书的内容（如果启用 SSL）。如果禁用 SSL，则会忽略 ssl_ca 值。

展开以查看证书示例

使用 Docker 部署

编辑

您可以使用 Docker 将 PostgreSQL 连接器部署为自管理连接器。请按照以下说明操作。

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

如果您正在针对 Dockerized 版本的 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: postgresql
    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。

文档和同步

编辑

表必须由 PostgreSQL 用户拥有。
将跳过未定义主键的表。
要获取 PostgreSQL 中上次更新的时间，必须将 track_commit_timestamp 设置为 on。否则，所有数据将在每次同步中编制索引。

不会提取大于 10 MB 的文件。
不会同步权限。索引到 Elastic 部署的所有文档对于所有有权访问该 Elastic 部署的用户可见。

同步规则

编辑

高级同步规则

编辑

要使高级同步规则生效，需要进行 //connectors-sync-types-full, 完全同步。

高级同步规则通过特定于源的 DSL JSON 代码段定义。

示例数据

编辑

以下是在以下示例中将使用的一些示例数据。

employee 表

emp_id	name	age
3	John	28
10	Jane	35
14	Alex	22

customer 表

c_id	name	age
2	Elm	24
6	Pine	30
9	Oak	34

高级同步规则示例

编辑

多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee"
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer"
  }
]

带有 id_columns 的多表查询

[
  {
    "tables": [
      "employee"
    ],
    "query": "SELECT * FROM employee",
    "id_columns": ["emp_id"]
  },
  {
    "tables": [
      "customer"
    ],
    "query": "SELECT * FROM customer",
    "id_columns": ["c_id"]
  }
]

此示例使用 id_columns 字段分别指定 employee 和 customer 表的唯一字段 emp_id 和 c_id。

使用 WHERE 子句过滤数据

[
  {
    "tables": ["employee"],
    "query": "SELECT * FROM employee WHERE emp_id > 5"
  }
]

JOIN 操作

[
  {
    "tables": ["employee", "customer"],
    "query": "SELECT * FROM employee INNER JOIN customer ON employee.emp_id = customer.c_id"
  }
]

端到端测试

编辑

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

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

$ make ftest NAME=postgresql

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

make ftest NAME=postgresql DATA_SIZE=small

已知问题

编辑

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

故障排除

编辑

请参阅故障排除。

安全性

编辑

请参阅安全性。

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