Документацияbreadcrumb arrow Grafanabreadcrumb arrow Документация GlaberGraphbreadcrumb arrow Ресурсы для разработчиковbreadcrumb arrow API Grafanabreadcrumb arrow Справочное руководство по HTTP API Grafanabreadcrumb arrow API Structure

Новая структура HTTP API в Grafana

Note

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

В этом документе объясняется, как Grafana структурирует HTTP API /apis, которые используют уровень API в стиле Kubernetes со стандартизированной структурой и согласованным версионированием. Читайте далее, чтобы понять пути запросов, версии, пространства имён и общие поля ответов при переходе с устаревших конечных точек /api или при работе с новыми API.

Перед началом

Перед началом убедитесь, что у вас есть следующее:

  • Версия Grafana: используйте Grafana 12 или более позднюю.
  • Доступ к API: убедитесь, что вы можете отправлять HTTP-запросы к своему экземпляру Grafana.
  • Контекст устаревшего API: знайте, какие устаревшие конечные точки /api вы хотите заменить, если планируете миграцию.

Переход с устаревших конечных точек api

Grafana 13 объявляет устаревшими конечные точки устаревшего API (/api) в пользу нового поколения улучшенных API (/apis). Устаревшие API на данный момент не отключаются. Удаление устаревших API планируется в одном из будущих мажорных релизов, и о любых ломающих изменениях будет объявлено заранее, чтобы избежать сбоев.

Дополнительные сведения см. в разделе Переход на новые API.

Структура API

API Grafana используют общий формат пути и общую форму ответа.

Путь API

Все API Grafana следуют этому стандартизированному формату:

text 
/apis/<GROUP>/<VERSION>/namespaces/<NAMESPACE>/<RESOURCE>[/<NAME>]

Замените заполнители значениями для своей группы API, версии, пространства имён, ресурса и необязательного имени ресурса. Используйте конечный сегмент /<NAME> для операций над отдельными ресурсами, таких как получение, обновление или удаление. Опускайте его для операций над коллекциями, таких как получение списка или создание.

Формат ответа API

Все ответы API Grafana следуют этой структуре:

JSON 
{
  "kind": "<KIND>",
  "apiVersion": "<GROUP>/<VERSION>",
  "metadata": {
    "name": "<NAME>",
    "namespace": "<NAMESPACE>",
    "uid": "db323171-c78a-42fa-be98-16a3d799a779",
    "resourceVersion": "1758777451428472",
    "generation": 10,
    "creationTimestamp": "2026-01-23T22:06:40Z",
    "annotations": {}
  },
  "spec": {
    // resource-specific fields
  }
}

Замените заполнители значениями, возвращёнными запрошенным вами ресурсом.

Понимание компонентов

Каждая часть пути и ответа имеет определённое назначение.

Группа (<group>)

Группы организуют связанную функциональность в логические наборы. Например, dashboard.grafana.app используется для операций, связанных с дашбордами.

Версия (<version>)

API Grafana используют семантическое версионирование с тремя уровнями стабильности:

Уровень Формат Описание Сценарий использования Включено по умолчанию?
Alpha v1alpha1 Ранняя стадия разработки. Нестабильно, может содержать ошибки и подлежит удалению Для тестирования новых функций Нет
Beta v1beta1 Более стабильно, чем alpha, но всё ещё возможны некоторые изменения Для некритичного использования Нет
GA v1 Общедоступно (Generally Available). Стабильно с гарантиями обратной совместимости Для промышленной эксплуатации Да

Alpha

Версии Alpha не должны обслуживаться, если они явно не включены флагом функции, и должны считаться полностью экспериментальными и подверженными серьёзным изменениям. Версия alpha может претерпеть ломающие изменения без добавления новой версии, и на неё не следует полагаться в производственных процессах. Версии alpha могут быть удалены полностью, даже без повышения до более стабильного уровня (например, экспериментальный API может быть представлен как alpha для новой функции и впоследствии полностью удалён, если эта функция будет отменена).

Beta

Версии Beta не должны содержать ломающих изменений в схеме, но всё ещё могут быть подвержены изменениям в логике обработки или семантике. Ломающие изменения схемы требуют новой опубликованной версии beta (например, публикации v1beta2 для ломающих изменений в схеме v1beta1). Хотя версии beta больше не считаются экспериментальными, как версии alpha, они всё ещё должны быть отключены по умолчанию.

GA

Версии GA включены по умолчанию и могут считаться полностью стабильными. Единственные изменения, которые можно вносить в эти API, — это исправления ошибок, а любые другие изменения должны вместо этого приводить к публикации новой версии API.

Пространство имён (<namespace>)

Пространства имён изолируют ресурсы внутри вашего экземпляра Grafana. Формат зависит от типа развёртывания:

OSS и локальная Grafana

  • Организация по умолчанию: используйте default для организации 1.
  • Дополнительные организации: используйте org-<ORG_ID>.

Grafana Cloud

  • Формат: используйте stacks-<STACK_ID>.
  • ID экземпляра: ваш ID экземпляра — это STACK_ID.

ID экземпляра можно найти в следующих местах:

  • Портал Grafana Cloud: перейдите на grafana.com, откройте свой стек и выберите Details для вашего экземпляра Grafana.
  • Swagger UI: откройте страницу /swagger в вашем экземпляре Grafana Cloud, где пространство имён автоматически подставляется для соответствующих конечных точек.

Ресурс (<resource>)

Ресурс — это тип, с которым вы хотите взаимодействовать. Распространённые примеры включают следующее:

  • Дашборды: используйте dashboards.
  • Плейлисты: используйте playlists.
  • Папки: используйте folders.

Kind (<kind>)

Kind идентифицирует тип ресурса в ответах API и соответствует форме единственного числа ресурса. Например, ресурс dashboards имеет kind Dashboard.

Имя (<name>)

<name> — уникальный идентификатор конкретного экземпляра ресурса внутри его пространства имён и типа ресурса. <name> отличается от поля metadata.uid. В пути URL всегда используется metadata.name.

Например, чтобы получить дашборд, определённый как:

JSON 
{
  "kind": "Dashboard",
  "apiVersion": "dashboard.grafana.app/v1",
  "metadata": {
    "name": "production-overview", // This value IS used in the URL path
    "namespace": "default",
    "uid": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8" // This value is NOT used in the URL path
    // ... other metadata
  },
  "spec": {
    // ... dashboard spec
  }
}

Вы бы использовали следующий вызов API:

GET /apis/dashboard.grafana.app/v1/namespaces/default/dashboards/production-overview

Метаданные

Раздел метаданных содержит информацию об экземпляре ресурса. Этот раздел включает имя и пространство имён, описанные ранее в этом документе, а также следующие поля:

UID

Внутренний идентификатор, который можно игнорировать в большинстве сценариев использования. Вместо него используйте поле name как уникальный идентификатор. Это значение не совпадает с UID Grafana.

ResourceVersion

Значение, которое меняется при любом изменении ресурса, включая метаданные или статус.

Используйте это поле для:

  • Обнаружения изменений: отслеживания, изменился ли ресурс.
  • Оптимистичного контроля параллелизма: предотвращения перезаписи более новой версии ресурса.

Generation

Монотонно возрастающее число, которое увеличивается только при изменении spec. Обновления метаданных или статуса не влияют на это значение.

CreationTimestamp

Время создания объекта, отформатированное как метка времени RFC 3339 UTC (например, 2026-01-23T22:06:40Z).

Аннотации

Карта пар ключ-значение.

Распространённые аннотации включают:

  • grafana.app/createdBy и grafana.app/updatedBy: указывают, кто создал ресурс или последним обновил его. Используйте формат <USER_TYPE>:<UID>, например user:u000000839.
  • grafana.app/folder: если ресурс поддерживает папки, здесь содержится UID папки, к которой принадлежит объект.
  • grafana.app/updatedTimestamp: хранит время последнего обновления как метку времени RFC 3339 UTC, например 2026-01-23T05:17:31Z.

Метки

Необязательная карта пар ключ-значение для организации и выбора ресурсов.

Spec

Поле spec описывает желаемое состояние ресурса. Его структура зависит от типа ресурса и версии API. Точную схему spec ресурса см. в документации Swagger или OpenAPI.

Используйте следующие материалы для дальнейшей работы с API Grafana:

  • Руководство по миграции: см. Переход на новые API.
  • Справочник по HTTP API: см. Справочник по HTTP API.
  • Swagger UI: откройте страницу /swagger в вашем экземпляре Grafana, чтобы изучить схемы конечных точек и опробовать запросы.