opensource/grafana
1
0
Fork 0
mirror of https://github.com/grafana/grafana.git synced 2025-08-03 01:22:29 +08:00
Code Issues Packages Projects Releases Wiki Activity

Alerting: Notification channel http api enhancements (#16219)

Browse Source 
Now returns uid in response to get notification channel by id.
Adds GET/PUT/DELETE support for notification channel by uid, 
  /api/alert-notifications/uid/:uid.
Break apart alerting and alert notification http api docs in two 
  pages and update documentation to make it up to date
  with current implementation.

Fixes #16012
This commit is contained in:
Marcus Efraimsson
2019-03-26 18:37:02 +07:00
committed by GitHub
parent 9f58b85693
commit 2ae63e70c0
8 changed files with 443 additions and 202 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/sources/http_api/admin.md
View File

@ -319,7 +319,7 @@ Only works with Basic Authentication (username and password). See [introduction]
**Example Request**:
```json
```http
POST /api/admin/pause-all-alerts HTTP/1.1
Accept: application/json
Content-Type: application/json
@ -335,11 +335,15 @@ JSON Body schema:
```http
HTTP/1.1 200
Content-Type: application/json
```json
```
## Auth tokens for User
{"state": "new state", "message": "alerts pause/un paused", "alertsAffected": 100}
`GET /api/admin/users/:id/auth-tokens`
Return a list of all auth tokens (devices) that the user currently have logged in from.
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
**Example Request**:

196
docs/sources/http_api/alerting.md
View File

@ -1,7 +1,7 @@
+++
title = "Alerting HTTP API "
description = "Grafana Alerting HTTP API"
keywords = ["grafana", "http", "documentation", "api", "alerting"]
description = "Grafana Alerts HTTP API"
keywords = ["grafana", "http", "documentation", "api", "alerting", "alerts"]
aliases = ["/http_api/alerting/"]
type = "docs"
[menu.docs]
@ -9,14 +9,11 @@ name = "Alerting"
parent = "http_api"
+++
# Alerting API
You can use the Alerting API to get information about alerts and their states but this API cannot be used to modify the alert.
To create new alerts or modify them you need to update the dashboard json that contains the alerts.
This API can also be used to create, update and delete alert notifications.
## Get alerts
`GET /api/alerts/`
@ -69,7 +66,7 @@ Content-Type: application/json
**Example Response**:
```http
HTTP/1.1 200
HTTP/1.1 200
Content-Type: application/json
```
@ -120,7 +117,7 @@ Content-Type: application/json
If data from one server triggers the alert first and, before that server is seen leaving alerting state,
a second server also enters a state that would trigger the alert, the second server will not be visible in "evalMatches" data.
Content-Type: application/json
## Pause alert by id
`POST /api/alerts/:id/pause`
@ -158,187 +155,4 @@ Content-Type: application/json
## Pause all alerts
## Create alert notification
You can find the full list of [supported notifiers](/alerting/notifications/#all-supported-notifier) at the alert notifiers page.
`POST /api/alert-notifications`
**Example Request**:
```http
POST /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Update alert notification
`PUT /api/alert-notifications/:id`
**Example Request**:
```http
PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Delete alert notification
`DELETE /api/alert-notifications/:id`
**Example Request**:
```http
DELETE /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
]
```
## Create alert notification
You can find the full list of [supported notifiers](/alerting/notifications/#all-supported-notifier) at the alert notifiers page.
`POST /api/alert-notifications`
**Example Request**:
```http
POST /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"name": "new alert notification", //Required
"type": "email", //Required
"isDefault": false,
"sendReminder": false,
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
}
}
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"name": "new alert notification",
"type": "email",
"isDefault": false,
"sendReminder": false,
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
},
"created": "2018-04-23T14:44:09+02:00",
"updated": "2018-08-20T15:47:49+02:00"
}
```
## Update alert notification
`PUT /api/alert-notifications/:id`
**Example Request**:
```http
PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"id": 1,
"name": "new alert notification", //Required
"type": "email", //Required
"isDefault": false,
"sendReminder": true,
"frequency": "15m",
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
}
}
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"name": "new alert notification",
"type": "email",
"isDefault": false,
"sendReminder": true,
"frequency": "15m",
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
},
"created": "2017-01-01 12:34",
"updated": "2017-01-01 12:34"
}
```
## Delete alert notification
`DELETE /api/alert-notifications/:id`
**Example Request**:
```http
DELETE /api/alert-notifications/1 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": "Notification deleted"
}
```
See [Admin API]({{< relref "http_api/admin.md#pause-all-alerts" >}}).

369
docs/sources/http_api/alerting_notification_channels.md Normal file
View File

@ -0,0 +1,369 @@
+++
title = "Alerting Notification Channels HTTP API "
description = "Grafana Alerting Notification Channel HTTP API"
keywords = ["grafana", "http", "documentation", "api", "alerting", "alerts", "notifications"]
aliases = []
type = "docs"
[menu.docs]
name = "Alerting Notification Channels"
parent = "http_api"
+++
# Alerting Notification Channels API
## Identifier (id) vs unique identifier (uid)
The identifier (id) of a notification channel is an auto-incrementing numeric value and is only unique per Grafana install.
The unique identifier (uid) of a notification channel can be used for uniquely identify a notification channel between
multiple Grafana installs. It's automatically generated if not provided when creating a notification channel. The uid
allows having consistent URL's for accessing notification channels and when syncing notification channels between multiple
Grafana installs, see [alert notification channel provisioning](/administration/provisioning/#alert-notification-channels)
for more information.
The uid can have a maximum length of 40 characters.
## Get all notification channels
Returns all notification channels that the authenticated user has permission to view.
`GET /api/alert-notifications`
**Example Request**:
```http
GET /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Get notification channel by uid
`GET /api/alert-notifications/uid/:uid`
Will return the notification channel given the notification channel uid.
**Example Request**:
```http
GET /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Get notification channel by id
`GET /api/alert-notifications/:id`
Will return the notification channel given the notification channel id.
**Example Request**:
```http
GET /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Create notification channel
You can find the full list of [supported notifiers](/alerting/notifications/#all-supported-notifier) at the alert notifiers page.
`POST /api/alert-notifications`
**Example Request**:
```http
POST /api/alert-notifications HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Update notification channel by uid
`PUT /api/alert-notifications/uid/:uid`
Updates an existing notification channel identified by uid.
**Example Request**:
```http
PUT /api/alert-notifications/uid/cIBgcSjkk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Update notification channel by id
`PUT /api/alert-notifications/:id`
Updates an existing notification channel identified by id.
**Example Request**:
```http
PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Delete alert notification by uid
`DELETE /api/alert-notifications/uid/:uid`
Deletes an existing notification channel identified by uid.
**Example Request**:
```http
DELETE /api/alert-notifications/uid/team-a-email-notifier HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Delete alert notification by id
`DELETE /api/alert-notifications/:id`
Deletes an existing notification channel identified by id.
**Example Request**:
```http
DELETE /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
## Test notification channel
Sends a test notification message for the given notification channel type and settings.
You can find the full list of [supported notifiers](/alerting/notifications/#all-supported-notifier) at the alert notifiers page.
`POST /api/alert-notifications/test`
**Example Request**:
```http
POST /api/alert-notifications/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
```
Updates an existing notification channel identified by id.
**Example Request**:
```http
PUT /api/alert-notifications/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"id": 1,
"uid": "cIBgcSjkk",
"name": "new alert notification", //Required
"type": "email", //Required
"isDefault": false,
"sendReminder": true,
"frequency": "15m",
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
}
}
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"id": 1,
"uid": "cIBgcSjkk",
"name": "new alert notification",
"type": "email",
"isDefault": false,
"sendReminder": true,
"frequency": "15m",
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
},
"created": "2017-01-01 12:34",
"updated": "2017-01-01 12:34"
}
```
## Delete alert notification by uid
`DELETE /api/alert-notifications/uid/:uid`
Deletes an existing notification channel identified by uid.
**Example Request**:
```http
DELETE /api/alert-notifications/uid/team-a-email-notifier 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": "Notification deleted"
}
```
## Delete alert notification by id
`DELETE /api/alert-notifications/:id`
Deletes an existing notification channel identified by id.
**Example Request**:
```http
DELETE /api/alert-notifications/1 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": "Notification deleted"
}
```
## Test notification channel
Sends a test notification message for the given notification channel type and settings.
You can find the full list of [supported notifiers](/alerting/notifications/#all-supported-notifier) at the alert notifiers page.
`POST /api/alert-notifications/test`
**Example Request**:
```http
POST /api/alert-notifications/test HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk
{
"type": "email",
"settings": {
"addresses": "carl@grafana.com;dev@grafana.com"
}
}
```
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"message": "Test notification sent"
}
```

1
docs/sources/http_api/index.md
View File

@ -30,6 +30,7 @@ dashboards, creating users and updating data sources.
* [Snapshot API]({{< relref "http_api/snapshot.md" >}})
* [Annotations API]({{< relref "http_api/annotations.md" >}})
* [Alerting API]({{< relref "http_api/alerting.md" >}})
* [Alert Notification Channels API]({{< relref "http_api/alert_notification_channels.md" >}})
* [User API]({{< relref "http_api/user.md" >}})
* [Team API]({{< relref "http_api/team.md" >}})
* [Admin API]({{< relref "http_api/admin.md" >}})