使用 InfluxDB API 入门

作者：社区 / 产品，用例，开发者，入门
2022年2月4日

导航至

本文由 Nicolas Bohorquez 撰写。向下滚动查看作者的图片和简介。

与 InfluxDB 等时序数据库一样，数据按时间索引。它们在记录恒定的数据流，如服务器指标、应用监控数据、传感器报告以及包含时间戳的任何数据方面非常高效。

时序数据库中的数据始终以最新的数据值写入，但不会更新以前的值。在传统的交易方法中，您会修改实体的模型信息，但在时序数据库中，您可以保存通过时间生成的所有数据点。

Telegraf 是收集 InfluxDB 数据的首选方式，但在某些情况下，您可能希望使用应用程序程序接口（API）来开发您的解决方案；例如，如果您需要在将数据放入时序数据库之前预处理数据，或者如果您找不到与您的源系统兼容的输入插件。

InfluxDB 包括针对最流行的编程语言（Python、Java、Go、Ruby 等）的 API 客户端，并且可以直接与 REST API 一起使用。

在本教程中，您将学习如何通过 API 进行身份验证，读取数据流，将其作为时序数据存储到 InfluxDB 中，并使用 InfluxDB 的 HTTP API 对数据进行查询。

在开始之前，您需要在您的操作系统上安装 InfluxDB 2.x 和一个 HTTP 客户端，如 curl、httpie 或 Postman。本教程将展示如何使用您机器上的本地 InfluxDB 实例，但您也可以使用 InfluxDB Cloud 来更快地开始，而无需在您的机器上安装任何东西。

什么是时序数据库？

时序数据库是一种需要数据模型包含基于时间的维度的特殊数据存储类别。

此类数据的几个示例包括一天中特定地理位置的温度、高峰时段穿越街道的人数或一周内应用程序的注册人数。

累积数据，具有较小的数据点和更多的时间粒度，是存储在时间序列数据库中的首选数据类型。以下是一些时间序列数据的例子

传感器数据：能够记录特定动作的小型设备为时间序列数据提供了良好的来源。
金融数据：股票价格或金融资产的价值随时间变化，是时间序列数据的经典例子。
计算基础设施监控数据：随着云基础设施的增长，监控工具的数量也在增加，为每个组件的性能提供了许多数据点。

InfluxDB是您可以使用来处理此类数据的最佳工具之一，因为它允许您以一致和可扩展的方式捕获、存储和查询数据。

InfluxDB API

InfluxDB的API（当前版本为2.x）是一组HTTP端点，它提供了对InfluxDB系统所有功能的编程访问。API按资源及其操作组织。

端点覆盖

系统信息：端点可以检查实例的状态、启动时实例的可用性、实例的健康状况以及可用的顶级路由。
安全和访问：端点管理组织、用户和授权，为API访问提供令牌。这种基于令牌的安全方法提供了自包含的对象（令牌），它提供了访问和权限以管理组织。
资源访问：端点可以管理桶、仪表板、任务和其他资源。
数据I/O：端点执行桶中数据的读写操作。
其他资源：端点允许您执行备份操作和管理其他InfluxDB资源，如单元格、检查、标签和通知规则。

在本教程中，您将使用数据I/O端点来编写和查询API，但在开始之前，您需要了解您可以使用的不同认证方法来调用InfluxDB API端点。

认证类型

与InfluxDB一起使用有三种认证方法

_用户/密码_组合，也称为_基本认证_，其中您发送一个编码的_用户:密码_字符串
_查询字符串_方法使用两个URL编码的参数（_u和p_）
基于令牌的认证，这是首选方法

对于前两种选项，您需要生成一个用户名和密码；但在此教程中，您将使用基于令牌的认证，您可以从InfluxDB UI或使用/api/v2/authorizations API端点生成。

建立连接

基于令牌的方法是首选的，因为基本和查询字符串认证方法不支持令牌方案。

一旦您有一个运行的InfluxDB安装，系统将提示您创建组织、用户和桶。

InfluxDB initial user setup

在创建您的组织、用户和桶之后，请在Web用户界面的加载数据> API令牌选项卡中检查自动创建的API令牌。

在此界面中，您还可以通过选择“生成API令牌”按钮来创建新的令牌。在那里，您可以命名令牌并分配权限。

对于此示例，所使用的令牌具有完全访问权限，但您应该在生产环境中应用最小权限原则。

InfluxDB-web-UI-tokens

要测试您对InfluxDB实例的访问状态，请使用 _/ping_ 端点。例如，使用以下终端中的 _curl_ 客户端

$ curl localhost:8086/health

您将获得一个包含本地服务器状态和版本的JSON响应负载

{
	"checks": [],
	"commit": "657e1839de",
	"message": "ready for queries and writes",
	"name": "influxdb",
	"status": "pass",
	"version": "2.1.1"
}

启用TLS/SSL加密

与其他任何对外开放的资源一样，您需要尽量减少在受控环境中暴露数据时可能出现的潜在安全风险。

您可以使用SSL/TLS加密API和消费者之间的通信，通过获取证书（自签名或由证书颁发机构签名）并配置InfluxDB以使用证书来加密数据。

您可以按照influxdata的安全和授权说明启用TLS/SSL加密，这允许客户端验证InfluxDB服务器的真实性。

插入数据

要使用API插入数据，您需要目标组织和存储桶。在此教程中，我们将使用包含全球CO2数据的此数据集。请确保您已下载文件并将其存储在与您使用本教程相同的文件夹中。下面的脚本将期望CSV文件位于同一目录中。

让我们使用API调用 _/api/v2/buckets_ 端点来检查所有可用的存储桶

curl https://127.0.0.1:8086/api/v2/buckets --header "Authorization: Token your_api_token"

JSON响应至少包含三个存储桶。之前显示的设置屏幕中的 _InfluxDB-API-test-bucket_ 是最初配置的，也是我们的测试目标。

{
	"id": "81fef1d4510e235d",
	"orgID": "b9b77e9c6e2d331d",
	"type": "user",
	"name": "InfluxDB-API-test-bucket",
	"retentionRules": [
        	{
                	"type": "expire",
                	"everySeconds": 0,
                	"shardGroupDurationSeconds": 604800
        	}
	],
	"createdAt": "2021-11-11T23:11:26.588182068Z",
	"updatedAt": "2021-11-11T23:11:26.588182158Z",
	"links": {
        	"labels": "/api/v2/buckets/81fef1d4510e235d/labels",
        	"members": "/api/v2/buckets/81fef1d4510e235d/members",
        	"org": "/api/v2/orgs/b9b77e9c6e2d331d",
        	"owners": "/api/v2/buckets/81fef1d4510e235d/owners",
        	"self": "/api/v2/buckets/81fef1d4510e235d",
        	"write": "/api/v2/write?org=b9b77e9c6e2d331d\u0026bucket=81fef1d4510e235d"
	},
	"labels": []
}|

保存 orgID 值以在以下请求中使用。

现在，使用公开数据集将数据写入存储桶：自1751年以来化石燃料的全球CO2排放。此存储桶包含碳 dioxide 信息分析中心编纂的266年碳排放数据。使用简单的bash脚本，您可以读取文件，打印每年的最有意思的值，并将数据写入InfluxDB存储桶。

首先，让我们创建一个简单的 write.sh bash脚本

#! /bin/bash
#1. iterates over the global_emissions.csv file and reads each comma-separated column
while IFS="," read -r Year Total GasFuel LiquidFuel SolidFuel Cement GasFlaring PerCapita
do
	echo "Year: $Year , total: $Total , Per capita $PerCapita"
	#2. Converts the value of the year into a UNIX timestamp
	ts=`date "+%s" -u -d "Dec 31 $Year 23:59:59"`

	#3. Inserts the total value of co2 per year
	curl -i -XPOST "https://127.0.0.1:8086/api/v2/write?precision=s&orgID=$1&bucket=$2" \
    	--header "Authorization: Token $3" \
    	--data-raw "total_co2,source=CDIAC value=$Total $ts"

	#4. Checks if there is a value per capita
	if [ -z "$PerCapita" ]; then
    	PerCapita=0
	fi

	#5. Inserts the per capita value of co2 emissions per year
	curl -i -XPOST "https://127.0.0.1:8086/api/v2/write?precision=s&orgID=$1&bucket=$2" \
    	--header "Authorization: Token $3" \
    	--data-raw "per_capita_co2,source=CDIAC value=$PerCapita $ts"

done < <(tail -n +2 global_emissions.csv)

上述脚本执行以下操作

遍历 global_emissions.csv 文件并读取每个以逗号分隔的列
将年份的值转换为UNIX时间戳
插入每年的CO2总价值
检查是否有人均值
插入每年的CO2排放人均值

您可以使用终端调用此脚本，传递三个空格分隔的参数：之前保存的组织ID（orgID）、存储桶的名称和之前使用的API令牌。

请注意，前面的脚本在脚本所在的文件夹中寻找 global_emissions.csv 文件。

一旦你得到了源文件和脚本，可以使用以下命令运行它：

./write.sh b9b77e9c6e2d331d InfluxDB-API-test-bucket your_api_token

输出应该类似于以下代码，这是每个API调用的HTTP 204响应代码。

HTTP/1.1 204 No Content
X-Influxdb-Build: OSS
X-Influxdb-Version: 2.1.1
Date: Fri, 12 Nov 2021 00:05:44 GMT

注意InfluxDB的 /api/v2/write 端点的调用。如文档所述，它需要精度、组织、和bucket查询参数，并期望一个遵循InfluxDB 行协议的负载。

此协议是一种基于文本的数据表示，包含四个组件

测量： 你所测量的内容
标签集： 如何识别测量
字段集： 与测量相关联的值集合（在这种情况下，只有一个）
时间戳：最后一次测量的时间

使用此格式，你可以表达复杂的时间序列数据。在这个例子中，只有 total co2 和 per capita co2 测量被写入到桶中。

查询数据

与写入操作类似，存在一个接受以Flux语言（这是一种为查询、分析和在数据上采取行动而设计的简洁且功能性的语言）为负载的查询端点。你还将使用先前保存为查询参数的 orgID 值来调用端点。

查询将生成一个CSV结果，显示从2000年到2015年每五年一次的 total co2 的平均值

curl --request POST \
  https://127.0.0.1:8086/api/v2/query?orgID=your_org_id  \
  --header 'Authorization: Token your_api_token' \
  --header 'Accept: application/csv' \
  --header 'Content-type: application/vnd.flux' \
  --data 'from(bucket:"InfluxDB-API-test-bucket")
    	|> range(start: 2000-12-31T00:00:00Z, stop: 2015-01-01T00:00:00Z)
    	|> filter(fn: (r) => r._measurement == "total_co2")
    	|> aggregateWindow(every: 5y, fn: mean)'

/api/v2/query 可以使用请求中的附加头压缩结果。

你也可以包含一组键/值对，表示要注入查询的参数，甚至可以以特定的CSV方言获取结果。这使得提取数据变得简单，其中你的创造力和对Flux语言的知识是驱动力。

如果你有一个InfluxDB v1.x数据库，你也可以使用InfluxDB v2.x API查询你的数据。首先，确保使用 /api/v2/dbrps 端点列出和创建必要的映射，以将数据库和保留策略映射到桶，然后使用API启动查询

curl --request GET \
  https://127.0.0.1:8086/api/v2/query?orgID=your_org_id  \
  --header 'Authorization: Token your_token' \
  --header 'Accept: application/csv' \
  --header 'Content-type: application/json' \
  --data-urlencode "q=SELECT mean(*) FROM example-db.example-rp.total_co2"

鉴于本教程使用的是InfluxDB v2.x数据库，你无法直接使用当前设置测试这个InfluxQL示例。但它对于与先前版本的兼容性测试很有用。

你可能在与InfluxDB这样的时间序列数据库相关的常见错误是试图按照关系型范式设计你的解决方案。InfluxDB的文档提供了在时间序列用例中的最佳实践来设计架构，在开始建模之前你应该查阅。

结论

在本教程中，你学习了InfluxDB HTTP API的使用基础，如何对InfluxDB实例进行身份验证和测试API的可用性，以及如何使用行协议通过写入端点发送数据。

你还学习了如何通过使用Flux语言进行查询来读取数据。脚本和所使用的数据作为GitHub Gist提供。

InfluxDB HTTP API为您提供了大量资源和操作，可以以编程方式使用，增加了灵活性和与任何编程语言的兼容性。您可以使用任何InfluxDB安装方法在本地部署InfluxDB HTTP API，或者尝试InfluxData平台以获取托管环境的所有好处。

请记住，您还可以使用许多流行语言的API客户端。

关于作者

尼古拉斯·博哈罗克（Nicolas Bohorquez）是Merqueo的数据架构师，曾参与过几个初创公司的发展团队，并在美洲创立了三家公司。他对复杂性的建模以及使用数据科学改善世界的热情。

导航至

尝试 InfluxDB Cloud

停止盲目飞行

使用 InfluxDB API 入门

作者：社区 / 产品，用例，开发者，入门
2022年2月4日

导航至

什么是时序数据库？

InfluxDB API

认证类型

建立连接

启用TLS/SSL加密

插入数据

查询数据

结论

关于作者

尝试 InfluxDB Cloud

了解更多关于InfluxDB的信息

产品与解决方案

开发者

公司

数据处理

导航至

尝试 InfluxDB Cloud

停止盲目飞行

获取更新

使用 InfluxDB API 入门

作者：社区 / 产品，用例，开发者，入门 2022年2月4日

导航至

什么是时序数据库？

InfluxDB API

认证类型

建立连接

启用TLS/SSL加密

插入数据

查询数据

结论

关于作者

尝试 InfluxDB Cloud

了解更多关于InfluxDB的信息

产品与解决方案

开发者

公司

注册InfluxData通讯

关注我们

作者：社区 / 产品，用例，开发者，入门
2022年2月4日