Elastic GraphQL 连接器参考
编辑Elastic GraphQL 连接器参考
编辑Elastic GraphQL 连接器是使用 Elastic 连接器框架 以 Python 编写的。查看此连接器的源代码。
可用性和先决条件
编辑此连接器在 Elastic 8.14.0 中引入,可作为自管理的自管理连接器使用。
要使用此连接器,请满足所有自管理连接器的先决条件。重要的是,您必须在您自己的基础设施上部署连接器服务。您有两种部署选项
- 从源代码运行连接器服务。如果您熟悉使用 Python 并希望在本地快速迭代,请使用此选项。
- 在 Docker 中运行连接器服务。如果您想将连接器部署到服务器,或使用容器编排平台,请使用此选项。
此连接器处于技术预览阶段,可能会发生更改。其设计和代码不如正式 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.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。
配置
编辑配置 GraphQL 连接器
编辑请注意以下配置字段
-
http_endpoint
(必需) - GraphQL 端点的基本 URL。示例:
https://api.xyz.com/graphql
-
http_method
(必需) -
GET
或POST
。 -
authentication_method
(必需) - 从
No Auth
、Basic Auth
和Bearer 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 pagination
和Cursor-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
。
已知问题
编辑- 每个文档都将在每次同步中更新。
- 如果同一字段名称在不同对象中存在不同的类型,则连接器可能会引发映射解析器异常。
有关所有连接器的已知问题列表,请参阅已知问题。
故障排除
编辑请参阅故障排除。
安全性
编辑请参阅安全性。