InfluxDB 3.0 Go 客户端库

作者：社区 / 开发者
2024 年 12 月 04 日

导航至

在数据驱动的世界中，高效的时序数据管理日益受到关注。API 在自动化任务中发挥着重要作用，尤其是在基于云的环境中。Go 以其高性能和并发性，正迅速成为编写云基础设施和用于管理数据流的实用程序的标准语言之一。InfluxDB 的 Go 客户端库帮助开发者在其 Go 应用程序中处理时序数据，使其成为任何从事实时分析、物联网或监控系统的人员不可或缺的工具。

InfluxDB 3.0 是一款高性能、可扩展的时序数据库，专为实时分析而设计。它配备了丰富的功能，例如数据摄取管理、查询和大量时序数据的可视化，使其成为需要实时洞察的工业用例、物联网、监控等的完美工具。

在本教程中，您将学习如何

  • 设置 InfluxDB Cloud（Serverless 或 Dedicated）
  • 安装和配置 Go 客户端库
  • 写入和查询时序数据
  • 开发高效且可扩展的安全最佳实践

让我们深入了解。

先决条件

为了充分利用本教程，您需要

  • 对 RESTful API 有基本的了解
  • 熟悉 时序数据库（指标、标签和字段等概念）

在我们开始之前，请设置以下软件要求

  • InfluxDB 3.0 Cloud（Serverless 或 Dedicated）
  • Go
  • InfluxDB CLI（可选，但对于直接与数据库交互很有用）
  • Postman 或 cURL（可选，用于测试 API 端点）

设置 InfluxDB 3.0

本教程中的演示将使用 InfluxDB Cloud Serverless。因此，让我们从设置它开始。

安装

由于我们使用的是 InfluxDB Cloud Serverless，因此无需本地安装。您只需按照以下步骤创建一个帐户

  1. 转到 InfluxDB Cloud 注册页面。选择 通过 InfluxData 订阅 并创建一个帐户。

1. 输入您的帐户和组织名称，选择您的 AWS 存储的首选区域，同意条款和条件，然后单击“继续”按钮。

1. 选择您的首选计划以继续。

1. 选择您希望如何使用 InfluxDB；选中所有适用于您的用例的选项。

配置

在使用 InfluxDB Go 客户端之前，您需要创建一个数据库，设置身份验证，并确定您的 InfluxDB 实例。以下是如何执行此操作

  1. 创建一个新的数据库（bucket）： 从您的 InfluxDB 仪表板，使用左侧导航栏导航到“加载数据”>“数据库”。输入您的数据库名称，选择您的数据保留偏好（我选择了一小时，因为我想在本教程结束后删除它），然后单击“创建”按钮。

1. 创建 API 令牌： 单击“API 令牌”，然后单击“生成 API 令牌”按钮以设置新的“全访问 API 令牌”，该令牌能够对您的数据库和组织进行读取、创建、更新、删除和写入访问。您还可以选择创建自定义 API 令牌并根据需要自定义访问权限。

  1. 查找您的 InfluxDB 云 URL： 您需要此 URL 来连接您的 Go 客户端。只需转到“来源”选项卡。然后，在仪表板上的“客户端库”下，选择“Go”。

A screenshot of a computer Description automatically generated

InfluxDB 3.0 的 API 概述

InfluxDB 3.0 提供了一系列 API，以方便处理不同编程语言的时序数据。以下是可用客户端库的列表以及它们的身份验证方式。

API 类型

InfluxDB 3.0 为多种语言提供了专用客户端库，每种库都经过优化，可在其特定环境中顺利工作，因此开发者可以高效地写入和查询数据

  • C# (.NET)： influxdb3-csharp 用 C# 编写，它为 C# 应用程序提供数据交互。
  • Go： influxdb3-go 针对 Go 应用程序进行了优化，它也是一个高效的数据管理工具。
  • Java： influxdb3-java 库可用于支持 Java 应用程序管理可靠的数据操作。
  • JavaScript： influxdb3-js 库支持 JavaScript，因此可以轻松地适用于基于 Web 的应用程序。
  • Python： influxdb3-python 专为 Python 构建，用于无故障地处理脚本中的数据。

这些库允许您通过 HTTP API 写入批量数据，并使用基于 gRPC 的 Arrow Flight 协议执行 SQL 和 InfluxQL 查询。它们还可以将数据格式转换为 InfluxDB 行协议。在本教程中，我们的重点是 influxdb3-go 客户端。

身份验证

为了安全地访问数据，InfluxDB 3.0 使用基于令牌的身份验证

  • 用户在 InfluxDB Cloud 的 GUI 中创建一个数据库令牌。
  • 在每个 API 请求的 Authorization 标头中使用该令牌作为 Bearer 令牌。

此配置仅提供对数据库的相关访问权限，并使所有受支持的客户端库的身份验证安全且容易。

使用 Go 客户端库

现在，让我们了解使用 InfluxDB Go 客户端库与您的数据交互的核心步骤。

安装 Go 客户端库

首先，我们需要使用以下命令创建一个新的 Go 模块

mkdir -p influxdb_go_client_demo
cd influxdb_go_client_demo
go mod init influxdb_go_client_demo
touch main.go

然后，运行以下命令安装 InfluxDB 3.0 的 Go 客户端库。

go get github.com/InfluxCommunity/influxdb3-goz

这将下载并安装与 InfluxDB Cloud 交互所需的软件包。

导入软件包

安装后，在您的 Go 项目中导入软件包

import (
    "github.com/InfluxCommunity/influxdb3-go/influxdb3"
)

初始化客户端

客户端类充当您与 InfluxDB 交互的主要接口。InfluxDB Cloud 使用令牌对 API 访问进行身份验证，因此您需要使用以下命令将您之前创建的全访问令牌保存为环境变量

export INFLUXDB_TOKEN=<YOUR_API_TOKEN>

将 <YOUR_API_TOKEN> 替换为您实际的 API 令牌。接下来，使用服务器 URL 和令牌初始化 Go 客户端，以设置与 InfluxDB 的初始连接。此客户端具有 WritePoints 和 Query 函数。将以下代码粘贴到您的 main.go 文件中

package main

import (
    "context"
    "fmt"
    "time"

  "github.com/InfluxCommunity/influxdb3-go/influxdb3"
)

func main() {
    // Create client
    url := "https://us-east-1-1.aws.cloud2.influxdata.com"
    token := os.Getenv("INFLUXDB_TOKEN")

// Create a new client using an InfluxDB server base URL and an authentication token
    client, err := influxdb3.New(influxdb3.ClientConfig{
      Host:  url,
      Token: token,
    })

      if err != nil {
      panic(err)
    }
    // Close client at the end and escalate error if present
    defer func (client *influxdb3.Client)  {
      err := client.Close()
      if err != nil {
        panic(err)
      }
    }(client)

    database := "testDB"
}

influxdb3.New 函数用于创建新的客户端实例。它将 ClientConfig 结构作为参数，其中包括两个元素

  • host (string): InfluxDB Cloud 服务器 URL
  • token (string): 用于验证请求的 API 令牌

将 testDB 替换为您的数据库名称。

将数据写入 InfluxDB

写入数据非常简单。首先，创建一个包含相关指标、标签和字段的数据点，然后将其发送到 InfluxDB。

package main
import (

    //...
     "context"
    "time"
  )

func writeData(database string, client *influxdb3.Client) {
	data := map[string]map[string]interface{}{
		"post1": {
			"title":    "InfluxDB Basics",
			"author":   "Alice",
			"views":    150,
			"category": "Databases",
		},
		"post2": {
			"title":    "Go Client Libraries for InfluxDB",
			"author":   "Bob",
			"views":    200,
			"category": "Programming",
		},
		"post3": {
			"title":    "Understanding Time Series Data",
			"author":   "Alice",
			"views":    175,
			"category": "Data Science",
		},
		"post4": {
			"title":    "Getting Started with Flux",
			"author":   "Charlie",
			"views":    220,
			"category": "Databases",
		},
		"post5": {
			"title":    "Optimizing Queries in InfluxDB",
			"author":   "Alice",
			"views":    180,
			"category": "Databases",
		},
	}

	// Write blog data to InfluxDB
	options := influxdb3.WriteOptions{
		Database: database,
	}

	for key := range data {
		point := influxdb3.NewPointWithMeasurement("blog_views").
			AddTag("author", data[key]["author"].(string)).
			AddTag("category", data[key]["category"].(string)).
			AddField("views", data[key]["views"].(int)).
			AddField("title", data[key]["title"].(string))

		if err := client.WritePointsWithOptions(context.Background(), &options, point); err != nil {
			panic(err)
		}

		time.Sleep(1 * time.Second) // separate points by 1 second
	}
}

func main() {
   //...
   writeData(database, client)
}

在上面的代码中，我们使用了六个函数

  • Client.WritePoint() 将单个数据点写入 InfluxDB。它需要一个数据库名称。
  • NewPointWithMeasurement() 创建一个具有指定指标名称的新数据点。
  • AddTag() 将元数据作为键值对添加到点。
  • AddField() 将实际数据值作为键值对添加到点。
  • WritePointsWithOptions() 使用特定的配置选项将点写入 InfluxDB。
  • WriteOptions 定义用于将数据写入 InfluxDB 的结构配置设置。

这会将博客数据写入您的数据库。现在，使用以下命令运行程序

go run ./main.go

从 InfluxDB 查询数据

查询数据就像使用 Go 客户端中的 Query 函数一样简单。InfluxDB 使用 SQL 运行查询。现在，让我们添加一个新函数来查询您的数据库并获取之前插入的所有博客数据。

package main

import (
    //...
    "fmt"
)

func queryBlogs(database string, client *influxdb3.Client) {
	query := `SELECT *
              FROM 'blog_views'
              WHERE time >= now() - interval '1 hour'

	queryOptions := influxdb3.QueryOptions{
		Database: database,
	}
	iterator, err := client.QueryWithOptions(context.Background(), &queryOptions, query)
	if err != nil {
		panic(err)
	}

	for iterator.Next() {
		value := iterator.Value()
		title := value["title"]
		author := value["author"]
		views := value["views"]
		category := value["category"]
		fmt.Printf("%s by %s has %d views in category %s\\n", title, author, views, category)
	}

}

func main() {
  //...

  queryBlogs(database, client)
}

上面的代码检索特定时间范围内的博客记录并打印值。

  • QueryWithOptions() 使用特定的数据库选项执行 SQL 查询。
  • Value() 将当前记录作为字段名称到值的映射返回。
  • Next() 将迭代器前进到结果中的下一条记录。
  • QueryOptions 指定查询执行的配置选项。

现在，再次运行程序以执行查询。

最佳实践

以下是一些最佳实践，可帮助您充分利用 InfluxDB 集成。这些建议将帮助您维护安全、高效且高度可扩展的解决方案。

安全

保护您的数据并确保对您的 InfluxDB 实例的安全访问

  • 始终使用安全的 HTTPS 连接连接到 InfluxDB。
  • 定期轮换您的令牌以降低安全风险。
  • 将 API 令牌和敏感数据存储在环境变量中。

效率

您还可以通过优化数据写入和查询来显着提高应用程序的性能。以下是一些有效执行此操作的技巧

  • 对于高吞吐量应用程序，批量处理写入操作以减少网络开销。
  • 根据您的需要使用适当的时间精度。它可以是纳秒或秒。这样做可以最大限度地减少存储并提高性能。

可扩展性

随着数据的增长，您需要确保您的 InfluxDB 设置可以扩展。以下是一些可扩展性方面的考虑因素

  • 使用保留策略自动删除旧数据并控制存储成本。
  • InfluxDB Cloud Dedicated 更适合企业应用程序，并提供更高的吞吐量和可扩展性。

总结

在本教程中，我们介绍了使用 InfluxDB 3.0 Go 客户端库的一些基本知识，包括如何执行以下操作

  • 设置和配置 InfluxDB Cloud。
  • 使用 Go 客户端库写入和查询数据。
  • 实施安全、效率和可扩展性的最佳实践。

现在您已经了解了如何使用 InfluxDB Go 客户端库，是时候开始使用了！注册 InfluxDB Cloud Serverless 或深入了解 InfluxDB Cloud Dedicated 的企业解决方案。

进一步阅读

要了解有关 InfluxDB 的更多信息，请参阅以下额外资源