리포팅(Reporting) API

리포팅(Reporting) API

이 API는 리포팅(Reporting) 기능과 프로그래밍 방식으로 상호작용할 수 있게 해줘요.

⚠️ Reporting API는 아직 안정화되지 않았어요. 활발히 개발 중이며 사전 통지 없이 변경될 수 있어요.

Reporting은 Grafana Enterprise에서만 사용할 수 있어요. Grafana Enterprise에 대해 자세히 알아보세요.

Grafana Enterprise를 사용 중이라면 일부 엔드포인트에 특정 권한이 필요해요. 자세한 내용은 "Role-based access control permissions" 문서를 참조해요.

⚠️ Grafana 13부터 /api 엔드포인트가 /apis 라우트로 대체되어 더 이상 사용되지 않게(deprecated) 되고 있어요. Grafana가 기존 API를 마이그레이션하는 동안 현재 사용 중인 레거시 API와 정확히 일치하지 않을 수 있어요. 이 변경으로 현재 설정이 중단되거나 깨지지는 않아요. 레거시 API는 비활성화되지 않으며 완전히 접근·사용 가능하지만, /api 라우트는 더 이상 업데이트되지 않아요. 자세한 내용은 "Grafana의 새 API 구조" 문서를 참조해요.

출처: 문서

본문

모든 보고서 나열

GET /api/reports

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:read reports:*reports:id:*

예제 요청:

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

예제 응답:

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

[
	{
		"id": 2,
		"userId": 1,
		"orgId": 1,
		"name": "Report 2",
		"recipients": "[email protected]",
		"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 - Authentication failed, Authentication 문서 참조.
  • 500 – Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 가져오기

GET /api/reports/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:read reports:*reports:id:*reports:id:1(단일 보고서)

예제 요청:

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

예제 응답:

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

{
	"id": 2,
	"userId": 1,
	"orgId": 1,
	"name": "Report 2",
	"recipients": "[email protected]",
	"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 – Bad request (잘못된 report ID).
  • 401 - Authentication failed, Authentication 문서 참조.
  • 403 – Forbidden (보고서 또는 보고서에 사용된 대시보드에 대한 접근 거부).
  • 404 – Not found (해당 보고서가 존재하지 않음).
  • 500 – Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 생성

POST /api/reports

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:create n/a

예제 요청:

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

{
	"name": "Report 4",
	"recipients": "[email protected]",
	"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"
	]
}

Config JSON Body 스키마

Field name Data type Description
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 사용자 지정 간격의 유형: hours, days, weeks, months.
intervalAmount number 사용자 지정 간격 값.
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 보고서를 생성할 대시보드. 아래 "Report Dashboard Schema" 섹션 참조.

Report Dashboard 스키마

Field name Data type Description
dashboard.uid string 대시보드 UID.
timeRange.from string 대시보드 시간 범위 from.
timeRange.to string 대시보드 시간 범위 to.
reportVariables. string 이 보고서의 템플릿 변수를 담은 키-값 쌍, JSON 형식. 비어 있으면 보고서의 대시보드에서 템플릿 변수를 사용함.

예제 응답:

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

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

상태 코드:

  • 200 – OK
  • 400 – Bad request (잘못된 json, 누락되거나 잘못된 필드 값 등).
  • 403 - Forbidden (보고서 또는 보고서에 사용된 대시보드에 대한 접근 거부).
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 업데이트

PUT /api/reports/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:write reports:*reports:id:*reports:1(단일 보고서)

예제 요청 — 필드 설명은 JSON body 스키마 참조:

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

{
	"name": "Updated Report",
	"recipients": "[email protected]",
	"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 – Bad request (잘못된 json, 누락되거나 잘못된 필드 값 등).
  • 401 - Authentication failed, Authentication API 문서 참조.
  • 403 – Forbidden (보고서 또는 보고서에 사용된 대시보드에 대한 접근 거부).
  • 404 – Not found (해당 보고서가 존재하지 않음).
  • 500 – Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 삭제

DELETE /api/reports/:id

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:delete reports:*reports:id:*reports:1(단일 보고서)

예제 요청:

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

예제 응답:

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

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

상태 코드:

  • 200 – OK
  • 400 – Bad request (잘못된 report ID).
  • 401 - Authentication failed, Authentication API 문서 참조.
  • 404 - Not found (이 ID의 보고서가 존재하지 않음).
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 보내기

POST /api/reports/email

보고서를 생성하고 보내요. 이 API는 보고서가 생성될 때까지 대기한 후 반환해요. 클라이언트의 타임아웃을 최소 60초로 설정하는 것을 권장해요.

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:send n/a

예제 요청:

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

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

JSON Body 스키마

Field name Data type Description
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 – Report was sent.
  • 400 – Bad request (잘못된 json, 누락된 content-type, 누락되거나 잘못된 필드 등).
  • 401 - Authentication failed, Authentication API 문서 참조.
  • 403 - Forbidden (보고서 또는 보고서에 사용된 대시보드에 대한 접근 거부).
  • 404 - Report not found.
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 브랜딩 설정 가져오기

GET /api/reports/settings

모든 보고서에서 전역으로 사용되는 보고서 브랜딩 설정을 반환해요.

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports.settings:read n/a

예제 요청:

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

예제 응답:

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 - Authentication failed, Authentication API 문서 참조.
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

보고서 브랜딩 설정 저장

POST /api/reports/settings

설정이 없으면 생성하고, 있으면 업데이트해요. 이 설정은 전역이며 모든 보고서에서 사용돼요.

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports.settings:write n/a

예제 요청:

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

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

JSON Body 스키마

Field name Data type Description
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 이메일 "Sent by" 바닥글에 추가되는 URL 텍스트.
branding.emailFooterLink string 이메일 "Sent by" 바닥글에 추가되는 URL 주소 값.

예제 응답:

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

{
	"message": "Report settings saved"
}

상태 코드:

  • 200 – OK
  • 400 – Bad request (잘못된 json, 누락되거나 잘못된 필드 값 등).
  • 401 - Authentication failed, Authentication API 문서 참조.
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

테스트 이메일 보내기

POST /api/reports/test-email

데이터베이스에 저장하지 않고 보고서와 함께 테스트 이메일을 보내요.

필요한 권한 — 서문의 참고를 참조해요.

Action Scope
reports:send n/a

예제 요청 — 필드 설명은 JSON body 스키마 참조:

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

{{
	"name": "Report 4",
	"recipients": "[email protected]",
	"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 – Bad request (잘못된 json, 누락되거나 잘못된 필드 값 등).
  • 401 - Authentication failed, Authentication API 문서 참조.
  • 403 - Forbidden (보고서 또는 보고서에 사용된 대시보드에 대한 접근 거부).
  • 500 - Unexpected error or server misconfiguration. 서버 로그 참조.

더 알아보기 (Learn more)

  • 리포팅 (Reporting) 기능 (Enterprise)
  • Grafana의 새 API 구조