influxdb-client-java

本仓库包含用于InfluxDB 2.x和Flux的Java客户端库。目前已实现Java、Reactive、Kotlin和Scala客户端。InfluxDB 3.x用户应改用轻量级的v3客户端库。InfluxDB 1.x用户应使用v1客户端库。

为了便于迁移并提供一致的查询和写入体验，v2用户应考虑使用InfluxQL和v1客户端库。

• 功能
• 客户端
• 使用方法
  • 在InfluxDB 2.x中进行写入和查询
  • 使用管理API在InfluxDB 2.x中创建新的Bucket
  • 在InfluxDB 1.7+中进行Flux查询
• 构建要求
• 贡献
• 许可证

文档

本节包含客户端库文档的链接。

• 产品文档，入门指南
• 示例
• API参考
• 更新日志

功能

• InfluxDB 2.x客户端
  • 使用Flux语言查询数据
  • 使用InfluxQL查询数据
  • 使用以下方式写入数据
    • 行协议
    • 数据点
    • POJO
  • InfluxDB 2.x管理API客户端，用于管理
    • 数据源、存储桶
    • 任务
    • 授权
    • 健康检查
    • ...
• 支持通过InfluxDB 1.7+ REST API（/api/v2/query端点）使用Flux语言进行查询

客户端

已为InfluxDB 2.x实现了Java、Reactive、OSGi、Kotlin和Scala客户端：

客户端	描述	文档	兼容性
[Java](https://github.com/influxdata/influxdb-client-java/blob/master/./client	参考Java客户端，允许查询、写入和管理InfluxDB 2.x。	Javadoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client#influxdb-client-java/	2.x
[响应式](https://github.com/influxdata/influxdb-client-java/blob/master/./client-reactive	InfluxDB 2.x的参考RxJava客户端，允许以响应式方式进行查询和写入。	Javadoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client-reactive#influxdb-client-reactive/	2.x
[Kotlin](https://github.com/influxdata/influxdb-client-java/blob/master/./client-kotlin	参考Kotlin客户端，通过Kotlin Channel和Flow协程允许对InfluxDB 2.x进行查询和写入。	KDoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client-kotlin#influxdb-client-kotlin/	2.x
[Scala](https://github.com/influxdata/influxdb-client-java/blob/master/./client-scala	参考Scala客户端，通过Pekko Streams允许对InfluxDB 2.x进行查询和写入。	Scaladoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client-scala#influxdb-client-scala/	2.x
[OSGi](https://github.com/influxdata/influxdb-client-java/blob/master/./client-osgi	参考OSGi (R6)客户端，嵌入Java和响应式客户端，并为InfluxDB 2.x提供标准功能（声明性服务、配置、事件处理）。	Javadoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client-osgi	2.x
[Karaf](https://github.com/influxdata/influxdb-client-java/blob/master/./karaf	InfluxDB 2.x的Apache Karaf功能定义。	[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./karaf	2.x

还可以使用以下方式通过Flux语言操作InfluxDB 1.7+：

客户端	描述	文档	兼容性
[Flux](https://github.com/influxdata/influxdb-client-java/blob/master/./client-legacy	参考Java客户端，允许对InfluxDB 1.7+执行Flux查询。	Javadoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./client-legacy#influxdb-client-flux/	1.7+

最后一个有用的部分是 **[flux-dsl](https://github.com/influxdata/influxdb-client-java/blob/master/./flux-dsl**，它通过查询构建器模式帮助构造Flux查询：

Flux flux = Flux
    .from("telegraf")
    .window(15L, ChronoUnit.MINUTES, 20L, ChronoUnit.SECONDS)
    .sum();

模块	描述	文档	兼容性
[flux-dsl](https://github.com/influxdata/influxdb-client-java/blob/master/./flux-dsl	Flux语言的Java查询构建器	Javadoc，[自述文件](https://github.com/influxdata/influxdb-client-java/blob/master/./flux-dsl#flux-dsl/	1.7+, 2.x

如何使用

这些客户端托管在Maven中央仓库中。 如果你想在 Maven 中使用它，你只需添加对该构件的依赖即可。

InfluxDB 2.x 中的写入和查询

以下示例演示了如何使用 Flux 语言向 InfluxDB 2.x 写入数据并读取数据。

安装

下载最新版本：

Maven 依赖：

<dependency>
    <groupId>com.influxdb</groupId>
    <artifactId>influxdb-client-java</artifactId>
    <version>7.2.0</version>
</dependency>

或者使用 Gradle：

dependencies {
    implementation "com.influxdb:influxdb-client-java:7.2.0"
}

package example;

import java.time.Instant;
import java.util.List;

import com.influxdb.annotations.Column;
import com.influxdb.annotations.Measurement;
import com.influxdb.client.InfluxDBClient;
import com.influxdb.client.InfluxDBClientFactory;
import com.influxdb.client.QueryApi;
import com.influxdb.client.WriteApiBlocking;
import com.influxdb.client.domain.WritePrecision;
import com.influxdb.client.write.Point;
import com.influxdb.query.FluxRecord;
import com.influxdb.query.FluxTable;

public class InfluxDB2Example {

    private static char[] token = "my-token".toCharArray();
    private static String org = "my-org";
    private static String bucket = "my-bucket";

    public static void main(final String[] args) {

        InfluxDBClient influxDBClient = InfluxDBClientFactory.create("http://localhost:8086", token, org, bucket);

        //
        // 写入数据
        //
        WriteApiBlocking writeApi = influxDBClient.getWriteApiBlocking();

        //
        // 通过数据点写入
        //
        Point point = Point.measurement("temperature")
                .addTag("location", "west")
                .addField("value", 55D)
                .time(Instant.now().toEpochMilli(), WritePrecision.MS);

        writeApi.writePoint(point);

        //
        // 通过行协议写入
        //
        writeApi.writeRecord(WritePrecision.NS, "temperature,location=north value=60.0");

        //
        // 通过 POJO 写入
        //
        Temperature temperature = new Temperature();
        temperature.location = "south";
        temperature.value = 62D;
        temperature.time = Instant.now();

        writeApi.writeMeasurement( WritePrecision.NS, temperature);

        //
        // 查询数据
        //
        String flux = "from(bucket:\"my-bucket\") |> range(start: 0)";

        QueryApi queryApi = influxDBClient.getQueryApi();

        List<FluxTable> tables = queryApi.query(flux);
        for (FluxTable fluxTable : tables) {
            List<FluxRecord> records = fluxTable.getRecords();
            for (FluxRecord fluxRecord : records) {
                System.out.println(fluxRecord.getTime() + ": " + fluxRecord.getValueByKey("_value"));
            }
        }

        influxDBClient.close();
    }

    @Measurement(name = "temperature")
    private static class Temperature {

        @Column(tag = true)
        String location;

        @Column
        Double value;

        @Column(timestamp = true)
        Instant time;
    }
}

使用管理 API 在 InfluxDB 2.x 中创建新的 Bucket

以下示例演示了如何使用 InfluxDB 2.x 管理 API。有关更多信息，请参阅客户端文档。

安装

下载最新版本：

Maven 依赖：

<dependency>
    <groupId>com.influxdb</groupId>
    <artifactId>influxdb-client-java</artifactId>
    <version>7.2.0</version>
</dependency>

或者使用 Gradle：

dependencies {
    implementation "com.influxdb:influxdb-client-java:7.2.0"
}

package example;

import java.util.Arrays;

import com.influxdb.client.InfluxDBClient;
import com.influxdb.client.InfluxDBClientFactory;
import com.influxdb.client.domain.Authorization;
import com.influxdb.client.domain.Bucket;
import com.influxdb.client.domain.Permission;
import com.influxdb.client.domain.PermissionResource;
import com.influxdb.client.domain.BucketRetentionRules;

public class InfluxDB2ManagementExample {

    private static char[] token = "my-token".toCharArray();

    public static void main(final String[] args) {

        InfluxDBClient influxDBClient = InfluxDBClientFactory.create("http://localhost:8086", token);

        //
        // 创建数据保留时间设置为 3,600 秒的 "iot_bucket" bucket
        //
        BucketRetentionRules retention = new BucketRetentionRules();
        retention.setEverySeconds(3600);

        Bucket bucket = influxDBClient.getBucketsApi().createBucket("iot-bucket", retention, "12bdc4164c2e8141");

        //
        // 创建 "iot_bucket" 的访问令牌
        //
        PermissionResource resource = new PermissionResource();
        resource.setId(bucket.getId());
        resource.setOrgID("12bdc4164c2e8141");
        resource.setType(PermissionResource.TYPE_BUCKETS);
// 读取权限
Permission read = new Permission();
read.setResource(resource);
read.setAction(Permission.ActionEnum.READ);

// 写入权限
Permission write = new Permission();
write.setResource(resource);
write.setAction(Permission.ActionEnum.WRITE);

Authorization authorization = influxDBClient.getAuthorizationsApi()
        .createAuthorization("12bdc4164c2e8141", Arrays.asList(read, write));

//
// 创建可用于向"iot_bucket"写入的令牌
//
String token = authorization.getToken();
System.out.println("令牌：" + token);

influxDBClient.close();
}
}

### InfluxDB 1.8 API 兼容性

[InfluxDB 1.8.0 引入了与 InfluxDB 2.x 的前向兼容 API](https://docs.influxdata.com/influxdb/v1.8/tools/api/#influxdb-2-0-api-compatibility-endpoints)。这使您可以轻松地从 InfluxDB 1.x 迁移到 InfluxDB 2.x 云服务或开源版本。

以下是可用的前向兼容 API：

| API | 端点 | 描述 |
|:----------|:----------|:----------|
| [QueryApi.java](https://github.com/influxdata/influxdb-client-java/blob/master/client/src/main/java/com/influxdb/client/QueryApi.java | [/api/v2/query](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-query-http-endpoint) | 使用 InfluxDB 2.x API 和 [Flux](https://docs.influxdata.com/flux/latest/) 在 InfluxDB 1.8.0+ 中查询数据（端点应通过 [`flux-enabled` 选项](https://docs.influxdata.com/influxdb/latest/administration/config/#flux-enabled-false) 启用）|
| [WriteApi.java](https://github.com/influxdata/influxdb-client-java/blob/master/client/src/main/java/com/influxdb/client/WriteApi.java | [/api/v2/write](https://docs.influxdata.com/influxdb/latest/tools/api/#api-v2-write-http-endpoint) | 使用 InfluxDB 2.x API 向 InfluxDB 1.8.0+ 写入数据 |
| [health()](https://github.com/influxdata/influxdb-client-java/blob/master/client/src/main/java/com/influxdb/client/InfluxDBClient.java#L236 | [/health](https://docs.influxdata.com/influxdb/latest/tools/api/#health-http-endpoint) | 检查 InfluxDB 实例的健康状况 |

详细信息请参阅 [InfluxDB 1.8 示例](https://github.com/influxdata/influxdb-client-java/blob/master/examples/src/main/java/example/InfluxDB18Example.java)。

### InfluxDB 1.7+ 中的 Flux 查询

以下示例演示了使用 Flux 语言进行查询。

#### 安装

下载最新版本：

##### Maven 依赖：

```XML
<dependency>
    <groupId>com.influxdb</groupId>
    <artifactId>influxdb-client-flux</artifactId>
    <version>7.2.0</version>
</dependency>

或者使用 Gradle：

dependencies {
    implementation "com.influxdb:influxdb-client-flux:7.2.0"
}

package example;

import java.util.List;

import com.influxdb.client.flux.FluxClient;
import com.influxdb.client.flux.FluxClientFactory;
import com.influxdb.query.FluxRecord;
import com.influxdb.query.FluxTable;

public class FluxExample {

    public static void main(String[] args) {

        FluxClient fluxClient = FluxClientFactory.create("http://localhost:8086/");

        //
        // Flux
        //
        String flux = "from(bucket: \"telegraf\")\n" +
                " |> range(start: -1d)" +
                " |> filter(fn: (r) => (r[\"_measurement\"] == \"cpu\" and r[\"_field\"] == \"usage_system\"))" +
                " |> sample(n: 5, pos: 1)";

        //
        // 同步查询
        //
        List<FluxTable> tables = fluxClient.query(flux);

        for (FluxTable fluxTable : tables) {
            List<FluxRecord> records = fluxTable.getRecords();
            for (FluxRecord fluxRecord : records) {
                System.out.println(fluxRecord.getTime() + ": " + fluxRecord.getValueByKey("_value"));
            }
        }

        //
        // 异步查询
        //
        fluxClient.query(flux, (cancellable, record) -> {

            // 处理 flux 查询结果记录
            System.out.println(record.getTime() + ": " + record.getValue());

        }, error -> {

            // 处理结果时的错误处理
            System.out.println("发生错误："+ error.getMessage());

        }, () -> {

            // 完成时
            System.out.println("查询完成");
        });

        fluxClient.close();
    }
}

构建要求

• Java 17+（已在JDK 17上测试）
• :警告: 如果您想使用较旧版本的JDK，必须使用6.x版本的客户端。
• Maven 3.0+（已在maven 3.5.0上测试）
• 正在运行的Docker守护进程
• 最新的InfluxDB 2.x和InfluxDB 1.X docker实例，可以使用./scripts/influxdb-restart.sh脚本启动

准备好这些后，您可以使用以下命令构建influxdb-client-java并运行所有测试：

$ mvn clean install

如果您本地没有运行Docker，可以通过将-DskipTests标志设置为true来跳过测试：

$ mvn clean install -DskipTests=true

如果您正在运行Docker，但无法通过localhost访问（例如，您在Mac上使用docker-machine），可以设置可选的环境变量来指向正确的IP地址和端口：

• INFLUXDB_IP
• INFLUXDB_PORT_API
• INFLUXDB_2_IP
• INFLUXDB_2_PORT_API

$ export INFLUXDB_IP=192.168.99.100
$ mvn test

贡献

如果您想贡献代码，可以通过GitHub fork仓库并向master分支发送拉取请求。

许可证

InfluxDB 2.x JVM基础客户端是根据MIT许可证发布的。