Geomap WMS 面板插件

💡 此项目使用 语义化版本控制。

关于

此插件从 Orchestra Cities 地图面板插件 演变而来。它通过集成 OGC Web 地图服务 (WMS 版本 1.3.0) 作为底图层扩展了原始版本的功能。此外，该插件还附带一个交互式过滤器工具，用于通过空间关系查询数据。还提供了最小的数据链接实现，通过点击地图要素来更新仪表盘变量。

根据 Grafana Labs 的插件指南，有必要移除 Nextzen 底图层，因为它需要在配置中存储 API 密钥，这在面板插件中应避免。

功能

• 集成来自不同端点的多个 OGC WMS 1.3.0 作为底图层
• 每个 WMS 端点的透明度设置
• 所用 WMS 图层的可折叠图例
• 交互式空间过滤器
• 最小数据链接实现

从 Geomap WMS 面板插件 v1.0.1 迁移

由于能够使用多个 WMS 端点作为底图层，需要更改插件配置对象，这与 1.y.z 版本的插件所使用的配置对象不兼容。

使用主版本 1 的 Geomap WMS 面板插件并使用 WMS 作为底图层，且想要使用最新版本插件的仪表盘，需要迁移其面板的 JSON 定义。

⚠️ 迁移仅对于使用 WMS 作为底图层的插件是强制性的。使用 WMS 底图以外其他底图的面板无需任何操作。⚠️

迁移示例

插件版本 1.y.z 中 WMS 底图层的 JSON 定义

...
"basemap": {
      "type": "wms",
      "config": {
        "layer": [
          "g_stadtkarte_gesamt"
        ],
        "url": "https://geoportal.muenchen.de/geoserver/gsm/wms?"
      }
    },
...

插件版本 2.y.z 中 WMS 底图层的对应 JSON 定义

...
"basemap": {
      "type": "wms",
      "config": {
        "wmsBaselayer": [
          {
            "url": "https://geoportal.muenchen.de/geoserver/gsm/wms?",
            "layers": ["g_stadtkarte_gesamt"],
            "attribution": "",
            "opacity": 1,
            "showLegend": false
          }
        ]
      }
    },
...

面板的 JSON 定义可以直接在 Grafana GUI 中编辑。

⚠️ 在编辑仪表盘之前务必备份，或者利用 Grafana 的版本控制功能在编辑出错时回滚更改 ⚠️

使用 Geomap WMS 面板插件

⚠️ 目前仅支持 WMS 1.3.0 版本 ⚠️

1. 在底图层选择中，选择类型 OGC Web 地图服务
2. 点击按钮 + 添加 WMS 打开 WMS 对话框
3. 在文本字段 URL 中输入 WMS 端点的基本 URL（注意：仅限服务端点的 URL，不包含请求参数，例如 https://geoportal.muenchen.de/geoserver/gsm/wms）
4. 从下拉列表中选择一个或多个图层
5. 调整该 WMS 条目的透明度（影响该 WMS 条目的所有图层；如需使用同一 WMS 端点并对不同图层应用不同透明度，可通过 + 添加 WMS 添加多个条目）
6. 可选地，切换图例按钮以显示包含所选 WMS 图层图标的图例
7. 可选地，为 WMS 端点提供归属信息
8. 要移除条目，请点击按钮 - 移除 WMS

示例 1)：包含 3 个图层的 WMS 底图

图层名称

• g_stadtkarte_gesamt_gtay
• g_stadtspaziergang_moosach_route_a
• baustellen_2_weeks

示例 2)：包含 3 个图层的 WMS 底图（图层名称包含空格）

图层名称

• Blöcke
• Linie_u_Stadtplanü. bis 150k
• stehende Gewässer generalisiert

⚠️ 合并多个数据源查询到一个地图图层时的数据图层故障排除

有时可能需要将多个数据源查询合并到一个输出数据集中，以便在单个地图图层中汇总来自不同源的信息。这可以通过对返回的数据帧应用转换来实现。

这通常会得到如下所示的数据结构，可以在转换面板的调试视图中检查，其中缺少诸如查询“name”和“refId”等元数据属性。

上述数据结构与 Geomap 面板插件的查询输入不兼容，插件输入需要包含“refId”或“meta”等元数据字段的数据帧。

解决此问题的一种变通方法是在处理链中将准备时间序列转换设置为 "宽格式时间序列" 作为最后一步转换。

后者转换会向数据对象添加一个“meta”字段，因此现在可以由 Geomap 面板插件处理。

使用空间过滤器工具

Geomap WMS 插件的另一个功能是空间过滤器工具，允许在地图面板上绘制多边形作为数据查询的过滤器。该多边形表示为 熟知文本 (WKT)，并存储在仪表盘变量 "geomap_wms_spatial_filter_geometry" 中。

⚠️ 仪表盘变量名称必须为 "geomap_wms_spatial_filter_geometry" ⚠️

⚠️ 空间过滤器工具使用地理坐标系 urn:ogc:def:crs:OGC::CRS84，轴顺序为经度，纬度。Openlayers (geomap 插件的依赖项) 使用 CRS CSR:84 作为 EPSG:4326 的别名 (源)，即使 EPSG:4326 的官方轴顺序定义为纬度，经度。这是因为 Proj4Js 库默认使用 [x=经度,y=纬度] 的顺序。⚠️

要启用空间过滤器工具，请按照以下步骤操作

1. 创建一个类型为 "Textbox" 或 "Custom" 的仪表盘变量（最终将显示属性设置为 "Nothing" 以对用户隐藏变量），名称为 "geomap_wms_spatial_filter_geometry"（空间过滤器工具将在内部更新此变量，目前不支持在外部设置不同的变量名称）。例如，使用 POLYGON((-180 -90,180 -90,180 90,-180 90,-180 -90)) 作为初始值，以便在未绘制多边形时选择全部。

1. 在数据源查询中使用该仪表盘变量，例如 SensorThings API，它允许在 geometry 函数中提供 WKT 进行过滤

/Things?$expand=Locations&$filter=substringof(name,'${tree_sensor:csv}') and st_intersects(Locations/location, geography'${geomap_wms_spatial_filter_geometry}')

1. 在面板编辑器中启用该工具，点击保存或应用并退出编辑模式

1. 在面板中激活该工具

1. 绘制一个多边形作为空间过滤几何图形。要应用几何图形，请将最后一个点设置在起点上。之后，使用变量 "geomap_wms_spatial_filter_geometry" 的面板和数据源将自动更新。要删除几何图形，请点击交叉符号。

使用数据链接

Geomap WMS 面板插件允许使用数据链接以所点击要素的数据更新仪表盘变量。这使得地图面板与仪表盘中使用相同仪表盘变量的其他面板之间能够进行交互。要使用此功能，必须创建一个数据链接（参见官方文档了解具体操作）。

⚠️ 目前，该插件只能处理 1 个（第一个）数据链接 ⚠️

此示例演示如何配置 Geomap WMS 面板插件，通过点击地图上的要素，使用名为 "name" 的数据字段的值更新仪表盘变量 "ladestationen"。

点击地图上的某个要素，会同时更新地图以及所有在查询中使用仪表盘变量 "ladestationen" 的面板。

之前：

之后：

开发

原始仓库状态

此仓库引用其原始仓库的以下版本：https://github.com/orchestracities/map-panel/tree/c0d3a19ce910b9c3ab8416f5a609afb10ff8c0fe

技术设置

• Grafana >= 10.0.2 作为 Docker 容器，使用绑定挂载到主机文件系统，挂载以下容器目录 /var/lib/grafana/plugins
• node v20.3.1
• npm 10.5.0
• 基于 Linux 的操作系统 Windows with WSL

运行测试

单元/集成测试

npm run test:all

端到端测试

需要一个在 localhost:3000 运行的 Grafana Docker 容器，使用默认凭据（用户：admin，密码：admin）。

npm run e2e

构建插件

1. 克隆仓库

git clone https://github.com/felix-mu/geomap-wms-panel.git

1. 进入目录 geomap-wms-panel

cd ./geomap-wms-panel

1. 安装 node 模块

npm install

1. 运行构建脚本

npm run build

构建插件用于开发/调试

重复构建插件中的步骤 1 到 3。

然后运行

npm run dev

将（未签名）插件部署到 Docker 容器（用于调试）

打包好的插件（无论是生产构建还是开发构建）位于输出文件夹 ./felixrelleum-geomapwms-panel 中。为了允许 Grafana 加载未签名插件，必须将容器环境变量 GF_PLUGINS_ALLOW_UNSIGNED_PLUGINS=<插件 ID 列表，以逗号分隔> 设置为 "felixrelleum-geomapwms-panel"。此外，还需要配置将容器的 plugins 目录绑定挂载到打包好的 Geomap WMS 面板插件所在的主机文件系统目录。

快捷方式： 使用 docker compose up 运行 docker-compose.yaml

如果插件是使用 npm run dev 构建的，则 Webpack 目录会加载到浏览器。这使得可以使用浏览器的开发者工具设置断点并调试插件源代码（建议禁用缓存）。

⚠️ 故障排除

每次构建后，必须重启 Docker 容器以重新加载插件的新版本。如果插件的更改未生效，可能需要清除浏览器缓存并刷新页面。

验证插件

npm run validate

使用自动生成变更日志

首先提升 npm 包的版本 (package.json 和 package-lock.json)

npm --no-git-tag-version version <version>

运行自动变更日志生成

npm run release

提交变更日志更改，标记最新提交并推送所有内容

git add . && npm run commit

git push origin main

git tag v<version> && git push origin main v<version>

贡献

请参阅贡献指南了解如何为项目做出贡献。

更多资源

• Grafana 和 Docker
• 在 Docker 中配置 Grafana
• 插件构建工具
• 创建面板插件
• 示例插件
• Grafana UI 目录