使用HTTP API查詢、寫入與管理資料庫-時間序列資料庫 TSDB-阿里雲

TSDB For InfluxDB®提供了一種與資料庫進行互動的簡易方法，它使用了HTTP響應碼、HTTP認證、JWT令牌和基本（basic）認證，並以JSON格式返回結果。

以下章節假設TSDB For InfluxDB®執行個體運行在<網路地址>上，連接埠為3242，並且開啟HTTPS。

TSDB For InfluxDB® HTTP路徑（endpoint）

路徑	描述
/ping	使用`/ping`檢查TSDB For InfluxDB®執行個體的狀態和TSDB For InfluxDB®的版本
/query	使用`/query`查詢資料和管理資料庫、保留原則和使用者
/write	使用`/write`將資料寫入到一個已經存在的資料庫

/ping HTTP路徑

/ping路徑接受GET和HEAD的HTTP請求。使用這個路徑，檢查TSDB For InfluxDB®執行個體的狀態和TSDB For InfluxDB®的版本。

定義

GET https://<網路地址>:3242/ping?u=<帳號名稱>&p=<密碼>

HEAD https://<網路地址>:3242/ping?u=<帳號名稱>&p=<密碼>

選項verbose

預設情況下，/ping HTTP路徑返回一個簡單的HTTP 204狀態，讓用戶端知道伺服器正在運行。verbose的預設值是false。當verbose設定為true時（/ping?verbose=true），返回HTTP 200狀態。

樣本

您可以使用/ping路徑查看TSDB For InfluxDB®執行個體的版本（version）。頭部欄位X-Influxdb-Version顯示了TSDB For InfluxDB®的版本。

~ curl -sl -I https://<網路地址>:3242/ping?u=<帳號名稱>&p=<密碼>

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
X-Influxdb-Build: OSS
X-Influxdb-Version: v1.7.x
X-Request-Id: 9c353b0e-aadc-11e8-8023-000000000000
Date: Tue, 05 Nov 2018 16:08:32 GMT

狀態代碼和響應

響應的本文是空的。

HTTP狀態代碼	描述
204	成功！TSDB For InfluxDB®執行個體已經啟動並正在運行

/query HTTP路徑

/query路徑接受GET和POST的HTTP請求。使用這個路徑，查詢資料和管理資料庫、保留原則和使用者。

定義

GET https://<網路地址>:3242/query?u=<帳號名稱>&p=<密碼>

POST https://<網路地址>:3242/query?u=<帳號名稱>&p=<密碼>

動詞用法（Verb usage）

動詞（Verb）	查詢類型
GET	用於以如下關鍵字開頭的所有查詢： SELECT SHOW
POST	用於以如下關鍵字開頭的所有查詢： ALTER CREATE DELETE DROP GRANT KILL REVOKE

* 唯一的例外是包含INTO子句的SELECT查詢，這些查詢需要使用POST請求。

樣本

使用SELECT語句查詢資料

$ curl -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

measurement mymeas中有兩個資料點。在第一個資料點中，時間戳記是2017-03-01T00:16:18Z，field key myfield的值是33.1，tag key mytag1和mytag2沒有tag value。在第二個資料點中，時間戳記是2017-03-01T00:17:18Z，field key myfield的值是12.4，tag key mytag1和mytag2的值分別為12和14。

相同的查詢在TSDB For InfluxDB®的命令列介面中則返回：

name: mymeas
time                  myfield  mytag1  mytag2
----                  -------  ------  ------
2017-03-01T00:16:18Z  33.1
2017-03-01T00:17:18Z  12.4     12      14

使用SELECT語句和INTO子句查詢資料

$ curl -XPOST 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * INTO "newmeas" FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"result","columns":["time","written"],"values":[["1970-01-01T00:00:00Z",2]]}]}]}

包含INTO子句的SELECT查詢需要使用POST請求。

返回結果顯示，TSDB For InfluxDB®寫入兩個資料點到measurement newmeas。請注意，系統使用epoch 0（1970-01-01T00:00:00Z）作為空白時間戳記。

字串類型的查詢參數

字串類型的查詢參數	可選/必需	描述
chunked=[true, `number_of_points`]	可選。	批量流式地返回資料點，而不是將所有資料一次性返回。如果設定為true，TSDB For InfluxDB®按序列或按10,000個資料點（哪個條件最先滿足就以哪個條件來分塊）分批返回結果。如果設定為一個特定的值，TSDB For InfluxDB®按序列或按指定數量的資料點分批返回結果。
db=`database_name`	對依賴資料庫的查詢是必需的（大多數`SELECT`查詢和`SHOW`查詢需要此參數）。	設定查詢的目標資料庫
epoch=[ns,u,µ,ms,s,m,h]	可選。	返回具有特定精度的epoch時間戳記。TSDB For InfluxDB®預設返回RFC3339格式的時間戳記，精度為納秒。`u`和`µ`都表示微秒。
p=`password`	如果沒有開啟認證，這是可選的。開啟認證後，這是必需的。	如果開啟了認證，請設定用於認證的密碼。需要與參數`u`同時使用。
pretty=true	可選。	開啟JSON輸出的美觀列印（pretty-printed）。雖然它在調試的時候非常有用，但是不建議用於生產，因為它會消耗不必要的網路頻寬。
q=`query`	必需。	需要執行的InfluxQL命令。
u=`username`	如果沒有開啟認證，這是可選的。開啟認證後，這是必需的。	如果開啟了認證，請設定用於認證的使用者名稱。使用者必須具有讀資料庫的許可權。需要與參數`p`同時使用。

* 如果沒有使用參數chunked，TSDB For InfluxDB®不會截斷請求返回的行數。

樣本

使用SELECT語句查詢資料並返回美觀列印的JSON

$ curl -G 'https://<網路地址>:3242/query?db=mydb&pretty=true&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{
    "results": [
        {
            "statement_id": 0,
            "series": [
                {
                    "name": "mymeas",
                    "columns": [
                        "time",
                        "myfield",
                        "mytag1",
                        "mytag2"
                    ],
                    "values": [
                        [
                            "2017-03-01T00:16:18Z",
                            33.1,
                            null,
                            null
                        ],
                        [
                            "2017-03-01T00:17:18Z",
                            12.4,
                            "12",
                            "14"
                        ]
                    ]
                }
            ]
        }
    ]
}

使用SELECT語句查詢資料並返回除納秒外其它精度的epoch時間戳記

$ curl -G 'https://<網路地址>:3242/query?db=mydb&epoch=s&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]}]}

Request body

--data-urlencode "q=<InfluxQL query>"

所有查詢都必須進行URL編碼，並遵循InfluxQL文法。本頁面的所有樣本都使用了curl，在curl命令中使用參數--data-urlencode。

選項（options）

請求多個查詢

用分號（;）將多個查詢隔開。

傳送檔案中的查詢

API支援使用multipart POST請求傳送檔案中的查詢。檔案中的多個查詢必須用分號隔開。

文法：

curl -F "q=@<path_to_file>" -F "async=true" https://<網路地址>:3242/query?u=<帳號名稱>&p=<密碼>

請求返回CSV格式的查詢結果

文法：

curl -H "Accept: application/csv" -G 'https://<網路地址>:3242/query?u=<帳號名稱>&p=<密碼>' [...]

請注意，當請求中包含-H Accept: application/csv，系統將返回epoch格式的時間戳記，而不是RFC3339格式。

綁定參數

API支援將參數綁定到WHERE子句中特定的field value或tag value。使用文法$<placeholder_key>作為查詢中的預留位置（placeholder），並且URL會對request body中的placeholder key和placeholder value的映射（Map）進行編碼：

查詢文法：

--data-urlencode 'q= SELECT [...] WHERE [ <field_key> | <tag_key> ] = $<placeholder_key>'

映射文法：

--data-urlencode 'params={"<placeholder_key>":[ <placeholder_float_field_value> | <placeholder_integer_field_value> | "<placeholder_string_field_value>" | <placeholder_boolean_field_value> | "<placeholder_tag_value>" ]}'

使用逗號（,）將多個placeholder key-value pair隔開。

樣本

請求多個查詢

$ curl -G 'https://<網路地址>:3242/query?db=mydb&epoch=s&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas";SELECT mean("myfield") FROM "mymeas"'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[[1488327378,33.1,null,null],[1488327438,12.4,"12","14"]]}]},{"statement_id":1,"series":[{"name":"mymeas","columns":["time","mean"],"values":[[0,22.75]]}]}]}

該請求包含兩個查詢：SELECT * FROM "mymeas"和SELECT mean("myfield") FROM "mymeas"。從結果中我們可以看到，系統為每個返回的查詢分配一個statement標識符：statement_id。第一個查詢返回的結果對應的statement_id是0，第二個查詢返回的結果對應的statement_id是1。

請求返回CSV格式的查詢結果

$ curl -H "Accept: application/csv" -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

name,tags,time,myfield,mytag1,mytag2
mymeas,,1488327378000000000,33.1,mytag1,mytag2
mymeas,,1488327438000000000,12.4,12,14

第一個資料點的兩個tag key mytag1和mytag2都沒有tag value。

傳送檔案中的查詢語句

$ curl -F "q=@queries.txt" -F "async=true" 'https://<網路地址>:3242/query?u=<帳號名稱>&p=<密碼>'

其中，檔案queries.txt中的查詢如下：

SELECT * FROM "mymeas";
SELECT mean("myfield") FROM "mymeas";

將WHERE子句中的參數綁定到指定的tag value

$ curl -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value' --data-urlencode 'params={"tag_value":"12"}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

該請求將$tag_value映射到12。TSDB For InfluxDB®將tag value儲存為字串，所以必須使用雙引號將請求中的tag value括起來。

將WHERE子句中的參數綁定到數實值型別的field value

$ curl -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "myfield" > $field_value' --data-urlencode 'params={"field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null]]}]}]}

該請求將$field_value映射到30。不需要使用雙引號將30括起來，因為在myfield中儲存的是數實值型別的field value。

將WHERE子句中的兩個參數分別綁定到指定的tag value和數實值型別的field value

$ curl -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas" WHERE "mytag1" = $tag_value AND  "myfield" < $field_value' --data-urlencode 'params={"tag_value":"12","field_value":30}'

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

該請求將$tag_value映射到12，並且將$field_value映射到30。

狀態代碼和響應

響應以JSON格式返回。通過添加參數pretty=true，可開啟JSON的美觀列印（pretty-print）。

總結

HTTP狀態代碼	描述
200 OK	成功！返回的JSON提供更多資訊。
400 Bad Request	無法處理該請求。可能是查詢的文法不正確引起的。返回的JSON提供更多資訊。
401 Unauthorized	無法處理該請求。可能是認證憑證無效引起的。

樣本

成功返回資料的請求

$ curl -i -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:22:54 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"series":[{"name":"mymeas","columns":["time","myfield","mytag1","mytag2"],"values":[["2017-03-01T00:16:18Z",33.1,null,null],["2017-03-01T00:17:18Z",12.4,"12","14"]]}]}]}

成功返回錯誤的請求

$ curl -i -G 'https://<網路地址>:3242/query?db=mydb1&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT * FROM "mymeas"'

HTTP/1.1 200 OK
Connection: close
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:23:48 GMT
Transfer-Encoding: chunked

{"results":[{"statement_id":0,"error":"database not found: mydb1"}]}

格式錯誤的查詢

$ curl -i -G 'https://<網路地址>:3242/query?db=mydb&u=<帳號名稱>&p=<密碼>' --data-urlencode 'q=SELECT *'

HTTP/1.1 400 Bad Request
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:24:25 GMT
Content-Length: 76

{"error":"error parsing query: found EOF, expected FROM at line 1, char 9"}

使用無效的認證憑證查詢資料

$ curl -i  -XPOST 'https://<網路地址>:3242/query?u=myusername&p=notmypassword' --data-urlencode 'q=CREATE DATABASE "mydb"'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 19:11:26 GMT
Content-Length: 33

{"error":"authorization failed"}

/write HTTP路徑

/write路徑接受POST的HTTP請求。使用這個路徑，將資料寫入已經建立好的資料庫。

定義

POST https://<網路地址>:3242/write?u=<帳號名稱>&p=<密碼>

字串類型的查詢參數

字串類型的查詢參數	可選/必需	描述
db=\	必需	設定寫入的目標資料庫。
p=\	如果沒有開啟認證，這是可選的。開啟認證後，這是必需的。	如果開啟了認證，請設定用於認證的密碼。需要與參數`u`同時使用。
precision=[ns,u,ms,s,m,h]	可選	設定所提供的Unix時間的精度。如果您不指定精度，TSDB For InfluxDB®假設時間戳記的精度為納秒。
rp=\	可選	設定寫入的目標保留原則。如果您不指定保留原則，TSDB For InfluxDB®會將資料寫入預設(`DEFAULT`)保留原則。
u=\	如果沒有開啟認證，這是可選的。開啟認證後，這是必需的。	如果開啟了認證，請設定用於認證的使用者名稱。使用者必須具有寫資料庫的許可權。需要與參數`p`同時使用。

** 我們建議盡量使用最低的精度，因為這可以顯著提高壓縮效果。

樣本

將時間戳記精確到秒的資料點寫入資料庫mydb

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&precision=s&u=<帳號名稱>&p=<密碼>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:33:23 GMT

將資料點寫入資料庫mydb和保留原則myrp

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&rp=myrp&u=<帳號名稱>&p=<密碼>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:31 GMT

使用HTTP認證，將資料點寫入資料庫mydb

有效憑證：

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=myusername&p=mypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:34:56 GMT

無效的憑證：

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=myusername&p=notmypassword" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:40:30 GMT
Content-Length: 33

{"error":"authorization failed"}

使用基本（basic）認證，將資料點寫入資料庫mydb

有效憑證：

$ curl -i -XPOST -u myusername:mypassword "https://<網路地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:36:40 GMT

無效的憑證：

$ curl -i -XPOST -u myusername:notmypassword "https://<網路地址>:3242/write?db=mydb" --data-binary 'mymeas,mytag=1 myfield=91'

HTTP/1.1 401 Unauthorized
Content-Type: application/json
Request-Id: [...]
Www-Authenticate: Basic realm="InfluxDB"
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 17:46:40 GMT
Content-Length: 33

{"error":"authorization failed"}

Request body

--data-binary '<Data in Line Protocol format>'

所有資料必須採用二進位編碼並採用行協議格式。本頁面的所有樣本都使用了curl，在curl命令中使用參數--data-binary。使用除--data-binary外的其它編碼方式，可能會導致錯誤；-d、--data-urlencode和--data-ascii可能會將分行符號去掉或者引入新的、非預期的格式。

選項：

通過用分行符號分隔多個資料點，可在一個請求中將這些資料點寫入資料庫。
將檔案中的資料點寫入資料庫，該檔案需帶標記@。檔案中的資料點需要使用行協議格式。每個資料點必須佔據一行，多個資料點用分行符號（\n）隔開。檔案中包含斷行符號鍵會導致解析錯誤。

我們建議分批寫入資料，每批資料5,000或10,000個資料點。如果每一批資料的資料點變少，會產生更多的HTTP請求，導致效能無法達到最優。

樣本

將時間戳記精確到納秒的資料點寫入資料庫mydb

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=<帳號名稱>&p=<密碼>" --data-binary 'mymeas,mytag=1 myfield=90 1463683075000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:02:57 GMT

將使用本機伺服器時間戳記（精確到納秒）的資料點寫入資料庫mydb

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=<帳號名稱>&p=<密碼>" --data-binary 'mymeas,mytag=1 myfield=90'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:03:44 GMT

使用分行符號，將多個資料點寫入資料庫mydb

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=<帳號名稱>&p=<密碼>" --data-binary 'mymeas,mytag=3 myfield=89 1463689152000000000
mymeas,mytag=2 myfield=34 1463689152000000000'

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:04:02 GMT

從檔案data.txt中，將多個資料點寫入資料庫mydb

$ curl -i -XPOST "https://<網路地址>:3242/write?db=mydb&u=<帳號名稱>&p=<密碼>" --data-binary @data.txt

HTTP/1.1 204 No Content
Content-Type: application/json
Request-Id: [...]
X-Influxdb-Version: 1.7.x
Date: Wed, 08 Nov 2017 18:08:11 GMT

其中，檔案data.txt中的樣本資料如下：

mymeas,mytag1=1 value=21 1463689680000000000
mymeas,mytag1=1 value=34 1463689690000000000
mymeas,mytag2=8 value=78 1463689700000000000
mymeas,mytag3=9 value=89 1463689710000000000

狀態代碼和響應

一般來說，2xx形式的狀態代碼表示成功，4xx表示TSDB For InfluxDB®無法理解請求，5xx表示系統過載或嚴重受損。錯誤以JSON格式返回。

總結

HTTP狀態代碼	描述
204 No Content	成功！
400 Bad Request	無法處理該請求。可能寫協議語法錯誤引起的，或者是使用者嘗試將資料寫入之前接受不同資料類型的field引起的。返回的JSON提供更多資訊。
401 Unauthorized	無法處理該請求。可能是認證憑證無效引起的。
404 Not Found	無法處理該請求。可能是使用者嘗試將資料寫入不存在的資料庫引起的。返回的JSON提供更多資訊。
500 Internal Server Error	系統過載或嚴重受損。可能是使用者嘗試將資料寫入不存在的保留原則引起的。返回的JSON提供更多資訊。

樣本

寫入成功

HTTP/1.1 204 No Content

寫入時間戳記不正確的資料點

HTTP/1.1 400 Bad Request
[...]
{"error":"unable to parse 'mymeas,mytag=1 myfield=91 abc123': bad timestamp"}

將整數寫入到之前接受浮點數的field

HTTP/1.1 400 Bad Request
[...]
{"error":"field type conflict: input field \"myfield\" on measurement \"mymeas\" is type int64, already exists as type float"}

使用無效的認證憑證寫入資料

HTTP/1.1 401 Unauthorized
[...]
{"error":"authorization failed"}

將資料點寫入不存在的資料庫

HTTP/1.1 404 Not Found
[...]
{"error":"database not found: \"mydb1\""}

將資料點寫入不存在的保留原則

HTTP/1.1 500 Internal Server Error
[...]
{"error":"retention policy not found: myrp"}

InfluxDB® is a trademark registered by InfluxData, which is not affiliated with, and does not endorse, TSDB for InfluxDB®.