ICS 35.240.01 CCS L 67 黑 DB23 龙 江 省 地 方 标 准 DB23/T XXXX—XXXX 政务信息共享交换平台 接口接入 XXXX - XX - XX 发布 黑龙江省市场监督管理局 XXXX - XX - XX 实施 发 布 DB23/T XXXX-XXXX 前 言 本文件依据GB/T 1.1-2020《标准化工作导则 第1部分：标准化文件的结构和起草规则》 的规定起 草。 请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别这些专利的责任。 本文件由黑龙江省营商环境建设监督局提出并归口。 本文件起草单位：黑龙江省营商环境建设监督局、黑龙江省标准化研究院、浪潮软件集团有限公司。 本文件主要起草人：张建峰、谭嘉宁、王艳君、侯雨含、江中阳、于运来、董鹏飞、张桐瑗、陈要 武、杨大志、吕猛、李严。 I DB23/T XXXX-XXXX 政务信息共享交换平台接口接入 1 范围 本文件规定了黑龙江省政务信息共享交换平台应用程序接口接入的总体架构，以及接口接入的要 求。 本文件适用于黑龙江省政务信息资源数据提供方接口接入的开发、建设和应用。 2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件， 仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本 文件。 本文件没有规范性引用文件 3 术语和定义 下列术语和定义适用于本文件。 3.1 政务信息资源 政务部门在履行职责过程中制作或获取的，以一定形式记录、保存的文件、资料、图表和数据等各 类信息资源，包括政务部门直接或通过第三方依法采集的、依法授权管理的和因履行职责需要依托政务 信息系统形成的信息资源等。 3.2 Application Programming Interface 应用程序接口,是一些预先定义的接口（如函数、HTTP接口），或指软件系统不同组成部分衔接的 约定。用来提供应用程序与开发人员基于某软件或硬件得以访问的一组例程，而又无需访问源码，或理 解内部工作机制的细节。通过程序调用接口，通常用于查询或核验信息。 4 缩略语 下列缩略语适用于本文件。 API：应用程序接口，（Application Programming Interface） URL：每一信息资源都有统一的且在网上唯一的地址，该地址就叫URL， （Uniform Resource Locator） 5 接口接入总体要求 5.1 接口设计原则 接口开发者在设计接口的时候，可以参考以下接口原则： 1 DB23/T XXXX-XXXX a) b) c) d) e) f) 5.2 安全可靠性原则：系统应提供良好的安全性和可靠性策略，支持多种安全而可靠的技术手段， 制定严格的安全可靠的管理措施； 开放性原则：提供统一、开放式标准接口，确保与其它系统的互联互通； 灵活性原则：提供灵活的接口设计，适宜接口的变动； 可扩展性原则：支持新业务的扩展以及接口容量与接口性能的提高； 可管理性原则：提供良好的管理机制，确保在运行过程中提供给管理员方便的管理方式以处理 各种情况； 统一性原则：当保证系统的接口方式、接口形式、使用的协议等标准、统一。 API 接口规范 5.2.1 概述 API接口最大的特点就是既能让资源提供方开放自己的资源访问权限，又能确保数据安全性并让资 源提供方继续握有控制权。资源提供方要根据业务情况描述接口功能，并按照API规范进行开发接口， 能够让使用方更好的应用接口。 5.2.2 协议 API与客户端用户的通信协议，常用HTTP超文本传输协议和HTTPS安全超文本传输协议两种。 5.2.3 接口类型 查询类接口常用接口类型主要有以下两种： a) HTTP API 接口：请求报文通常为 Key-Value 形式，返回报文一般为 JSON 串，有 GET 和 POST 等方法； b) WebService 接口：通常走 SOAP 协议通过 HTTP 传输，请求报文和返回报文都是 XML 格式。 5.2.4 版本控制 5.2.4.1 应该将 API 的版本号放入 URL。 5.2.4.2 采用多版本并存、增量发布的方式，对于一个 API 或服务，应在生产中最多保留 3 个最详 细的版本。版本号分为整型和浮点型，整型：大功能版本，如 v1、v2；浮点型：补充功能版本，如 v1.1、 v2.1。 5.2.5 请求方式 查询类接口常用请求方式主要有以下两种方式： a) GET：从服务器取出资源（一项或多项）； b) POST：在服务器新建一个资源。 5.2.6 请求参数 接口入参一般为XML、JSON格式，常用传入参数主要分为3种类型： a) Params：URL 后面的参数，存放请求接口的参数数据； b) Header：消息头，根据需要存放公共参数、RequestId（请求者标识）、Token（身份验证令牌） 、 加密字段等； c) Body：消息体，存放请求接口的参数数据。 注：资源提供方根据共享要求及相关安全考虑，可在接口入参中增加调用IP、访问人身份证号、调用时间戳等字段。 2 DB23/T XXXX-XXXX 5.2.7 过滤信息 若记录数量很多，服务器不可能返回全部记录给用户，API应该提供分页参数及其它筛选参数，过 滤返回结果。 5.2.8 返回参数 返回参数包括： a) code：接口响应状态代码，资源提供方可自行定义。如接口调用成功，返回 200； b) msg：对 Status 返回的代码进行具体解释。如接口调用失败，返回具体错误信息； c) data：接口返回的具体数据。 示例： { "code": "200", "msg": "接口调用成功", "data": "{\"error\":\"该人员未参加失业保险\"}" } 5.2.9 其他 其他内容包括： a) 如有业务需要，接口设计时应考虑限流设计、熔断设计、降级设计等； b) 如有业务需要，接口设计时应考虑敏感数据脱敏处理，部分数据加 “*”号处理； c) 日志平台设计：日志平台有利于故障定位和日志统计分析； d) 当记录数量很多时，API 应该提供分页参数及其它筛选参数，过滤返回结果。 5.2.10 接口文档 接口文档中应包含以下内容： a) 接口地址：不包含接口 BASE 地址； b) 请求方式: GET、POST 等； c) 请求参数：数据格式（默认 JSON）、参数含义、参数类型、长度、精度等； d) 响应参数：参数含义、参数类型、值域等； e) 错误代码表； f) 其他：如算法生成说明，例 Token。 注：当接口发生变化时，应及时更新接口文档并提供给资源需求方。 6 接口接入流程 6.1 接口接入流程图 接口接入流程图见图1。 3 DB23/T XXXX-XXXX 图1 6.2 接口接入流程图 接口接入准备阶段 6.2.1 接口开发 资源提供方需根据接口需要开发相应的接口，并提供一份接口使用说明文档。 6.2.2 存量数据处理 接口后台的数据应保证其实时性及全面性，并且数据有更新时应保证接口的返回参数尽量不会发生 改变。 6.2.3 资源确认 省数据共享交换平台需确认资源提供方提供的接口是否符合的要求。 6.2.4 接口测试 4 DB23/T XXXX-XXXX 确认接口符合要求后，资源提供方需提供接口测试环境访问地址、接口入参等相关信息，由省数据 共享交换平台对接口进行联调，测试接口是否可以正常使用。 6.2.5 资源注册、审核 省数据共享交换平台，将资源提供方提供的接口在平台上进行接口注册，并进行资源审核。 6.2.6 接口上线 省数据共享交换平台对接口进行测试且能够正常使用后，可将接口发布上线。 7 特殊情况处理 如发生如下情况，需要通知省数据共享交换平台，并重新调试接口： a) 原始接口地址发生变化； b) 原始接口返回参数发生变化； c) 原始接口遇到如服务器升级、网络异常导致接口不通。 5 DB23/T XXXX-XXXX 参 考 文 献 [1] 《政务信息资源共享管理暂行办法》（国发〔2016〕51号） [2] 《政务信息系统整合共享实施方案》（国办发〔2017〕39号） [3] 国家发展改革委关于印发“十三五”国家政务信息化工程建设规划的通知》 （发改高技〔2017〕 1449号） [4] 国务院关于加快推进全国一体化在线政务服务平台建设的指导意见（国发〔2018〕27号） [5] 《全国一体化在线政务服务平台数据共享服务管理暂行办法》（国办电政函〔2019〕235号） [6] 国务院办公厅关于建立健全政务数据共享协调机制加快推进数据有序共享的意见（国办发 〔2021〕6号） ______________________ 6