DB3303T+069-2023渔船安全管理数据服务接口规范.pdf

ICS 35.080 CCS L 77 3303 温州市地方标准 DB3303/T 0692023 渔船安全管理数据服务接口规范 Specification for fishing vessel safety management data service interface 2023-09-07 发布 2023-10-07 实施 温州市市场监督管理局 发 布 目次 前言.II 1 范围.1 2 规范性引用文件.1 3 术语和定义.1 4 缩略语.1 5 服务接口规则.1 6 数据访问服务接口.2 7 数据维护服务接口.3 附录 A（资料性）数据目录服务.5 附录 B（资料性）渔船信息结构体格式.6 参考文献.7 前言 本文件按照GB/T 1.12020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由温州市农业农村局提出及归口。本文件起草单位：浙江索思科技有限公司、温州市渔业应急处置指挥中心、温州市大数据发展管理局、温州大学、杭州万国软宝信息科技有限公司、温州市鹿城区大数据管理中心、温州市洞头区大数据管理中心、乐清市大数据管理中心、永嘉县大数据管理中心、中国移动通信集团浙江有限公司温州分公司、温州市质量技术检测科学研究院。本文件主要起草人：王国庆、张笑钦、林志全、卫达、李克祥、洪珏、郑国华、陈辉、雷文理、黄步统、夏晨彰、潘国栋、黄海广、王智新、陈晓明、陈月斌、滕飞鹏、陈孝云、潘海华、谢亮、孙夏帆、陈博、黄小春。渔船安全管理数据服务接口规范 1 范围 本文件规定了温州籍渔船安全管理数据服务接口规则、数据访问服务接口、数据维护服务接口等内容。本文件适用于涉海涉渔单位部门对温州籍渔船安全管理数据的访问和维护。2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 11457 信息技术 软件工程术语 3 术语和定义 GB/T 11457界定的以及下列术语和定义适用于本文件。渔船安全管理数据 Fishing vessel safety management data 渔船、船员、渔港、气象等基础数据。海上斑马线信息 Maritime zebra crossing information 温州市海上斑马线系统的数据，包括渔船进出港数据、动态点验数据、点验统计列表等信息。4 缩略语 下列缩略语适用于本文件。API：应用程序接口（Application Programming Interface）HTTP：超文本传输协议（Hypertext Transfer Protocol）HTTPS：基于SSL的HTTP（Hypertext Transfer Protocol over Secure Socket Layer）SSL：安全套接字层（Secure Socket Layer）ID：身份标识号（Identity document）JSON：JavaScript对象简谱（JavaScript Object Notation）URI：统一资源标识符（Uniform Resource Identifier)5 服务接口规则 URI 域名地址 域名地址为，替换本文件中URI的domain部分，以更新数据服务接口的域名地址。URI 版本 API可以在URI中带上版本号。示例：https:/domain/wz-api/V1.0/*https:/domain/wz-api/V1.2/*https:/domain/wz-api/V2.0/*数据目录服务 数据目录服务见附录A。服务异常 当接收到一个请求时，如果 URI 路径错误，将返回一个 HTTPS 404 状态码。当接收到一个无效的请求时，服务将生成一个服务异常报告。该报告用于向客户端应用程序和用户解释请求无效的原因，并通过使用 HTTPS 响应码来表示请求的结果。示例：200 OK-GET：服务器成功返回用户请求的数据。201 CREATED-POST/PUT/PATCH：用户新建或修改数据成功。202 Accepted-*：表示一个请求已经进入后台排队（异步任务）。204 NO CONTENT-DELETE：用户删除数据成功。400 INVALID REQUEST-POST/PUT/PATCH：用户发出的请求有错误，服务器没有进行新建或修改数据的操作，该操作是幂等的。401 Unauthorized-*：表示用户没有权限（令牌、用户名、密码错误）。403 Forbidden-*表示用户得到授权（与 401 错误相对），但是访问是被禁止的。404 NOT FOUND-*：用户发出的请求针对的是不存在的记录，服务器没有进行操作，该操作是幂等的。406 Not Acceptable-GET：用户请求的格式不可得（比如用户请求 JSON 格式，但是只有 XML 格式）。410 Gone-GET：用户请求的资源被永久删除，且不会再得到的。422 Unprocurable entity-POST/PUT/PATCH 当创建一个对象时，发生一个验证错误。500 INTERNAL SERVER ERROR-*：服务器发生错误。6 数据访问服务接口 数据访问机制 数据访问服务接口应符合HTTPS请求规则，用于用户对平台整合的各类数据服务的浏览、查询、访问。ID 查询接口 6.2.1 请求规则 接口请求应支持HTTPS的GET请求方式，按唯一ID查询业务数据。示例：如请求获取渔船信息，地址：https:/domain/wz-api/V*/ships/id 6.2.2 响应规则 服务请求响应后返回JSON格式的报文。其中各字段若无特别说明均为字符串类型，编码格式为UTF-8，日期字段默认格式为yyyy-MM-dd HH:mm:ss。示例：code:0,接口响应状态码，0表示成功，1表示失败 success:true,true表示数据访问成功，false表示数据访问失败 msg:查询成功,成功返回查询成功，失败返回查询失败 data:渔船信息结构体,渔船信息数据主体，符合渔船信息结构体格式 time:2018-06-27 15:24:21 信息创建时间戳 列表接口 6.3.1 请求规则 列表请求接口应支持HTTPS的GET请求方式，请求参数按照各业务数据访问接口需求进行设定。示例：如请求渔船列表信息，地址：https:/domain/wz-api/V*/ships 6.3.2 响应规则 服务请求响应后返回JSON格式的报文。其中各字段若无特别说明均为字符串类型，编码格式为UTF-8，日期字段默认格式为yyyy-MM-dd HH:mm:ss。示例：code:0,接口响应状态码，0表示成功，1表示失败 success:true,true表示数据访问成功，false表示数据访问失败 msg:查询成功,成功返回查询成功，失败返回查询失败 data:渔船信息结构体1,渔船信息结构体2,渔船信息结构体3.,渔船信息数据主体，符合渔船信息结构体格式 time:2018-06-27 15:24:21 信息创建时间戳 7 数据维护服务接口 数据维护机制 数据维护服务接口用于对已注册用户的各类数据增加、删除、修改等维护操作，数据库中以时间戳及历史库的形式保存修改历史，保证数据的可追溯性。新增接口 7.2.1 请求规则 数据维护新增接口应支持 POST 请求方式，按渔船信息结构体提交新增业务数据，新增数据需要按照渔船信息结构体格式进行提交，渔船信息结构体格式见附录 B。示例：如请求新增渔船信息，地址：https:/domain/wz-api/V*/ships 7.2.2 响应规则 服务请求响应后返回JSON格式的新增业务数据。其中各字段若无特别说明均为字符串类型，编码格式为UTF-8，日期字段默认格式为yyyy-MM-dd HH:mm:ss。示例：code:0,接口响应状态码，0表示成功，1表示失败 success:true,true表示数据新增成功，false表示数据新增失败 msg:新增成功,成功返回新增成功，失败返回新增失败 data:渔船信息结构体,渔船信息数据主体，符合渔船信息结构体格式 time:2018-06-27 15:24:21 信息创建时间戳 修改接口 7.3.1 请求规则 数据维护修改接口应支持 PATCH 请求方式，用于按照唯一 ID 修改业务数据，修改数据需要按照渔船信息结构体格式进行提交，渔船信息结构体格式见附录 B。示例：如请求修改渔船信息，地址：https:/domain/wz-api/V*/ships/id 7.3.2 响应规则 服务请求响应后返回JSON格式的报文。其中各字段若无特别说明均为字符串类型，编码格式为UTF-8，日期字段默认格式为yyyy-MM-dd HH:mm:ss。示例：code:0,接口响应状态码，0表示成功，1表示失败 success:true,true表示数据修改成功，false表示数据修改失败 msg:修改成功,成功返回修改成功，失败返回修改失败 time:2018-06-27 15:24:21 信息创建时间戳 删除接口 7.4.1 请求规则 数据维护删除接口应支持 DELETE 请求方式，用于按照唯一 ID 删除业务数据。示例：如请求删除渔船信息，地址：https:/domain/wz-api/V*/ships/id 7.4.2 响应规则 服务请求响应后返回JSON格式的报文。其中各字段若无特别说明均为字符串类型，编码格式为UTF-8，日期字段默认格式为yyyy-MM-dd HH:mm:ss。示例：code:0,接口响应状态码，0表示成功，1表示失败 success:true,true表示数据删除成功，false表示数据删除失败 msg:删除成功,成功返回删除成功，失败返回删除失败 time:2018-06-27 15:24:21 信息创建时间戳 附录A （资料性）数据目录服务 数据目录服务见表A.1。表A.1 数据目录服务 序号 目录 数据名称 资源 URI 1 渔船 渔船基础信息 https:/domain/wz-api/V*/ships 2 国籍所有权登记信息 https:/domain/wz-api/V*/ship/syqs 3 渔船捕捞许可信息 https:/domain/wz-api/V*/ship/blxkzs 4 渔船违法信息 https:/domain/wz-api/V*/ship/illegals 5 船员 船员证书信息 https:/domain/wz-api/V*/crews 6 船员违法信息 https:/domain/wz-api/V*/crew/illegals 7 渔港 温州渔港基础信息 https:/domain/wz-api/V*/ports 8 环境 台风信息 https:/domain/wz-api/V*/typhoons 9 浪高信息 https:/domain/wz-api/V*/wave 10 渔场气象信息 https:/domain/wz-api/V*/weather 11 空间地理 海上斑马线信息 https:/domain/wz-api/V*/zebraCrossings 12 渔船位置信息 https:/domain/wz-api/V*/ship/positions 13 网位仪信息 https:/domain/wz-api/V*/ship/netsondes A B 附录B （资料性）渔船信息结构体格式 渔船信息结构体格式见表B.1。表B.1 渔船信息结构体格式 名称 格式 渔船信息结构体 data:id:ff808081424e1e7101425023*,渔船id address:浙江省苍南县*,联系地址 cardno:330327*,持证人身份证或工商注册号 codefishingArea:330327,所属地区代码 completeDate:2014-01-23 00:00:00,建造完工时间 depth:2.5,船深 fishingCode:33108120*,渔船编码 intfUpdateTime:2021-10-15 14:35:58,更新时间 length:23.9,船长 managerid:da5ba42bed2f4d84868b3c49*,属地 mannum:6,核定人数 mmsi:412432*,AIS号码(MMSI)nation:中国,国籍 owner:赖*享,船东 portregistry:苍南,船籍港 power:88.0,主机功率 shipmate:钢质,船体材料 shipname:浙苍渔00*,船名 shiptype:国内捕捞船,船舶类型 tel:150*,联系方式 tonnage:82.0,总吨位 width:4.8,船宽 workmode:漂流,作业方式 worktype:刺网 作业类型 参考文献 1 HY/T 075 海洋信息分类与代码 2 SC/T 6091 海洋渔船管理数据软件接口技术规范 3 ISO/IEC 106462020 Information technology Universal coded character set(UCS)4 IETF RFC 2396(August 1998),Uniform Resource Identifiers(URI):Generic Syntax,Berners-Lee,T.,Fielding,N.,and Masinter,L.,eds.,5 IETF RFC 2616(June 1999),Hypertext Transfer Protocol-HTTP/1.1,Gettys,J.,Mogul,J.,Frystyk,H.,Masinter,L.,Leach,P.,and Berners-Lee,T.,eds.,6 IETF RFC 8259(December 2017),The JavaScript Object Notation(JSON)Data Interchange Format,Bray,T.,ed.,