Elastic GraphQL 连接器参考

编辑

Elastic GraphQL 连接器是使用 Elastic 连接器框架 以 Python 编写的。查看此连接器的源代码

可用性和先决条件

编辑

此连接器在 Elastic 8.14.0 中引入,可作为自管理的自管理连接器使用。

要使用此连接器,请满足所有自管理连接器的先决条件。重要的是,您必须在您自己的基础设施上部署连接器服务。您有两种部署选项

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

用法

编辑

要在 UI 中设置此连接器,请在搜索 → 连接器下创建新连接器时,选择GraphQL磁贴。

如果您已经熟悉连接器的工作方式,您也可以使用连接器 API

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

使用 Docker 部署

编辑

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

步骤 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: graphql
    api_key: <CONNECTOR_API_KEY_FROM_KIBANA> # Optional. If not provided, the connector will use the elasticsearch.api_key instead

使用 elasticsearch.api_key 是推荐的身份验证方法。但是,您也可以使用 elasticsearch.usernameelasticsearch.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

配置

编辑
配置 GraphQL 连接器
编辑

请注意以下配置字段

http_endpoint(必需)
GraphQL 端点的基本 URL。示例https://api.xyz.com/graphql
http_method(必需)
GETPOST
authentication_method(必需)
No AuthBasic AuthBearer Token 中选择。
username
使用基本身份验证时必需。
password
使用基本身份验证时必需。
token
使用持有者令牌身份验证时必需。
graphql_query(必需)

用于从源提取数据的查询。可以包含在 graphql_variables 字段中提供的变量。连接器会将查询中的变量替换为 graphql_variables 中的值,并向源发出 GraphQL 查询。

示例:

query getUser($id: ID!) {
    user(id: $id) {
        name
        email
    }
}
graphql_variables

包含 GraphQL 查询中使用的变量的键/值对的 JSON 对象。连接器会将查询中的变量替换为此处提供的值,并向源发出 GraphQL 查询。

示例:

对于 GraphQL 查询 query getUser($id: ID!) { user(id: $id) { name } }

  • 其中 graphql_variables 的值为 {"id": "123"}
  • 连接器将执行 query getUser { user(id: "123") { name } } 从源提取数据
graphql_object_to_id_map(必需)

GraphQL 响应对象到索引及其 ID 字段之间的 JSON 映射。连接器将提取每个对象(JSON 键)的数据,并使用提供的 ID 字段(JSON 值)将该对象索引到 Elasticsearch 中。连接器将索引映射中指定的每个对象的所有字段。使用点 (.) 表示法来指定从 GraphQL 响应根到所需对象的完整路径。

示例:

GraphQL 查询 query getUser { organization { users{ user_id name email} } } 从源提取所有可用用户。要将每个用户索引为单独的文档,请按如下方式配置此字段。

{
    "organization.users": "user_id"
}

在此示例中,user_id 在每个用户文档中都是唯一的。因此,我们将 user_id 设置为 organization.users 的值。

此字段中提供的路径应仅包含 JSON 对象,而不包含列表。

headers

包含要与每个 GraphQL 请求一起发送的自定义标头的 JSON 对象

{
    "content-type": "Application/json"
}
pagination_model(必需)

此字段指定连接器要使用的分页模型。连接器支持 No paginationCursor-based pagination 分页模型。

对于基于游标的分页,请在您想要的节点(分页键)处的查询中添加 pageInfo {endCursor hasNextPage}after 参数变量。将带有变量的 after 查询参数用于遍历页面。此字段的默认值为 No pagination。示例

对于 Cursor-based pagination,查询应如下例所示

query getUsers($cursor: String!) {
    sampleData {
        users(after: $cursor) {
            pageInfo {
                endCursor
                hasNextPage
            }
            nodes {
                first_name
                last_name
                address
            }
        }
    }
}

pagination_key 的值为 sampleData.users,因此它必须包含

  • pageInfo {endCursor hasNextPage}
  • 使用基于游标的分页时带有变量的 after 参数
pagination_key(必需)

指定哪个 GraphQL 对象用于分页。使用 . 来提供对象从响应根的完整路径。

示例:

  • organization.users
connection_timeout
指定等待 GraphQL 源响应的最大时间(以秒为单位)。默认值为 30 秒

文档和同步

编辑

连接器基于 GraphQL 查询和 GraphQL 对象列表同步对象和实体。

同步类型

编辑

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

此连接器当前不支持增量同步

同步规则

编辑

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

高级同步规则

编辑

当前版本中此连接器不提供高级同步规则。

连接器客户端操作

编辑
端到端测试
编辑

连接器框架使操作员能够使用 Docker Compose 对真实数据源运行功能测试。您不需要运行 Elasticsearch 实例或 GraphQL 源即可运行此测试。

有关更多详细信息,请参阅连接器测试

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

$ make ftest NAME=graphql

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

make ftest NAME=graphql DATA_SIZE=small

默认情况下,DATA_SIZE=MEDIUM

已知问题

编辑
  • 每个文档都将在每次同步中更新。
  • 如果同一字段名称在不同对象中存在不同的类型,则连接器可能会引发映射解析器异常。

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

故障排除

编辑

请参阅故障排除

安全性

编辑

请参阅安全性