菜单

数据源 HTTP API

Enterprise 开源

数据源 API

如果您正在运行 Grafana Enterprise，某些端点需要特定的权限。有关更多信息，请参阅基于角色的访问控制权限。

获取所有数据源

GET /api/datasources

警告
此 API 目前不支持分页。返回的数据源默认最大数量为 5000。您可以在 default.ini 文件中更改此值。

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
datasources:read	datasources:*

示例

请求示例:

GET /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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

根据 ID 获取单个数据源

GET /api/datasources/:datasourceId

警告
此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅根据 UID 获取单个数据源的 API 或根据名称获取单个数据源的 API。

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
datasources:read	datasources:* datasources:id:* datasources:id:1 (单个数据源)

示例

请求示例:

GET /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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
}

根据 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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

注意
通过在 secureJsonData 下定义 password 和 basicAuthPassword，Grafana 会将其安全地加密为数据库中的加密 blob。然后，响应会在 secureJsonFields 下列出加密字段。

启用基本身份验证的 Graphite 请求示例:

POST /api/datasources HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

启用基本身份验证的响应示例:

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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

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

根据 ID 更新现有数据源

PUT /api/datasources/:datasourceId

警告
此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅新的数据源更新 API。

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
datasources:write	datasources:* datasources:id:* datasources:id:1 (单个数据源)

示例

请求示例:

PUT /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id":1,
  "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
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "uid": "kLtEtcRGk",
    "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"
}

注意
类似于创建数据源，password 和 basicAuthPassword 应该在 secureJsonData 下定义，以便安全地存储为数据库中的加密 blob。然后，响应中的 secureJsonFields 部分会列出加密字段。

更新现有数据源

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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

{
  "id":1,
  "uid": "updated 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
}

响应示例:

HTTP/1.1 200
Content-Type: application/json

{
  "datasource": {
    "id": 1,
    "uid": "updated 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"
}

注意
类似于创建数据源，password 和 basicAuthPassword 应该在 secureJsonData 下定义，以便安全地存储为数据库中的加密 blob。然后，响应中的 secureJsonFields 部分会列出加密字段。

根据 ID 删除现有数据源

DELETE /api/datasources/:datasourceId

警告
此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅根据 UID 删除现有数据源的 API 或根据名称删除现有数据源的 API

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
datasources:delete	datasources:* datasources:id:* datasources:id:1 (单个数据源)

示例

请求示例:

DELETE /api/datasources/1 HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

{"message":"Data source deleted"}

根据 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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

根据名称删除现有数据源

DELETE /api/datasources/name/:datasourceName

所需权限

有关说明，请参阅介绍中的说明。

操作	范围
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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

HTTP/1.1 200
Content-Type: application/json

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

根据 ID 进行数据源代理调用

警告
此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅新的数据源请求代理 API。

GET /api/datasources/proxy/:datasourceId/*

将所有调用代理到由 datasourceId 标识的实际数据源。

数据源代理调用

GET /api/datasources/proxy/uid/:uid/*

将所有调用代理到由 uid 标识的实际数据源。

根据 ID 检查数据源健康状态

警告：此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅新的数据源健康检查 API。

GET /api/datasources/:datasourceId/health

调用由给定 datasourceId 标识的数据源的健康端点。这不是强制性的 - 每个插件作者都必须在他们的插件中自行实现对健康检查的支持。

示例

请求示例:

GET api/datasources/112/health HTTP/1.1
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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/health

调用由给定 uid 标识的数据源的健康端点。这不是强制性的 - 每个插件作者都必须在他们的插件中自行实现对健康检查的支持。

示例

请求示例:

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

响应示例:

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

根据 ID 获取数据源资源

警告
此 API 自 Grafana v9.0.0 起已弃用，并将在未来版本中移除。请参阅新的数据源资源 API。

GET /api/datasources/:datasourceId/resources/*

调用由给定 dashboardId 标识的数据源的资源端点。

示例

请求示例:

GET api/datasources/112/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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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

获取数据源资源

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 eyJrIjoiT0tTcG1pUlY2RnVKZTFVaDFsNFZXdE9ZWmNrMkZYbk

响应示例:

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

注意
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 Body Schema

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）。要更好地了解如何为特定数据源构建查询，请使用您所选浏览器的开发者工具，检查发送到 /api/ds/query 的 HTTP 请求。

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	发生意外错误。请参考响应体和/或服务器日志获取更多详细信息。