菜单

报告 API

企业版开源

报告 API

此 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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

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 – 成功
401 - 认证失败，请参阅认证 API。
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

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 – 成功
400 – 错误请求（报告 ID 无效）。
401 - 认证失败，请参阅认证 API。
403 – 禁止访问（拒绝访问报告或报告中使用的仪表盘）。
404 – 未找到（该报告不存在）。
500 – 意外错误或服务器配置错误。有关详细信息，请参阅服务器日志。

创建报告

POST /api/reports

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
reports:create	不适用

请求示例

POST /api/reports HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
	"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 请求体 Schema

字段名	数据类型	描述
name	string	报告的名称，用作电子邮件主题。
recipients	string	用逗号分隔的电子邮件列表，报告将发送到这些地址。
replyTo	string	用逗号分隔的电子邮件列表，用作报告电子邮件的回复地址。
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	要生成报告的仪表盘。请参阅下面的“报告仪表盘 Schema”部分。

报告仪表盘 Schema

字段名	数据类型	描述
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 – 成功
400 – 错误请求（JSON 无效、字段值缺失或无效等）。
403 - 禁止访问（拒绝访问报告或报告中使用的仪表盘）。
500 - 意外错误或服务器配置错误。有关详细信息，请参阅服务器日志。

更新报告

PUT /api/reports/:id

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
reports:write	reports:* reports:id:* reports:1 (单个报告)

请求示例

有关字段描述，请参阅JSON 请求体 schema。

GET /api/reports HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
	"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 – 成功
400 – 错误请求（JSON 无效、字段值缺失或无效等）。
401 - 认证失败，请参阅认证 API。
403 – 禁止访问（拒绝访问报告或报告中使用的仪表盘）。
404 – 未找到（该报告不存在）。
500 – 意外错误或服务器配置错误。有关详细信息，请参阅服务器日志。

删除报告

DELETE /api/reports/:id

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
reports:delete	reports:* reports:id:* reports:1 (单个报告)

请求示例

GET /api/reports/6 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

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

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

状态码

200 – 成功
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

JSON 请求体 Schema

字段名	数据类型	描述
id	string	要发送的报告 ID。与编辑报告时 URL 中的 ID 相同，不要与仪表盘 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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例

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.org.cn/"
	}
}

状态码

200 – 成功
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

JSON 请求体 Schema

字段名	数据类型	描述
branding.reportLogoUrl	string	用作报告每一页 Logo 的图片 URL。
branding.emailLogoUrl	string	用作电子邮件中 Logo 的图片 URL。
branding.emailFooterMode	string	可以是 `sent-by` (发送人) 或 `none` (无)。 `sent-by` 在电子邮件底部添加“发送人 `branding.emailFooterText`”页脚链接。需要在 `branding.emailFooterText` 和 `branding.emailFooterLink` 字段中指定值。 `none` 禁止在电子邮件中添加“发送人”页脚链接。
branding.emailFooterText	string	添加到电子邮件“发送人”页脚的 URL 文本。
branding.emailFooterLink	string	添加到电子邮件“发送人”页脚的 URL 地址值。

响应示例

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

{
	"message": "Report settings saved"
}

状态码

200 – 成功
400 – 错误请求（JSON 无效、字段值缺失或无效等）。
401 - 认证失败，请参阅认证 API。
500 - 意外错误或服务器配置错误。有关详细信息，请参阅服务器日志。

发送测试电子邮件

POST /api/reports/test-email

发送包含报告的测试电子邮件，但不将其保留在数据库中。

所需权限

有关说明，请参阅简介中的注意事项。

操作	范围
reports:send	不适用

请求示例

有关字段描述，请参阅JSON 请求体 schema。

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

{{
	"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 – 成功
400 – 错误请求（JSON 无效、字段值缺失或无效等）。
401 - 认证失败，请参阅认证 API。
403 - 禁止访问（拒绝访问报告或报告中使用的仪表盘）。
500 - 意外错误或服务器配置错误。有关详细信息，请参阅服务器日志。

此页面是否有帮助？

在 GitHub 中提交编辑建议

创建 GitHub Issue

发送电子邮件至 docs@grafana.com

帮助与支持

社区

报告 API

列出所有报告

所需权限

请求示例

响应示例

状态码

获取报告

所需权限

请求示例

响应示例

状态码

创建报告

所需权限

请求示例

配置 JSON 请求体 Schema

报告仪表盘 Schema

响应示例

状态码

更新报告

所需权限

请求示例

响应示例

状态码

删除报告

所需权限

请求示例

响应示例

状态码

发送报告

所需权限

请求示例

JSON 请求体 Schema

响应示例

状态码

获取报告品牌设置

所需权限

请求示例

响应示例

状态码

保存报告品牌设置

所需权限

请求示例

JSON 请求体 Schema

响应示例

状态码

发送测试电子邮件

所需权限

请求示例

响应示例

状态码

此页面是否有帮助？

Grafana Labs 相关资源