Apache Griffin 0.6.0 REST API 与运维命令详解

详解 Apache Griffin（官方镜像实测 0.2.0 service）REST API 与运维命令：measure/job/metadata/metrics/health 全端点实测回显、trigger API 版本差异、predicate 路径错配端到端排障链、ES 指标查询与 accuracy 实测结果

Apache GriffinApacheGriffin大数据数据质量运维2026/10/15

Apache Griffin 0.6.0 REST API 与运维命令详解

Griffin 的主控界面是 REST API（与 Angular UI 同端口 8080，compose 映射宿主 38080）。本文全部请求/响应在官方 all-in-one 镜像部署环境实测：service 自报版本 0.2.0（镜像 tag griffin_spark2:0.3.0），与 0.6.0 文档存在 API 代差，本文如实标注。官方 Postman 集合（tag griffin-0.6.0，griffin-doc/service/postman/griffin.json）作为请求体来源。

一、API 基线与版本探测

curl -i http://localhost:38080/api/v1/version

0.2.0            ← HTTP 200
事实说明
service 版本0.2.0（jar 日期 2018-09-06）
文档版本0.6.0（postman 集合/官方文档）
影响0.6.0 文档中新增端点（如 POST /api/v1/jobs/trigger/{id}）在本镜像 404

二、元数据 API（实测）

curl http://localhost:38080/api/v1/metadata/hive/dbs
curl "http://localhost:38080/api/v1/metadata/hive/tables/names?db=default"

["default"]
["demo_src","demo_tgt"]

数据源是 hive.metastore.uris 指向的 thrift metastore；demo 表由容器 bootstrap 预建，表 location 在 hdfs://griffin:9000/griffin/data/batch/（排障时关键，见第六章）。

三、Measure API（实测）

3.1 创建 accuracy 度量

curl -s -X POST http://localhost:38080/api/v1/measures \
  -H 'Content-Type: application/json' \
  -d @measure-accuracy.json -w '\nHTTP_CODE=%{http_code}\n'

响应（真实摘录）：

{"measure.type":"griffin","id":1,"name":"accuracy_measure","owner":"test",...,
 "sinks":["ELASTICSEARCH","HDFS"],
 "evaluate.rule":{"id":2,"rules":[{"id":3,"rule":"source.desc=target.desc","dsl.type":"griffin-dsl","dq.type":"ACCURACY"}]}}
HTTP_CODE=201

要点：创建 measure 自动挂两个 sink（ELASTICSEARCH、HDFS）；规则 source.desc=target.desc 为 griffin-dsl 语法的 accuracy 比对。

3.2 更新度量

curl -s -X PUT http://localhost:38080/api/v1/measures/1 -H 'Content-Type: application/json' -d @measure-accuracy-fix2.json -w '%{http_code}'

200

实测注意：PUT 后 measure 内部 connector/predicate 的 id 会整体重建（实测 id 5/8 → 35/38），外部脚本不要缓存这些子 id。

四、Job API（实测）

curl -s -X POST http://localhost:38080/api/v1/jobs \
  -H 'Content-Type: application/json' \
  -d '{"measure.id":1,"job.name":"accuracy_job_exp","job.type":"batch","cron.expression":"0 0/2 * * * ?","cron.time.zone":"GMT+8:00","predicate.config":{"checkdonefile.schedule":{"interval":"1m","repeat":2}},"data.segments":[{"begin":"-1h","length":"1h"}]}' \
  -w '\nHTTP_CODE=%{http_code}\n'

{"id":40,"quartz.name":"accuracy_job_exp_1791990423152","quartz.group":"BA",...}
HTTP_CODE=201
操作实测结果
POST /api/v1/jobs201，返回 quartz 任务组 BA
DELETE /api/v1/jobs/25204
GET /api/v1/jobs/health{"healthyJobCount":1,"jobCount":1}（修复后）
POST /api/v1/jobs/trigger/10404（0.2.0 无此端点；0.6.0 postman 有，属版本代差）

job instance 状态流转（实测）：自动创建 instance → FINDING →（predicate 通过后）SUCCESS，携带 appId=application_1791990164994_0001。

五、指标 API 与 ES 查询（实测）

curl http://localhost:38080/api/v1/metrics

{"accuracy_measure":[{"name":"accuracy_job_exp3","type":"ACCURACY","owner":"test",
  "metricValues":[{"name":"accuracy_job_exp3","tmst":1791987600000,
  "value":{"total":125000,"miss":502,"matched":124498}}]}]}

直接查 ES 索引（等价数据源）：

curl "http://localhost:39200/griffin/accuracy/_search?pretty&filter_path=hits.hits._source" \
  -d '{"query":{"match_all":{}},"sort":[{"tmst":{"order":"asc"}}],"size":3}'

{"hits":{"hits":[{"_source":{"name":"accuracy_job_exp3","tmst":1791987600000,
  "value":{"total":125000,"miss":502,"matched":124498}}}]}}

accuracy = 124498/125000 ≈ 99.5984%（demo 数据预置约 0.4% 缺失，符合预期）。

六、predicate 路径错配：端到端排障实录（最典型故障）

现象：measure/job 均创建成功，instance 2 分钟后变 NOT_FOUND，livy /batches 始终 total=0。

service.log 特征（真实原文）：

2026-10-14 15:10:00.116  INFO [ryBean_Worker-4] o.a.g.c.j.FileExistPredicator : Predicate path: hdfs:///griffin/demo_src/dt=20261014/hour=14/_DONE
2026-10-14 15:10:00.122  INFO [ryBean_Worker-4] o.a.g.c.j.FileExistPredicator : Predicate path: hdfs:///griffin/demo_src/dt=20261014/hour=14/_DONE doesn't exist.

定位过程（三步）：

  1. 修正 measure root.path 为带 authority 的 hdfs://griffin:9000/griffin/demo_src 后复测，仍 doesn't exist → 排除 URI 格式问题（无 authority 的 hdfs:/// 会被单例 fileSystem 以 fs.defaultFS 补全）；
  2. 容器内用 Hadoop classpath 写探针程序直接验证（决定性实验）：
fs class: org.apache.hadoop.hdfs.DistributedFileSystem
isFile(hdfs://griffin:9000/griffin/demo_src/dt=20261014/hour=14/_DONE): false
isFile(hdfs://griffin:9000/griffin/data/batch/demo_src/dt=20261014/hour=14/_DONE): true
  1. 对照 Hive 表 location（hdfs://griffin:9000/griffin/data/batch/demo_src，metadata API 可查）确认真实布局。

根因：官方 postman 示例的 predicate root.path=hdfs:///griffin/demo_src 少了 data/batch 段，与镜像内 demo 数据布局不符。

修复：PUT measure，root.path 改为 hdfs://griffin:9000/griffin/data/batch/demo_src 与 .../demo_tgt → predicate 通过 → livy batch 0 提交成功 → instance SUCCESS → 指标落 ES（第五章）。

通用经验：predicate 报 doesn't exist 时先用 hdfs dfs -ls / 探针对比 Hive 表 location，而不是反复改 URI 格式。

七、官方 Postman 集合使用

集合文件（随 griffin-0.6.0 tag）：griffin-doc/service/postman/griffin.json，导入 Postman 后按目录分组：

分组常用请求
MeasuresAdd measure（ACCURACY/PROFILING 模板）、Get all measures、Update measure
JobsAdd job、Get all jobs、Delete job、Trigger job（0.6.0 端点，0.2.0 镜像 404）
MetricsGet metrics
HealthGet health

使用前把集合变量中的 host/port 改成 38080 映射端口，并按第六章修正 root.path。

八、运维命令速查

目的命令
看 service 日志docker exec griffin tail -f /root/service/service.log
看全部组件进程docker exec griffin ps aux | grep java（NN/DN/SNN/RM/NM/Spark Master/Worker/Livy/service）
提交状态curl http://localhost:38998/batches
YARN 应用curl http://localhost:38088/ws/v1/cluster/apps 或浏览器开 38088
HDFS 数据docker exec griffin hdfs dfs -ls /griffin/data/batch/demo_src
ES 健康curl http://localhost:39200/_cluster/health?pretty
调度元数据备份docker exec griffin pg_dump -U griffin quartz > quartz.sql
重启 servicedocker restart griffin（全组件同容器重启）

九、FAQ

Q1：measure 删除后 ES 里的历史指标还在吗？ 在。指标写入 ES 索引与 measure 生命周期解耦，需手工 DELETE /griffin 清理。

Q2：jobs/health 显示 unhealthy 但任务实际成功？ health 统计的是"最近一轮 instance 状态"，NOT_FOUND/FAILED 积累后需等下一轮成功刷新。

Q3：能直接用 Spark UI 看任务吗？ 能。standalone Master 8082/Worker 8081 在容器内，未映射宿主；经 YARN 代理 http://localhost:38088/proxy/application_xxx/ 访问。

Q4：griffin-dsl 还支持哪些规则？ 0.2.0 支持.accuracy 与 profiling 类度量；completeness/timeliness 按 0.6.0 文档语法编写后在 0.2.0 上不保证可用（版本代差）。

Q5：UI 打不开（白屏）？ 确认 38080 返回 200 且 title 为 Griffin - Data Quality Service（实测 1937 字节 index.html）；若 ES 未启动，UI 能开但无指标图。

Q6：如何强制立即跑一轮？ 0.2.0 无 trigger API；把 cron.expression 改成 1-2 分钟内触发，或等自然调度。

Q7：HDFS sink 写到哪里？ 实测 sink 配置落 /griffin/publish/* 类路径（由 service 配置组装），排查用 hdfs dfs -ls /griffin。

Q8：metrics API 返回空？ 检查 ES 索引 griffin 是否有文档（_cat/indices）与 job 最近 instance 是否 SUCCESS。

Q9：多 measure 并行调度会互相影响吗？ Quartz 多 worker 并行，注意 livy/YARN 资源上限；实测单任务 spark-client 模式占 YARN 2 container。

Q10：想用 0.6.0 全新 service？ 官方未发布含 0.6.0 service 的 all-in-one 镜像，需源码构建（mvn -B clean package）+ 自建镜像，成本高；评估新特性建议直接看 0.7.0-rc 分支源码。

参考链接