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。

安装

将 elasticsearch crate 和版本添加到 Cargo.toml。选择与您使用的 Elasticsearch 版本兼容的版本

[dependencies]
elasticsearch = "8.5.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 请求，这允许设置代理、身份验证方案、证书验证和其他传输相关设置。

要创建一个客户端，使其能够向运行在 https://: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 构建 Transport，并将其传递给 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 调用

以下将执行一个向 /_search?allow_no_indices=true 发送的 POST 请求，其 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 License Version 2.0 许可。