开始使用 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，使用 系统输入插件。但是，此示例将指导您在查询之前写入一个点，因此您不需要数据。

授权参数

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 允许您写入名为“telegraf”的 InfluxDB 1.x 数据库，保留策略名为“1week”。同样，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("https://127.0.0.1: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 客户端写入的两个字段和三个时间序列数据点，使用表格可视化展示</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("https://127.0.0.1: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 注解CSV查询响应。
  • QueryRaw()：此方法返回原始、未解析的查询结果字符串，并自行处理它。使用DefaultDialect()控制返回的CSV格式。请看这个例子了解如何使用QueryRaw()。

使用InfluxDB v2 Go客户端轻松入门

希望这个教程能帮助您开始使用InfluxDB。一如既往，如果您遇到困难，请在我们社区网站 或Slack频道分享。我们非常希望得到您的反馈，并帮助您解决遇到的问题。