Resource History HTTP API

Note Grafana 12 이상에서 사용할 수 있어요. 이 API는 새 Grafana API 구조를 준수해요. 더 배우려면 Grafana의 API 구조 문서를 참고해요.

새 Grafana API는 리소스의 버전 기록을 추적해요. 특정 쿼리 매개변수와 함께 표준 List 엔드포인트를 사용해 어떤 리소스의 기록이든 검색할 수 있어요. 이 페이지는 대시보드를 예로 사용해 리소스 기록을 나열하는 방법을 문서화해요. 같은 패턴이 어떤 리소스에도 적용돼요.

리소스 기록은 모든 안정(GA) API 버전(예: v1, v2)에서 사용할 수 있어요. 알파나 베타 버전은 이를 지원하지 않을 수 있어요.

출처: 문서

본문

리소스 기록은 모든 안정(GA) API 버전(예: v1, v2)에서 사용할 수 있어요. 알파나 베타 버전은 이를 지원하지 않을 수 있어요.

리소스 기록 나열 (List resource history)

GET /apis/<group>/<version>/namespaces/<namespace>/<resource>?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=<NAME>

특정 리소스의 버전 기록을 나열해요. 이는 두 개의 필수 쿼리 매개변수와 함께 표준 List 엔드포인트를 사용해요:

labelSelector: 일반 목록 대신 기록을 요청하려면 grafana.app/get-history=true로 설정해야 해요.
fieldSelector: 특정 리소스를 식별하려면 metadata.name=<NAME>으로 설정해야 해요. <NAME>은 리소스의 metadata.name 필드(Grafana UID)예요.

추가 쿼리 매개변수로 페이지네이션을 제어할 수 있어요:

limit (선택): 페이지당 반환할 최대 기록 항목 수.
continue (선택): 다음 페이지를 가져오기 위한 이전 응답의 토큰.

기록 항목은 역시간순(최신이 먼저)으로 반환돼요.

대시보드 예제 (Dashboard example)

다음 요청은 default 네임스페이스에서 metadata.name이 production-overview인 대시보드의 버전 기록을 검색해요:

예제 요청 (Example request):

http

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예제 응답 (Example response):

http

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

{
  "kind": "DashboardList",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "resourceVersion": "1758777451428472",
    "continue": "eyJvIj...NlfQ=="
  },
  "items": [
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1",
      "metadata": {
        "name": "production-overview",
        "namespace": "default",
        "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
        "resourceVersion": "1758777451428472",
        "generation": 3,
        "creationTimestamp": "2026-03-15T14:22:10Z",
        "annotations": {
          "grafana.app/updatedBy": "user:u000000001",
          "grafana.app/message": "Added latency panel"
        }
      },
      "spec": {
        "title": "Production Overview",
        "schemaVersion": 41,
        ...
      }
    },
    {
      "kind": "Dashboard",
      "apiVersion": "dashboard.grafana.app/v1",
      "metadata": {
        "name": "production-overview",
        "namespace": "default",
        "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
        "resourceVersion": "1758777451428100",
        "generation": 2,
        "creationTimestamp": "2026-03-10T09:15:30Z",
        "annotations": {
          "grafana.app/updatedBy": "user:u000000001",
          "grafana.app/message": "Updated thresholds"
        }
      },
      "spec": {
        "title": "Production Overview",
        "schemaVersion": 41,
        ...
      }
    }
  ]
}

items 배열의 각 항목은 리소스의 기록 버전 하나를 나타내요. 다음 metadata 필드는 기록에 특히 관련이 있어요:

metadata.generation: 버전 번호. 리소스의 spec이 바뀔 때마다 증가해요.
metadata.resourceVersion: 이 특정 버전의 고유 식별자. 페이지네이션과 변경 감지에 사용해요.
metadata.creationTimestamp: 이 특정 버전이 저장된 시점.
metadata.annotations.grafana.app/updatedBy: 이 버전을 저장한 사용자. 형식은 <user-type>:<uid>예요.
metadata.annotations.grafana.app/message: 업데이트 중 설정한 선택적 커밋 메시지. 리소스 업데이트 시 이 주석을 설정할 수 있어요.
spec: 그 버전에 존재했던 전체 리소스 spec.

페이지네이션 (Pagination)

표준 List 요청을 페이지네이션하는 것과 같은 방식으로 limit와 continue를 사용해 기록을 페이지네이션할 수 있어요.

페이지네이션이 포함된 예제 요청 (Example request with pagination):

http

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview&limit=2 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

응답에 metadata.continue 필드가 포함되어 있다면 다음 요청에서 continue 쿼리 매개변수로 전달해 다음 페이지를 가져와요. 응답에 continue 필드가 없으면 마지막 페이지에 도달한 거예요.

다음 페이지 요청의 예 (Example request for the next page):

http

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards?labelSelector=grafana.app/get-history=true&fieldSelector=metadata.name=production-overview&limit=2&continue=eyJvIj...NlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

특정 버전 검색 (Retrieve a specific version)

특정 기록 버전의 전체 리소스를 검색하려면 resourceVersion 쿼리 매개변수를 기록 목록의 metadata.resourceVersion으로 설정해 표준 Get 엔드포인트를 사용해요.

예제 요청 (Example request):

http

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview?resourceVersion=1758777451428100 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

이것은 그 버전에 존재했던 완전한 리소스를 반환해요.

상태 코드 (Status codes)

200: OK
400: 잘못된 요청(fieldSelector 누락, 잘못된 labelSelector 등)
401: 인증되지 않음
403: 접근 거부

Resource History HTTP API