## HTTP API
---
在Prometheus服務上`/api/v1`版本api是穩定版。
### 格式概述
這個API返回是JSON格式。每個請求成功的返回值都是以`2xx`開頭的編碼。
到達API處理的無效請求,返回一個JSON錯誤對象,并返回下面的錯誤碼:
- `400 Bad Request`。當參數錯誤或者丟失時。
- `422 Unprocessable Entity`。當一個表達式不能被執行時。
- `503 Service Unavailable`。當查詢超時或者中斷時。
在請求到達API之前,其他非`2xx`的錯誤碼可能會被返回。
JSON返回格式如下所示:
```JSON
{
"status": "success" | "error",
"data": <data>,
// 如果status是"error", 這個數據字段還會包括下面的數據
"errorType": "<string>",
"error": "<string>"
}
```
輸入時間戳可以被[RFC3339](https://www.ietf.org/rfc/rfc3339.txt)格式或者Unix時間戳提供。輸出時間戳以Unix時間戳的方式呈現。
查詢參數名稱可以用`[]`中括號重復次數。
`<series_selector>`占位符提供像`http_requests_total`或者`http_requests_total{method=~"^GET|POST$"}`的Prometheus時間序列選擇器,并需要在URL中編碼傳輸。
`<duration>`占位符涉及到`[0-9]-[smhdwy]`。例如:`5m`表示5分鐘的持續時間。
### 表達式查詢
查詢語言表達式可以在瞬時向量或者范圍向量中執行。
#### Instant queries(即時查詢)
瞬時向量的http restful api查詢:
> GET /api/v1/query
URL查詢參數:
- `query=<string>`: Prometheus表達式查詢字符串。
- `time=<rfc3339 | uninx_timestamp>`: 執行時間戳,可選項。
- `timeout=<duration>`: 執行超時時間設置,默認由`-query.timeout`標志設置
如果`time`缺省,則用當前服務器時間表示執行時刻。
這個查詢結果的`data`部分有下面格式:
```JSON
{
"resultType": "matrix" | "vector" | "scalar" | "string",
"result": <value>
}
```
<value>是一個查詢結果數據,依賴于這個`resultType`格式, 不同的結果類型,則會有不同的結果數據格式。見[表達式查詢結果格式](https://prometheus.io/docs/querying/api/#expression-query-result-formats)。
下面例子執行了在時刻是`2015-07-01T20:10:51.781Z`的`up`表達式:
```JSON
$ curl 'http://localhost:9090/api/v1/query?query=up&time=2015-07-01T20:10:51.781Z'
{
"status": "success",
"data":{
"resultType": "vector",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"value": [ 1435781451.781, "1" ]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9100"
},
"value" : [ 1435781451.781, "0" ]
}
]
}
}
```
#### 范圍查詢
下面評估了一個范圍時間的查詢表達式:
> GET /api/v1/query_range
URL查詢參數
- `query=<string>`: Prometheus表達式查詢字符串。
- `start=<rfc3339 | unix_timestamp>`: 開始時間戳。
- `end=<rfc3339 | unix_timestamp>`: 結束時間戳。
- `step=<duration>`: 查詢時間步長,范圍時間內每step秒執行一次。
下面查詢結果格式的`data`部分:
```json
{
"resultType": "matrix",
"result": <value>
}
```
對于`<value>`占位符的格式,詳見[范圍向量結果格式](https://prometheus.io/docs/querying/api/#range-vectors)。
下面例子評估的查詢條件`up`,且30s范圍的查詢,步長是15s。
```JSON
$ curl 'http://localhost:9090/api/v1/query_range?query=up&start=2015-07-01T20:10:30.781Z&end=2015-07-01T20:11:00.781Z&step=15s'
{
"status" : "success",
"data" : {
"resultType" : "matrix",
"result" : [
{
"metric" : {
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
"values" : [
[ 1435781430.781, "1" ],
[ 1435781445.781, "1" ],
[ 1435781460.781, "1" ]
]
},
{
"metric" : {
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
"values" : [
[ 1435781430.781, "0" ],
[ 1435781445.781, "0" ],
[ 1435781460.781, "1" ]
]
}
]
}
}
```
### 查詢元數據
#### 通過標簽匹配器找到度量指標列表
下面例子返回了度量指標列表 且不返回時間序列數據值。
> GET /api/v1/series
URL查詢參數:
- `match[]=<series_selector>`: 選擇器是series_selector。這個參數個數必須大于等于1.
- `start=<rfc3339 | unix_timestamp>`: 開始時間戳。
- `end=<rfc3339 | unix_timestamp>`: 結束時間戳。
返回結果的`data`部分,是由key-value鍵值對的對象列表組成的。
下面這個例子返回時間序列數據, 選擇器是`up`或者`process_start_time_seconds{job="prometheus"}`
```JSON
$ curl -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
{
"status" : "success",
"data" : [
{
"__name__" : "up",
"job" : "prometheus",
"instance" : "localhost:9090"
},
{
"__name__" : "up",
"job" : "node",
"instance" : "localhost:9091"
},
{
"__name__" : "process_start_time_seconds",
"job" : "prometheus",
"instance" : "localhost:9090"
}
]
}
```
#### 查詢標簽值
下面這個例子,返回了帶有指定標簽的標簽值列表
> GET /api/v1/label/<label_name>/values
這個返回JSON結果的`data`部分是帶有label_name=job的值列表:
```JSON
$ curl http://localhost:9090/api/v1/label/job/values
{
"status" : "success",
"data" : [
"node",
"prometheus"
]
}
```
### 刪除時間序列
下面的例子,是從Prometheus服務中刪除匹配的度量指標和標簽列表:
> DELETE /api/v1/series
URL查詢參數
- `match[]=<series_selector>`: 刪除符合series_selector匹配器的時間序列數據。參數個數必須大于等于1.
返回JSON數據中的`data`部分有以下的格式
```
{
"numDeleted": <number of deleted series>
}
```
下面的例子刪除符合度量指標名稱是`up`或者時間序列為`process_start_time_seconds{job="prometheus"}`:
```JSON
$ curl -XDELETE -g 'http://localhost:9090/api/v1/series?match[]=up&match[]=process_start_time_seconds{job="prometheus"}'
{
"status" : "success",
"data" : {
"numDeleted" : 3
}
}
```
### 表達式查詢結果格式
表達式查詢結果,在`data`部分的`result`部分中,返回下面的數據。`\<sample_value\>`占位符有數值樣本值。JSON不支持特殊浮點值,例如:`NaN`, `Inf`和`-Inf`。因此樣本值返回結果是字符串,不是原生的數值。
#### 范圍向量
范圍向量返回的result類型是一個`matrix`矩陣。下面返回的結果是`result`部分的數據格式:
```JSON
[
{
"metric": { "<label_name>": "<label_value>", ... },
"values": [ [ <unix_time>, "<sample_value>" ], ... ]
},
...
]
```
#### 瞬時向量
瞬時向量的`result`類型是`vector`。下面是`result`部分的數據格式
```JSON
[
{
"metric": { "<label_name>": "<label_value>", ... },
"value": [ <unix_time>, "<sample_value>" ]
},
...
]
```
#### Scalars標量
標量查詢返回`result`類型是`scalar`。下面是`result`部分的數據格式:
> [ <unix_time>, "<scalar_value>" ]
#### 字符串
字符串的`result`類型是`string`。下面是`result`部分的數據格式:
> [ <unix_time>, "<string_value>" ]
### Targets目標
這個API是實驗性的,暫不翻譯。
### Alertmanagers
這個API也是實驗性的,暫不翻譯