grafana-client

关于

用于访问Grafana HTTP API的客户端库，用Python编写。

设置

从PyPI安装包。

pip install grafana-client --upgrade

用法

API概述

本节为您提供了如何通过一些示例使用API的思路。

from grafana_client import GrafanaApi

# Connect to Grafana API endpoint using the `GrafanaApi` class
grafana = GrafanaApi.from_url(
    "https://username:password@daq.example.org/grafana/")

# Create user
user = grafana.admin.create_user({
    "name": "User", 
    "email": "user@example.org", 
    "login": "user", 
    "password": "userpassword", 
    "OrgId": 1,
})

# Change user password
user = grafana.admin.change_user_password(2, "newpassword")

# Search dashboards based on tag
grafana.search.search_dashboards(tag="applications")

# Find a user by email
user = grafana.users.find_user("test@example.org")

# Add user to team 2
grafana.teams.add_team_member(2, user["id"])

# Create or update a dashboard
grafana.dashboard.update_dashboard(
    dashboard={"dashboard": {...}, "folderId": 0, "overwrite": True})

# Delete a dashboard by UID
grafana.dashboard.delete_dashboard(dashboard_uid="foobar")

# Create organization
grafana.organization.create_organization(
    organization={"name": "new_organization"})

或者使用异步代码...接口与处理协程（async/await）的实际情况相同。

from grafana_client import AsyncGrafanaApi
import asyncio

async def main():
    # Connect to Grafana API endpoint using the `GrafanaApi` class
    grafana = AsyncGrafanaApi.from_url("https://username:password@daq.example.org/grafana/")
    
    # Create user
    user = await grafana.admin.create_user({
        "name": "User", 
        "email": "user@example.org", 
        "login": "user", 
        "password": "userpassword", 
        "OrgId": 1,
    })
    
    # Change user password
    user = await grafana.admin.change_user_password(2, "newpassword")

asyncio.run(main())

示例程序

在仓库的示例文件夹中，您可以找到一些完整的示例程序，以帮助您开始。

请随意使用它们作为您自己程序的蓝图。如果您认为您的练习对其他人可能有帮助，请不要犹豫，分享它们。

身份验证

有几种方式可以验证Grafana HTTP API。

1. 匿名访问
2. Grafana API令牌
3. HTTP基本身份验证
4. HTTP头身份验证

Grafana管理API是Grafana API的一个子集。要访问这些API资源，您需要使用HTTP基本身份验证。

from grafana_client import GrafanaApi, HeaderAuth, TokenAuth

# 1. Anonymous access
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
)

# 2. Use Grafana API token.
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
    credential=TokenAuth(token="eyJrIjoiWHg...dGJpZCI6MX0="),
)

# 3. Use HTTP basic authentication.
grafana = GrafanaApi.from_url(
    url="https://username:password@daq.example.org/grafana/",
)
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
    credential=("username", "password")
)

# 4. Use HTTP Header authentication.
grafana = GrafanaApi.from_url(
    url="https://daq.example.org/grafana/",
    credential=HeaderAuth(name="X-WEBAUTH-USER", value="foobar"),
)

# Optionally turn off TLS certificate verification.
grafana = GrafanaApi.from_url(
    url="https://username:password@daq.example.org/grafana/?verify=false",
)

# Use `GRAFANA_URL` and `GRAFANA_TOKEN` environment variables.
grafana = GrafanaApi.from_env()

请注意，除了上述特定示例之外，通过credential获得的对象可以是任意的niquests.auth.AuthBase实例。

选择组织

如果Grafana API以用户身份进行身份验证（例如，使用HTTP基本身份验证），它将使用用户的当前组织上下文。可以使用GrafanaApi.user.switch_actual_user_organisation函数更改此上下文。

grafana.user.switch_actual_user_organisation(1)

GrafanaApi的实例也可以通过organization_id参数绑定到单个组织，确保所有请求都将针对该组织进行。此参数将导致GrafanaClient使用X-Grafana-Org-Id头。

grafana = GrafanaApi(..., organization_id=1)

API令牌绑定到单个组织，因此不需要指定organization_id参数。

超时设置

默认超时值为五秒，用于连接和读取超时。

GrafanaApi和GrafanaClient的构造函数以及工厂方法from_url和from_env接受timeout参数，该参数可以作为一个标量float值，也可以作为一个元组(, )。

代理

底层niquests库尊重HTTP_PROXY和HTTPS_PROXY环境变量。在调用使用grafana-client的应用程序之前设置它们已被证实是有效的。例如

export HTTP_PROXY=10.10.1.10:3128
export HTTPS_PROXY=10.10.1.11:1080

DNS解析器

niquests支持使用自定义DNS解析器，例如DNS-over-HTTPS和DNS-over-QUIC，但不仅限于这些。您需要设置NIQUESTS_DNS_URL环境变量。例如

export NIQUESTS_DNS_URL="doh+cloudflare://"

请参阅文档以了解更多关于接受的URL参数和协议的信息。

详细信息

本节文档概述了Grafana HTTP API的支持部分及其程度。另请参阅Grafana HTTP API参考。

兼容性

grafana-client在大多数情况下与Grafana 5.x-10.x兼容。但是，Grafana的早期版本可能不支持某些功能或子系统。

概述

数据源健康检查

简介

为了检查Grafana数据源是否健康，Grafana 9和更新的版本有一个服务器端数据源健康检查API。对于早期版本，提供了一个客户端实现。

此实现与在用户界面创建数据源时“保存并测试”按钮的功能方式相同。

您可以通过该存储库的示例文件夹中的相应客户端程序来探索此功能。

兼容性

数据源健康检查所需的最小版本为Grafana 7。Prometheus仅在Grafana 8及更高版本上运行。

数据源覆盖范围

以下Grafana数据源类型支持健康检查。

• CrateDB
• Elasticsearch
• Graphite
• InfluxDB
• Jaeger
• Loki
• Microsoft SQL Server
• OpenTSDB
• PostgreSQL
• Prometheus
• Tempo
• Testdata
• Zipkin

我们谦卑地向社区呼吁，为其他数据源类型（无论流行与否）贡献适配器。

应用程序

基于grafana-client的应用程序列表。

• grafana-import-tool
• grafana-ldap-sync-script
• grafana-snapshots-tool
• grafana-wtf
• nixops-grafana

项目信息

历史

该库最初由Andrew Prokhorenkov和贡献者作为grafana_api构思。非常感谢您的努力！

在对grafana_api的后续维护中，我们讨论了分支的需求，因为自一年多以来该存储库就没有收到更新。在分支它时，我们将包重命名为grafana-client并略微缩减了模块命名空间。

致谢

感谢原始作者和所有贡献者，他们以某种方式共同创造和构思了这款软件。您知道您是谁。

贡献

任何形式的贡献和反馈都非常欢迎！如果您认为我们应该包含新功能，或者报告或修复错误，请创建问题或提交补丁。

问题跟踪器URL为：https://github.com/panodata/grafana-client/issues

开发

为了设置grafana-client的开发环境，请按照开发文档进行操作。

许可证

grafana-client根据MIT许可证的条款进行许可，请参阅LICENSE文件。