#elasticsearch #api-client #search #api-calls #lucene #api-bindings #elastic

elasticsearch_wasi

官方Elasticsearch Rust客户端,适用于WASI和WasmEdge

1 个版本 (0 个不稳定)

8.6.0-alpha.12023年9月12日

#1772 in 数据库接口

Apache-2.0

3MB
72K SLoC

elasticsearch   最新版本 文档 Apache-2 许可

官方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 上,或者在 命名空间客户端 上,例如 CatIndices 等。这些 命名空间客户端 基于在 ElasticsearchX-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