라이브러리 요소 API

라이브러리 요소 API

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

출처: 문서

본문

식별자(id)와 고유 식별자(uid)

라이브러리 요소의 식별자(ID)는 Grafana 설치마다 고유한 자동 증가 숫자 값이에요.

라이브러리 요소의 고유 식별자(UID)는 여러 Grafana 설치 간에 라이브러리 요소를 고유하게 식별해요. 라이브러리 요소 생성 시 지정하지 않으면 자동으로 생성돼요. UID는 라이브러리 요소에 접근하고 여러 Grafana 설치 간에 동기화할 때 일관된 URL을 제공해요.

UID의 최대 길이는 40자예요.

모든 라이브러리 요소 가져오기

GET /api/library-elements

인증된 사용자가 볼 권한이 있는 모든 라이브러리 요소 목록을 반환해요. perPage 쿼리 매개변수를 사용해 반환되는 최대 라이브러리 요소 수를 제어해요. 기본 한도는 100이에요. page 쿼리 매개변수를 사용해 첫 페이지 이외의 다른 페이지의 라이브러리 요소를 가져올 수도 있어요.

쿼리 매개변수:

• searchString: 검색할 이름 또는 설명의 일부.
• kind: 검색할 요소의 종류. 라이브러리 패널에는 1을 사용해요.
• sortDirection: 요소의 정렬 순서. 오름차순은 alpha-asc, 내림차순은 alpha-desc를 사용해요.
• typeFilter: 요소를 필터링할 쉼표로 구분된 타입 목록.
• excludeUid: 검색 결과에서 제외할 요소 UID.
• folderFilter: 더 이상 사용되지 않음(deprecated). 요소를 필터링할 쉼표로 구분된 폴더 ID 목록. folderFilterUIDs를 대신 사용해요.
• folderFilterUIDs: 요소를 필터링할 쉼표로 구분된 폴더 UID 목록.
• perPage: 페이지당 결과 수. 기본값은 100.
• page: 한 번에 perPage 개의 레코드만 반환된다고 할 때, 레코드 집합의 페이지. 번호는 1부터 시작.

예제 요청:

GET /api/library-elements?perPage=10 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
  "result": {
     "totalCount": 15,
     "page": 1,
     "perPage": 10
     "elements": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        },
        {...}
        {...}
     ],
  }
}

상태 코드:

• 200: Found
• 401: Unauthorized

uid로 라이브러리 요소 가져오기

GET /api/library-elements/:uid

주어진 UID의 라이브러리 요소를 반환해요.

예제 요청:

GET /api/library-elements/V--OrYHnz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
      "id": 25,
      "orgId": 1,
      "folderId": 0,
      "uid": "V--OrYHnz",
      "name": "API docs Example",
      "kind": 1,
      "type": "text",
      "description": "",
      "model": {...},
      "version": 1,
      "meta": {
          "folderName": "General",
          "folderUid": "",
          "connectedDashboards": 1,
          "created": "2021-09-27T09:56:17+02:00",
          "updated": "2021-09-27T09:56:17+02:00",
          "createdBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          },
          "updatedBy": {
              "id": 1,
              "name": "admin",
              "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
          }
      }
   }
}

상태 코드:

• 200: Found
• 401: Unauthorized
• 404: Library element not found

이름으로 라이브러리 요소 가져오기

GET /api/library-elements/name/:name

주어진 이름의 라이브러리 요소를 반환해요.

예제 요청:

GET /api/library-elements/name/API docs Example HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 25,
            "orgId": 1,
            "folderId": 0,
            "uid": "V--OrYHnz",
            "name": "API docs Example",
            "kind": 1,
            "type": "text",
            "description": "",
            "model": {...},
            "version": 1,
            "meta": {
                "folderName": "General",
                "folderUid": "",
                "connectedDashboards": 1,
                "created": "2021-09-27T09:56:17+02:00",
                "updated": "2021-09-27T09:56:17+02:00",
                "createdBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                },
                "updatedBy": {
                    "id": 1,
                    "name": "admin",
                    "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
                }
            }
        }
    ]
}

상태 코드:

• 200: Found
• 401: Unauthorized
• 404: Library element not found

라이브러리 요소 연결 가져오기

GET /api/library-elements/:uid/connections

지정된 UID를 기준으로 라이브러리 요소의 연결 목록을 반환해요.

예제 요청:

GET /api/library-elements/V--OrYHnz/connections HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": [
        {
            "id": 148, // Deprecated: will be removed in the future.
            "kind": 1,
            "elementId": 25,
            "connectionId": 527,
            "connectionUid": "dHEquNzGz",
            "created": "2021-09-27T10:00:07+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    ]
}

상태 코드:

• 200: Found
• 401: Unauthorized
• 404: Library element not found

라이브러리 요소 생성

POST /api/library-elements

새 라이브러리 요소를 생성해요.

JSON body 스키마:

• folderId: 라이브러리 요소가 저장된 폴더의 ID. Grafana v9부터 더 이상 사용되지 않음(deprecated).
• folderUid: 선택 사항. 라이브러리 요소가 저장된 폴더의 UID. 루트 레벨에 있을 때는 빈 문자열.
• name: 선택 사항. 라이브러리 요소의 이름.
• model: 라이브러리 요소의 JSON 모델.
• kind: 생성할 요소의 종류. 라이브러리 패널에는 1을 사용해요.
• uid: 선택 사항. 고유 식별자.

예제 요청:

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

{
  "uid": "nErXDvCkzz",
  "folderUid": "",
  "name": "Example library panel",
  "model": {...},
  "kind": 1
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "folderUid": "",
        "uid": "nErXDvCkzz",
        "name": "Example library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {...},
        "version": 1,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22.378307+02:00",
            "updated": "2021-09-30T09:14:22.378307+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

상태 코드:

• 200: Created
• 400: Errors (예: 이름 또는 UID가 이미 존재, 잘못된 JSON, 누락되거나 잘못된 필드 등)
• 401: Unauthorized
• 403: Access denied

라이브러리 요소 업데이트

PATCH /api/library-elements/:uid

uid로 식별되는 기존 라이브러리 요소를 업데이트해요.

JSON body 스키마:

• folderId: 라이브러리 요소가 저장된 폴더의 ID. Grafana v9부터 더 이상 사용되지 않음(deprecated).
• folderUid: 라이브러리 요소가 저장된 폴더의 UID. 루트 레벨에 있을 때는 빈 문자열.
• name: 라이브러리 요소의 이름.
• model: 라이브러리 요소의 JSON 모델.
• kind: 생성할 요소의 종류. 라이브러리 패널에는 1을 사용해요.
• version: 업데이트 중인 라이브러리 요소의 버전.
• uid: 선택 사항. 고유 식별자.

예제 요청:

PATCH /api/library-elements/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "name": "Renamed library panel",
  "kind": 1,
  "version": 1
}

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "result": {
        "id": 28,
        "orgId": 1,
        "folderId": 0,
        "folderUid": "",
        "uid": "nErXDvCkzz",
        "name": "Renamed library panel",
        "kind": 1,
        "type": "",
        "description": "",
        "model": {
            "description": "",
            "type": ""
        },
        "version": 2,
        "meta": {
            "folderName": "General",
            "folderUid": "",
            "connectedDashboards": 0,
            "created": "2021-09-30T09:14:22+02:00",
            "updated": "2021-09-30T09:25:57.697214+02:00",
            "createdBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            },
            "updatedBy": {
                "id": 1,
                "name": "admin",
                "avatarUrl": "/avatar/46d229b033af06a191ff2267bca9ae56"
            }
        }
    }
}

상태 코드:

• 200: Updated
• 400: Errors (예: 이름 또는 UID가 이미 존재, 잘못된 JSON, 누락되거나 잘못된 필드 등)
• 401: Unauthorized
• 403: Access denied
• 404: Library element not found
• 412: Version mismatch

라이브러리 요소 삭제

DELETE /api/library-elements/:uid

UID로 지정된 기존 라이브러리 요소를 삭제해요. 이 작업은 되돌릴 수 없어요.

⚠️ 연결되어 있는 라이브러리 요소는 삭제할 수 없어요. 이 작업은 되돌릴 수 없어요.

예제 요청:

DELETE /api/library-elements/nErXDvCkzz HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...>

예제 응답:

HTTP/1.1 200
Content-Type: application/json

{
    "message": "Library element deleted",
    "id": 28
}

상태 코드:

• 200: Deleted
• 401: Unauthorized
• 400: Bad request
• 403: Access denied
• 404: Library element not found

더 알아보기 (Learn more)

• 대시보드에서 라이브러리 패널 사용하기
• Grafana의 새 API 구조