1、ICS35.240CCS L 67山东省地方标准DB37/T 4225202037政务信息资源数据服务接口规范Government information resourcesData service interface specification2020 - 11 - 26 发布2020 - 12 - 26 实施山东省市场监督管理局发 布FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 2020I目次前言.II1范围.12规范性引用文件.13术语和定义.14缩略语.15服务接口要求.26服务提供要求.47服务使用要求.48服务安全要求.5附录 A（资料性）服务接口注
2、册信息表模板. 6附录 B（资料性）服务接口描述信息填写示例. 7附录 C（资料性）服务使用申请信息表模板. 9参考文献.10FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 2020II前言本文件按照GB/T 1.12020标准化工作导则第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由山东省大数据局提出、归口并组织实施。本文件起草单位：山东省大数据局、山东省大数据中心、山东新一代标准化研究院有限公司、山东省计算中心（国家超级计算济南中心）。本文件主要起草人：石伟、王伟、李德金、张媛、
3、王旭东、张昭、傅川、王建坤、张荣光、王茜、柯林森、马金钊、金龙、史丛丛、王溪、李杨、逄锦山。FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 20201政务信息资源数据服务接口规范1范围本文件规定了政务信息资源的数据服务接口要求、提供要求、使用要求和安全要求。本文件适用于政务信息资源数据服务接口的设计、开发和实施。注：本文件规定的政务信息资源数据为政务业务办理中产生的结构化数据。2规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。 其中， 注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）
4、适用于本文件。GB/T 222392019信息安全技术网络安全等级保护基本要求GB/T 352732020信息安全技术个人信息安全规范DB37/T 3521.12019政务信息资源目录第1部分：编码规则DB37/T 3523.22019公共数据开放第2部分：数据脱敏指南3术语和定义下列术语和定义适用于本文件。3.1数据服务data service通过一定的技术手段，对外提供政务信息资源。4缩略语下列缩略语适用于本文件。API：应用程序接口（Application Programming Interface）APP：移动应用（Application）HTML5：超文本标记语言5.0（Hyper
5、Text Markup Language 5.0）IP：网络互连协议（Internet Protocol）JSON：JavaScript对象简谱（JavaScript Object Notation）REST：表述性状态传递（Representational State Transfer）RPC：远程过程调用（Remote Procedure Call）SDK：软件开发工具包（Software Development Kit）SOAP：简单对象访问协议（Simple Object Access Protocol）UTF-8：Unicode的可变长度字符编码(8-bit Unicode Tran
6、sformation Format)WSDL：Web服务描述语言（Web Services Description Language）XML：可扩展标记语言（Extensible Markup Language）FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 202025服务接口要求5.1服务接口设计原则服务接口设计原则主要包括：a)安全性原则：应提供多种安全可靠的技术手段，保证服务接口的安全；b)开放性原则：应采用通用的接口设计标准，保证与其他系统的互联互通；c)灵活性原则：应能根据业务变化，灵活调整接口性能；d)松耦合原则：应避免服务提供方的业务系统对服务接口
7、实现的依赖。5.2服务接口名称服务接口名称应采用中文名称，由服务提供方名称、信息资源名称和接口分类三部分组成。服务提供方名称宜使用国家规定的部门简称，如山东省公安厅简称为省公安厅。注1：部门简称可参照山东省人民政府办公厅关于印发省政府机构简称的通知（鲁政办字2018203号）。注2：服务提供方：政务信息资源数据服务接口的提供部门。注3：服务接口的英文表示名称为中文名称的汉语拼音简写，且首字母大写。5.3服务接口编码服务接口编码由接口提供类型编码、政务信息资源编码、接口分类编码和接口顺序码四部分组成，编码结构见图1。图 1服务接口编码结构服务接口编码规则如下：a)第 1 位为接口提供类型编码，使
8、用 1 位阿拉伯数字表示， “0”标识服务提供方开发接口， “1”标识省一体化大数据平台统一开发接口；b)第 213 位为政务信息资源编码，使用 12 位阿拉伯数字表示，由政务部门系列顺序码和信息资源顺序码组成，编码规则应符合 DB37/T 3521.12019 中 4.2 的规定；c)第 14 位为接口分类编码，使用 1 位阿拉伯数字表示，编码范围为 19，分类编码见 5.4；d)第 1517 位为接口顺序码， 使用 3 位阿拉伯数字表示， 用于标识同一接口分类下的接口顺序，编码范围为 001999。5.4服务接口分类服务接口分类见表1。FORMTEXT DB37/T FORMTEXT 42
9、25 FORMTEXT 20203表 1接口分类代码代码分类名称1查询类2验证类3数据传输类4下载类9其他类5.5服务接口技术要求服务接口技术要求包括但不限于：a)接口方式：一般包括 WebService 和 REST 两种方式，WebService 服务描述的内容格式应符合WSDL 1.1，服务消息封装应符合 SOAP 1.1/1.2 标准，REST 服务消息封装应符合 HTTP 1.0/1.1标准，若为 REST 方式，应标明 REST 操作；b)接口授权：服务提供方应对每条申请授权唯一的接口授权码，通过分配的接口密钥调用身份认证接口获取访问令牌，接口授权的安全要求包括但不限于 IP 地址
10、白名单、动态访问令牌；c)接口输入参数：1)REST 类型的服务接口，应允许在 header 里输入授权验证相关参数；2)WebService 类型的服务接口，不应在 header 中传递参数，应在 Body 中传递参数；3)传递参数为中文字符时，应采用 UTF-8 编码。d)接口返回数据：1)返回数据应采用固定格式封装，如 XML、JSON 等；2)服务接口调用失败，应通过返回码响应。5.6服务接口管理要求5.6.1概述通过服务接口访问时，应提供自动监管和异常处理能力，并统一管理管控参数。5.6.2接口注册服务接口注册要求包括但不限于：a)应提供测试样例，确保服务使用方能对服务接口进行测试；
11、b)应填写准确的技术联系人信息；c)应填写服务接口注册信息表，经服务管理方审核通过后正式发布，服务接口注册信息表模板见附录 A。注1：服务使用方：政务信息资源数据服务接口的使用部门。注2：服务管理方：政务信息资源数据服务接口的管理部门。5.6.3接口发布服务接口发布要求包括但不限于：a)服务管理方和服务提供方应负责服务接口统一发布；b)服务接口发布信息包括但不限于接口概述、接口名称、接口分类、接口方式、接口地址、接口授权、接口方法、输入输出参数和接口示例，接口描述信息表填写示例见附录 B。FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 202045.6.4接口变更
12、服务接口变更要求包括但不限于：a)服务提供方对已发布的服务接口进行变更时应不影响服务接口的正常使用；b)如服务接口已被服务使用方调用，服务提供方应首先发布新版服务接口并通知服务使用方在一定期限内应用新版服务接口；c)接口变更应实行版本控制机制；d)接口变更应实行备案制，备案内容包括但不限于接口更新的计划停止时间、重新启用时间、更新内容。5.6.5接口撤销服务接口撤销要求包括但不限于：a)服务接口无服务使用方调用，服务提供方应向服务管理方提交接口撤销申请并备案；b)服务接口已被服务使用方调用，服务提供方应通知服务使用方后向服务管理方提交接口撤销申请并备案；c)服务接口撤销应实行备案制，备案内容包
13、括但不限于接口撤销的原因，计划撤销时间；d)服务管理方应对接口撤销备案进行审核，审核通过后撤销接口。6服务提供要求提供的服务应满足的要求包括但不限于：a)应提供审计功能，记录数据服务调用的时间、服务提供方、服务使用方、接口调用情况等信息；b)应满足服务数据获取有效性、及时性、准确性和完整性等数据质量要求；c)服务接口应根据具体情况满足一定的技术要求，如接口响应时间、并发数等；d)接口调用应保持良好的稳定性，如高并发调用服务时，稳定性应达到 99.99 %以上。7服务使用要求7.1服务申请服务申请的具体要求主要包括：a)服务使用方调用服务接口时，应提交服务接口使用申请并填写服务申请信息表，服务使
14、用申请信息表模板见附录 C；b)服务提供方和服务管理方应在服务申请审核通过后，为服务使用方提供唯一的接口授权码；c)服务使用方使用服务接口过程中获取的数据信息应遵守保密规定，不应泄露给第三方。7.2服务使用服务使用方应获取授权认证信息后进行服务接口调用，调用的具体步骤如下：a)获取唯一授权码：服务使用方应获取接口的唯一授权码，唯一授权码不限调用次数；b)接口调用：服务使用方调用服务接口时，输入参数应满足服务提供方的格式、位置等要求，同时须在 header 中增加传入服务访问令牌 token 信息验证访问权限，验证通过后，返回接口响应结果；FORMTEXT DB37/T FORMTEXT 422
15、5 FORMTEXT 20205c)鉴权监测：服务提供方应获取 header 中服务访问令牌 token 信息进行权限验证并监测接口调用情况；d)服务处理：服务提供方应根据服务使用方的输入参数进行服务处理，同时保存服务处理过程中产生的日志信息。8服务安全要求服务安全应满足GB/T 222392019、GB/T 352732020、DB37/T 3523.22019中的要求。FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 20206AA附录A（资料性）服务接口注册信息表模板服务接口注册信息表模板见表A.1。表 A.1 服务接口注册信息表序号名称描述1服务名称数据服务
16、接口的中文名称，确保唯一性2服务摘要提供服务的简单描述3服务提供方代码数据服务接口的服务提供方代码（统一社会信用代码）4服务提供方名称数据服务接口的服务提供方名称5所属资源目录数据服务接口所属的资源目录，资源目录由服务提供方编目并注册，当服务接口注册时，选择相应的资源目录6服务地址服务接口的 IP 地址7协议类型基于 HTTP 协议的类型，如 RPC、RESTFUL、SOAP WEBSERVICE8请求方法数据服务接口的请求方法，如 POST9响应格式数据服务接口的响应方法，如 JSON10调用频率服务接口的每天调用频次之和的上限值， （如：1000 次/天）11服务有效日期服务接口调用的有效
17、截止日期，日期格式（YYYY-MM-DD）12参数表参数表13参数名参数名14参数位置参数位置（1：header；2：body）15参数类型参数类型包括但不限于 string、int、long、array、boolean、object16约束条件参数约束限制条件，如字符长度等17描述信息参数的描述信息18服务接口说明文档详细的服务接口使用说明文档，内容应包括但不限于服务接口概述、服务接口访问限制、服务接口参数说明、服务接口授权说明、服务接口调用示例注：避免在服务接口使用说明文档中暴露原始服务接口地址。FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 20207BB附
18、录B（资料性）服务接口描述信息填写示例B.1服务接口返回 JSON 格式示例用户信息查询接口描述信息填写示例见表B.1。表 B.1 用户信息查询接口描述信息填写示例接口概述通过姓名、身份证件号码，在人口信息资源库中定位人员信息，并将该人员的性别、民族、出生日期和出生地信息进行反馈接口名称省公安厅山东省户籍人口信息查询接口接口分类查询类接口方式REST接口地址http:/XX.XXX.XXX.XXX:XXX/gateway/1/sgatxxcx接口授权服务提供方授权接口方法GET输入（业务请求参数说明）参数名参数说明类型约束姓名在户籍管理部门正式登记注册，人事档案中正式记载的姓氏名称。字符型必填
19、身份证件号码身份证件上记载的、可唯一标识个人身份的号码。字符型必填输出（业务返回参数）参数名参数说明类型备注姓名在户籍管理部门正式登记注册，人事档案中正式记载的姓氏名称。字符型非空项身份证件号码身份证件上记载的、可唯一标识个人身份的号码。字符型非空项性别性别的标识代码按 GB/T 2261.12003 的规定取值。字符型非空项民族民族的标识代码按 GB/T 33041991 的规定取值。字符型非空项出生日期出生证签署的， 并在户籍部门正式登记注册， 人事档案中记载的日期。字符型非空项出生地出生地，国家-省-市-县-详细地址。字符型非空项返回数据格式JSON 接口返回模板如下：status:da
20、ta:|msg:FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 20208B.2服务接口返回 XML 格式示例用户信息查询接口描述信息填写示例见表B.2。表 B.2 用户信息查询接口描述信息填写示例接口概述通过姓名、身份证件号码，在人口信息资源库中定位人员信息，并将该人员的性别、民族、出生日期和出生地信息进行反馈接口名称省公安厅山东省户籍人口信息查询接口接口分类查询类接口方式WebService接口地址http:/XX.XXX.XXX.XXX:XXX/gateway/api/1/gjrkk_jzxxcx接口授权服务提供方授权接口方法cxreceiveRequest
21、输入（业务请求参数说明）参数名参数说明类型约束姓名在户籍管理部门正式登记注册，人事档案中正式记载的姓氏名称。字符型必填身份证件号码身份证件上记载的、可唯一标识个人身份的号码。字符型必填输出（业务返回参数）参数名参数说明类型备注姓名在户籍管理部门正式登记注册，人事档案中正式记载的姓氏名称。字符型非空项身份证件号码身份证件上记载的、可唯一标识个人身份的号码。字符型非空项性别性别的标识代码按 GB/T 2261.12003 的规定取值。字符型非空项民族民族的标识代码按 GB/T 33041991 的规定取值。字符型非空项出生日期出生证签署的， 并在户籍部门正式登记注册， 人事档案中记载的日期。字符型
22、非空项出生地出生地，国家-省-市-县-详细地址。字符型非空项返回数据格式XML 接口返回模板如下：FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 20209CC附录C（资料性）服务使用申请信息表模板服务使用申请信息表模板见表C.1。表 C.1 服务使用申请信息表序号名称描述1服务名称服务使用方申请使用的服务名称2服务使用方代码服务使用方的统一社会信用代码3服务使用方名称服务使用方的名称4服务使用方联系人服务使用方的联系人5服务使用方联系人电话服务使用方的联系人电话6服务使用方联系人邮箱服务使用方的联系人电子邮箱7服务应用系统名称使用该服务接口的业务系统名称8涉及的
23、办理事项名称使用该服务用于办理的业务事项名称9申请依据描述服务使用方办理所涉及事项时使用该服务的具体依据，如相关法律、法规、政策等10业务场景服务使用方应用该服务的具体业务场景11服务使用期限服务期限以天为单位， 如 980 天； 特殊情况下须详细说明每年服务使用具体日期，如 1 月 1 日-5 月 1 日等12服务使用时间范围服务使用的具体时间范围，比如 1：工作日（8:00-18:00）或 2：全天（含非工作日）13附件附件包括但不限于加盖服务使用方印章的申请表扫描件等FORMTEXT DB37/T FORMTEXT 4225 FORMTEXT 202010参考文献1GB/T 2261.12003个人基本信息分类与代码第1部分：人的性别代码2GB/T 33041991中国各民族名称的罗马字母拼写法和代码3山东省人民政府办公厅.关于印发省政府机构简称的通知:鲁政办字2018203号A/OL.(2018-10-26)2020-08-28.http:/
