跳到主要内容

插件元数据 (plugin.json)

plugin.json 文件是所有插件必需的。当 Grafana 启动时，它会扫描插件文件夹，并挂载包含 plugin.json 文件的所有文件夹，除非该文件夹包含名为 dist 的子文件夹。在这种情况下，Grafana 会改为挂载 dist 文件夹。

属性

名称类型描述必需
id字符串插件的唯一名称。如果插件发布在 grafana.com 上，则插件 id 必须遵循命名约定。
模式: ^[0-9a-z]+\-([0-9a-z]+\-)?(app|panel|datasource)$
✅
type字符串插件类型。
枚举: "app", "datasource", "panel", "renderer"
✅
info对象插件的元数据。部分字段用于 Grafana 的插件页面，如果插件已发布，则部分字段用于 grafana.com。
✅
name字符串插件的人类可读名称，显示在 UI 中给用户看。
✅
dependencies对象与 Grafana 和其他插件相关的依赖信息。
✅
$schema字符串plugin.json 文件的模式定义。主要用于模式验证。
alerting布尔值对于数据源插件，表示插件是否支持告警。需要将 backend 设置为 true。
annotations布尔值对于数据源插件，表示插件是否支持注解查询。
autoEnabled布尔值对于应在所有组织中启用并固定到导航栏的应用插件，请设置为 true。
backend布尔值表示插件是否具有后端组件。
buildMode字符串插件的构建模式。此字段在构建时自动设置，因此不应手动提供。
builtIn布尔值[仅限内部使用] 指示插件是否作为 Grafana 的一部分进行开发和分发。也称为“核心插件”。
category字符串在“添加数据源”页面上使用的插件类别。
枚举: "tsdb", "logging", "cloud", "tracing", "profiling", "sql", "enterprise", "iot", "other"
enterpriseFeatures对象Grafana Enterprise 特定的功能
executable字符串后端组件可执行文件文件名的第一部分。可以针对不同的操作系统和架构构建多个可执行文件。Grafana 将检查名为 <executable>_<$GOOS>_<lower case $GOARCH><.exe for Windows> 的可执行文件，例如 plugin_linux_amd64。$GOOS 和 $GOARCH 的组合可以在此处找到：https://golang.ac.cn/doc/install/source#environment。
hideFromList布尔值[仅限内部使用] 从 Grafana 的 UI 列表中排除插件。仅允许用于 builtIn 插件。
includes对象数组包含在插件中的资源。
logs布尔值对于数据源插件，表示插件是否支持日志。它可能用于过滤仅日志功能。
metrics布尔值对于数据源插件，表示插件是否支持指标查询。用于在面板编辑器中启用插件。
multiValueFilterOperators布尔值对于数据源插件，表示插件是否支持 adhoc 过滤器中的多值运算符。
pascalName字符串[仅限内部使用] 插件的 PascalCase 名称。用于创建机器友好的标识符，通常用于代码生成。如果未提供，则默认为 name，但会转换为首字母大写并进行净化（仅允许字母字符）。
模式: ^([A-Z][a-zA-Z]{1,62})$
preload布尔值在启动时初始化插件。默认情况下，插件在首次使用时初始化，但当 preload 设置为 true 时，插件会在 Grafana web 应用首次加载时加载。仅适用于应用插件。设置为 true 时，请实现前端代码分割以最大程度地减少性能影响。
queryOptions对象对于数据源插件。插件的查询编辑器中有一个查询选项部分，如果需要可以启用这些选项。
routes对象数组对于数据源插件。用于插件认证和向插件发出的 HTTP 请求添加请求头的代理路由。有关更多信息，请参阅数据源插件的认证。
skipDataQuery布尔值对于面板插件。隐藏查询编辑器。
state字符串将插件标记为预发布版本。
枚举: "alpha", "beta"
streaming布尔值对于数据源插件，表示插件是否支持流式传输。用于在 Explore 中启动实时流式传输。
tracing布尔值对于数据源插件，表示插件是否支持追踪。例如，用于将日志（如 Loki 日志）与追踪插件关联。
iam对象Grafana 读取 Identity and Access Management 部分，并为插件初始化一个服务账号，该账号具有一套定制的 Grafana RBAC 权限。Grafana 将使用 GF_PLUGIN_APP_CLIENT_SECRET 环境变量与插件后端共享该服务账号的持有者令牌。需要 Grafana 10.3.0 或更高版本。目前，此功能位于 externalServiceAccounts 功能开关之后。要试用此功能，请按照此指南进行操作。
roles对象数组插件定义的 RBAC 角色列表及其与基本角色（Viewer、Editor、Admin、Grafana Admin）的默认分配。需要 Grafana 9.4.0 或更高版本。
extensions对象插件扩展是一种扩展 Grafana 核心 UI 或其他插件的方式。

info​

插件的元数据。部分字段用于 Grafana 的插件页面，如果插件已发布，则部分字段用于 grafana.com。

属性

名称类型描述必需
author对象关于插件作者的信息。
build对象构建信息
description字符串插件描述。用于 Grafana 的插件页面和 grafana.com 上的搜索。
keywords字符串数组插件关键词数组。用于 grafana.com 上的搜索。
✅
links对象数组要在该插件项目页面上显示的链接对象数组，格式为 {name: 'foo', url: 'http://example.com'}
logos对象用作插件图标的 SVG 图像。
✅
screenshots对象数组截图对象数组，格式为 {name: 'bar', path: 'img/screenshot.png'}
updated字符串此插件构建的日期。
模式: ^(\d{4}-\d{2}-\d{2}|\%TODAY\%)$
✅
version字符串此提交的SemVer 版本，例如 6.7.1。
模式: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)|(\%VERSION\%)$
✅

info.author​

关于插件作者的信息。

属性

名称类型描述必需
name字符串作者姓名。
email字符串作者姓名。
格式: "email"
url字符串作者网站链接。
格式: "uri"

info.build​

构建信息

属性

名称类型描述必需
time数字插件构建时的时间，以 Unix 时间戳表示。
repo字符串
branch字符串构建插件所用的 Git 分支。
hash字符串构建插件所用的 Git 提交哈希值
数字数字
pr数字构建插件所用的 GitHub pull request
build数字构建此插件所用的构建作业编号。

info.keywords[]​

插件关键词数组。用于 grafana.com 上的搜索。

项

项类型： 字符串
最小项数 1

要在该插件项目页面上显示的链接对象数组，格式为 {name: 'foo', url: 'http://example.com'}

项

项属性

名称类型描述必需
name字符串链接的显示名称。具有预定义行为的特殊名称
• documentation - 在插件详情页设置文档链接
• repository - 用于确定并链接到插件的代码库
• license - 在插件详情页设置许可证链接
• raise issue - 在插件详情页设置提出问题链接
• sponsorship - 在插件详情页设置赞助此开发者链接，引导用户了解如何支持您的工作
url字符串此特定链接使用的 URL 值。
格式: "uri"

info.logos​

用作插件图标的 SVG 图像。

属性

名称类型描述必需
small字符串指向插件小版本 Logo 的链接，必须是 SVG 图像。“大”和“小”Logo 可以是同一图像。
✅
large字符串指向插件大版本 Logo 的链接，必须是 SVG 图像。“大”和“小”Logo 可以是同一图像。
✅

info.screenshots[]​

截图对象数组，格式为 {name: 'bar', path: 'img/screenshot.png'}

项

项属性

名称类型描述必需
name字符串
path字符串

dependencies​

与 Grafana 和其他插件相关的依赖信息。

属性

名称类型描述必需
grafanaVersion字符串（已弃用）此插件所需的 Grafana 版本，例如 6.x.x 7.x.x 表示插件需要 Grafana v6.x.x 或 v7.x.x。
模式: ^([0-9]+)(\.[0-9x]+)?(\.[0-9x])?$
grafanaDependency字符串此插件所需的 Grafana 版本。使用 https://github.com/npm/node-semver 进行验证。
模式: ^(<=|>=|<|>|=|~|\^)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?(\s(<=|>=|<|=>)?([0-9]+)(\.[0-9x\*]+)?(\.[0-9x\*]+)?)?$
✅
plugins对象数组此插件依赖的必需插件数组。只有非核心（即外部插件）才必须在此列表中指定。
extensions对象此插件依赖的插件扩展。

dependencies.plugins[]​

此插件依赖的必需插件数组。只有非核心（即外部插件）才必须在此列表中指定。

项

插件依赖项。用于在 Grafana UI 中显示有关插件依赖项的信息。

项属性

名称类型描述必需
id字符串模式: ^[0-9a-z]+\-([0-9a-z]+\-)?(app|panel|datasource)$
✅
type字符串枚举: "app", "datasource", "panel"
✅
name字符串✅

dependencies.extensions​

此插件依赖的插件扩展。

属性

名称类型描述必需
exposedComponents字符串数组此插件依赖的暴露组件 ID 数组。

dependencies.extensions.exposedComponents[]​

此插件依赖的暴露组件 ID 数组。

项

项类型： 字符串

enterpriseFeatures​

Grafana Enterprise 特定的功能

属性

名称类型描述必需
healthDiagnosticsErrors布尔值启用/禁用健康诊断错误。需要 Grafana >=7.5.5。
默认值: false

includes[]​

包含在插件中的资源。

项

项属性

名称类型描述必需
uid字符串包含的资源的唯一标识符
type字符串枚举: "dashboard", "page", "panel", "datasource"
name字符串
component字符串（旧版）用于页面的 Angular 组件。
role字符串用户在导航菜单中查看此页面所需的最低角色。
枚举: "Admin", "Editor", "Viewer"
action字符串用户在导航菜单中查看此页面必须具有的 RBAC 操作。警告：除非操作目标是插件，否则仅验证操作本身，而不验证其应用的具体内容。
path字符串用于应用插件。
addToNav布尔值将此项添加到导航菜单。
defaultNav布尔值当用户点击侧边菜单中的图标时显示的页面或仪表盘。
icon字符串在侧边菜单中使用的图标。有关可用图标的信息，请参阅图标概述。

queryOptions​

对于数据源插件。插件的查询编辑器中有一个查询选项部分，如果需要可以启用这些选项。

属性

名称类型描述必需
maxDataPoints布尔值对于数据源插件。表示是否应在查询编辑器的查询选项部分显示最大数据点选项。
minInterval布尔值对于数据源插件。表示是否应在查询编辑器的查询选项部分显示最小间隔选项。
cacheTimeout布尔值对于数据源插件。表示是否应在查询编辑器的查询选项部分显示缓存超时选项。

routes[]​

对于数据源插件。用于插件认证和向插件发出的 HTTP 请求添加请求头的代理路由。有关更多信息，请参阅数据源插件的认证。

项

项属性

名称类型描述必需
path字符串对于数据源插件。调用被代理时，由 route URL 字段替换的路由路径。
method字符串对于数据源插件。路由方法匹配 HTTP 动词，如 GET 或 POST。可以提供逗号分隔的多个方法列表。
url字符串对于数据源插件。Route URL 是请求被代理到的位置。
reqSignedIn布尔值
reqRole字符串
reqAction字符串用户使用此路由必须具有的 RBAC 操作。警告：除非操作目标是插件（或嵌套的数据源插件），否则仅验证操作本身，而不验证其应用的具体内容。
headers数组对于数据源插件。路由头用于向代理请求添加 HTTP 头。
body对象对于数据源插件。路由头设置代理请求的主体内容和长度。（*注意：原文此处描述似乎有误，可能应指 body 本身而非 headers*）
tokenAuth对象对于数据源插件。与 OAuth API 一起使用的令牌认证部分。
jwtTokenAuth对象对于数据源插件。与 JWT OAuth API 一起使用的令牌认证部分。
urlParams对象数组向代理路由添加 URL 参数

routes[].headers[]​

对于数据源插件。路由头用于向代理请求添加 HTTP 头。

routes[].body​

对于数据源插件。路由头设置代理请求的主体内容和长度。（*注意：原文此处描述似乎有误，可能应指 body 本身而非 headers*）

routes[].tokenAuth​

对于数据源插件。与 OAuth API 一起使用的令牌认证部分。

属性

名称类型描述必需
url字符串用于获取认证令牌的 URL。
scopes字符串数组您的应用程序应被授予访问权限的范围列表。
params对象令牌认证请求的参数。

routes[].tokenAuth.scopes[]​

您的应用程序应被授予访问权限的范围列表。

项

项类型： 字符串

routes[].tokenAuth.params​

令牌认证请求的参数。

属性

名称类型描述必需
grant_type字符串OAuth 授权类型
client_id字符串OAuth 客户端 ID
client_secret字符串OAuth 客户端 secret。通常通过解密 SecureJson blob 中的 secret 来填充。
resource字符串OAuth 资源

routes[].jwtTokenAuth​

对于数据源插件。与 JWT OAuth API 一起使用的令牌认证部分。

属性

名称类型描述必需
url字符串用于获取 JWT 令牌的 URL。
格式: "uri"
scopes字符串数组您的应用程序应被授予访问权限的范围列表。
params对象JWT 令牌认证请求的参数。

routes[].jwtTokenAuth.scopes[]​

您的应用程序应被授予访问权限的范围列表。

项

项类型： 字符串

routes[].jwtTokenAuth.params​

JWT 令牌认证请求的参数。

属性

名称类型描述必需
token_uri字符串
client_email字符串
private_key字符串

routes[].urlParams[]​

向代理路由添加 URL 参数

项

项属性

名称类型描述必需
name字符串URL 参数名称
content字符串URL 参数值

iam​

Grafana 读取 Identity and Access Management 部分，并为插件初始化一个服务账号，该账号具有一套定制的 Grafana RBAC 权限。Grafana 将使用 GF_PLUGIN_APP_CLIENT_SECRET 环境变量与插件后端共享该服务账号的持有者令牌。需要 Grafana 10.3.0 或更高版本。目前，此功能位于 externalServiceAccounts 功能开关之后。要试用此功能，请按照此指南进行操作。

属性

名称类型描述必需
permissions对象数组权限是插件需要其关联服务账号拥有的、用于查询 Grafana 的权限。

iam.permissions[]​

权限是插件需要其关联服务账号拥有的、用于查询 Grafana 的权限。

项

项属性

名称类型描述必需
action字符串操作，例如：teams:read。
scope字符串插件需要访问的范围，例如：teams:*。

roles[]​

插件定义的 RBAC 角色列表及其与基本角色（Viewer、Editor、Admin、Grafana Admin）的默认分配。需要 Grafana 9.4.0 或更高版本。

项

项属性

名称类型描述必需
role对象角色将您的插件相关的 RBAC 权限分组（例如：Projects Admin 会将创建、读取、写入和删除项目的权限分组）。您的角色中定义的 RBAC 操作必须以您的插件 id 开头（例如：grafana-test-app.projects:read）。
grants字符串数组角色与 Grafana 基本角色（Viewer、Editor、Admin、Grafana Admin）的默认分配。

roles[].role​

角色将您的插件相关的 RBAC 权限分组（例如：Projects Admin 会将创建、读取、写入和删除项目的权限分组）。您的角色中定义的 RBAC 操作必须以您的插件 id 开头（例如：grafana-test-app.projects:read）。

属性

名称类型描述必需
name字符串角色的显示名称。
description字符串描述角色的目的。
permissions对象数组插件上的 RBAC 权限。

roles[].role.permissions[]​

插件上的 RBAC 权限。

项

项属性

名称类型描述必需
action字符串
scope字符串

roles[].grants[]​

角色与 Grafana 基本角色（Viewer、Editor、Admin、Grafana Admin）的默认分配。

项

项类型： 字符串

extensions​

插件扩展是一种扩展 Grafana 核心 UI 或其他插件的方式。

属性

名称类型描述必需
addedComponents对象数组此列表必须包含您的插件使用 .addComponent() 注册到其他扩展点的所有组件扩展。未在此处列出的组件将无法工作。
addedLinks对象数组此列表必须包含您的插件使用 .addLink() 注册到其他扩展点的所有链接扩展。未在此处列出的链接将无法工作。
exposedComponents对象数组此列表必须包含您的插件使用 .exposeComponent() 暴露的所有组件。未在此处列出的组件将无法工作。
extensionPoints对象数组此列表必须包含您的插件使用 usePluginLinks() 或 usePluginComponents() 定义的所有扩展点。未在此处列出的扩展点将无法工作。

extensions.addedComponents[]​

此列表必须包含您的插件使用 .addComponent() 注册到其他扩展点的所有组件扩展。未在此处列出的组件将无法工作。

项

项属性

名称类型描述必需
targets字符串数组您的插件注册扩展所针对的扩展点 ID，例如 ["grafana/user/profile/tab"]
✅
title字符串您的组件扩展的标题。
最小长度: 10
✅
description字符串关于您的组件扩展的附加信息。

extensions.addedComponents[].targets[]​

您的插件注册扩展所针对的扩展点 ID，例如 ["grafana/user/profile/tab"]

项

项类型： 字符串

此列表必须包含您的插件使用 .addLink() 注册到其他扩展点的所有链接扩展。未在此处列出的链接将无法工作。

项

项属性

名称类型描述必需
targets字符串数组您的插件注册扩展所针对的扩展点 ID，例如 ["grafana/dashboard/panel/menu"]
✅
title字符串您的链接扩展的标题。
最小长度: 10
✅
description字符串关于您的链接扩展的附加信息。

extensions.addedLinks[].targets[]​

您的插件注册扩展所针对的扩展点 ID，例如 ["grafana/dashboard/panel/menu"]

项

项类型： 字符串

extensions.exposedComponents[]​

此列表必须包含您的插件使用 .exposeComponent() 暴露的所有组件。未在此处列出的组件将无法工作。

项

项属性

名称类型描述必需
id字符串暴露组件的唯一标识符。用于在其他插件中引用该组件。格式必须如下：{PLUGIN_ID}/component-name/v1。建议添加版本后缀以防止未来出现重大更改。例如：myorg-extensions-app/exposed-component/v1。
模式: ^[0-9a-z]+-([0-9a-z]+-)?(app|panel|datasource)\/[a-zA-Z0-9_-]+\/v[0-9_.-]+$
✅
title字符串您的暴露组件的标题。
description字符串关于您的暴露组件的附加信息。

extensions.extensionPoints[]​

此列表必须包含您的插件使用 usePluginLinks() 或 usePluginComponents() 定义的所有扩展点。未在此处列出的扩展点将无法工作。

项

项属性

名称类型描述必需
id字符串您的扩展点的唯一标识符。用于在其他插件中引用该扩展点。格式必须如下：{PLUGIN_ID}/extension-point-name/v1。建议添加版本后缀以防止未来出现重大更改。例如：myorg-extensions-app/extension-point/v1。
模式: ^[0-9a-z]+-([0-9a-z]+-)?(app|panel|datasource)\/[a-zA-Z0-9_-]+\/v[0-9_.-]+$
✅
title字符串您的扩展点的标题。
description字符串关于您的扩展点的附加信息。