apitech
/
grafana
mirror of https://github.com/grafana/grafana
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Plugins: Add deprecation notice for /api/tsdb/query endpoint (#45238)

Browse Source 
* add deprecation notice for /api/tsdb/query

* fix linking

* regenerate after gen-go

* add newline

* add API docs for ds/query

* regenerate spec

* pr feedback

* add helpful tip

* make sub heading

* add more data

* update spec

* update wording

* mention both from/to

* add suggestions

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>

* docs feedback

Co-authored-by: Marcus Efraimsson <marcus.efraimsson@gmail.com>
pull/47071/head
Will Browne 4 years ago committed by GitHub
parent 8e52dbb87b
commit 572ca553b6
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 120 additions and 16 deletions
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Show Stats Download Patch File Download Diff File
  1. 114
      docs/sources/http_api/data_source.md
  2. 1
      pkg/api/api.go
  3. 4
      pkg/api/docs/definitions/datasources.go
  4. 2
      pkg/api/dtos/models.go
  5. 1
      pkg/api/metrics.go
  6. 7
      public/api-merged.json
  7. 7
      public/api-spec.json

114
docs/sources/http_api/data_source.md
Unescape View File

@ -604,13 +604,106 @@ Content-Type: application/json
Proxies all calls to the actual data source.
## Query a data source by ID
## Query a data source
Queries a data source having backend implementation.
Queries a data source having a backend implementation.
`POST /api/ds/query`
> **Note:** Grafana's built-in data sources usually have a backend implementation.
**Example request for the Test data source**:
```http
POST /api/ds/query HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"queries":[
{
"refId":"A",
"scenarioId":"csv_metric_values",
"datasource":{
"uid":"PD8C576611E62080A"
},
"format": "table"
"maxDataPoints":1848,
"intervalMs":200,
"stringInput":"1,20,90,30,5,0",
}
],
"from":"now-5m",
"to":"now"
}
```
JSON Body schema:
- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`.
- **queries** – Specifies one or more queries. Must contain at least 1.
- **queries.datasource.uid** – Specifies the UID of data source to be queried. Each query in the request must have a unique `datasource`.
- **queries.refId** – Specifies an identifier of the query. Defaults to "A".
- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source.
- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100.
- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000.
In addition, specific properties of each data source should be added in a request (for example **queries.stringInput** as shown in the request above). To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/ds/query`.
**Example Test data source time series query response:**
```json
{
"results": {
"A": {
"frames": [
{
"schema": {
"refId": "A",
"fields": [
{
"name": "time",
"type": "time",
"typeInfo": {
"frame": "time.Time"
}
},
{
"name": "A-series",
"type": "number",
"typeInfo": {
"frame": "int64",
"nullable": true
}
}
]
},
"data": {
"values": [
[1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
[1, 20, 90, 30, 5, 0]
]
}
}
]
}
}
}
```
## Deprecated resources
The following resources have been deprecated. They will be removed in a future release.
### Query a data source by ID
> **Warning:** This API is deprecated since Grafana v8.5.0 and will be removed in a future release. Refer to the [new data source query API](#query-a-data-source-by-id).
Queries a data source having a backend implementation.
`POST /api/tsdb/query`
> **Note:** Most of Grafana's builtin data sources have backend implementation.
> **Note:** Grafana's built-in data sources usually have a backend implementation.
**Example Request**:
@ -635,17 +728,16 @@ Content-Type: application/json
}
```
> **Note:** The `from`, `to`, and `queries` properties are required.
JSON Body schema:
- **from/to** – Should be either absolute in epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-1h`.
- **queries.refId** – Specifies an identifier of the query. Is optional and default to "A".
- **queries.datasourceId** – Specifies the data source to be queried. Each `query` in the request must have an unique `datasourceId`.
- **queries.maxDataPoints** - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
- **queries.intervalMs** - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.
- **from/to** – Specifies the time range for the queries. The time can be either epoch timestamps in milliseconds or relative using Grafana time units. For example, `now-5m`.
- **queries.refId** – Specifies an identifier of the query. Defaults to "A".
- **queries.format** – Specifies the format the data should be returned in. Valid options are `time_series` or `table` depending on the data source.
- **queries.datasourceId** – Specifies the data source to be queried. Each `query` in the request must have a unique `datasourceId`.
- **queries.maxDataPoints** - Species the maximum amount of data points that a dashboard panel can render. Defaults to 100.
- **queries.intervalMs** - Specifies the time series time interval in milliseconds. Defaults to 1000.
In addition, each data source has its own specific properties that should be added in a request.
In addition, specific properties of each data source should be added in a request. To better understand how to form a query for a certain data source, use the Developer Tools in your browser of choice and inspect the HTTP requests being made to `/api/tsdb/query`.
**Example request for the MySQL data source:**

1
pkg/api/api.go
Unescape View File

@ -401,6 +401,7 @@ func (hs *HTTPServer) registerRoutes() {
apiRoute.Get("/search/", routing.Wrap(hs.Search))
// metrics
// Deprecated: use /ds/query API instead.
apiRoute.Post("/tsdb/query", authorize(reqSignedIn, ac.EvalPermission(datasources.ActionQuery)), routing.Wrap(hs.QueryMetrics))
// DataSource w/ expressions

4
pkg/api/docs/definitions/datasources.go
Unescape View File

@ -200,6 +200,8 @@ import (
//
// Query metrics.
//
// Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead
//
// Queries a data source having backend implementation.
//
// Most of Grafana’s builtin data sources have backend implementation.
@ -207,6 +209,8 @@ import (
// If you are running Grafana Enterprise and have Fine-grained access control enabled
// you need to have a permission with action: `datasources:query`.
//
// Deprecated: true
//
// Responses:
// 200: queryDatasourceResponse
// 401: unauthorisedError

2
pkg/api/dtos/models.go
Unescape View File

@ -63,7 +63,7 @@ type MetricRequest struct {
// queries.maxDataPoints - Species maximum amount of data points that dashboard panel can render. Is optional and default to 100.
// queries.intervalMs - Specifies the time interval in milliseconds of time series. Is optional and defaults to 1000.
// required: true
// example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasourceId": 86, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ]
// example: [ { "refId": "A", "intervalMs": 86400000, "maxDataPoints": 1092, "datasource":{ "uid":"PD8C576611E62080A" }, "rawSql": "SELECT 1 as valueOne, 2 as valueTwo", "format": "table" } ]
Queries []*simplejson.Json `json:"queries"`
// required: false
Debug bool `json:"debug"`

1
pkg/api/metrics.go
Unescape View File

@ -145,6 +145,7 @@ func (hs *HTTPServer) QueryMetricsFromDashboard(c *models.ReqContext) response.R
// POST /api/tsdb/query
//nolint: staticcheck // legacydata.DataResponse deprecated
//nolint: staticcheck // legacydata.DataQueryResult deprecated
// Deprecated: use QueryMetricsV2 instead.
func (hs *HTTPServer) QueryMetrics(c *models.ReqContext) response.Response {
reqDto := dtos.MetricRequest{}
if err := web.Bind(c.Req, &reqDto); err != nil {

7
public/api-merged.json
Unescape View File

@ -8299,10 +8299,11 @@
},
"/tsdb/query": {
"post": {
"description": "Queries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.",
"description": "Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead\n\nQueries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.",
"tags": ["datasources"],
"summary": "Query metrics.",
"operationId": "queryDatasource",
"deprecated": true,
"parameters": [
{
"name": "Body",
@ -13100,7 +13101,9 @@
"x-go-name": "Queries",
"example": [
{
"datasourceId": 86,
"datasource": {
"uid": "PD8C576611E62080A"
},
"format": "table",
"intervalMs": 86400000,
"maxDataPoints": 1092,

7
public/api-spec.json
Unescape View File

@ -6868,10 +6868,11 @@
},
"/tsdb/query": {
"post": {
"description": "Queries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.",
"description": "Please refer to [updated API](#/ds/queryMetricsWithExpressions) instead\n\nQueries a data source having backend implementation.\n\nMost of Grafana’s builtin data sources have backend implementation.\n\nIf you are running Grafana Enterprise and have Fine-grained access control enabled\nyou need to have a permission with action: `datasources:query`.",
"tags": ["datasources"],
"summary": "Query metrics.",
"operationId": "queryDatasource",
"deprecated": true,
"parameters": [
{
"name": "Body",
@ -10425,7 +10426,9 @@
"x-go-name": "Queries",
"example": [
{
"datasourceId": 86,
"datasource": {
"uid": "PD8C576611E62080A"
},
"format": "table",
"intervalMs": 86400000,
"maxDataPoints": 1092,

Write Preview
Loading…
Cancel
Save