mirror of
https://github.com/grafana/grafana.git
synced 2025-02-25 18:55:37 -06:00
Docs: Create documentation for enterprise caching HTTP API (#67169)
* create http docs for query caching * fix endpoints * Update docs/sources/developers/http_api/query_and_resource_caching.md Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com> * run prettier * super small change to reflect incoming API update --------- Co-authored-by: Eve Meelan <81647476+Eve832@users.noreply.github.com>
This commit is contained in:
Michael Mandrus
GitHub
parent
893bf08dcf
commit
e9971dd153
@ -65,3 +65,4 @@ Grafana Enterprise includes all of the Grafana OSS APIs as well as those that fo
|
|||||||
- [External group sync API]({{< relref "external_group_sync/" >}})
|
- [External group sync API]({{< relref "external_group_sync/" >}})
|
||||||
- [License API]({{< relref "licensing/" >}})
|
- [License API]({{< relref "licensing/" >}})
|
||||||
- [Reporting API]({{< relref "reporting/" >}})
|
- [Reporting API]({{< relref "reporting/" >}})
|
||||||
|
- [Query and resource caching API]({{< relref "query_and_resource_caching/" >}})
|
||||||
|
|||||||
295
docs/sources/developers/http_api/query_and_resource_caching.md
Normal file
295
docs/sources/developers/http_api/query_and_resource_caching.md
Normal file
@ -0,0 +1,295 @@
|
|||||||
|
---
|
||||||
|
aliases:
|
||||||
|
- ../../http_api/query_caching/
|
||||||
|
- ../../http_api/resource_caching/
|
||||||
|
- ../../http_api/caching/
|
||||||
|
canonical: /docs/grafana/latest/developers/http_api/query_and_resource_caching/
|
||||||
|
description: Grafana Enterprise Query and Resource Caching HTTP API
|
||||||
|
keywords:
|
||||||
|
- grafana
|
||||||
|
- http
|
||||||
|
- documentation
|
||||||
|
- api
|
||||||
|
- caching
|
||||||
|
- query caching
|
||||||
|
- resource caching
|
||||||
|
- data source
|
||||||
|
title: Query and Resource Caching HTTP API
|
||||||
|
---
|
||||||
|
|
||||||
|
# Query and resource caching API
|
||||||
|
|
||||||
|
> **Note:** If you are running Grafana Enterprise, for some endpoints you'll need to have specific permissions. Refer to [Role-based access control permissions]({{< relref "/docs/grafana/latest/administration/roles-and-permissions/access-control/custom-role-actions-scopes" >}}) for more information.
|
||||||
|
|
||||||
|
## Enable caching for a data source
|
||||||
|
|
||||||
|
`POST /api/datasources/:dataSourceUID/cache/enable`
|
||||||
|
|
||||||
|
**Required permissions**
|
||||||
|
|
||||||
|
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
|
||||||
|
|
||||||
|
| Action | Scope |
|
||||||
|
| ------------------------- | -------------- |
|
||||||
|
| datasources.caching:write | datasources:\* |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Example Request**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /api/datasources/jZrmlLCGka/cache/enable HTTP/1.1
|
||||||
|
Accept: application/json
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example Response**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
HTTP/1.1 200
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"message": "Data source cache enabled",
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": true,
|
||||||
|
"ttlQueriesMs": 300000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
"useDefaultTTL": true,
|
||||||
|
"defaultTTLMs": 300000,
|
||||||
|
"created": "2023-04-21T11:49:22-04:00",
|
||||||
|
"updated": "2023-04-24T16:30:29-04:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Status codes
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
| ---- | ------------------------------------------------------------------------ |
|
||||||
|
| 200 | Cache was successfully enabled for the data source |
|
||||||
|
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||||
|
|
||||||
|
## Disable caching for a data source
|
||||||
|
|
||||||
|
`POST /api/datasources/:dataSourceUID/cache/disable`
|
||||||
|
|
||||||
|
**Required permissions**
|
||||||
|
|
||||||
|
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
|
||||||
|
|
||||||
|
| Action | Scope |
|
||||||
|
| ------------------------- | -------------- |
|
||||||
|
| datasources.caching:write | datasources:\* |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Example Request**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /api/datasources/jZrmlLCGka/cache/disable HTTP/1.1
|
||||||
|
Accept: application/json
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example Response**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
HTTP/1.1 200
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"message": "Data source cache disabled",
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": false,
|
||||||
|
"ttlQueriesMs": 300000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
"useDefaultTTL": true,
|
||||||
|
"defaultTTLMs": 0,
|
||||||
|
"created": "2023-04-21T11:49:22-04:00",
|
||||||
|
"updated": "2023-04-24T16:30:31-04:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Status codes
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
| ---- | ------------------------------------------------------------------------ |
|
||||||
|
| 200 | Cache was successfully enabled for the data source |
|
||||||
|
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||||
|
|
||||||
|
## Clean cache for all data sources
|
||||||
|
|
||||||
|
`POST /api/datasources/:dataSourceUID/cache/clean`
|
||||||
|
|
||||||
|
Will clean cached data for _all_ data sources with caching enabled. The `dataSourceUID` specified will only be used to return the configuration for that data source.
|
||||||
|
|
||||||
|
**Required permissions**
|
||||||
|
|
||||||
|
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
|
||||||
|
|
||||||
|
| Action | Scope |
|
||||||
|
| ------------------------- | -------------- |
|
||||||
|
| datasources.caching:write | datasources:\* |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Example Request**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /api/datasources/jZrmlLCGka/cache/clean HTTP/1.1
|
||||||
|
Accept: application/json
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example Response**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
HTTP/1.1 200
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"message": "Data source cache cleaned",
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": false,
|
||||||
|
"ttlQueriesMs": 300000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
"useDefaultTTL": true,
|
||||||
|
"defaultTTLMs": 0,
|
||||||
|
"created": "2023-04-21T11:49:22-04:00",
|
||||||
|
"updated": "2023-04-24T16:30:31-04:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Status codes
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
| ---- | ------------------------------------------------------------------------ |
|
||||||
|
| 200 | Cache was successfully enabled for the data source |
|
||||||
|
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||||
|
|
||||||
|
## Update cache configuration for a data source
|
||||||
|
|
||||||
|
`POST /api/datasources/:dataSourceUID/cache`
|
||||||
|
|
||||||
|
**Required permissions**
|
||||||
|
|
||||||
|
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
|
||||||
|
|
||||||
|
| Action | Scope |
|
||||||
|
| ------------------------- | -------------- |
|
||||||
|
| datasources.caching:write | datasources:\* |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Example Request**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
POST /api/datasources/jZrmlLCGka/cache HTTP/1.1
|
||||||
|
Accept: application/json
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||||
|
|
||||||
|
{
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": true,
|
||||||
|
"useDefaultTTL": false,
|
||||||
|
"ttlQueriesMs": 60000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### JSON Body Schema
|
||||||
|
|
||||||
|
| Field name | Data type | Description |
|
||||||
|
| -------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||||
|
| dataSourceID | number | The ID of the data source to configure. |
|
||||||
|
| dataSourceUID | string | The UID of the data source to configure. |
|
||||||
|
| enabled | boolean | Whether or not to enable caching for this data source. |
|
||||||
|
| useDefaultTTL | boolean | Whether the configured default TTL (Time-To-Live) should be used for both query and resource caching, instead of the user-specified values. |
|
||||||
|
| ttlQueriesMs | number | The TTL to use for query caching, in milliseconds. |
|
||||||
|
| ttlResourcesMs | number | The TTL to use for resource caching, in milliseconds. |
|
||||||
|
|
||||||
|
**Example Response**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
HTTP/1.1 200
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"message": "Data source cache settings updated",
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": true,
|
||||||
|
"useDefaultTTL": false,
|
||||||
|
"ttlQueriesMs": 60000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
"defaultTTLMs": 300000,
|
||||||
|
"created": "2023-04-21T11:49:22-04:00",
|
||||||
|
"updated": "2023-04-24T17:03:40-04:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Status codes
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
| ---- | ------------------------------------------------------------------------ |
|
||||||
|
| 200 | Cache was successfully enabled for the data source |
|
||||||
|
| 400 | Request errors (invalid json, missing or invalid fields, etc) |
|
||||||
|
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||||
|
|
||||||
|
## Get cache configuration for a data source
|
||||||
|
|
||||||
|
`GET /api/datasources/:dataSourceUID/cache`
|
||||||
|
|
||||||
|
**Required permissions**
|
||||||
|
|
||||||
|
See note in the [introduction]({{< ref "#query-and-resource-caching-api" >}}) for an explanation.
|
||||||
|
|
||||||
|
| Action | Scope |
|
||||||
|
| ------------------------ | -------------- |
|
||||||
|
| datasources.caching:read | datasources:\* |
|
||||||
|
|
||||||
|
### Examples
|
||||||
|
|
||||||
|
**Example Request**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
GET /api/datasources/jZrmlLCGka/cache HTTP/1.1
|
||||||
|
Accept: application/json
|
||||||
|
Content-Type: application/json
|
||||||
|
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
|
||||||
|
```
|
||||||
|
|
||||||
|
**Example Response**:
|
||||||
|
|
||||||
|
```http
|
||||||
|
HTTP/1.1 200
|
||||||
|
Content-Type: application/json
|
||||||
|
|
||||||
|
{
|
||||||
|
"message": "Data source cache settings loaded",
|
||||||
|
"dataSourceID": 1,
|
||||||
|
"dataSourceUID": "jZrmlLCGka",
|
||||||
|
"enabled": true,
|
||||||
|
"useDefaultTTL": false,
|
||||||
|
"ttlQueriesMs": 60000,
|
||||||
|
"ttlResourcesMs": 300000,
|
||||||
|
"defaultTTLMs": 300000,
|
||||||
|
"created": "2023-04-21T11:49:22-04:00",
|
||||||
|
"updated": "2023-04-24T17:03:40-04:00"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### Status codes
|
||||||
|
|
||||||
|
| Code | Description |
|
||||||
|
| ---- | ------------------------------------------------------------------------ |
|
||||||
|
| 200 | Cache was successfully enabled for the data source |
|
||||||
|
| 500 | Unexpected error. Refer to the body and/or server logs for more details. |
|
||||||
Loading…
Reference in New Issue
Block a user