Folder API

Note Grafana 12 이상에서 사용할 수 있어요. 이 API는 새 Grafana API 구조를 준수해요. 더 배우려면 Grafana의 API 구조 문서를 참고해요. 이 문서는 API의 최신 버전을 포함하지 않을 수 있어요. 사용 가능한 최신 엔드포인트 목록은 Swagger의 folder.grafana.app/v1을 참고해요.

출처: 문서

본문

Note Grafana 12 이상에서 사용할 수 있어요. 이 API는 새 Grafana API 구조를 준수해요. 더 배우려면 Grafana의 API 구조 문서를 참고해요. 이 문서는 API의 최신 버전을 포함하지 않을 수 있어요. 사용 가능한 최신 엔드포인트 목록은 Swagger의 folder.grafana.app/v1을 참고해요.

요구 사항 (Requirements)

Grafana Enterprise를 실행한다면 일부 엔드포인트에 특정 권한이 필요해요. 자세한 내용은 Role-based access control permissions을 참고해요.

엔드포인트 (Endpoints)

테이블 펼치기

Method	URI	Summary
GET	/apis/folder.grafana.app/v1/namespaces/:namespace/folders	Get all folders
GET	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Get folder by uid
POST	/apis/folder.grafana.app/v1/namespaces/:namespace/folders	Create folder
PUT	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Update folder
DELETE	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Delete folder

모든 폴더 가져오기 (Get all folders)

GET /apis/folder.grafana.app/v1/namespaces/:namespace/folders

인증된 사용자가 주어진 조직 내에서 볼 권한이 있는 모든 폴더를 반환해요. limit 쿼리 매개변수로 반환되는 최대 대시보드 수를 제어해요. 추가 대시보드를 검색하려면 응답에 제공된 continue 토큰을 사용해 다음 페이지를 가져와요.

namespace: 어떤 네임스페이스를 사용할지에 대해 더 읽으려면 API 개요를 참고해요.

쿼리 매개변수:

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

필수 권한

설명은 소개의 주석을 참고해요.

테이블 펼치기

Action	Scope
`folders:read`	`folders:*`

예제 요청 (Example Request):

http

GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예제 응답 (Example Response):

http

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "continue": "eyJvIj...NlfQ=="
  },
  "items": [
    {
      "kind": "Folder",
      "apiVersion": "folder.grafana.app/v1",
      "metadata": {
        "name": "aef30vrzxs3y8d",
        "namespace": "default",
        "uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
        "resourceVersion": "1741343686000",
        "creationTimestamp": "2025-03-07T10:34:46Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z"
        }
      },
      "spec": {
        "title": "example"
      }
    }
  ]
}

metadata.continue 필드에는 다음 페이지를 가져오기 위한 토큰이 들어 있어요.

continue 토큰을 사용한 후속 요청의 예 (Example subsequent request using continue token):

http

GET /apis/folder.grafana.app/v1/namespaces/default/folders?limit=1&continue=eyJvIj...NlfQ== HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예제 후속 응답 (Example subsequent response):

http

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1",
  "items": [
    {
      "kind": "Folder",
      "apiVersion": "folder.grafana.app/v1",
      "metadata": {
        "name": "bef30vrzxs3y8e",
        "namespace": "default",
        "uid": "YCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb5Y",
        "resourceVersion": "1741343687000",
        "creationTimestamp": "2025-03-07T10:35:47Z",
        "annotations": {
          "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
          "grafana.app/updatedTimestamp": "2025-03-07T10:35:47Z"
        }
      },
      "spec": {
        "title": "another folder"
      }
    }
  ]
}

metadata에 continue 필드가 없는 응답을 받아 마지막 페이지에 도달했음을 나타낼 때까지 업데이트된 continue 토큰으로 요청을 계속해요.

상태 코드:

200 – OK
401 – Unauthorized
403 – Access Denied

uid로 폴더 가져오기 (Get folder by uid)

GET /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

폴더 uid가 주어지면 폴더를 반환해요.

namespace: 어떤 네임스페이스를 사용할지에 대해 더 읽으려면 API 개요를 참고해요.
uid: 업데이트할 폴더의 고유 식별자. 폴더 응답에서 name이 될 거예요.

필수 권한

설명은 소개의 주석을 참고해요.

테이블 펼치기

Action	Scope
`folders:read`	`folders:*`

예제 요청 (Example Request):

http

GET /apis/folder.grafana.app/v1/namespaces/default/folders/aef30vrzxs3y8d HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예제 응답 (Example Response):

http

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "namespace": "default",
    "uid": "KCtv1FXDsJmTYQoTgcPnfuwZhDZge3uMpXOefaOHjb4X",
    "resourceVersion": "1741343686000",
    "creationTimestamp": "2025-03-07T10:34:46Z",
    "annotations": {
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T10:34:46Z",
      "grafana.app/folder": "fef30w4jaxla8b"
    }
  },
  "spec": {
    "title": "test"
  }
}

상위 폴더의 uid를 담고 있는 주석 grafana.app/folder를 참고해요.

상태 코드:

200 – Found
401 – Unauthorized
403 – Access Denied
404 – Folder not found

폴더 만들기 (Create folder)

POST /apis/folder.grafana.app/v1/namespaces/:namespace/folders

새 폴더를 만들어요.

namespace: 어떤 네임스페이스를 사용할지에 대해 더 읽으려면 API 개요를 참고해요.

필수 권한

설명은 소개의 주석을 참고해요.

folders:create는 폴더와 하위 폴더 생성을 허용해요. 범위 folders:uid:general로 부여되면 루트 수준 폴더 생성을 허용해요. 그렇지 않으면 지정된 폴더 아래에 하위 폴더 생성을 허용해요.

테이블 펼치기

Action	Scope
`folders:create`	`folders:*`
`folders:write`	`folders:*`

예제 요청 (Example Request):

http

POST /apis/folder.grafana.app/v1/namespaces/default/folders HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b"
    }
  },
  "spec": {
    "title": "child-folder"
  }
}

JSON 본문 스키마:

metadata.name – Grafana 고유 식별자. 이를 제공하고 싶지 않다면 metadata.generateName을 uid에 원하는 접두사로 설정해요.
metadata.annotations.grafana.app/folder - 선택 필드, 폴더가 생성되어야 할 상위 폴더의 고유 식별자. 중첩 폴더가 활성화되어 있어야 해요.
spec.title – 폴더의 제목.

Note metadata 필드의 커스텀 레이블과 주석은 일부 인스턴스에서 지원되며, 이 API가 일반 공개에 도달하면 모든 인스턴스에서 전체 지원이 계획되어 있어요. 인스턴스에서 아직 지원되지 않는다면 무시돼요.

예제 응답 (Example Response):

http

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "eef33r1fprd34d",
    "namespace": "default",
    "uid": "X8momvVZnsXdOqvLD9I4ngqLVif2CgRWXHy9xb2UgjQX",
    "resourceVersion": "1741320415009",
    "creationTimestamp": "2025-03-07T04:06:55Z",
    "labels": {
      "grafana.app/deprecatedInternalID": "1159"
    },
    "annotations": {
      "grafana.app/folder": "fef30w4jaxla8b",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb"
    }
  },
  "spec": {
    "title": "child-folder"
  }
}

상태 코드:

201 – Created
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access denied
409 – Conflict (folder with the same uid already exists)

폴더 업데이트 (Update folder)

PUT /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

uid로 식별되는 기존 폴더를 업데이트해요.

namespace: 어떤 네임스페이스를 사용할지에 대해 더 읽으려면 API 개요를 참고해요.
uid: 업데이트할 폴더의 고유 식별자. 폴더 응답에서 name이 될 거예요.

필수 권한

설명은 소개의 주석을 참고해요.

테이블 펼치기

Action	Scope
`folders:write`	`folders:*`

예제 요청 (Example Request):

http

PUT /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

{
  "metadata": {
    "name": "aef30vrzxs3y8d",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4"
    }
  },
  "spec": {
    "title": "updated title"
  }
}

JSON 본문 스키마:

metadata.name – 폴더의 고유 식별자.
metadata.annotations.grafana.app/folder - 선택 필드, 폴더가 위치해야 할 상위 폴더의 고유 식별자. 이를 업데이트하면 폴더를 다른 상위 폴더 아래로 이동해요. 중첩 폴더가 활성화되어 있어야 해요.
spec.title – 폴더의 제목.

Note metadata 필드의 커스텀 레이블과 주석은 일부 인스턴스에서 지원되며, 이 API가 일반 공개에 도달하면 모든 인스턴스에서 전체 지원이 계획되어 있어요. 인스턴스에서 아직 지원되지 않는다면 무시돼요.

예제 응답 (Example Response):

http

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "fef30w4jaxla8b",
    "namespace": "default",
    "uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
    "resourceVersion": "1741345736000",
    "creationTimestamp": "2025-03-07T11:08:56Z",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
    }
  },
  "spec": {
    "title": "updated title"
  }
}

상태 코드:

200 – Updated
400 – Errors (invalid json, missing or invalid fields, etc)
401 – Unauthorized
403 – Access Denied
404 – Folder not found
412 – Precondition failed (the folder has been changed by someone else). 이 상태 코드에서 응답 본문은 다음 속성을 갖게 돼요:

http

HTTP/1.1 412 Precondition Failed
Content-Type: application/json; charset=UTF-8
Content-Length: 97

{
  "message": "The folder has been changed by someone else",
  "status": "version-mismatch"
}

폴더 삭제 (Delete folder)

DELETE /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

UID로 식별되는 기존 폴더와 함께 폴더에 저장된 모든 대시보드(및 그 알림)를 삭제해요. 이 작업은 되돌릴 수 없어요.

Grafana Alerting이 활성화되어 있다면 선택적 쿼리 매개변수 forceDeleteRules=false를 설정해 폴더에 Grafana 알림이 포함된 경우 요청이 400(Bad Request) 오류로 실패하도록 할 수 있어요. 그러나 이 매개변수를 true로 설정하면 이 폴더 아래의 모든 Grafana 알림이 삭제돼요.

namespace: 어떤 네임스페이스를 사용할지에 대해 더 읽으려면 API 개요를 참고해요.
uid: 삭제할 폴더의 고유 식별자. 폴더 응답에서 name이 될 거예요.

필수 권한

설명은 소개의 주석을 참고해요.

테이블 펼치기

Action	Scope
`folders:delete`	`folders:*`

예제 요청 (Example Request):

http

DELETE /apis/folder.grafana.app/v1/namespaces/default/folders/fef30w4jaxla8b HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer <SERVI...KEN>

예제 응답 (Example Response):

http

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "Folder",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "name": "fef30w4jaxla8b",
    "namespace": "default",
    "uid": "YaWLsFrMwEaTlIQwX2iMnhHlJuZHtZugps50BQoyjXEX",
    "resourceVersion": "1741345736000",
    "creationTimestamp": "2025-03-07T11:08:56Z",
    "annotations": {
      "grafana.app/folder": "xkj92m5pqw3vn4",
      "grafana.app/createdBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedBy": "service-account:cef2t2rfm73lsb",
      "grafana.app/updatedTimestamp": "2025-03-07T11:08:56Z"
    }
  },
  "spec": {
    "title": "updated title"
  }
}

상태 코드:

200 – Deleted
401 – Unauthorized
400 – Bad Request
403 – Access Denied
404 – Folder not found

Folder API

Folder API

본문

요구 사항 (Requirements)

엔드포인트 (Endpoints)

모든 폴더 가져오기 (Get all folders)

uid로 폴더 가져오기 (Get folder by uid)

폴더 만들기 (Create folder)

폴더 업데이트 (Update folder)

폴더 삭제 (Delete folder)

더 알아보기 (Learn more)