资源简介
ICS 07. 060
CCS A 45
中华人民共和国海洋行业标准
HY/T 0484—2025
海洋应用软件集成规范接口
Specification foroceanicapplication softwareintegration—Interface
2025-02-06发布 2025-05-01实施
中华人民共和国自然资源部发 布
HY/T 0484—2025
目次
前言 Ⅲ
1 范围 1
2 规范性引用文件 1
3 术语、定义和缩略语 1
3. 1 术语和定义 1
3. 2 缩略语 2
4 接口基本要求 2
5 接口编码 2
5. 1 接口类型 2
5. 2 权限开放级别 2
5. 3 编码方式 2
5. 4 参数格式 3
6 接口调用 4
6. 1 调用类型 4
6. 2 调用安全 4
附录 A (资料性) 海洋应用软件集成接口示例 6
附录 B (资料性) XML和 JSON格式说明及返回参数示例 10
B. 1 概述 10
B. 2 XML格式说明及返回参数样例 10
B. 3 JSON格式说明及返回参数样例 11
参考文献 13
Ⅰ
HY/T 0484—2025
前言
本文件按照 GB/T 1. 1—2020《标准化工作导则第 1部分 :标准化文件的结构和起草规则》的规定起草。
请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。
本文件由中华人民共和国自然资源部提出。
本文件由全国海洋标准化技术委员会(SAC/TC 283)归口。
本文件起草单位 : 国家海洋信息中心、自然资源部北海海域海岛中心、南宁师范大学、广西壮族自治区海洋研究院。
本文件主要 起草 人 : 姜晓 轶、吕憧 憬、曹丽 娟、刘金、曹盛 文、孙苗、蒋冰、郭雪、康林 冲、宋丽 丽、许贵林、黄乐、李焰、邬满、文莉莉、符昱。
Ⅲ
HY/T 0484—2025
海洋应用软件集成规范接口
1 范围
本文件规定了海洋应用软件集成接口的基本要求、类型、格式、调用规范等 ,并给出了接口编码结构的说明。
本文件适用于海洋应用软件整合集成 , 以及各海洋应用软件之间的服务资源、业务数据、用户信息等接口资源的共享交换。
2 规范性引用文件
下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中 , 注日期的引用文件 ,仅该日期对应的版本适用于本文件 ;不注日期的引用文件 ,其最新版本(包括所有的修改单)适用于本文件。
GB 32100 法人和其他组织统一社会信用代码编码规则
3 术语、定义和缩略语
3. 1 术语和定义
下列术语和定义适用于本文件。
3. 1. 1
安全认证接口 security authentication interface
为海洋应用软件集成提供的用户单点登录/登出、用户访问权限校验等接口。
3. 1.2
地图服务接口 map service interface
一种利用地理信息软件制作并发布的、符合开放地理空间信息标准的、可以通过网络进行地图资源调用的接口。
注 : 主要包括地图要素、切片地图、遥感影像、空间分析等服务接口。
3. 1.3
资源调用接口 resource invocation interface
海洋应用软件集成和对外提供的资源共享和交换接口。
注 : 主要包括数据资源、开发组件和模式算法等资源调用服务接口。
3. 1.4
界面集成接口 portalintegration interface
为海洋应用软件门户界面集成提供的开放接口。
3. 1.5
Web服务 web service
网络分布式计算环境中提供基础功能的应用程序。
[来源 :DB37/T 2761. 3—2016,3. 3,有修改]
1
HY/T 0484—2025
3.2 缩略语
下列缩略语适用于本文件。
HTTP 超文本传输协议(HypertextTransferProtocol)
JSON 对象表示法(JavaScriptObjectNotation)
UDDI 统一描述、发现和集成协议(UniversalDescription Discovery and Integration)
URL 统一资源定位符(Uniform Resource Locator)
XML 可扩展标记语言(Extensible Markup Language)
4 接口基本要求
为确保软件集成与信息交互的稳定性、便捷性和可扩展性 , 海洋应用软件集成接口满足以下基本要求 :
a) 所有接口的描述、注册和发布应符合 UDDI标准 ;
b) 仅提供 Web 服务接口调用 ;
c) 应符合高内聚、低耦合的接口封装要求 ,某一接口的变更不影响其他接口的调用 ;
d) 应符合向下兼容的接口升级要求 ,接口更新时应尽可能保留其对外公布的调用地址、函数名、输入输出参数等 , 降低原接口调用者更新和维护的成本 ;
e) 海洋应用软件并发增加、移除或更新时 ,接口应支持动态扩展和平滑移植 ;
f) 应支持对接口请求响应的动态控制 ,确保接口高并发调用的流畅与稳定 ;
g) 宜支持跨语言、跨操作系统的接口调用 ;
h) 应支持与国土空间信息基础平台之间的接口调用。
5 接口编码
5. 1 接口类型
接口按照功能类型 ,主要包括安全认证接口、地图服务接口、资源调用接口和界面集成接口 4类 ,支持按需扩展 ,安全认证接口示例参见附录 A 中的表 A. 1~ 表 A. 5、地图服 务接 口示 例参 见表 A. 6~ 表A. 7、资源调用接口示例参见表 A. 8~表 A. 10、界面集成接口示例参见表 A. 11。
5.2 权限开放级别
接口应定义其权限开放级别 ,包括以下 2类 :
— 调用完全公开类接口 ,不必对调用者身份和权限进行验证 ;
— 调用依权限公开类接口 ,应对调用者身份和权限进行安全验证。
5.3 编码方式
为确保海洋应用软件和接口的唯一性 ,其编码应遵循统一的命名规则。
海洋应用软件应采用 “‘软件缩写(6位 ,首字母大写) ’+ ‘_ ’+ ‘统一社会信用代码(18位) ’”共 25位混合码的方式编码 ,其中 ,软件缩写宜使用软件的英文单词或汉语拼音首字母缩写 ,统一社会信用代码应符合 GB 32100的规定(见示例 1)。
示例 1:“海洋综合监管平台 ”的软件编码为“Hyjgpt_ 121000004013602937”,其中“Hyjgpt”为系统中文名称首字母缩写 ,“121000004013602937”为该应用软件承建单位统一社会信用代码。
接口名称应采用帕斯卡命名法编码 ,宜使用英文单词命名 ,不宜使用汉语拼音或拼音缩写 ,每个单
2
HY/T 0484—2025
词首字母大写(见示例 2)。
示例 2:“获取单个资源服务地 址 ”的接 口编 码宜 为 “GetResourceUrl”(参见 附录 A 中的 表 A. 9) , 不宜 使用 “GetZ- iYuanUrl”或“GetZYUrl”。
5.4 参数格式
5.4. 1 参数类型
接口参数包括请求参数和返回参数。
5.4.2 格式要求
参数格式满足以下基本要求 :
a) 接口发布时应提供 每个 参数 的详 细说 明 , 包括 但不 限于 参数 名称、中文 释义、参数 类型 和常用值 ;
b) 参数名称应采用骆驼式命名法编码 ,宜使用英文单词命名 ,不宜使用汉语拼音或拼音缩写 ,第一个单词的首字母应小写 ,其余单词首字母都应大写 ;
示例 :参数“我的用户 ID”的命名为“myUserId”,不宜使用“MyUserID”“myYongHuID”或“myYHID”。
c) 返回参数应支持 XML 和 JSON 两种 格式(参见 附录 B) , 在接 口调 用时 应予 以指 定(见 6. 1. 1) ,默认应为 JSON格式 ;
d) 响应成功或失败都应返回状态码 ,接口响应通用状态码见表 1。
表 1 接口响应通用状态码
序号
通用状态码
相关说明
1
200
请求成功
2
400
错误请求
3
401
没有权限或权限验证失败
4
403
服务器拒绝请求
5
404
请求页面未找到
6
405
请求方法被禁用
7
406
无法响应请求要求
8
407
需要代理授权
9
408
请求超时
10
409
请求冲突
11
410
请求的资源已被删除
12
411
标头字段包含无效内容
13
412
未满足前提条件
14
413
请求实体过大
15
414
请求的 URI过长
16
415
不支持的媒体类型
17
416
请求范围不符合要求
18
417
服务器未满足期望值要求
3
HY/T 0484—2025
表 1 接口响应通用状态码 (续)
序号
通用状态码
相关说明
19
500
服务器内部错误
20
501
服务器无法识别请求
21
502
服务器网关错误
22
503
服务器超载或停机
23
504
网关超时
24
505
HTTP 协议版本不支持
6 接口调用
6. 1 调用类型
6. 1. 1 调用方式
应支持 HttpGet或 HttpPost两种 Web服务接口调用方式。
示例 :前端接口调用示例代码如下 :
$ . ajax({
type: "post",//"get"代表 HttpGet调用,"post"代表 HttpPost调用
async: true,//true为异步调用 , false为同步调用
cache: false,//清除缓存为 false,不清除为 true
url: XXX,
dataType: "json",//返回参数类型 ,可为 json或 xml
data: args, //{参数 1:'值',参数 2:'值', …}
success: callbackFunction,//调用成功 ,执行该函数
complete: completeFunction,
error: function (err) { } }) ;
6. 1.2 调用模式
接口支持以下两种调用模式。
a) 同步调用模式。接口调用请求应在得到响应消息后 ,方可继续处理 ,直至响应超时 ;
b) 异步调用模式。接口调用请求可不必等待响应消息 , 即可继续处理其他事务。
6.2 调用安全
6.2. 1 基于 IP地址的安全验证方式
在服务器端建立授权访问的 IP地址列表 , 当通过接口调用服务资源时 ,服务器应验证 IP地址的有效性 ,认证通过后执行调用请求并返回接口响应通用状态码。
6.2.2 基于动态密钥的安全认证方式
用户提出接口调用申请 ,服务器采用非对称加密算法生成动态密钥对(公钥与私钥) ,用户获取公钥后对身份信息进行加密 ,服务器利用私钥解密并验证调用者身份 ,根据用户权限生成 Token加密令牌
4
HY/T 0484—2025
并返回用户 ,用户调用接口时应传入该 Token,服务器验证 Token令牌的有效性 ,安全验证通过后执行调用请求并返回接口响应通用状态码(流程见图 1)。
图 1 接口调用的动态密钥认证流程
5
HY/T 0484—2025
附录 A
(资料性)
海洋应用软件集成接口示例
表 A. 1~表 A. 5 为安全认证接口。
表 A. 1 获取动态密钥接口
数据项名称
数据项目 内容
接口类型
安全认证接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetPublicToken
接口提供者
海洋综合监管平台
功能描述
获取动态密钥
请求方式
HttpGet
返回值
正常返回值 :200,公钥。
异常返回值 :根据导致异常的原因返回对应状态码 ,见表 1
表 A.2 IP地址验证接口
数据项名称
数据项目 内容
接口类型
安全认证接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
VerifyIPAddress
接口提供者
海洋综合监管平台
功能描述
验证调用接口的 IP地址是否为安全地址
请求方式
HttpGet
返回值
正常返回值 :200,验证通过。
异常返回值 :见表 1
表 A.3 用户身份验证接口
数据项名称
数据项目 内容
接口类型
安全认证接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
VerifyUserAuthentication
6
HY/T 0484—2025
表 A.3 用户身份验证接口 (续)
数据项名称
数据项目 内容
接口提供者
海洋综合监管平台
功能描述
验证调用接口的用户身份和访问权限
请求方式
HttpGet
返回值
正常返回值 :200,验证通过。
异常返回值 :见表 1
表 A.4 用户单点登录接口
数据项名称
数据项目 内容
接口类型
安全认证接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetLogin
接口提供者
海洋综合监管平台
功能描述
弹出登录页 ,输入用户名、密码后登录系统
请求方式
HttpGet
返回值
正常返回值 :200,登录成功 ,打开请求页面。
异常返回值 :见表 1
表 A.5 用户单点登出接口
数据项名称
数据项目 内容
接口类型
安全认证接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetLogout
接口提供者
海洋综合监管平台
功能描述
单点登出后 ,访问集成框架里的任何系统都需要重新登录
请求方式
HttpGet
返回值
正常返回值 :200,登出成功返回登录页面。
异常返回值 :见表 1
表 A. 6、表 A. 7 为地图服务接口。
7
HY/T 0484—2025
表 A.6 查询地图服务列表接口
数据项名称
数据项目 内容
接口类型
地图服务接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetMapServiceList
接口提供者
海洋综合监管平台
功能描述
查询海洋综合监管平台中地图服务列表
请求方式
HttpGet
返回值
正常返回值 :200,返回监管平台中权限范围内地图服务列表。
异常返回值 :见表 1
表 A.7 获取地图服务地址接口
数据项名称
数据项目 内容
接口类型
地图服务接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetMapServiceUrl
接口提供者
海洋综合监管平台
功能描述
获取地图服务地址
请求方式
HttpGet
返回值
正常返回值 :200,返回地图服务地址。
异常返回值 :见表 1
表 A. 8~表 A. 10为资源调用接口。
表 A. 8 获取全部资源目录接口
数据项名称
数据项目 内容
接口类型
资源调用接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetAllResourcesList
接口提供者
海洋综合监管平台
功能描述
获取全部资源目录
请求方式
HttpGet
返回值
正常返回值 :200,返回监管平台中权限范围内全部资源目录
异常返回值 :见表 1
8
HY/T 0484—2025
表 A.9 获取资源服务地址接口
数据项名称
数据项目 内容
接口类型
资源调用接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
GetResourceUrl
接口提供者
海洋综合监管平台
功能描述
获取单个资源服务地址
请求方式
HttpGet
返回值
正常返回值 :200,返回请求的资源服务地址。
异常返回值 :见表 1
表 A. 10 风流场可视化模型接口
数据项名称
数据项目 内容
接口类型
资源调用接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
VectorFieldVisualization
接口提供者
海洋综合监管平台
功能描述
风场、海流等可视化模型接口 ;
基于监管平台底图服务提供矢量场数据解析、流场线可视化服务
请求方式
HttpGet
返回值
正常返回值 :200,风流场在监管平台地图上可视化显示。
异常返回值 :见表 1
表 A. 11为界面集成接口。
表 A. 11 界面集成接口
数据项名称
数据项目 内容
接口类型
界面集成接口
权限开放级别
依权限公开
接口服务类型
Web API
接口名称
AddExtIntegrate
接口提供者
海洋综合监管平台
功能描述
添加业务部件集成至门户
请求方式
HttpGet
返回值
正常返回值 :200,业务信息在门户页面显示。
异常返回值 :见表 1
9
HY/T 0484—2025
附录 B
(资料性)
XML和 JSON格式说明及返回参数示例
B. 1 概述
说明 XML和 JSON参数的基本格式 ,给出接口调用成功、调用失败时返回的 XML和 JSON 参数样例。
B.2 XML格式说明及返回参数样例
B.2. 1 XML格式说明
请求服务响应的状态码枚举相关信息
< ! --response具体信息 ,接口返回的信息全部封装在 body中-->
B.2.2 接口调用成功 ,返回的 XML参数样例
200
请求数据成功
资源 ID
资源名称资源类型
… …
资源 ID
资源名称
资源类型
… …
… …
10
HY/T 0484—2025
B.2.3 接口调用失败 ,返回的 XML参数样例
500
服务器内部错误
B.3 JSON格式说明及返回参数样例
B.3. 1 JSON格式说明
code: 请求服务响应的状态码枚举 ,
description: 相关信息 ,
var response = {
dataobj: { < ! --response具体信息 ,接口返回的信息封装在 dataobj中-->} } ;
B.3.2 接口调用成功 ,返回的 JSON参数样例
var response = {
code: 200,
description: 请求数据成功 ,
dataobj: [
{
id:资源 ID,
name: ’资源名称 ’, type:’资源类型 ’,
……
} ,
{
id:资源 ID,
name: ’资源名称 ’, type:’资源类型 ’,
……
}
……
]
} ;
B.3.3 接口调用失败 ,返回的 JSON参数样例
var response = {
code: 500,
11
HY/T 0484—2025
description: 服务器内部错误 ,
dataobj: {} } ;
12
HY/T 0484—2025
参考 文献
[1] GB/T 31991. 3—2015 电能服务管理平台技术规范第 3 部分 :接口规范
[2] CH/T 1038—2018 时空政务地理信息应用服务接口技术规范
[3] CH/T 9027—2018 数字城市地理信息公共平台服务接口
[4] GA/T 1036—2012 消防基础数据平台接口规范
[5] LY/T 2177—2013 林业信息服务接口规范
[6] DB37/T 2761. 3—2016 地理信息公共服务平台技术规范第 3 部分 :服务接口
[7] DB51/T 1935—2014 地理信息公共服务平台服务接口规范
评论