1 个版本 (0 个不稳定)
8.6.0-alpha.1 | 2023年9月12日 |
---|
#1772 in 数据库接口
3MB
72K SLoC
elasticsearch
官方Elasticsearch Rust客户端。
完整文档可在 https://docs.rs/elasticsearch 查阅
该项目仍处于开发中,处于 alpha 阶段;欢迎输入和贡献!
兼容性
Elasticsearch Rust客户端是向前兼容的;这意味着客户端可以与Elasticsearch更高版本的次要版本通信。Elasticsearch语言客户端也可以向后兼容较低支持的次要Elasticsearch版本。
功能
以下是可以启用或禁用的Cargo功能列表
- native-tls (默认启用):启用由
native-tls
提供的TLS功能。 - rustls-tls:启用由
rustls
提供的TLS功能。 - beta-apis:启用beta API。Beta API正在成为稳定和永久的功能。请谨慎使用,因为这些API可能在较小版本中进行破坏性更改。
- experimental-apis:启用实验性API。实验性API就是实验。实验性API可能在任何未来版本中进行破坏性更改,甚至可能会完全删除。此功能还启用了
beta-apis
。
入门
客户端将所有 Elasticsearch API 以关联函数的形式暴露出来,这些函数位于根客户端 Elasticsearch
上,或者在 命名空间客户端 上,例如 Cat
、Indices
等。这些 命名空间客户端 基于在 Elasticsearch 和 X-Pack REST API 规范中的 API 分组,这些规范生成了客户端的大部分功能。所有 API 函数都是 async
的,并且可以 await
。
安装
在 Cargo.toml 中添加 elasticsearch
包和版本。选择与您使用的 Elasticsearch 版本兼容的版本。
[dependencies]
elasticsearch = "8.7.0-alpha.1"
以下 可选 依赖项在创建请求和读取响应时可能也很有用。
serde = "~1"
serde_json = "~1"
与 tokio 的异步支持
客户端使用 reqwest
来执行 HTTP 请求,它内部使用 tokio
运行时来提供异步支持。因此,您可能需要将 tokio
作为依赖项添加,以便使用客户端。例如,在 Cargo.toml 中,您可能需要以下依赖项:
tokio = { version = "*", features = ["full"] }
并且将异步主函数标记为 #[tokio::main]
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
// your code ...
Ok(())
}
并将测试函数标记为 #[tokio::test]
#[tokio::test]
async fn my_test() -> Result<(), Box<dyn std::error::Error>> {
// your code ...
Ok(())
}
创建客户端
使用 TransportBuilder
构建传输,以通过 Elasticsearch API 发送请求,这允许设置代理、认证方案、证书验证和其他传输相关设置。
要创建一个客户端,以对运行在 http://localhost:9200
上的 Elasticsearch 发送 API 请求
use elasticsearch::Elasticsearch;
fn main() {
let client = Elasticsearch::default();
}
或者,您也可以创建一个客户端,以对运行在特定 URL 上的 Elasticsearch 发送 API 请求
use elasticsearch::{
Elasticsearch, Error,
http::transport::Transport
};
fn main() -> Result<(), Error> {
let transport = Transport::single_node("https://example.com")?;
let client = Elasticsearch::new(transport);
Ok(())
}
如果您正在与运行在 Elastic Cloud 上的 Elasticsearch 部署交互,可以使用从云控制台获取的 Cloud ID 和凭据创建一个客户端
use elasticsearch::{
auth::Credentials,
Elasticsearch, Error,
http::transport::Transport,
};
fn main() -> Result<(), Error> {
let cloud_id = "cluster_name:Y2xvdWQtZW5kcG9pbnQuZXhhbXBsZSQzZGFkZjgyM2YwNTM4ODQ5N2VhNjg0MjM2ZDkxOGExYQ==";
// can use other types of Credentials too, like Bearer or ApiKey
let credentials = Credentials::Basic("<username>".into(), "<password>".into());
let transport = Transport::cloud(cloud_id, credentials)?;
let client = Elasticsearch::new(transport);
Ok(())
}
使用 TransportBuilder
构建传输,并将其传递给 Elasticsearch::new()
来创建一个新的 Elasticsearch
实例,可以更精细地控制 Transport
的构建过程。
use url::Url;
use elasticsearch::{
Error, Elasticsearch,
http::transport::{TransportBuilder,SingleNodeConnectionPool},
};
fn main() -> Result<(), Error> {
let url = Url::parse("https://example.com")?;
let conn_pool = SingleNodeConnectionPool::new(url);
let transport = TransportBuilder::new(conn_pool).disable_proxy().build()?;
let client = Elasticsearch::new(transport);
Ok(())
}
执行 API 请求
以下代码将执行一个 POST
请求到 /_search?allow_no_indices=true
,其 JSON 主体为 {"query":{"match_all":{}}}
use elasticsearch::{Elasticsearch, Error, SearchParts};
use serde_json::{json, Value};
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Elasticsearch::default();
// make a search API call
let search_response = client
.search(SearchParts::None)
.body(json!({
"query": {
"match_all": {}
}
}))
.allow_no_indices(true)
.send()
.await?;
// get the HTTP response status code
let status_code = search_response.status_code();
// read the response body. Consumes search_response
let response_body = search_response.json::<Value>().await?;
// read fields from the response body
let took = response_body["took"].as_i64().unwrap();
Ok(())
}
客户端为每个 API 构建结构体提供了所有该 API 可用的查询字符串参数的功能。具有多个 URI 路径变体的 API(其中一些可以包含部分参数)被建模为枚举。
Elasticsearch
还在根目录提供了一个异步 send
函数,允许向一个不表示为 API 函数的端点发送 API 调用,例如实验性和测试版 API。
use elasticsearch::{http::Method, Elasticsearch, Error, SearchParts};
use http::HeaderMap;
use serde_json::Value;
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
let client = Elasticsearch::default();
let body = b"{\"query\":{\"match_all\":{}}}";
let response = client
.send(
Method::Post,
SearchParts::Index(&["tweets"]).url().as_ref(),
HeaderMap::new(),
Option::<&Value>::None,
Some(body.as_ref()),
None,
)
.await?;
Ok(())
}
许可证
这是免费软件,根据 Apache 许可证 2.0 版 许可。
依赖项
~4–20MB
~257K SLoC