API отчётности

Документация

Grafana

Документация GlaberGraph

Ресурсы для разработчиков

API Grafana

Справочное руководство по HTTP API Grafana

Устаревший HTTP API Grafana

API отчётности

Note
Starting in Grafana 13, /api endpoints are being deprecated in favor of the /apis route. Note that while Grafana is working on migrating existing APIs, currently there may not be an exact match to the legacy API you’re using.

This change doesn’t disrupt or break your current setup. Legacy APIs are not being disabled and remain fully accessible and operative, but /api routes will no longer be updated.

To learn more refer to the new API structure in Grafana.

Этот API позволяет программно взаимодействовать с функцией Отчётность.

API отчётности пока не стабилизирован, он всё ещё активно разрабатывается и может изменяться без предварительного уведомления.

Отчётность доступна только в Grafana Enterprise. Подробнее о Grafana Enterprise.

Если вы используете Grafana Enterprise, для некоторых конечных точек потребуются определённые права. Дополнительные сведения см. в разделе Права управления доступом на основе ролей.

Получение списка всех отчётов

GET /api/reports

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:read	reports:* reports:id:*

Пример запроса

GET /api/reports HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 1840

[
	{
		"id": 2,
		"userId": 1,
		"orgId": 1,
		"name": "Report 2",
		"recipients": "example-report@grafana.com",
		"replyTo": "",
		"message": "Hi, \nPlease find attached a PDF status report. If you have any questions, feel free to contact me!\nBest,",
		"schedule": {
			"startDate": "2022-10-02T00:00:00+02:00",
			"endDate": null,
			"frequency": "once",
			"intervalFrequency": "",
			"intervalAmount": 0,
			"workdaysOnly": false,
			"dayOfMonth": "2",
			"timeZone": "Europe/Warsaw"
		},
		"options": {
			"orientation": "landscape",
			"layout": "grid",
		},
		"enableDashboardUrl": true,
		"state": "scheduled",
		"dashboards": [
			{
				"dashboard": {
					"id": 463,
					"uid": "7MeksYbmk",
					"name": "Alerting with TestData"
				},
				"reportVariables": {
					"namefilter": "TestData"
				}
			}
		],
		"formats": [
			"pdf",
			"csv"
		],
		"created": "2022-09-19T11:44:42+02:00",
		"updated": "2022-09-19T11:44:42+02:00"
	}
]

Коды состояния

200 – OK
401 — Ошибка аутентификации, см. Аутентификация.
500 – Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера.

Получение отчёта

GET /api/reports/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:read	reports:* reports:id:* reports:id:1(один отчёт)

Пример запроса

GET /api/reports/2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 940

{
	"id": 2,
	"userId": 1,
	"orgId": 1,
	"name": "Report 2",
	"recipients": "example-report@grafana.com",
	"replyTo": "",
	"message": "Hi, \nPlease find attached a PDF status report. If you have any questions, feel free to contact me!\nBest,",
	"schedule": {
		"startDate": "2022-10-02T00:00:00+02:00",
		"endDate": null,
		"frequency": "once",
		"intervalFrequency": "",
		"intervalAmount": 0,
		"workdaysOnly": false,
		"dayOfMonth": "2",
		"timeZone": "Europe/Warsaw"
	},
	"options": {
		"orientation": "landscape",
		"layout": "grid",
	},
	"enableDashboardUrl": true,
	"state": "scheduled",
	"dashboards": [
		{
			"dashboard": {
				"id": 463,
				"uid": "7MeksYbmk",
				"name": "Alerting with TestData"
			},
			"timeRange": {
				"from": "",
				"to": ""
			},
			"reportVariables": {
				"namefilter": "TestData"
			}
		}
	],
	"formats": [
		"pdf",
		"csv"
	],
	"created": "2022-09-12T11:44:42+02:00",
	"updated": "2022-09-12T11:44:42+02:00"
}

Коды состояния

200 – OK
400 – Некорректный запрос (неверный ID отчёта).
401 — Ошибка аутентификации, см. Аутентификация.
403 – Запрещено (доступ к отчёту или используемому в отчёте дашборду запрещён).
404 – Не найдено (такого отчёта не существует).
500 – Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера.

Создание отчёта

POST /api/reports

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:create	н/д

Пример запроса

POST /api/reports HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
	"name": "Report 4",
	"recipients": "texample-report@grafana.com",
	"replyTo": "",
	"message": "Hello, please, find the report attached",
	"schedule": {
		"startDate": "2022-10-02T10:00:00+02:00",
		"endDate": "2022-11-02T20:00:00+02:00",
		"frequency": "daily",
		"intervalFrequency": "",
		"intervalAmount": 0,
		"workdaysOnly": true,
		"timeZone": "Europe/Warsaw"
	},
	"options": {
		"orientation": "landscape",
		"layout": "grid"
	},
	"enableDashboardUrl": true,
	"dashboards": [
		{
			"dashboard": {
				"uid": "7MeksYbmk",
			},
			"timeRange": {
				"from": "2022-08-08T15:00:00+02:00",
				"to": "2022-09-02T17:00:00+02:00"
			},
			"reportVariables": {
				"variable1": "Value1"
			}
		}
	],
	"formats": [
		"pdf",
		"csv"
	]
}

Схема тела JSON конфигурации

Имя поля	Тип данных	Описание
name	string	Имя отчёта, используемое в качестве темы письма.
recipients	string	Разделённый запятыми список адресов электронной почты, на которые отправляется отчёт.
replyTo	string	Разделённый запятыми список адресов электронной почты, используемых в поле reply-to письма с отчётом.
message	string	Текстовое сообщение, используемое в теле письма с отчётом.
startDate	string	С этой даты начинается рассылка отчёта.
endDate	string	На эту дату рассылка отчёта заканчивается.
frequency	string	Задаёт, как часто отправлять отчёт. Может быть `once`, `hourly`, `daily`, `weekly`, `monthly`, `last` или `custom`. `last` — планирует отчёт на последний день месяца. `custom` — планирует отправку отчёта с настраиваемым интервалом. Требует указания `intervalFrequency` и `intervalAmount`: например, каждые 2 недели, где 2 — это `intervalAmount`, а `weeks` — это `intervalFrequency`.
intervalFrequency	string	Тип интервала `custom`: `hours`, `days`, `weeks`, `months`.
intervalAmount	number	Величина интервала `custom`.
workdaysOnly	string	Отправлять отчёт только с понедельника по пятницу. Применимо к типам расписания `hourly` и `daily`.
timeZone	string	Часовой пояс, используемый для планирования выполнения отчёта.
orientation	string	Может быть `portrait` или `landscape`.
layout	string	Может быть `grid` или `simple`.
enableDashboardUrl	bool	Добавляет URL дашборда в конец письма с отчётом.
formats	[]string	Задаёт, какой тип вложения создавать для отчёта — `csv`, `pdf`, `image`. `pdf` — тип по умолчанию. `csv` — прикрепляет файл CSV для каждой панели-таблицы. `image` — встраивает изображение дашборда в тело письма.
dashboards	[]object	Дашборды, для которых создаётся отчёт. См. раздел «Схема дашборда отчёта» ниже.

Схема дашборда отчёта

Имя поля	Тип данных	Описание
dashboard.uid	string	UID дашборда.
timeRange.from	string	Начало временного диапазона дашборда.
timeRange.to	string	Конец временного диапазона дашборда.
reportVariables.	string	Пары ключ-значение, содержащие переменные шаблона для этого отчёта, в формате JSON. Если пусто, будут использоваться переменные шаблона из дашборда отчёта.

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 35

{
	"id": 4,
	"message": "Report created"
}

Коды состояния

200 – OK
400 – Некорректный запрос (некорректный json, отсутствующие или недопустимые значения полей и т. д.).
403 — Запрещено (доступ к отчёту или используемому в отчёте дашборду запрещён).
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера

Обновление отчёта

PUT /api/reports/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:write	reports:* reports:id:* reports:1(один отчёт)

Пример запроса

Описание полей см. в схеме тела JSON.

GET /api/reports HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
	"name": "Updated Report",
	"recipients": "example-report@grafana.com",
	"replyTo": "",
	"message": "Hello, please, find the report attached",
	"schedule": {
		"frequency": "hourly",
		"timeZone": "Africa/Cairo",
		"workdaysOnly": true,
		"startDate": "2022-10-10T10:00:00+02:00",
		"endDate": "2022-11-20T19:00:00+02:00"
	},
	"options": {
		"orientation": "landscape",
		"layout": "grid",
	},
	"enableDashboardUrl": true,
	"state": "scheduled",
	"dashboards": [
		{
			"dashboard": {
				"id": 463,
				"uid": "7MeksYbmk",
				"name": "Alerting with TestData"
			},
			"timeRange": {
				"from": "2022-08-08T15:00:00+02:00",
				"to": "2022-09-02T17:00:00+02:00"
			},
			"reportVariables": {
				"variable1": "Value1"
			}
		}
	],
	"formats": [
		"pdf",
		"csv"
	]
}

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 28

{
	"message": "Report updated"
}

Коды состояния

200 – OK
400 – Некорректный запрос (некорректный json, отсутствующие или недопустимые значения полей и т. д.).
401 — Ошибка аутентификации, см. API аутентификации.
403 – Запрещено (доступ к отчёту или используемому в отчёте дашборду запрещён).
404 – Не найдено (такого отчёта не существует).
500 – Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера.

Удаление отчёта

DELETE /api/reports/:id

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:delete	reports:* reports:id:* reports:1(один отчёт)

Пример запроса

DELETE /api/reports/6 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 39

{
	"message": "Report config was removed"
}

Коды состояния

200 – OK
400 – Некорректный запрос (неверный ID отчёта).
401 — Ошибка аутентификации, см. API аутентификации.
404 — Не найдено (отчёта с таким ID не существует).
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера

Отправка отчёта

POST /api/reports/email

Создаёт и отправляет отчёт. Этот API ждёт генерации отчёта перед возвратом. Мы рекомендуем устанавливать тайм-аут клиента не менее 60 секунд.

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:send	н/д

Пример запроса

POST /api/reports/email HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
  "id":"3",
  "useEmailsFromReport": true
}

Схема тела JSON

Имя поля	Тип данных	Описание
id	string	ID отчёта для отправки. Он совпадает с указанным в URL при редактировании отчёта; не путайте его с ID дашборда. Обязательно.
emails	string	Разделённый запятыми список адресов электронной почты, на которые отправляется отчёт. Переопределяет адреса из отчёта. Обязательно, если `useEmailsFromReport` отсутствует.
useEmailsFromReport	boolean	Отправлять отчёт на адреса, указанные в отчёте. Обязательно, если `emails` отсутствует.

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 29

{"message":"Report was sent"}

Коды состояния

200 – Отчёт отправлен.
400 – Некорректный запрос (некорректный json, отсутствует content-type, отсутствующие или недопустимые поля и т. д.).
401 — Ошибка аутентификации, см. API аутентификации.
403 — Запрещено (доступ к отчёту или используемому в отчёте дашборду запрещён).
404 — Отчёт не найден.
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера.

Получение настроек брендирования отчётов

GET /api/reports/settings

Возвращает глобальные настройки брендирования отчётов, используемые во всех отчётах.

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports.settings:read	н/д

Пример запроса

GET /api/reports/settings HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 181

{
	"id": 1,
	"userId": 1,
	"orgId": 1,
	"branding": {
		"reportLogoUrl": "",
		"emailLogoUrl": "",
		"emailFooterMode": "sent-by",
		"emailFooterText": "Grafana Labs",
		"emailFooterLink": "https://grafana.com/"
	}
}

Коды состояния

200 – OK
401 — Ошибка аутентификации, см. API аутентификации.
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера

Сохранение настроек брендирования отчётов

POST /api/reports/settings

Создаёт настройки, если они не существуют, иначе обновляет их. Эти настройки глобальны и используются во всех отчётах.

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports.settings:write	н/д

Пример запроса

POST /api/reports/settings HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{
	"branding": {
		"reportLogoUrl": "https://grafana.com/reportLogo.jpg",
		"emailLogoUrl": "https://grafana.com/emailLogo.jpg",
		"emailFooterMode": "sent-by",
		"emailFooterText": "Grafana Labs",
		"emailFooterLink": "https://grafana.com/"
	}
}

Схема тела JSON

Имя поля	Тип данных	Описание
branding.reportLogoUrl	string	URL изображения, используемого в качестве логотипа на каждой странице отчёта.
branding.emailLogoUrl	string	URL изображения, используемого в качестве логотипа в письме.
branding.emailFooterMode	string	Может быть `sent-by` или `none`. `sent-by` добавляет в письмо ссылку в нижнем колонтитуле «Sent by `branding.emailFooterText`». Требует указания значений в полях `branding.emailFooterText` и `branding.emailFooterLink`. `none` отменяет добавление ссылки «Sent by» в нижний колонтитул письма.
branding.emailFooterText	string	Текст URL, добавляемого в нижний колонтитул письма «Sent by».
branding.emailFooterLink	string	Значение URL-адреса, добавляемого в нижний колонтитул письма «Sent by».

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 35

{
	"message": "Report settings saved"
}

Коды состояния

200 – OK
400 – Некорректный запрос (некорректный json, отсутствующие или недопустимые значения полей и т. д.).
401 — Ошибка аутентификации, см. API аутентификации.
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера

Отправка тестового письма

POST /api/reports/test-email

Отправляет тестовое письмо с отчётом, не сохраняя его в базе данных.

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
reports:send	н/д

Пример запроса

Описание полей см. в схеме тела JSON.

POST /api/reports/test-email HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVICE_ACCOUNT_TOKEN>

{{
	"name": "Report 4",
	"recipients": "example-report@grafana.com",
	"replyTo": "",
	"message": "Hello, please, find the report attached",
	"schedule": {
		"startDate": "2022-10-02T10:00:00+02:00",
		"endDate": "2022-11-02T20:00:00+02:00",
		"frequency": "daily",
		"intervalFrequency": "",
		"intervalAmount": 0,
		"workdaysOnly": true,
		"timeZone": "Europe/Warsaw"
	},
	"options": {
		"orientation": "landscape",
		"layout": "grid"
	},
	"enableDashboardUrl": true,
	"dashboards": [
		{
			"dashboard": {
				"uid": "7MeksYbmk",
			},
			"timeRange": {
				"from": "2022-08-08T15:00:00+02:00",
				"to": "2022-09-02T17:00:00+02:00"
			},
			"reportVariables": {
				"variable1": "Value1"
			}
		}
	],
	"formats": [
		"pdf",
		"csv"
	]
}

Пример ответа

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 29

{
	"message": "Test email sent"
}

Коды состояния

200 – OK
400 – Некорректный запрос (некорректный json, отсутствующие или недопустимые значения полей и т. д.).
401 — Ошибка аутентификации, см. API аутентификации.
403 — Запрещено (доступ к отчёту или используемому в отчёте дашборду запрещён).
500 — Непредвиденная ошибка или неверная конфигурация сервера. Подробности см. в журналах сервера

Была ли эта страница полезна?

Написать на docs@glaber.ru

Справка и поддержка

Сообщество