쿼리 기록(Query history) API

이 문서는 Grafana의 쿼리 기록에 쿼리를 추가하고, 검색하고, 삭제하며, 별표(즐겨찾기)를 관리하는 API를 설명해요. 이 API를 사용하려면 사용자가 로그인되어 있고 설정 파일에서 쿼리 기록 기능이 활성화되어 있어야 합니다.

출처: 문서

본문

참고: Grafana 13부터 /api 엔드포인트는 /apis 경로를 위해 더 이상 사용되지 않습니다(deprecated). 이 변경은 현재 설정을 방해하거나 깨지 않습니다. 레거시 API는 비활성화되지 않으며 완전히 접근 가능하고 정상 작동하지만, /api 경로는 더 이상 업데이트되지 않습니다. 이 API는 마이그레이션되지 않을 거예요. 자세한 내용과 대안은 API 더 이상 사용 중단(deprecation) 참고를 참고하세요.

쿼리 기록에 쿼리 추가하기

POST /api/query-history

쿼리를 쿼리 기록에 추가합니다.

예시 요청:

POST /api/query-history HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>
{
  "datasourceUid": "PE1C5CBDA0504A6A3",
  "queries": [
    {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
    }
]
}

JSON 본문 스키마:

datasourceUid – 데이터소스 uid.
queries – 쿼리 또는 쿼리들의 JSON.

예시 응답:

HTTP/1.1 200
Content-Type: application/json
{
  "result": {
    "uid": "Ahg678z",
    "datasourceUid": "PE1C5CBDA0504A6A3",
    "createdBy": 1,
    "createdAt": 1643630762,
    "starred": false,
    "comment": "",
    "queries": [
      {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
      }
    ]
  }
}

상태 코드:

200 – OK
400 – 오류 (잘못된 JSON, 누락되거나 유효하지 않은 필드)
401 – 인증되지 않음
500 – 내부 오류

쿼리 기록 검색하기

GET /api/query-history

검색 조건과 일치하는 쿼리 기록의 쿼리 목록을 반환합니다. 쿼리 기록 검색은 페이징을 지원해요. limit 파라미터로 반환되는 최대 쿼리 수를 제어할 수 있으며 기본 제한은 100입니다. page 쿼리 파라미터로 첫 페이지가 아닌 다른 페이지의 쿼리를 가져올 수도 있습니다.

쿼리 파라미터:

datasourceUid – 선택한 데이터소스로 쿼리 기록을 필터링. 여러 데이터소스로 "AND" 필터링을 하려면 다음 형식으로 데이터소스 파라미터를 지정하세요: datasourceUid=uid1&datasourceUid=uid2.
searchString – 내용을 기준으로 쿼리 기록을 필터링.
sort – 정렬 순서를 지정. 정렬은 time-asc 또는 time-desc일 수 있으며 기본값은 time-desc.
onlyStarred – 별표(즐겨찾기)된 쿼리만 검색. 기본값은 false.
page – 검색은 페이징을 지원. 반환할 페이지 번호를 지정. 페이지당 쿼리 수는 limit 파라미터로 지정.
limit – 페이지당 반환되는 쿼리 기록 항목 수를 제한. 기본값은 페이지당 100개의 쿼리.
from/to – 쿼리 기록 검색의 시간 범위를 지정. 시간은 밀리초 단위의 epoch 타임스탬프이거나 Grafana 시간 단위를 사용한 상대 시간일 수 있어요(예: now-5m).

쿼리 기록 검색 예시 요청

GET /api/query-history?datasourceUid="PE1C5CBDA0504A6A3"&datasourceUid="FG1C1CBDA0504A6EL"&searchString="ALERTS"&sort="time-asc" HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

쿼리 기록 검색 예시 응답

HTTP/1.1 200
Content-Type: application/json
{
  "result": {
    "totalCount": 150,
    "page": 1,
    "perPage": 100
    "queryHistory":[{
    "uid": "Ahg678z",
    "datasourceUid": "PE1C5CBDA0504A6A3",
    "createdBy": 1,
    "createdAt": 1643630762,
    "starred": false,
    "comment": "",
    "queries": [
      {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PE1C5CBDA0504A6A3"
        }
      }
    ]
  }]
}

상태 코드:

200 – OK
401 – 인증되지 않음
500 – 내부 오류

UID로 쿼리 기록에서 쿼리 삭제하기

DELETE /api/query-history/:uid

지정된 uid와 일치하는 쿼리 기록의 쿼리를 삭제합니다. 사용자가 로그인되어 있고 설정 파일에서 쿼리 기록 기능이 활성화되어 있어야 해요.

예시 요청:

DELETE /api/query-history/P8zM2I1nz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Query deleted",
    "id": 28
}

상태 코드:

200 – OK
401 – 인증되지 않음
500 – 내부 오류

UID로 쿼리 기록의 쿼리 주석(comment) 갱신하기

PATCH /api/query-history/:uid

쿼리 기록에 저장된 특정 uid의 쿼리 주석을 갱신합니다.

쿼리 파라미터:

comment – 지정된 쿼리에 추가될 새 주석.

예시 요청:

PATCH /api/query-history/P8zM2I1nz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>
{
  "comment": "Debugging query",
}

예시 응답:

HTTP/1.1 200
Content-Type: application/json
{
  "result": {
    "uid": "P8zM2I1nz",
    "datasourceUid": "PE1C5CBDA0504A6A3",
    "createdBy": 1,
    "createdAt": 1643630762,
    "starred": false,
    "comment": "Debugging query",
    "queries": [
      {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
      }
    ]
  }
}

상태 코드:

200 – OK
400 – 오류 (잘못된 JSON, 누락되거나 유효하지 않은 필드)
401 – 인증되지 않음
500 – 내부 오류

쿼리 기록에서 쿼리 별표(즐겨찾기)하기

POST /api/query-history/star/:uid

쿼리 기록에서 쿼리에 별표를 답니다.

예시 요청:

POST /api/query-history/star/P8zM2I1nz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 200
Content-Type: application/json
{
  "result": {
    "uid": "P8zM2I1nz",
    "datasourceUid": "PE1C5CBDA0504A6A3",
    "createdBy": 1,
    "createdAt": 1643630762,
    "starred": false,
    "comment": "Debugging query",
    "queries": [
      {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
      }
    ]
  }
}

상태 코드:

200 – OK
401 – 인증되지 않음
500 – 내부 오류

쿼리 기록에서 쿼리 별표 해제하기

DELETE /api/query-history/star/:uid

쿼리 기록에서 쿼리의 별표를 제거합니다.

예시 요청:

DELETE /api/query-history/star/P8zM2I1nz  HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예시 응답:

HTTP/1.1 200
Content-Type: application/json
{
  "result": {
    "uid": "P8zM2I1nz",
    "datasourceUid": "PE1C5CBDA0504A6A3",
    "createdBy": 1,
    "createdAt": 1643630762,
    "starred": false,
    "comment": "Debugging query",
    "queries": [
      {
        "refId": "A",
        "key": "Q-87fed8e3-62ba-4eb2-8d2a-4129979bb4de-0",
        "scenarioId": "csv_content",
        "datasource": {
            "type": "testdata",
            "uid": "PD8C576611E62080A"
        }
      }
    ]
  }
}

상태 코드:

200 – OK
401 – 인증되지 않음
500 – 내부 오류

더 알아보기 (Learn more)

원문 문서