InfluxDB Go 客户端入门

作者：Anais Dotis-Georgiou / 产品, 用例, 开发者, 入门
2020 年 4 月 15 日

导航至

有几种方法可以写入和查询 InfluxDB v2（开源或云）。您可以使用 HTTP API、Telegraf 和 200 多个插件或客户端库。但是，如果您专门希望构建一个应用程序，该应用程序能够快速并发地获取数据，并易于二进制部署，那么 - 您猜对了 - 您可能需要使用 InfluxDB Go 客户端。

重要提示：InfluxDB v1.8 同时包含用于查询的 Flux 引擎和 InfluxDB v2 HTTP 写入 API。这意味着，如果您今天还没有准备好使用 InfluxDB v2，并且您计划利用新的客户端库，那么您可以这样做！这些读取和写入兼容性选项使您的代码面向未来！

Go 客户端的安装

需要 Go 1.13 或更高版本。安装和设置很简单

  • 将包 github.com/influxdata/influxdb-client-go/v2 添加到项目依赖项：go get github.com/influxdata/influxdb-client-go/v2。

如果您是 InfluxData 的新手，我建议在尝试使用客户端之前，先安装和配置 Telegraf 以及 System Input Plugin。但是，此示例将引导您完成在查询之前写入点的过程，因此您不需要数据。

授权参数

InfluxDB v2

为了将客户端与 InfluxDB v2 一起使用，您需要收集以下参数

InfluxDB v2 UI 示例 - 存储桶和令牌<figcaption> InfluxDB v2 UI 示例。存储桶和令牌可以在“加载数据”选项卡下找到。组织名称（如“my-org”）可以在左上角“加载数据”标题下方找到。</figcaption>

InfluxDB v1.8 及更高版本

如果您计划将此新客户端库与 InfluxDB 1.8 或更高版本一起使用，以下是关于收集所需授权参数的一些重要提示

  • 存储桶名称：InfluxDB v1.x 中没有存储桶的概念。但是，存储桶只是数据库名称及其保留策略的组合。因此，您可以通过提供 InfluxDB 1.x 数据库名称和保留策略（以正斜杠 (/) 分隔）来指定此项。如果您不提供保留策略，则使用默认保留策略。

例如：存储桶名称 telegraf/1week 允许您使用名为“1week”的保留策略写入名为“telegraf”的 InfluxDB 1.x 数据库。同样，telegraf/ 或 telegraf 允许您写入名为“telegraf”的 InfluxDB 1.x 数据库和默认保留策略（通常为 autogen）。

  • 令牌：在 InfluxDB v2 中，API 令牌用于访问平台及其所有功能。InfluxDB v1.x 在访问 HTTP API 时使用用户名和密码组合。提供您的 InfluxDB 1.x 用户名和密码，以冒号 (:) 分隔以表示令牌。例如： username:password
  • 组织：在与 InfluxDB v1.x 的兼容模式下，组织参数将被忽略，可以留空。

导入包

在开始之前，您需要导入必要的包并指定我们可执行程序的入口点。

package main

import (
    "context"
    "fmt"
    "time"
    "github.com/influxdata/influxdb-client-go/v2"
)

使用 InfluxDB Go 客户端写入 InfluxDB v2

以下示例使用同步、阻塞写入客户端和默认客户端设置写入三个时间序列点。它使用 WritePoint() 方法写入两个时间序列数据点，并使用 WriteRecord() 方法写入一个时间序列数据点

func main() {
    // create new client with default option for server url authenticate by token
    client := influxdb2.NewClient("http://localhost:9999", "my-token")
    // user blocking write client for writes to desired bucket
    writeAPI := client.WriteAPIBlocking("my-org", "my-bucket")
    // create point using full params constructor
    p := influxdb2.NewPoint("stat",
        map[string]string{"unit": "temperature"},
        map[string]interface{}{"avg": 24.5, "max": 45},
        time.Now())
    // write point immediately
    writeAPI.WritePoint(context.Background(), p)
    // create point using fluent style
    p = influxdb2.NewPointWithMeasurement("stat").
        AddTag("unit", "temperature").
        AddField("avg", 23.2).
        AddField("max", 45).
        SetTime(time.Now())
    writeAPI.WritePoint(context.Background(), p)

    // Or write directly line protocol
    line := fmt.Sprintf("stat,unit=temperature avg=%f,max=%f", 23.5, 45.0)
    writeAPI.WriteRecord(context.Background(), line)
    // Ensures background processes finish
    client.Close()
}

InfluxDB 2 Go 客户端<figcaption> 使用表格可视化工具可视化的 InfluxDB Go 客户端写入的具有两个字段的 3 个时间序列数据点</figcaption>

写入客户端选项

有许多方法可以使用 Go 客户端写入 InfluxDB v2，但最终您必须确定是否需要

  1. 使用默认设置或定义客户端设置
  2. 使用阻塞写入客户端同步写入点，或使用非阻塞写入客户端异步写入点。

为了帮助您决定如何使用客户端，让我们看一下我们的所有选项。

有两个客户端构造函数

  • NewClient()：创建 InfluxDBClient 以连接到给定的服务器 URL 并提供身份验证令牌，使用默认选项
  • NewClientWithOptions()：创建 InfluxDBClient 以连接到给定的服务器 URL 并提供身份验证令牌，并使用自定义选项进行配置

有两个写入 API

  • WriteAPIBlocking()：返回同步、阻塞写入客户端。批处理由用户定义。批次从给定的点数生成。
  • WriteAPI()：返回异步、非阻塞写入客户端。它提供隐式批处理。时间序列数据被添加到缓冲区，直到达到批处理大小，此时它被写入 InfluxDB。Flush() 刷新所有待处理的写入。请查看此示例，了解如何使用非阻塞写入客户端。

这些客户端各自有两种将时间序列数据写入 InfluxDB 实例的方法

  • WritePoint()：写入数据点
  • WriteRecord()：写入行协议记录

可以通过以下两种方法之一创建点

使用 InfluxDB Go 客户端查询 InfluxDB

查询您的 InfluxDB v2 服务器要简单得多。要查询您的实例，您需要获取查询客户端并迭代表格结果。

func main() {
    // Create client
    client := influxdb2.NewClient("http://localhost:9999", "my-token")
    // Get query client
    queryAPI := client.QueryAPI("my-org")
    // Get QueryTableResult
    result, err := queryAPI.Query(context.Background(), `from(bucket:"my-bucket")|> range(start: -1h) |> filter(fn: (r) => r._measurement == "stat")`)
    if err != nil {
        panic(err)
    }
    // Iterate over query response
    for result.Next() {
        // Notice when group key has changed
        if result.TableChanged() {
            fmt.Printf("table: %s\n", result.TableMetadata().String())
        }
        // Access data
        fmt.Printf("value: %v\n", result.Record().Value())
    }    
    // check for an error
    if result.Err() != nil {
        fmt.Printf("query parsing error: %s\n", result.Err().Error())
    }
    // Ensures background processes finishes
    client.Close()
}

只有两个查询客户端选项

  • Query()：上面的示例使用此方法轻松解析 Flux annotated CSV 查询响应。
  • QueryRaw()：这会返回原始的、未解析的查询结果字符串，并在您自己的基础上处理它。使用 DefaultDialect() 控制返回的 CSV 格式。请查看此示例，了解如何使用 QueryRaw()。

轻松开始使用 InfluxDB v2 Go 客户端

我希望本教程可以帮助您开始使用 InfluxDB。与往常一样，如果您遇到障碍，请在我们的社区网站或 Slack 频道上分享它们。我们很乐意获得您的反馈并帮助您解决遇到的任何问题。