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 格式的字符串。