API папок | Grafana Labs

Документация

Grafana

Документация GlaberGraph

Ресурсы для разработчиков

API Grafana

Справочное руководство по HTTP API Grafana

API папок

Note
Доступно в Grafana 12 и более поздних версиях.

Этот API соответствует новой структуре API Grafana. Дополнительные сведения см. в документации о структуре API в Grafana.

Этот документ может не содержать последнюю версию API. Самый актуальный список доступных конечных точек см. в folder.grafana.app/v1 в Swagger.

Требования

Если вы используете Grafana Enterprise, для некоторых конечных точек потребуются определённые права. Дополнительные сведения см. в разделе Права управления доступом на основе ролей.

Конечные точки

Метод	URI	Описание
GET	/apis/folder.grafana.app/v1/namespaces/:namespace/folders	Получить все папки
GET	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Получить папку по uid
POST	/apis/folder.grafana.app/v1/namespaces/:namespace/folders	Создать папку
PUT	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Обновить папку
DELETE	/apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid	Удалить папку

Получение всех папок

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

Возвращает все папки, которые аутентифицированный пользователь имеет право просматривать в данной организации. Используйте параметр запроса limit, чтобы управлять максимальным количеством возвращаемых дашбордов. Чтобы получить дополнительные дашборды, используйте токен continue, предоставленный в ответе, для получения следующей страницы.

namespace: подробнее о том, какое пространство имён использовать, см. в обзоре API.

Параметры запроса:

limit (необязательно): максимальное количество возвращаемых папок
continue (необязательно): токен продолжения из предыдущего ответа для получения следующей страницы

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
`folders:read`	`folders:*`

Пример запроса:

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

Пример ответа:

HTTP/1.1 200
Content-Type: application/json
{
  "kind": "FolderList",
  "apiVersion": "folder.grafana.app/v1",
  "metadata": {
    "continue": "eyJvIjoxNTIsInYiOjE3NjE3MDQyMjQyMDcxODksInMiOmZhbHNlfQ=="
  },
  "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 содержит токен для получения следующей страницы.

Пример последующего запроса с использованием токена продолжения:

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

Пример последующего ответа:

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"
      }
    }
  ]
}

Продолжайте выполнять запросы с обновлённым токеном continue, пока не получите ответ без поля continue в метаданных, что означает, что вы достигли последней страницы.

Коды состояния:

200 – OK
401 – Не авторизован
403 – Доступ запрещён

Получение папки по uid

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

Возвращает папку по uid папки.

namespace: подробнее о том, какое пространство имён использовать, см. в обзоре API.
uid: уникальный идентификатор обновляемой папки. Это будет name в ответе папки

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
`folders:read`	`folders:*`

Пример запроса:

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

Пример ответа:

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"
  }
}

Обратите внимание на аннотацию grafana.app/folder, которая содержит uid родительской папки.

Коды состояния:

200 – Найдено
401 – Не авторизован
403 – Доступ запрещён
404 – Папка не найдена

Создание папки

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

Создаёт новую папку.

namespace: подробнее о том, какое пространство имён использовать, см. в обзоре API.

Требуемые права

Пояснения см. в примечании во введении.

folders:create позволяет создавать папки и подпапки. Если предоставлено с областью folders:uid:general, позволяет создавать папки корневого уровня. В противном случае позволяет создавать подпапки в указанных папках.

Действие	Область
`folders:create`	`folders:*`
`folders:write`	`folders:*`

Пример запроса:

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

{
  "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 станут общедоступными. Если они пока не поддерживаются на вашем экземпляре, они будут игнорироваться.

Пример ответа:

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 – Создано
400 – Ошибки (некорректный json, отсутствующие или недопустимые поля и т. д.)
401 – Не авторизован
403 – Доступ запрещён
409 – Конфликт (папка с таким же uid уже существует)

Обновление папки

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

Обновляет существующую папку, идентифицируемую uid.

namespace: подробнее о том, какое пространство имён использовать, см. в обзоре API.
uid: уникальный идентификатор обновляемой папки. Это будет name в ответе папки

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
`folders:write`	`folders:*`

Пример запроса:

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

{
  "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 станут общедоступными. Если они пока не поддерживаются на вашем экземпляре, они будут игнорироваться.

Пример ответа:

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 – Обновлено
400 – Ошибки (некорректный json, отсутствующие или недопустимые поля и т. д.)
401 – Не авторизован
403 – Доступ запрещён
404 – Папка не найдена
412 – Предусловие не выполнено (папка была изменена кем-то другим). С этим кодом состояния тело ответа будет содержать следующие свойства:

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 /apis/folder.grafana.app/v1/namespaces/:namespace/folders/:uid

Удаляет существующую папку, идентифицируемую UID, вместе со всеми дашбордами (и их алертами), хранящимися в этой папке. Эту операцию нельзя отменить.

Если включён Grafana Alerting, можно задать необязательный параметр запроса forceDeleteRules=false, чтобы запросы завершались ошибкой 400 (Bad Request), если папка содержит какие-либо алерты Grafana. Однако если этот параметр установлен в true, будут удалены все алерты Grafana в этой папке.

namespace: подробнее о том, какое пространство имён использовать, см. в обзоре API.
uid: уникальный идентификатор удаляемой папки. Это будет name в ответе папки

Требуемые права

Пояснения см. в примечании во введении.

Действие	Область
`folders:delete`	`folders:*`

Пример запроса:

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

Пример ответа:

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 – Удалено
401 – Не авторизован
400 – Некорректный запрос
403 – Доступ запрещён
404 – Папка не найдена

Была ли эта страница полезна?

Написать на docs@glaber.ru

Справка и поддержка

Сообщество