ICS 35.200
CCS M 57 体 GXAS
团 标 准
T/GXAS 811—2024
田长巡管理系统接口规范
Specification for interface of field chief patrol management system
2024 - 08 - 09 发布
2024 - 08 - 15 实施
广西标准化协会 发 布
T/GXAS 811—2024
目
次
前言 ................................................................................. II
1 范围 ............................................................................... 1
2 规范性引用文件 ..................................................................... 1
3 术语和定义 ......................................................................... 1
4 缩略语 ............................................................................. 1
5 系统接口架构 ....................................................................... 1
6 数据要求 ........................................................................... 2
7 接口调用流程 ....................................................................... 3
8 开发要求 .......................................................................... 10
附录 A（规范性） 互联互通接口描述 .................................................... 11
附录 B（规范性） 安全验证接口及消息描述 .............................................. 12
附录 C（资料性） 安全验证接口参数示例 ................................................ 13
附录 D（规范性） 结构化数据接口描述 .................................................. 14
附录 E（资料性） 结构化数据接口参数示例 .............................................. 16
附录 F（规范性） 文件接口描述 ........................................................ 20
附录 G（资料性） 文件接口参数示例 .................................................... 22
附录 H（规范性） 空间服务信息接口描述 ................................................ 25
附录 I（资料性） 空间服务信息接口参数示例 ............................................ 27
附录 J（规范性） 视频信息接口描述 .................................................... 30
附录 K（资料性） 视频信息接口参数示例 ................................................ 32
参考文献 ............................................................................. 35
I
T/GXAS 811—2024
前
言
本文件参照GB/T 1.1—2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》的规定
起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由广西壮族自治区自然资源调查监测院提出并宣贯。
本文件由广西标准化协会归口。
本文件起草单位：广西壮族自治区自然资源调查监测院、广西壮族自治区自然资源产品质量检验中
心、南宁市自然资源信息集团有限公司。
本文件主要起草人：冯一军、杨如军、梁雄乾、梁绕、文浩翔、钟昌海、庄翔、陈远婷、杨捷、陈
伟健、李斌、谷小康、高珺瑶、黄永盛、程少强、蒋勋、黄应建、黄聪、叶科峰、刘佳、陈玉鑫、兰卉、
陆泽尧、梁文丽、赖敏娜。
II
T/GXAS 811—2024
田长巡管理系统接口规范
1 范围
本文件界定了田长巡管理系统接口涉及的术语和定义、缩略语，确立了系统接口框架，规定了数据
要求、接口调用流程、开发要求。
本文件适用于田长巡管理系统的数据交互和业务协同。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，
仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本
文件。
GB/T 28168 信息技术 中间件 消息中间件技术规范
GB/T 32907 信息安全技术 SM4分组密码算法
HJ 1144 生态保护红线监管技术规范 台账数据库建设（试行）
HJ 1145 生态保护红线监管技术规范 数据质量控制（试行）
T/GXAS 809 田长巡管理系统数据库建设规范
3 术语和定义
下列术语和定义适用于本文件。
3.1
田长巡管理系统 field chief patrol management system
运用地理信息系统、大数据分析与云计算、移动互联网等技术，建立具有实地巡查、上报、信息共
享等功能的耕地网格化信息化管理应用系统。
3.2
反地理编码 reverse geocode location
将地球表面的经纬度坐标转换为标准地址信息。
4 缩略语
下列缩略语适用于本文件。
TCP/IP：传输控制协议/互联网协议（Transmission Control Protocol/Internet Protocol）
HTTP：超文本传输协议（Hyper Text Transfer Protocol）
HTTPS：超文本传输安全协议，是一种通过计算机网络进行安全通信的传输协议（HyperText
Transfer Protocol Secure）
JSON：JavaScript对象表示法（JavaScript Object Notation)
5 系统接口架构
5.1
访问机制
以国土变更调查（脱密成果）有关业务数据建立的统一空间、统一数据格式的各级田长责任耕地基
础底库数据库为基础，系统用户可通过授权服务建立身份安全校验，将举证材料换取成果校验码，举证
材料上报给田长巡管理系统，系统将举证信息传入消息中间件，授权服务通过消费消息形式生成举证校
验码入库。互联互通接口描述按附录A执行。
1
T/GXAS 811—2024
5.2
接口功能
5.2.1 访问授权
田长、网格员通过用户名和密码等方式进行安全验证，获取互联互通接口访问授权：
a) 四级田长及以上用户可查看和访问行政区域内的永久基本农田和举证任务数据；
b) 网格员用户可查看和访问本村的永久基本农田和个人举证任务数据。
5.2.2 数据推送
系统用户向田长巡管理系统推送符合规范的举证材料数据。
5.2.3 数据提取
系统用户从田长巡管理系统获取问题图斑、举证任务图斑数据等。
5.3
接口类型
5.3.1 安全验证接口
用于系统用户登录田长巡管理系统时的身份安全验证。
5.3.2 结构化数据接口
用于问题图斑上报下发、实时在线巡田轨迹上报、举证任务下发上报、农田耕地范围下发等结构化
数据的同步更新。
5.3.3 文件接口
用于收集调查图斑实时图片、耕地现状变化属性等实体数据的在线传输。
5.3.4 空间服务信息接口
用于反地理编码获取农田图斑范围服务、各类耕地功能产品栅格服务、耕地服务等空间服务地址及
服务信息的在线共享。
5.3.5 视频信息接口
用于收集调查图斑视频及视频信息的实时共享。
6 数据要求
6.1
数据内容
以国土变更调查（脱密成果）有关业务数据建立的统一空间、统一数据格式的各级田长责任耕地基
础底数数据库为基础，主要包括耕地的划定和调整、永久基本农田保护红线成果等相关成果数据，最终
形成耕地保护监管数据全覆盖、动态更新。其中：
a) 田长巡管理系统向系统用户提供的数据应符合 T/GXAS 809 的要求；
b) 系统用户向对应行政区的田长和网格员提供耕地保护红线划定和调整、疑似耕地破坏问题核
实处理与整改、耕地保护修复成效评估、人类活动准入和项目审批、视频监控、耕地红线管
理等数据。
6.2
格式
6.2.1 结构化数据
结构化数据格式应符合HJ 1144的规定。
6.2.2 文件实体
图片文件采用JPEG、PNG格式进行交换和共享，视频文件采用MP4格式进行交换和共享，矢量文件采
用SHP、GML格式进行交换和共享。
2
T/GXAS 811—2024
6.2.3 空间服务
空间服务采用OGC标准进行数据共享，支持WMS、WFS、WCS、WPS、WMTS等方式发布的地图服务、影
像服务或矢量服务。
6.2.4 流媒体
流媒体格式支持HTTP Live Streaming网络传输协议。
6.3
质量
6.3.1 应符合 HJ 1145 的规定。
6.3.2 响应时间≤3
s，吞吐量＞400
bps，并发数＞1000，出错率＜1％，7×24
h 可用。
7 接口调用流程
7.1
安全验证接口
系统用户通过安全验证接口访问田长巡管理系统，通过用户名和国密算法SM3加密后的密码进行身
份安全验证，提取令牌信息，实现其他应用程序接口的安全访问。安全验证接口及消息描述按附录B执
行，安全验证接口参数示例见附录C。
7.2
结构化数据接口
7.2.1 结构化数据推送接口
7.2.1.1 系统用户向田长巡管理系统推送结构化数据时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问结构化数据推送接口，将结构化数据推送至相应数据库。
7.2.1.2 结构化数据推送接口调用流程见图 1，结构化数据接口描述按附录 D 执行，结构化数据接口
参数示例见附录 E。
系统用户 田长巡管理系统
开始
登录

登录信息




令牌及用户信息
令牌
失败 结构化数据 令牌和结构化数据 结构化数据接口
操作结果 存储结构化数据
业务处理
数据库集群
结束
图1 结构化数据推送接口调用流程图
7.2.2 结构化数据提取接口
7.2.2.1 系统用户从田长巡管理系统提取结构化数据时：
a) 通过安全验证接口获取令牌信息；
3
T/GXAS 811—2024
b) 通过令牌信息访问结构化数据提取接口，从田长巡管理系统相应数据库获取所需数据，存储
至系统用户数据库。
7.2.2.2 结构化数据提取接口调用流程见图 2，结构化数据接口描述按附录 D 执行，结构化数据接口
参数示例见附录 E。
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
结构化数据 令牌和结构化数据 结构化数据接口
操作结果
失败
提取结构化数据
业务处理
数据库集群
结束
图2 结构化数据提取接口调用流程图
7.3
文件接口
7.3.1 文件推送接口
7.3.1.1 地方田长或网格员向田长巡管理系统推送举证文件数据时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问文件推送接口，将文件元数据推送至田长巡附件数据库，将文件实体数据
存储至田长巡管理系统磁盘阵列。
7.3.1.2 文件推送接口调用流程见图 3，文件接口描述按附录 F 执行，文件接口参数示例见附录 G。
4
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
文件数据 令牌和结构化数据 文件推送接口
操作结果
失败
业务处理 存储结构化数据
数据库集群
结束
obs 存储
图3 文件推送接口调用流程图
7.3.2 文件提取接口
7.3.2.1 地方田长或网格员向田长巡管理系统提取举证文件数据时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问文件提取接口，将所需文件的元数据保存至系统用户数据库，同时，根据
文件元数据信息中的文件地址，获取文件实体，并将文件实体存储至系统用户磁盘中。
7.3.2.2 文件提取接口调用流程见图 4，文件接口描述按附录 F 执行，文件接口参数示例见附录 G。
5
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
文件数据 令牌和结构化数据 文件提取接口
操作结果
失败
提取属性
通过文件地址
提取文件
数据库集群
结束
obs 存储
图4 文件提取接口调用流程图
7.4
空间服务信息接口
7.4.1 反地理编码获取耕地范围接口
7.4.1.1 系统用户向田长巡管理系统获取空间服务信息时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问反地理编码获取耕地范围接口，通过地方经纬度获取对应的耕地范围，并
存储至系统用户中。
7.4.1.2 反地理编码获取耕地范围接口调用流程见图 5，空间服务信息接口描述按附录 H 执行，空间
服务信息接口参数示例见附录 I。
6
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
空间数据 令牌和空间数据 空间数据接口
操作结果
失败
提取空间数据
业务处理
空间云服务
结束
空间数据库集群
图5 反地理编码获取农田范围接口调用流程图
7.4.2 空间服务信息提取接口
7.4.2.1 系统用户从田长巡管理系统提取空间服务信息时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问空间服务信息提取接口，从田长巡管理系统数据库获取所需数据，存储至
系统用户数据库；根据获取的空间服务地址，查看空间服务信息。
7.4.2.2 空间服务信息提取接口调用流程见图 6，空间服务信息接口描述按附录 H 执行，空间服务信
息接口参数示例见附录 I。
7
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
空间数据 令牌和空间数据 空间数据接口
操作结果
失败
提取空间数据
业务处理
空间云服务
结束
空间数据库集群
图6 空间服务信息提取接口调用流程图
7.5
视频信息接口
7.5.1 视频信息推送接口
7.5.1.1 系统用户向田长巡管理系统推送视频信息时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问视频信息注册接口，最后将本地举证视频流数据推送到田长巡管理系统。
7.5.1.2 视频信息推送接口调用流程见图 7，视频信息接口描述按附录 J 执行，视频信息接口参数示
例见附录 K。
8
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
视频数据 令牌和结构化数据 视频推送接口
操作结果
失败
业务处理 存储结构化数据
数据库集群
结束
obs 存储
图7 视频信息推送接口调用流程图
7.5.2 视频信息提取接口
7.5.2.1 系统用户从田长巡管理系统提取举证视频流数据时：
a) 通过安全验证接口获取令牌信息；
b) 通过令牌信息访问视频信息提取接口，从田长巡管理系统附件库获取所需视频流地址等信息，
存储至系统用户数据库；根据获取的视频地址，查看举证视频文件。
7.5.2.2 视频信息提取接口调用流程见图 8，视频信息接口描述按附录 J 执行，视频信息接口参数示
例见附录 K。
9
T/GXAS 811—2024
系统用户 田长巡管理系统
开始
登录 登录信息 安全验证接口
令牌及用户信息
令牌
视频数据 令牌和结构化数据 视频提取接口
操作结果
失败
提取属性
通过文件地址
提取文件
数据库集群
结束
obs 存储
图8 视频信息提取接口调用流程图
8 开发要求
8.1
字符集
汉字编码采用 UTF-8 字符集。
8.2
网络通信协议
支持 TCP/IP 协议和 HTTPS 协议。
8.3
交换格式
采用 JSON 格式进行数据交换。
8.4
消息机制
消息机制应符合GB/T 28168的规定。支持消息中间件，具备断点续传功能，用于消息的内容存储、
持久化处理及数据库日志记录。
8.5
数据加密机制
数据加密机制应符合GB/T 32907的规定。密码及数据传输按采用 SM4 分组密码加密方式。
10
T/GXAS 811—2024
附 录 A
（规范性）
互联互通接口描述
采用安全验证接口、结构化数据接口、文件接口、空间服务信息接口、视频信息接口等方式，通过
消息中间件进行消息传递，实现信息共享和交换传输。互联互通接口描述见表A.1。
表A.1 互联互通接口描述
序号 接口类型 接口名称 接口标识 请求方式 消息类型
1 安全验证接口 安全验证接口 login post json
2 结构化数据接口 结构化数据推送接口 report/saveOrUpdate post json
3 结构化数据提取接口 report/{id} get json
4 文件接口 文件推送接口 batchFjUpload post multipart
5 文件提取接口 issueinfo/{id} get json
6 空间服务信息接口 反地理编码获取农田范围接口 geocoder post json
7 空间服务信息提取接口 gislet/task get json
8 视频信息接口 视频信息推送接口 batchFjUpload post multipart
9 视频信息提取接口 issueinfo/{id} get json
11
T/GXAS 811—2024
附 录 B
（规范性）
安全验证接口及消息描述
安全验证接口功能是为访问田长巡管理系统应用程序接口提供安全验证信息，防御未授权的用户访
问田长巡管理系统数据。用户访问接口时，首先通过用户名和密码获取header token，然后将令牌添加
到请求头中访问其他应用程序接口获取或推送数据，否则接口访问失败。安全验证接口参数见表B.1、
B.2和B.3。
表 B.1 安全验证接口总体描述
项目 描述
接口名称 安全验证接口
接口标识 login
提供方 田长巡管理系统
接口地址 https://田长巡管理系统域名/milestone-api/api/login
请求参数类型 application/json
请求方式 POST
返回格式 JSON
包含操作 1.通过账号、密码登录获取 token； 2.获取 token令牌有效期。
表 B.2 安全验证接口请求参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 mobile 账号 String 登录系统的账号 必选
2 password 密码 String 登录系统的密码，通过SM4加密 必选
3 t 时间戳 String 用于加密密码的动态时间参数，加 密规则，SM4(‘前缀’+ t) 必选
4 uuid 设备唯一码 String 用于确认登录方的唯一ID 必选
表 B.3 安全验证接口响应参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 code 执行状态标识 Int 0（失败）、1（成功） 必选
2 msg 执行状态描述 String 执行失败、执行成功 可选
3 timestamp 当前服务器时间戳 String 获取系统服务时间 必选
4 token 用户 token标识 String 登录后返回的token令牌 必选
5 expire token有效期 String 获取当前token有效期 必选
12
T/GXAS 811—2024
附 录 C
（资料性）
安全验证接口参数示例
C.1 安全验证接口请求参数示例
安全验证接口请求头描述见表C.1；安全验证接口请求体描述见表C.2。
表 C.1 安全验证接口请求头描述
字段 值
package cn.gov.gxzf.dnr.jcytzx.admin
version 1.0.0
versionCode 240418181
src Android
timestamp 1713506822255
Content-Type application/json;charset=UTF-8
Accept-Language zh-Hans-CN;q=1.0
User-Agent Mozilla/5.0(Linux;Android 12)
Cache-Control no-cache;on-store
表 C.2 安全验证接口请求体描述
项目 内容
请求地址 https://田长巡管理系统域名/milestone-api/api/login
示例 { "password": "4F64FE529D827902486533325BDE1AA2"， "mobile": "17777777773"， "uuid": "d6831900-e605-41bd-b274-a4072577007f"， "t": "1713506822231" }
C.2 安全验证接口响应参数示例
安全验证接口响应头描述见表C.3；安全验证接口响应体描述见表C.4。
表 C.3 安全验证接口响应头描述
字段 值
Server nginx
Date Fri， 19 Apr 2024 06:05:04 GMT
Content-Type application/json
Transfer-Encoding chunked
Connection keep-alive
表 C.4 安全验证接口响应体描述
项目 内容
示例 { "code": 0， "msg": "登陆成功"， "timestamp": "1713510856785"， "data": { "token": "WQnFYThqch1psDzZC2egPBk29Xe0sBvKm-xldwkegaVjImSyzbg26VRuxPy8wSa_6AeZ0A"， "expire": 864000 } }
13
T/GXAS 811—2024
附 录 D
（规范性）
结构化数据接口描述
D.1 结构化数据推送接口
结构化数据推送接口功能是实现用户向田长巡管理系统推送并更新二维表等结构化数据的能力。结
构化数据推送接口参数见表D.1、D.2、D.3。
表 D.1 结构化数据推送接口总体描述
项目 描述
接口名称 结构化数据推送接口
接口标识 report/saveOrUpdate
提供方 田长巡管理系统
接口地址 https://田长巡管理系统域名/milestone-api/api/report/saveOrUpdate
请求参数类型 application/json
请求方式 POST
返回格式 JSON
包含操作 1.将token信息放入请求头中的header token中； 2.调用接口，推送并更新结构化数据。
表 D.2 结构化数据推送接口请求参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 id 上报id String 问题图斑唯一ID 必选
2 area 图斑面积 double 问题图斑面积 必选
3 creatorId 创建者id String 创建图斑用户ID 必选
4 prombleType 图斑类型 String 图斑类型值 必选
5 regionId 创建者图斑的 行政区 String 创建者当前图斑的行政区 必选
6 geometry 图斑矢量数据 String 图斑矢量json数据 必选
7 location 图斑地理位置 String 图斑地理位置描述 必选
8 locationRegionId 图斑的行政区 String 图斑的行政区 必选
9 remark 备注 String 附加信息 选填
表 D.3 结构化数据推送接口响应参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 code 执行状态标识 Int 0（失败）、1（成功） 必选
2 msg 执行状态描述 String 执行失败、执行成功 可选
D.2 结构化数据提取接口
结构化数据提取接口功能是实现系统用户向田长巡管理系统提取二维表等结构化数据的能力。结构
化数据提取接口参数见表D.4、D.5、D.6。
表 D.4 结构化数据提取接口总体描述
项目 描述
接口名称 结构化数据提取接口
接口标识 report/{id}
提供方 田长巡管理系统
接口地址 https://田长巡管理系统域名/milestone-api/api/report/{id}
请求参数类型 application/json
请求方式 POST
返回格式 JSON
包含操作 1.将token信息放入请求头中的header token中； 2.调用接口，提取更新的结构化数据。
14
T/GXAS 811—2024
表 D.5 结构化数据提取接口请求参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 id 问题图斑id String 问题图斑id 必选
表 D.6 结构化数据提取接口响应参数
序号 参数标识 参数名称 参数类型 参数说明 必选/可选
1 code 执行状态标识 Int 0（失败）、1（成功） 必选
2 msg 执行状态描述 String 执行失败、执行成功 可选
3 id 详情信息 String 问题图斑唯一ID 必选
3 creatorId 创建者id String 创建图斑用户ID 必选
4 prombleType 图斑类型 String 图斑类型值 必选
5 regionId 创建者图斑的行政区 String 创建者当前图斑的行政区 必选
6 geometry 图斑矢量数据 String 图斑矢量json数据 必选