데이터 소스(Data source) API

데이터 소스(Data source) API

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

요구 사항

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

출처: 문서

본문

엔드포인트

Method	URI	Summary
GET	/api/datasources	모든 데이터 소스 가져오기
GET	/api/datasources/uid/:uid	uid로 단일 데이터 소스 가져오기
GET	/api/datasources/name/:name	이름으로 단일 데이터 소스 가져오기 (deprecated)
GET	/api/datasources/id/:name	이름으로 데이터 소스 Id 가져오기 (deprecated)
POST	/api/datasources	데이터 소스 생성
PUT	/api/datasources/uid/:uid	기존 데이터 소스 업데이트
DELETE	/api/datasources/uid/:uid	uid로 기존 데이터 소스 삭제
DELETE	/api/datasources/name/:datasourceName	이름으로 기존 데이터 소스 삭제 (deprecated)
GET	/api/datasources/proxy/uid/:uid/*	데이터 소스 프록시 호출
GET	/api/datasources/uid/:uid/health	데이터 소스 상태 확인
GET	/api/datasources/uid/:uid/resources/*	데이터 소스 리소스 가져오기
POST	/api/ds/query	데이터 소스 쿼리

모든 데이터 소스 가져오기

GET /api/datasources

⚠️ 이 API는 현재 페이지네이션을 처리하지 않아요. 반환되는 데이터 소스의 기본 최대 개수는 5000이에요. 이 값은 default.ini 파일에서 변경할 수 있어요.

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

Action	Scope
datasources:read	datasources:*

예제 요청:

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

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
   {
     "id": 1,
     "orgId": 1,
     "uid": "H8joYFVGz"
     "name": "datasource_elastic",
     "type": "elasticsearch",
     "typeLogoUrl": "public/app/plugins/datasource/elasticsearch/img/elasticsearch.svg",
     "access": "proxy",
     "url": "http://mydatasource.com",
     "password": "",
     "user": "",
     "database": "grafana-dash",
     "basicAuth": false,
     "isDefault": false,
     "jsonData": {
         "logLevelField": "",
         "logMessageField": "",
         "maxConcurrentShardRequests": 256,
         "timeField": "@timestamp"
     },
     "readOnly": false
   }
]

uid로 단일 데이터 소스 가져오기

GET /api/datasources/uid/:uid

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

Action	Scope
datasources:read	datasources:*datasources:uid:*datasources:uid:kLtEtcRGk (단일 데이터 소스)

예제 요청:

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

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "kLtEtcRGk",
  "orgId": 1,
  "name": "test_datasource",
  "type": "graphite",
  "typeLogoUrl": "",
  "access": "proxy",
  "url": "http://mydatasource.com",
  "password": "",
  "user": "",
  "database": "",
  "basicAuth": false,
  "basicAuthUser": "",
  "basicAuthPassword": "",
  "withCredentials": false,
  "isDefault": false,
  "jsonData": {
    "graphiteType": "default",
    "graphiteVersion": "1.1"
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

이름으로 단일 데이터 소스 가져오기

GET /api/datasources/name/:name

⚠️ 이 API는 deprecated이며 향후 릴리스에서 제거될 예정이에요.

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

Action	Scope
datasources:read	datasources:*datasources:name:*datasources:name:test_datasource (단일 데이터 소스)

예제 요청:

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

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id": 1,
  "uid": "kLtEtcRGk",
  "orgId": 1,
  "name": "test_datasource",
  "type": "graphite",
  "typeLogoUrl": "",
  "access": "proxy",
  "url": "http://mydatasource.com",
  "password": "",
  "user": "",
  "database": "",
  "basicAuth": false,
  "basicAuthUser": "",
  "basicAuthPassword": "",
  "withCredentials": false,
  "isDefault": false,
  "jsonData": {
    "graphiteType": "default",
    "graphiteVersion": "1.1"
  },
  "secureJsonFields": {},
  "version": 1,
  "readOnly": false
}

이름으로 데이터 소스 Id 가져오기

GET /api/datasources/id/:name

⚠️ 이 API는 deprecated이며 향후 릴리스에서 제거될 예정이에요.

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

Action	Scope
datasources.id:read	datasources:*datasources:name:*datasources:name:test_datasource (단일 데이터 소스)

예제 요청:

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

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "id":1
}

데이터 소스 생성

POST /api/datasources

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

Action	Scope
datasources:create	n/a

예제 Graphite 요청:

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

{
  "name":"test_datasource",
  "type":"graphite",
  "url":"http://mydatasource.com",
  "access":"proxy",
  "basicAuth":false
}

예제 Graphite 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": false,
    "basicAuthUser": "",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {},
    "version": 1,
    "readOnly": false
  },
  "id": 1,
  "message": "Datasource added",
  "name": "test_datasource"
}

💡 password와 basicAuthPassword를 secureJsonData 아래에 정의하면 Grafana가 데이터베이스에서 암호화된 blob으로 안전하게 암호화해요. 그러면 응답이 암호화된 필드를 secureJsonFields 아래에 나열해요.

기본 인증이 활성화된 예제 Graphite 요청:

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

{
  "name": "test_datasource",
  "type": "graphite",
  "url": "http://mydatasource.com",
  "access": "proxy",
  "basicAuth": true,
  "basicAuthUser": "basicuser",
  "secureJsonData": {
    "basicAuthPassword": "basicpassword"
  }
}

기본 인증이 활성화된 예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": true,
    "basicAuthUser": "basicuser",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {
      "basicAuthPassword": true
    },
    "version": 1,
    "readOnly": false
  },
  "id": 102,
  "message": "Datasource added",
  "name": "test_datasource"
}

예제 CloudWatch 요청:

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

{
  "name": "test_datasource",
  "type": "cloudwatch",
  "url": "http://monitoring.us-west-1.amazonaws.com",
  "access": "proxy",
  "jsonData": {
    "authType": "keys",
    "defaultRegion": "us-west-1"
  },
  "secureJsonData": {
    "accessKey": "Ol4pIDpeKSA6XikgOl4p",
    "secretKey": "dGVzdCBrZXkgYmxlYXNlIGRvbid0IHN0ZWFs"
  }
}

기존 데이터 소스 업데이트

PUT /api/datasources/uid/:uid

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

Action	Scope
datasources:write	datasources:*datasources:uid:*datasources:uid:kLtEtcRGk (단일 데이터 소스)

예제 요청:

PUT /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "id":1,
  "uid": "uid",
  "orgId":1,
  "name":"test_datasource",
  "type":"graphite",
  "access":"proxy",
  "url":"http://mydatasource.com",
  "password":"",
  "user":"",
  "database":"",
  "basicAuth":true,
  "basicAuthUser":"basicuser",
  "secureJsonData": {
    "basicAuthPassword": "basicpassword"
  },
  "isDefault":false,
  "jsonData":null
}

UID는 수정할 수 없어요.

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "uid": "uid",
    "orgId": 1,
    "name": "test_datasource",
    "type": "graphite",
    "typeLogoUrl": "",
    "access": "proxy",
    "url": "http://mydatasource.com",
    "password": "",
    "user": "",
    "database": "",
    "basicAuth": true,
    "basicAuthUser": "basicuser",
    "basicAuthPassword": "",
    "withCredentials": false,
    "isDefault": false,
    "jsonData": {},
    "secureJsonFields": {
      "basicAuthPassword": true
    },
    "version": 1,
    "readOnly": false
  },
  "id": 102,
  "message": "Datasource updated",
  "name": "test_datasource"
}

💡 데이터 소스 생성과 유사하게, password와 basicAuthPassword는 데이터베이스에 암호화된 blob으로 안전하게 저장되도록 secureJsonData 아래에 정의해야 해요. 그러면 응답의 secureJsonFields 섹션 아래에 암호화된 필드가 나열돼요.

uid로 기존 데이터 소스 삭제

DELETE /api/datasources/uid/:uid

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

Action	Scope
datasources:delete	datasources:*datasources:uid:*datasources:uid:kLtEtcRGk (단일 데이터 소스)

예제 요청:

DELETE /api/datasources/uid/kLtEtcRGk HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Data source deleted",
    "id": 1
}

이름으로 기존 데이터 소스 삭제

DELETE /api/datasources/name/:datasourceName

⚠️ 이 API는 deprecated이며 향후 릴리스에서 제거될 예정이에요.

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

Action	Scope
datasources:delete	datasources:*datasources:name:*datasources:name:test_datasource (단일 데이터 소스)

예제 요청:

DELETE /api/datasources/name/test_datasource HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "message":"Data source deleted",
  "id": 1
}

데이터 소스 프록시 호출

GET /api/datasources/proxy/uid/:uid/*

uid로 식별되는 실제 데이터 소스에 모든 호출을 프록시해요.

데이터 소스 상태 확인

GET /api/datasources/uid/:uid/health

주어진 uid로 식별되는 데이터 소스의 health 엔드포인트에 호출을 만들어요. 필수는 아니에요 — 플러그인 작성자가 자신의 플러그인에서 health check 지원을 직접 구현해야 해요.

예제 요청:

GET api/datasources/uid/P8045C56BDA891CB2/health HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "message": "1. Successfully queried the CloudWatch metrics API.\n2. Successfully queried the CloudWatch logs API.",
  "status": "OK"
}

데이터 소스 리소스 가져오기

GET /api/datasources/uid/:uid/resources/*

주어진 uid로 식별되는 데이터 소스의 resources 엔드포인트에 호출을 만들어요.

예제 요청:

GET api/datasources/uid/P8045C56BDA891CB2/resources/dimension-keys?region=us-east-2&namespace=AWS%2FEC2&dimensionFilters=%7B%7D&metricName=CPUUtilization HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

[
	{
		"text": "AutoScalingGroupName",
		"value": "AutoScalingGroupName",
		"label": "AutoScalingGroupName"
	},
	{
		"text": "ImageId",
		"value": "ImageId",
		"label": "ImageId"
	},
	{
		"text": "InstanceId",
		"value": "InstanceId",
		"label": "InstanceId"
	},
	{
		"text": "InstanceType",
		"value": "InstanceType",
		"label": "InstanceType"
	}
]

데이터 소스 쿼리

백엔드 구현을 가진 데이터 소스에 쿼리해요.

POST /api/ds/query

💡 Grafana의 내장 데이터 소스는 대개 백엔드 구현을 가지고 있어요.

Test 데이터 소스 예제 요청:

POST /api/ds/query HTTP/1.1
Accept: application/json
Content-Type: application/json

{
   "queries":[
      {
         "refId":"A",
         "scenarioId":"csv_metric_values",
         "datasource":{
            "uid":"PD8C576611E62080A"
         },
         "format": "table",
         "maxDataPoints":1848,
         "intervalMs":200,
         "stringInput":"1,20,90,30,5,0"
      }
   ],
   "from":"now-5m",
   "to":"now"
}

JSON body 스키마:

• from/to – 쿼리 시간 범위를 지정해요. 시간은 밀리초 단위의 epoch 타임스탬프이거나 Grafana 시간 단위를 사용한 상대값일 수 있어요. 예: now-5m.
• queries – 하나 이상의 쿼리를 지정해요. 최소 1개를 포함해야 해요.
• queries.datasource.uid – 쿼리할 데이터 소스의 UID를 지정해요. 요청의 각 쿼리는 고유한 datasource를 가져야 해요.
• queries.refId – 쿼리의 식별자를 지정해요. 기본값은 "A".
• queries.format – 데이터가 반환될 형식을 지정해요. 데이터 소스에 따라 유효한 옵션은 time_series 또는 table.
• queries.maxDataPoints - 대시보드 패널이 렌더링할 수 있는 최대 데이터 포인트 수를 지정해요. 기본값은 100.
• queries.intervalMs - 시계열 시간 간격을 밀리초 단위로 지정해요. 기본값은 1000.

또한 각 데이터 소스의 특정 속성을 요청에 추가해야 해요(예: 위 요청의 queries.stringInput). 특정 데이터 소스에 대한 쿼리를 구성하는 방법을 더 잘 이해하려면 선택한 브라우저의 개발자 도구를 사용해 /api/ds/query로 전송되는 HTTP 요청을 검사해 보세요.

Test 데이터 소스 시계열 쿼리 응답 예제:

{
  "results": {
    "A": {
      "frames": [
        {
          "schema": {
            "refId": "A",
            "fields": [
              {
                "name": "time",
                "type": "time",
                "typeInfo": {
                  "frame": "time.Time"
                }
              },
              {
                "name": "A-series",
                "type": "number",
                "typeInfo": {
                  "frame": "int64",
                  "nullable": true
                }
              }
            ]
          },
          "data": {
            "values": [
              [1644488152084, 1644488212084, 1644488272084, 1644488332084, 1644488392084, 1644488452084],
              [1, 20, 90, 30, 5, 0]
            ]
          }
        }
      ]
    }
  }
}

상태 코드:

Code	Description
200	모든 데이터 소스 쿼리가 성공적인 응답을 반환함.
400	잘못된 JSON, 누락된 content type, 누락되거나 잘못된 필드 등의 잘못된 요청. 또는 하나 이상의 데이터 소스 쿼리가 실패함. 자세한 내용은 body 참조.
403	Access denied.
404	요청을 처리하는 데 필요한 데이터 소스 또는 플러그인을 찾을 수 없음.
500	예기치 않은 오류. 자세한 내용은 body 및/또는 서버 로그 참조.

더 알아보기 (Learn more)

• 데이터 소스 관리 및 구성
• 데이터 소스 권한 (Enterprise)
• Grafana의 새 API 구조