Skip to content

N
nexpie-grafana-theme
Commit 2ae63e70 by Marcus Efraimsson Committed by GitHub
Options

Alerting: Notification channel http api enhancements (#16219) 

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
parent 9f58b856
Showing with 443 additions and 202 deletions
docs/sources/http_api/admin.md
...@@ -319,7 +319,7 @@ Only works with Basic Authentication (username and password). See [introduction] ...@@ -319,7 +319,7 @@ Only works with Basic Authentication (username and password). See [introduction]
**Example Request**: **Example Request**:
```json ```http
POST /api/admin/pause-all-alerts HTTP/1.1 POST /api/admin/pause-all-alerts HTTP/1.1
Accept: application/json Accept: application/json
Content-Type: application/json Content-Type: application/json
...@@ -335,11 +335,15 @@ JSON Body schema: ...@@ -335,11 +335,15 @@ JSON Body schema:
**Example Response**: **Example Response**:
```json ```http
HTTP/1.1 200 HTTP/1.1 200
Content-Type: application/json Content-Type: application/json
{"state": "new state", "message": "alerts pause/un paused", "alertsAffected": 100} {
"state": "Paused",
"message": "alert paused",
"alertsAffected": 1
}
``` ```
## Auth tokens for User ## Auth tokens for User
......
docs/sources/http_api/alerting.md
+++ +++
title = "Alerting HTTP API " title = "Alerting HTTP API "
description = "Grafana Alerting HTTP API" description = "Grafana Alerts HTTP API"
keywords = ["grafana", "http", "documentation", "api", "alerting"] keywords = ["grafana", "http", "documentation", "api", "alerting", "alerts"]
aliases = ["/http_api/alerting/"] aliases = ["/http_api/alerting/"]
type = "docs" type = "docs"
[menu.docs] [menu.docs]
...@@ -9,14 +9,11 @@ name = "Alerting" ...@@ -9,14 +9,11 @@ name = "Alerting"
parent = "http_api" parent = "http_api"
+++ +++
# Alerting 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. 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. 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 alerts
`GET /api/alerts/` `GET /api/alerts/`
...@@ -69,7 +66,7 @@ Content-Type: application/json ...@@ -69,7 +66,7 @@ Content-Type: application/json
] ]
``` ```
## Get one alert ## Get alert by id
`GET /api/alerts/:id` `GET /api/alerts/:id`
...@@ -120,7 +117,7 @@ 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, 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. a second server also enters a state that would trigger the alert, the second server will not be visible in "evalMatches" data.
## Pause alert ## Pause alert by id
`POST /api/alerts/:id/pause` `POST /api/alerts/:id/pause`
...@@ -158,187 +155,4 @@ Content-Type: application/json ...@@ -158,187 +155,4 @@ Content-Type: application/json
## Pause all alerts ## Pause all alerts
`POST /api/admin/pause-all-alerts` See [Admin API]({{< relref "http_api/admin.md#pause-all-alerts" >}}).
Only works with Basic Authentication (username and password). See [introduction](http://docs.grafana.org/http_api/admin/#admin-api) for an explanation.
**Example Request**:
```http
POST /api/admin/pause-all-alerts HTTP/1.1
Accept: application/json
Content-Type: application/json
{
"paused": true
}
```
JSON Body Schema:
- **paused** – Can be `true` or `false`. True to pause an alert. False to unpause an alert.
**Example Response**:
```http
HTTP/1.1 200
Content-Type: application/json
{
"state": "Paused",
"message": "alert paused",
"alertsAffected": 1
}
```
## Get alert notifications
`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
[
{
"id": 1,
"name": "Team A",
"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"
}
]
```
## 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"
}
```
docs/sources/http_api/alerting_notification_channels.md 0 → 100644
+++
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
[
{
"id": 1,
"uid": "team-a-email-notifier",
"name": "Team A",
"type": "email",
"isDefault": false,
"sendReminder": false,
"disableResolveMessage": 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"
}
]
```
## 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
{
"id": 1,
"uid": "team-a-email-notifier",
"name": "Team A",
"type": "email",
"isDefault": false,
"sendReminder": false,
"disableResolveMessage": 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"
}
```
## 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
{
"id": 1,
"uid": "team-a-email-notifier",
"name": "Team A",
"type": "email",
"isDefault": false,
"sendReminder": false,
"disableResolveMessage": 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"
}
```
## 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
{
"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,
"uid": "cIBgcSjkk",
"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 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
{
"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"
}
```
## 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
{
"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"
}
```
docs/sources/http_api/index.md
...@@ -30,6 +30,7 @@ dashboards, creating users and updating data sources. ...@@ -30,6 +30,7 @@ dashboards, creating users and updating data sources.
* [Snapshot API]({{< relref "http_api/snapshot.md" >}}) * [Snapshot API]({{< relref "http_api/snapshot.md" >}})
* [Annotations API]({{< relref "http_api/annotations.md" >}}) * [Annotations API]({{< relref "http_api/annotations.md" >}})
* [Alerting API]({{< relref "http_api/alerting.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" >}}) * [User API]({{< relref "http_api/user.md" >}})
* [Team API]({{< relref "http_api/team.md" >}}) * [Team API]({{< relref "http_api/team.md" >}})
* [Admin API]({{< relref "http_api/admin.md" >}}) * [Admin API]({{< relref "http_api/admin.md" >}})
......
pkg/api/alerting.go
...@@ -208,6 +208,31 @@ func GetAlertNotificationByID(c *m.ReqContext) Response { ...@@ -208,6 +208,31 @@ func GetAlertNotificationByID(c *m.ReqContext) Response {
Id: c.ParamsInt64("notificationId"), Id: c.ParamsInt64("notificationId"),
} }
if query.Id == 0 {
return Error(404, "Alert notification not found", nil)
}
if err := bus.Dispatch(query); err != nil {
return Error(500, "Failed to get alert notifications", err)
}
if query.Result == nil {
return Error(404, "Alert notification not found", nil)
}
return JSON(200, dtos.NewAlertNotification(query.Result))
}
func GetAlertNotificationByUID(c *m.ReqContext) Response {
query := &m.GetAlertNotificationsWithUidQuery{
OrgId: c.OrgId,
Uid: c.Params("uid"),
}
if query.Uid == "" {
return Error(404, "Alert notification not found", nil)
}
if err := bus.Dispatch(query); err != nil { if err := bus.Dispatch(query); err != nil {
return Error(500, "Failed to get alert notifications", err) return Error(500, "Failed to get alert notifications", err)
} }
...@@ -239,6 +264,17 @@ func UpdateAlertNotification(c *m.ReqContext, cmd m.UpdateAlertNotificationComma ...@@ -239,6 +264,17 @@ func UpdateAlertNotification(c *m.ReqContext, cmd m.UpdateAlertNotificationComma
return JSON(200, dtos.NewAlertNotification(cmd.Result)) return JSON(200, dtos.NewAlertNotification(cmd.Result))
} }
func UpdateAlertNotificationByUID(c *m.ReqContext, cmd m.UpdateAlertNotificationWithUidCommand) Response {
cmd.OrgId = c.OrgId
cmd.Uid = c.Params("uid")
if err := bus.Dispatch(&cmd); err != nil {
return Error(500, "Failed to update alert notification", err)
}
return JSON(200, dtos.NewAlertNotification(cmd.Result))
}
func DeleteAlertNotification(c *m.ReqContext) Response { func DeleteAlertNotification(c *m.ReqContext) Response {
cmd := m.DeleteAlertNotificationCommand{ cmd := m.DeleteAlertNotificationCommand{
OrgId: c.OrgId, OrgId: c.OrgId,
...@@ -252,6 +288,19 @@ func DeleteAlertNotification(c *m.ReqContext) Response { ...@@ -252,6 +288,19 @@ func DeleteAlertNotification(c *m.ReqContext) Response {
return Success("Notification deleted") return Success("Notification deleted")
} }
func DeleteAlertNotificationByUID(c *m.ReqContext) Response {
cmd := m.DeleteAlertNotificationWithUidCommand{
OrgId: c.OrgId,
Uid: c.Params("uid"),
}
if err := bus.Dispatch(&cmd); err != nil {
return Error(500, "Failed to delete alert notification", err)
}
return Success("Notification deleted")
}
//POST /api/alert-notifications/test //POST /api/alert-notifications/test
func NotificationTest(c *m.ReqContext, dto dtos.NotificationTestCommand) Response { func NotificationTest(c *m.ReqContext, dto dtos.NotificationTestCommand) Response {
cmd := &alerting.NotificationTestCommand{ cmd := &alerting.NotificationTestCommand{
......
pkg/api/api.go
...@@ -350,6 +350,9 @@ func (hs *HTTPServer) registerRoutes() { ...@@ -350,6 +350,9 @@ func (hs *HTTPServer) registerRoutes() {
alertNotifications.Put("/:notificationId", bind(m.UpdateAlertNotificationCommand{}), Wrap(UpdateAlertNotification)) alertNotifications.Put("/:notificationId", bind(m.UpdateAlertNotificationCommand{}), Wrap(UpdateAlertNotification))
alertNotifications.Get("/:notificationId", Wrap(GetAlertNotificationByID)) alertNotifications.Get("/:notificationId", Wrap(GetAlertNotificationByID))
alertNotifications.Delete("/:notificationId", Wrap(DeleteAlertNotification)) alertNotifications.Delete("/:notificationId", Wrap(DeleteAlertNotification))
alertNotifications.Get("/uid/:uid", Wrap(GetAlertNotificationByUID))
alertNotifications.Put("/uid/:uid", bind(m.UpdateAlertNotificationWithUidCommand{}), Wrap(UpdateAlertNotificationByUID))
alertNotifications.Delete("/uid/:uid", Wrap(DeleteAlertNotificationByUID))
}, reqEditorRole) }, reqEditorRole)
apiRoute.Get("/annotations", Wrap(GetAnnotations)) apiRoute.Get("/annotations", Wrap(GetAnnotations))
......
pkg/models/alert_notifications.go
...@@ -67,14 +67,14 @@ type UpdateAlertNotificationCommand struct { ...@@ -67,14 +67,14 @@ type UpdateAlertNotificationCommand struct {
} }
type UpdateAlertNotificationWithUidCommand struct { type UpdateAlertNotificationWithUidCommand struct {
Uid string Uid string `json:"-"`
Name string Name string `json:"name" binding:"Required"`
Type string Type string `json:"type" binding:"Required"`
SendReminder bool SendReminder bool `json:"sendReminder"`
DisableResolveMessage bool DisableResolveMessage bool `json:"disableResolveMessage"`
Frequency string Frequency string `json:"frequency"`
IsDefault bool IsDefault bool `json:"isDefault"`
Settings *simplejson.Json Settings *simplejson.Json `json:"settings" binding:"Required"`
OrgId int64 OrgId int64
Result *AlertNotification Result *AlertNotification
......
pkg/services/sqlstore/alert_notification.go
...@@ -130,6 +130,7 @@ func getAlertNotificationInternal(query *m.GetAlertNotificationsQuery, sess *DBS ...@@ -130,6 +130,7 @@ func getAlertNotificationInternal(query *m.GetAlertNotificationsQuery, sess *DBS
sql.WriteString(`SELECT sql.WriteString(`SELECT
alert_notification.id, alert_notification.id,
alert_notification.uid,
alert_notification.org_id, alert_notification.org_id,
alert_notification.name, alert_notification.name,
alert_notification.type, alert_notification.type,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment