为应用程序插件添加后端组件

应用程序插件的后端组件允许您扩展应用程序插件以添加额外的功能，例如自定义身份验证方法和与其他服务的集成。

以下是在应用程序插件中使用后端组件的典型用例

使用 Grafana 不支持的定制身份验证方法
使用 Grafana 不支持的授权检查
在服务器端运行工作负载
连接通常无法从浏览器连接的非 HTTP 服务

在开始之前

在添加后端组件之前安装以下先决条件

Go (版本)
Mage
LTS 版本的 Node.js
Docker

创建一个新的应用程序插件

Grafana create-plugin 工具是一个 CLI 应用程序，简化了 Grafana 插件开发，让您可以专注于代码。该工具为您搭建了一个起始插件、所有必需的配置以及使用 Docker Compose 的开发环境。

在新的目录中，使用 create-plugin 工具从模板创建一个插件。当提示选择插件类型时，选择 app，并回答“您想要插件的后端部分吗？”为是
```
npx @grafana/create-plugin@latest
```
转到您新创建的插件目录
```
cd <your-plugin>
```
安装依赖项
```
npm install
```
构建插件前端
```
npm run dev
```
在新的终端窗口中，构建插件后端
```
mage -v build:linux
```
启动 Grafana
```
docker compose up
```
打开 Grafana，默认 https://127.0.0.1:3000/，然后转到管理 > 插件。确保您的app插件在那里。

您也可以通过检查日志来验证 Grafana 是否已发现该插件

INFO[01-01|12:00:00] Plugin registered       logger=plugin.loader pluginID=<your-plugin>

后端插件的结构

用于构建后端的文件夹和文件app是

文件/文件夹	描述
`Magefile.go`	使用 mage 构建文件不是必需的，但我们强烈建议使用它们，以便您可以使用插件 SDK 提供的构建目标。
`/go.mod`	Go 模块依赖项。
`/src/plugin.json`	描述插件的 JSON 文件。
`/pkg/main.go`	插件二进制文件的起始点。

plugin.json 文件

plugin.json 文件是所有插件必需的。在构建后端插件时，请注意这些属性

属性	描述
`backend`	对于后端插件，设置为 `true`。这告诉 Grafana，在加载插件时应该启动一个二进制文件。
`executable`	这是 Grafana 期望启动的可执行文件名称。有关详细信息，请参阅 plugin.json 参考。
`alerting`	如果您的后端数据源支持警报，设置为 `true`。需要将 `backend` 设置为 `true`。

为您的应用插件添加身份验证

有关添加身份验证到您的应用插件（例如，调用自定义后端或第三方 API）和处理机密的更多信息，请参阅为应用插件添加身份验证。

访问应用设置

设置是 AppInstanceSettings 结构的一部分。它们作为第二个参数传递给应用插件构造函数。例如

src/app.go
func NewApp(ctx context.Context, settings backend.AppInstanceSettings) (instancemgmt.Instance, error) {
  jsonData := settings.JSONData // json.RawMessage
  secureJsonData := settings.DecryptedSecureJSONData // map[string]string
}

您还可以从请求的 Context 中获取设置

src/resources.go
func (a *App) handleMyRequest(w http.ResponseWriter, req *http.Request) {
  pluginConfig := backend.PluginConfigFromContext(req.Context())
  jsonData := pluginConfig.AppInstanceSettings.JSONData // json.RawMessage
}

为您的应用插件添加自定义端点

以下是向您的应用插件添加 ServeMux 或 CallResource 端点的方法。

ServeMux（推荐）

您的脚手架应用程序插件已经包含了一个默认的 CallResource，它使用 ServeMux。它看起来像这样

app.go
type App struct {
	backend.CallResourceHandler
}

// NewApp creates a new example *App instance.
func NewApp(_ context.Context, _ backend.AppInstanceSettings) (instancemgmt.Instance, error) {
	var app App

	// Use an httpadapter (provided by the SDK) for resource calls. This allows us
	// to use a *http.ServeMux for resource calls, so we can map multiple routes
	// to CallResource without having to implement extra logic.
	mux := http.NewServeMux()
	app.registerRoutes(mux)
  // implement the CallResourceHandler interface
	app.CallResourceHandler = httpadapter.New(mux)

	return &app, nil
}

现在您可以为您的应用程序插件添加自定义端点。

脚手架代码已经包含了一个包含 registerRoutes 函数的 resources.go 文件。

resources.go
// this function already exists in the scaffolded app plugin
func (a *App) registerRoutes(mux *http.ServeMux) {
	mux.HandleFunc("/myCustomEndpoint", a.handleMyCustomEndpoint)
}

func (a *App) handleMyCustomEndpoint(w http.ResponseWriter, r *http.Request) {
  // handle the request
  // e.g. call a third-party API
  w.Write([]byte("my custom response"))
  w.WriteHeader(http.StatusOK)
}

CallResource

您也可以通过直接向您的后端组件添加一个 CallResource 处理器来为您的应用程序插件添加自定义端点。您必须实现处理多个请求的逻辑。

app.go
func (a *App) CallResource(ctx context.Context, req *backend.CallResourceRequest, sender backend.CallResourceResponseSender) error {
	switch req.Path {
	case "myCustomEndpoint":
		sender.Send(&backend.CallResourceResponse{
			Status: http.StatusOK,
			Body:   []byte("my custom response"),
		})
	default:
		return sender.Send(&backend.CallResourceResponse{
			Status: http.StatusNotFound,
		})
	}
	return nil
}

您还可以查看有关资源处理器的文档，这些文档也可以应用于您的应用程序插件。

从前端代码调用您的自定义端点

要从前端代码调用您的自定义端点，您可以使用 getBackendSrv 中的 fetch 函数。例如

import { getBackendSrv } from '@grafana/runtime';
import { lastValueFrom } from 'rxjs';

function getMyCustomEndpoint() {
  const response = await getBackendSrv().fetch({
    // replace ${PLUGIN_ID} with your plugin id
    url: '/api/plugins/${PLUGIN_ID}/myCustomEndpoint',
  });
  return await lastValueFrom(response);
}

故障排除

Grafana 无法加载我的插件

请确保 Grafana 已经以开发模式启动。如果您从源代码运行 Grafana，请在您的 conf/custom.ini 文件中添加以下行

app_mode = development

注意

如果您还没有 conf/custom.ini 文件，请在继续之前创建它。

然后您可以在 Grafana 仓库根目录中运行 make run & make run-frontend 以在开发模式下启动 Grafana。

如果您从二进制文件或 Docker 容器中运行 Grafana，您可以通过设置环境变量 GF_DEFAULT_APP_MODE 为 development 以在开发模式下启动它。

注意

默认情况下，Grafana 需要签名后端插件。要加载未签名的后端插件，您需要配置 Grafana 以允许未签名的插件。有关更多信息，请参阅插件签名验证。

示例

有关完整示例，请参阅我们的带有后端示例应用程序插件。

在开始之前​

创建一个新的应用程序插件​

后端插件的结构​

plugin.json 文件​

为您的应用插件添加身份验证​

访问应用设置​

为您的应用插件添加自定义端点​

ServeMux（推荐）​

CallResource​

从前端代码调用您的自定义端点​

故障排除​

Grafana 无法加载我的插件​

示例​