API источников данных

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

Grafana

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

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

API Grafana

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

Устаревший HTTP API Grafana

API источников данных

Warning

[ru] DOCS_SHARED: "docs/grafana/latest/developer-resources/api-reference/http-api/api-legacy/data_source.ru.md" ("/hugo/content/docs/grafana/latest/developer-resources/api-reference/http-api/api-legacy/data_source.ru.md:25:1") shared directory "docs/grafana/latest/shared" not found

Требования

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

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

Метод	URI	Описание
GET	/api/datasources	Получить все источники данных
GET	/api/datasources/uid/:uid	Получить один источник данных по uid
GET	/api/datasources/name/:name	Получить один источник данных по имени (устарело)
GET	/api/datasources/id/:name	Получить Id источника данных по имени (устарело)
POST	/api/datasources	Создать источник данных
PUT	/api/datasources/uid/:uid	Обновить существующий источник данных
DELETE	/api/datasources/uid/:uid	Удалить существующий источник данных по uid
DELETE	/api/datasources/name/:datasourceName	Удалить существующий источник данных по имени (устарело)
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

Warning
Этот API в настоящее время не поддерживает постраничную выдачу. Максимальное количество возвращаемых источников данных по умолчанию — 5000. Это значение можно изменить в файле default.ini.

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

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

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

Примеры

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

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

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

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

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

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

Warning
Этот API устарел и будет удалён в будущем релизе.

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

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

Warning
Этот API устарел и будет удалён в будущем релизе.

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

HTTP/1.1 200
Content-Type: application/json

{
  "id":1
}

Создание источника данных

POST /api/datasources

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

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

Действие	Область
datasources:create	н/д

Примеры

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

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

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

Note
Определив password и basicAuthPassword в secureJsonData, Grafana безопасно шифрует их как зашифрованный блок в базе данных. Затем ответ перечисляет зашифрованные поля в разделе secureJsonFields.

Пример запроса Graphite с включённой basic-аутентификацией:

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

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

Пример ответа с включённой basic-аутентификацией:

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 <SERVICE_ACCOUNT_TOKEN>

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

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

Note
Как и при создании источника данных, password и basicAuthPassword следует определять в secureJsonData, чтобы они хранились безопасно как зашифрованный блок в базе данных. Затем зашифрованные поля перечисляются в разделе secureJsonFields в ответе.

Удаление существующего источника данных по uid

DELETE /api/datasources/uid/:uid

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

HTTP/1.1 200
Content-Type: application/json

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

Удаление существующего источника данных по имени

DELETE /api/datasources/name/:datasourceName

Warning
Этот API устарел и будет удалён в будущем релизе.

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

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

Действие	Область
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 <SERVICE_ACCOUNT_TOKEN>

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

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. Это не обязательно — каждый автор плагина должен сам реализовать поддержку проверок состояния в своём плагине.

Примеры

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

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

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

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.

Примеры

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

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 <SERVICE_ACCOUNT_TOKEN>

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

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

Note
Встроенные источники данных 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:

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, как показано в запросе выше). Чтобы лучше понять, как формировать запрос для определённого источника данных, используйте инструменты разработчика в вашем браузере и просмотрите HTTP-запросы, отправляемые к /api/ds/query.

Пример ответа на запрос временного ряда источника данных 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]
            ]
          }
        }
      ]
    }
  }
}

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

Код	Описание
200	Все запросы к источникам данных вернули успешный ответ.
400	Некорректный запрос из-за неверного JSON, отсутствующего типа содержимого, отсутствующих или недопустимых полей и т. д. Либо один или несколько запросов к источникам данных не выполнились. Подробности см. в теле ответа.
403	Доступ запрещён.
404	Не удалось найти источник данных или плагин, необходимый для выполнения запроса.
500	Непредвиденная ошибка. Подробности см. в теле ответа и/или журналах сервера.

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

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

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

Сообщество