InfluxDB HTTP API 接口调用详解（一）

引言

在当今数字化时代，时间序列数据无处不在，从物联网设备产生的传感器数据，到金融领域的交易记录，再到系统运维中的监控指标，这些数据蕴含着丰富的信息，对于企业的决策制定、业务优化以及问题排查等都起着至关重要的作用。而 InfluxDB 作为一款高性能的开源时序数据库，专门针对时间序列数据的存储、查询和分析进行了优化，能够高效地处理大规模的时间序列数据，在众多领域得到了广泛应用。

InfluxDB 提供了丰富的功能和特性，其中 HTTP API 接口为用户与 InfluxDB 进行交互提供了一种便捷、灵活的方式。通过 HTTP API，我们可以使用各种编程语言发送 HTTP 请求，实现数据的写入、查询、删除以及数据库和表结构的管理等操作，这使得 InfluxDB 能够很容易地与不同的系统和应用进行集成。

本文将深入探讨 InfluxDB 的 HTTP API 接口调用，详细介绍其使用方法、常见操作以及实际应用案例，帮助大家更好地掌握 InfluxDB 的 HTTP API，充分发挥 InfluxDB 在时间序列数据处理方面的强大能力。无论是初学者想要快速上手，还是有经验的开发者寻求更深入的技术细节，相信本文都能为你提供有价值的参考。

InfluxDB HTTP API 基础介绍

1. InfluxDB 概述

InfluxDB 是一款基于 Go 语言编写的开源分布式时序数据库，旨在提供高性能的时间序列数据存储和查询服务。它无需外部依赖，这使得其部署和维护都相对简单。InfluxDB 专为处理大规模的时间序列数据而设计，这类数据的特点是包含时间戳以及与之相关的一系列测量值或事件记录。

InfluxDB 具备诸多显著特点，首先是其高性能的数据存储和处理能力。它采用了独特的时间结构合并树（TSM）存储引擎，该引擎针对时间序列数据的特性进行了优化，能够实现高速的数据读写操作，并且在数据压缩方面表现出色，有效减少了存储空间的占用，提高了存储效率。例如，在大规模的物联网数据采集场景中，每秒可能会产生数以万计的传感器数据点，InfluxDB 能够快速地将这些数据写入存储，同时保证数据的完整性和一致性。

InfluxDB 还提供了强大的查询语言，类似于 SQL，易于学习和使用。通过这种查询语言，用户可以方便地对时间序列数据进行各种复杂的查询操作，如聚合、过滤、排序等。例如，查询过去一小时内服务器 CPU 使用率的平均值，或者找出特定时间段内网络流量最高的设备等。这种强大的查询功能使得用户能够从海量的数据中快速提取有价值的信息，为数据分析和决策提供支持。

InfluxDB 支持灵活的数据模型，采用无模式（schemaless）设计，允许用户在写入数据时无需预先定义数据结构，这大大提高了数据写入的灵活性和效率。同时，它还支持对标签（tags）建立索引，标签是用于对数据进行分类和标记的键值对，通过对标签建立索引，可以实现快速的数据查询和过滤。比如，在监控系统中，可以将服务器的名称、地理位置、应用程序名称等作为标签，方便快速查询特定服务器或应用程序的相关数据。

InfluxDB 的应用场景十分广泛，在监控领域，无论是服务器性能监控，如 CPU 使用率、内存使用情况、磁盘 I/O 等指标的监控，还是网络设备监控，如网络流量、带宽利用率、丢包率等指标的监控，InfluxDB 都能高效地存储和处理这些监控数据，为系统运维人员提供实时的监控数据和历史数据分析，帮助他们及时发现和解决系统中的问题。

在物联网领域，大量的物联网设备会不断产生各种传感器数据，如温度、湿度、压力、光照等，InfluxDB 能够很好地适应这种高并发、海量数据的写入场景，并且可以通过其查询功能对这些数据进行实时分析和处理，实现设备状态监测、故障预警、能源管理等功能。例如，智能工厂中的设备可以将运行数据实时发送到 InfluxDB，通过分析这些数据，工厂管理者可以优化生产流程，提高生产效率。

2. HTTP API 简介

InfluxDB HTTP API 是一种 RESTful 风格的 API，它支持 HTTP 和 HTTPS 协议，这使得它能够方便地与各种网络应用进行交互。通过 HTTP API，用户可以使用标准的 HTTP 请求方法（如 GET、POST、PUT、DELETE 等）来与 InfluxDB 进行通信，实现数据的写入、查询、删除以及数据库和表结构的管理等操作。它为 InfluxDB 与外部程序之间搭建了一座桥梁，是实现 InfluxDB 与其他系统集成的重要方式。

在数据写入方面，我们可以使用 POST 请求将数据发送到 InfluxDB 的特定接口，数据格式可以采用 InfluxDB 特有的行协议（Line Protocol）或者 JSON 格式。行协议是一种简洁高效的数据表示方式，适合在网络传输和数据存储中使用；而 JSON 格式则更加通用，便于与其他基于 JSON 的系统进行交互。例如，使用 Python 的requests库发送 POST 请求将传感器数据写入 InfluxDB：

import requests

url = 'http://localhost:8086/write?db=mydb'

data = 'temperature,sensor_id=S1 value=25.5 1630424257000000000'

response = requests.post(url, data=data)

if response.status_code == 204:

print('Data written successfully')

else:

print('Failed to write data')

在数据查询方面，我们可以使用 GET 或 POST 请求，通过指定查询语句（使用 InfluxQL 或 Flux 查询语言）来获取所需的数据。InfluxQL 是 InfluxDB 早期版本使用的查询语言，类似于 SQL，语法简洁易懂；Flux 是 InfluxDB 2.0 引入的新一代查询语言，具有更强大的功能和灵活性，支持函数式编程风格。例如，使用 InfluxQL 查询过去一小时内温度的平均值：

import requests

url = 'http://localhost:8086/query?db=mydb'

query = 'SELECT mean("value") FROM "temperature" WHERE time >= now() - 1h'

params = {'q': query}

response = requests.get(url, params=params)

if response.status_code == 200:

data = response.json()

print(data)

else:

print('Failed to query data')

InfluxDB HTTP API 还支持对数据库、表、用户等资源的管理操作。例如，可以使用 POST 请求创建新的数据库，使用 DELETE 请求删除指定的数据库或表，使用 PUT 请求更新用户权限等。这些功能使得我们可以通过编程的方式灵活地管理 InfluxDB 的资源，满足不同应用场景的需求。

接口调用前的准备工作

1. 环境搭建

在开始调用 InfluxDB 的 HTTP API 接口之前，首先需要搭建好 InfluxDB 的运行环境。这里以在 Linux 系统（CentOS 7 为例）上安装 InfluxDB 2.0 版本进行说明。

首先，从 InfluxDB 官方网站（InfluxData Downloads ）下载适用于 CentOS 7 的 InfluxDB 安装包，下载命令如下：

wget https://dl.influxdata.com/influxdb/releases/influxdb2-2.7.1-linux-amd64.tar.gz

下载完成后，使用以下命令解压安装包：

tar -zxvf influxdb2-2.7.1-linux-amd64.tar.gz

解压后，进入解压后的目录：

cd influxdb2-2.7.1-linux-amd64

接着，可以将 InfluxDB 的可执行文件路径添加到系统环境变量中，以便在任何位置都能方便地执行 InfluxDB 相关命令。编辑~/.bashrc文件，在文件末尾添加以下内容：

export PATH=$PATH:/path/to/influxdb2-2.7.1-linux-amd64

其中，/path/to/需要替换为实际的解压目录路径。添加完成后，执行以下命令使环境变量生效：

source ~/.bashrc

然后，启动 InfluxDB 服务。在解压后的目录中，执行以下命令：

./influxd

如果希望 InfluxDB 在后台运行，可以使用nohup命令：

nohup./influxd &

启动完成后，可以通过访问http://localhost:8086（如果是在本地安装）来验证 InfluxDB 是否正常运行。如果看到 InfluxDB 的 Web 界面，说明安装和启动成功。

2. 获取 API Token

API Token 是访问 InfluxDB HTTP API 的重要凭证，它用于验证请求的身份和权限。获取 API Token 的方法如下：

首先，登录到 InfluxDB 的 Web 界面，在登录成功后，点击页面左上角的用户头像，选择 “Tokens” 选项。

在 Tokens 页面中，可以看到已有的 Tokens 列表。如果没有合适的 Token，可以点击 “Generate Token” 按钮来生成新的 Token。在生成 Token 时，需要选择 Token 的权限范围，如读写所有数据、只读特定数据库等。根据实际需求选择相应的权限，然后点击 “Generate” 按钮。

生成的 Token 会以字符串形式显示，务必妥善保管这个 Token，因为一旦关闭该页面，将无法再次查看该 Token。如果不慎丢失 Token，只能重新生成。在调用 HTTP API 时，需要将 Token 添加到请求的 Header 中，例如：

Authorization: Token <your_token>

其中，<your_token>需要替换为实际生成的 Token。

3. 选择接口测试工具

为了方便地测试 InfluxDB 的 HTTP API 接口，我们可以选择一些专业的接口测试工具，如 ApiPost、Postman 或 curl。

ApiPost 是一款功能强大且易于使用的 API 调试工具，支持多种请求方式和数据格式。可以从 ApiPost 官方网站（Apipost-API 文档、设计、调试、自动化测试一体化协作平台）下载并安装适合自己系统的版本。安装完成后，打开 ApiPost，首先可以创建一个新的目录来组织与 InfluxDB 相关的接口测试。在左侧导航栏中，点击 “+” 按钮，选择 “新建目录”，为目录命名，例如 “InfluxDB API Tests”。

接下来，设置公用的 Header。点击右上角的齿轮图标，选择 “环境变量”，在环境变量页面中，添加一个名为 “Authorization” 的变量，值为Token <your_token>，其中<your_token>替换为实际的 API Token。这样，在每个请求中，都会自动带上这个 Header。

Postman 也是一款广泛使用的 API 测试工具，安装方法与 ApiPost 类似，可以从 Postman 官方网站（Download Postman | Get Started for Free ）下载安装。安装完成后，打开 Postman，同样可以创建一个新的集合来管理 InfluxDB 的 API 请求。点击 “New” 按钮，选择 “Collection”，为集合命名。在集合中创建新的请求时，在请求编辑区的 “Headers” 标签下，添加 “Authorization” 头，值为Token <your_token>。

curl 是一个命令行工具，在 Linux 和 Windows 系统（需要安装 curl 工具）中都可以使用。使用 curl 调用 InfluxDB API 时，通过-H参数来添加 Header，例如：

curl -H "Authorization: Token <your_token>" -X GET "http://localhost:8086/api/v2/query?orgID=your_org_id&query=your_query"

其中，<your_token>替换为 API Token，your_org_id替换为实际的组织 ID，your_query替换为实际的查询语句。

常用 HTTP API 接口调用详解

1. Ping 接口

Ping 接口主要用于检查 InfluxDB 实例的状态，同时还能返回 InfluxDB 的构建类型和版本信息，这对于确认 InfluxDB 服务是否正常运行以及了解其版本情况非常有用。

该接口支持的请求方式为 GET 和 HEAD。其 URL 格式为http://<influxdb-host>:8086/ping，其中<influxdb-host>需要替换为实际的 InfluxDB 服务器主机名或 IP 地址。

使用示例如下，以在本地测试 InfluxDB 服务状态为例，使用 curl 命令发送 GET 请求：

curl http://localhost:8086/ping

如果 InfluxDB 服务正常运行，将返回 HTTP 状态码 204，表示 “无内容”，这意味着请求成功，并且服务器正常响应，但没有返回具体内容。如果 InfluxDB 服务未正常运行，可能会返回其他状态码，如 404（未找到）表示服务器未找到该请求的资源，或者 500（内部服务器错误）表示服务器在处理请求时发生了错误。

2. Query 接口

Query 接口是 InfluxDB 中非常重要的一个接口，它承担着多种关键功能，不仅可以用于查询数据，还能进行数据库管理、保留策略（Retention Policy，RP）管理以及用户管理等操作，是与 InfluxDB 进行数据交互和管理的核心接口之一。

该接口支持的请求方式有 GET 和 POST，其 URL 为http://<influxdb-host>:8086/query，同样，<influxdb-host>需替换为实际的服务器地址。

在使用 Query 接口时，有一些必选参数和可选参数需要了解。必选参数包括：

db：用于指定要操作的数据库名称，这是必不可少的参数，因为 InfluxDB 可能包含多个数据库，明确指定数据库才能确保操作在正确的数据集上进行。

q：即查询语句，需要使用 URL 编码。查询语句可以使用 InfluxQL 或 Flux 查询语言编写，用于定义具体的数据查询逻辑，例如查询特定时间范围内的某些测量值、对数据进行聚合操作等。

可选参数则有：

rp：用于指定查询的保留策略。保留策略定义了数据在数据库中保存的时间长度以及数据的副本数量等信息。如果不指定，将使用默认的保留策略。

u和p：分别表示用户名和密码，用于身份验证。如果 InfluxDB 启用了身份验证功能，需要提供正确的用户名和密码才能成功执行请求。

precision：用于指定时间戳的精度，可选值有ns（纳秒）、u（微秒）、ms（毫秒）和s（秒）。默认精度是纳秒，如果查询语句中涉及时间相关的操作，并且希望使用特定精度的时间戳，可以通过该参数进行设置。

下面给出一些使用示例：

单条查询示例，使用 GET 请求查询mydb数据库中temperature测量值在过去一小时内的平均值，使用 InfluxQL 查询语言：

curl -G 'http://localhost:8086/query?db=mydb' --data-urlencode 'q=SELECT mean("value") FROM "temperature" WHERE time >= now() - 1h'

在这个示例中，-G参数表示使用 GET 请求方式，--data-urlencode用于对查询语句进行 URL 编码，确保查询语句能正确传递。

多条查询示例，使用 POST 请求在mydb数据库中执行多个查询操作，假设我们要同时查询temperature测量值的最大值和最小值，并且指定时间戳精度为毫秒：

curl -XPOST 'http://localhost:8086/query?db=mydb&precision=ms' \

-H 'Content-Type: application/x-www-form-urlencoded' \

--data-urlencode 'q=SELECT max("value") FROM "temperature"; SELECT min("value") FROM "temperature"'

这里使用-XPOST指定请求方式为 POST，-H参数用于设置请求头，指定请求体的数据格式为application/x-www-form-urlencoded，因为我们要发送的查询语句是经过 URL 编码的。--data-urlencode后面跟着的是用分号分隔的多个查询语句。

3. Write 接口

Write 接口的主要职责是向 InfluxDB 数据库中写入数据，它是将各种时间序列数据存入 InfluxDB 的关键通道，无论是来自传感器的实时数据，还是系统产生的日志数据等，都可以通过这个接口写入到 InfluxDB 中进行存储和后续分析。

该接口的请求方式为 POST，URL 为http://<influxdb-host>:8086/write，<influxdb-host>为实际的服务器地址。

必选参数db用于指定要写入数据的目标数据库名称，和 Query 接口中的db参数类似，明确指定数据库是确保数据正确存储的关键。可选参数precision用于指定时间戳的精度，默认是纳秒，与 Query 接口中的precision参数作用相同，可根据实际需求设置时间戳精度。

InfluxDB 支持两种主要的数据写入格式：行协议（Line Protocol）和 JSON 格式。行协议是一种简洁高效的数据表示方式，特别适合在网络传输和数据存储中使用；JSON 格式则更加通用，便于与其他基于 JSON 的系统进行交互。

插入单条数据示例，使用行协议格式向mydb数据库的temperature测量值中插入一条数据，包含标签sensor_id=S1，字段value=25.5，并指定时间戳（这里假设时间戳为 1630424257000000000）：

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'temperature,sensor_id=S1 value=25.5 1630424257000000000'

-i参数用于显示响应头信息，方便查看服务器返回的状态和其他相关信息，--data-binary用于发送二进制数据，这里就是按照行协议格式编码的数据。

插入多条数据示例，同样使用行协议格式向mydb数据库的temperature测量值中插入多条数据，每条数据之间用换行符分隔：

curl -i -XPOST 'http://localhost:8086/write?db=mydb' --data-binary 'temperature,sensor_id=S1 value=25.5 1630424257000000000

temperature,sensor_id=S2 value=26.0 1630424258000000000

temperature,sensor_id=S3 value=24.8 1630424259000000000'

如果使用 JSON 格式写入数据，示例如下，假设要插入的数据包含测量值temperature，标签sensor_id和字段value：

curl -i -XPOST 'http://localhost:8086/write?db=mydb' \

-H 'Content-Type: application/json' \

--data-binary '[{"measurement": "temperature", "tags": {"sensor_id": "S1"}, "fields": {"value": 25.5}, "time": "2023-10-01T12:00:00Z"}]'

这里需要通过-H参数设置请求头的Content-Type为application/json，以表明发送的数据是 JSON 格式，--data-binary后面跟着的是符合 JSON 格式的字符串。