1、智慧城市公共信息平台附件七接口与服务要求附件七智慧城市公共信息平台平台接口与服务要求（试 行）中华人民共和国住房和城乡建设部建筑节能与科技司二一三年三月1 范围 本要求是智慧城市公共信息平台建设指南建设要求系列之接口与服务要求。 本部分要求分两大部分描述平台接口要求，第一部分：总体要求，总体要求描述消息的总体结构、接口访问方、接口地址、使用说明。第二部分：业务接口要求，具体描述每个业务应用服务接口的要求。也就是每一个业务接口要求套在总体要求内。只有使用业务接口要求+总体要求才能正常使用信息平台的应用服务来发现，查询，管理资源。 本部分适用于参与公共信息平台设计和研发人员，系统维护人员及要求接入
2、公共信息平台的外部应用的开发人员。2 规范性引用文件下列文件中的条款通过本部分的引用而成为本部分的条款。凡是注日期的引用文件，其随后所有的修改单（不包括勘误的内容）或修订版均不适用于本部分，鼓励根据本部分达成协议的各方研究是否可使用这些文件的最新版本。凡是不注日期的引用文件，其最新版本适用于本部分。GB/T 21063.1-2007 政务信息资源目录体系 第1部分：总体框架；GB/T 21063.2-2007 政务信息资源目录体系 第2部分：技术要求；GB/T 21063.3-2007 政务信息资源目录体系 第3部分：核心元数据；GB/T 21063.4-2007 政务信息资源目录体系 第4部
3、分： 政务信息资源分类；GB/T 21063.5-2007 政务信息资源目录体系 第5部分：政务信息资源标识符编码方案； 本文 引用GB/T 21063.2-2007中的附录A 目录服务接口； 本文引用GB/T 21063.2-2007中的附录A 目录服务接口，及引用GB/T 21063.2-2007中的附录C 政务信息资源目录服务属性集 本文引用 GB/T 21063.2-2007中的附录F 检索串示例9.3 术语与定义GB/T 19710-2005中规定的与以下术语和定义适用于本部分。 目录针对拥有共性的数据资源/文件资源进行分类，并且为该分类赋予唯一的资源标识符，该部分分类及分类描述的集
4、合统称为资源目录，简称目录。 结构化资源公共信息平台共享的二维库表结构数据，统称为结构化资源。 非结构化资源公共信息平台共享的非二维库表结构数据，例如：文本文件、视频、网络访问资源等统称为非结构化资源。 数据交换管理者管理信息资源结点的机构。 交换内容提供者提供信息资源交换内容的机构。 交换内容使用者使用信息资源交换内容的机构。 前置环境应用单位接入端系统软硬件及相关网络环境组成的应用单位前置系统的单元环境。 目录交换按订阅模式进行目录资源数据的交换； 桥接系统业务数据库与共享数据库的桥接器，保持交换数据库与共享数据库的同步； 变更捕捉捕捉数据资源变更情况。 数据转入以固定间隔时间轮询变更登记
5、表，读取其中的记录，并将这些记录以约定的格式组成XML报文，存储到共享库的换出表中；非结构化数据文件直接通过文件服务传输至交换中心文件服务器，并有中心分发非结构化数据文件。 数据交换路由以固定时间间隔轮询应用单位换入表，拆解XML报文，根据目标库自动分拣； 非结构化数据文件直接通过文件服务传输至交换中心文件服务器，并有中心分发非结构化数据文件。 数据转出独立运行的进程，以固定间隔时间轮询交换库中的换入表，读取其中的XML报文，并将数据按定制的格式同步到共享库中。非结构化数据文件描述信息存储在信息队列中，由各服务器根据队列信息分别从中心文件服务器获取所需数据文件。 交换管理程序完成数据交换审批流
6、程、交换监控、交换调度、系统管理等功能一套程序，部署于中心。 Web服务基于webservice技术开放的服务接口，采用约定的XML作为交易数据接口，提供给客户端调用。 WSDLWeb服务描述文件，一个用来描述Web服务和说明如何与Web服务通信的XML语言。为用户提供详细的接口说明。 访问认证公共信息平台提供用户认证服务，由托管应用系统的客户端调用，用于验证用户是否合法； 应用单位接入公共信息平台的机构单位。 主管单位公共信息平台的管理单位。 数据中心公共信息平台的组成部分，是公共信息平台数据及应用系统数据存储的地方。4 接口服务概述4.1 接口服务组成信息资源目录服务包含三种接口，即信息资
7、源基础服务接口、资源服务接口(发现接口、资源接口)、信息资源管理服务接口。其中，基础接口是将资源服务接口和管理接口中基础性的操作定义成一个公共接口。这3类接口实现了信息资源的发现功能、检索功能和管理功能。基础接口：提供会话管理功能和服务自描述功能，包含有目录服务初始化接口、目录服务终止接口和服务自描述接口。发现接口：提供信息资源元数据检索功能和信息资源元数据检索结果提取功能，包含有目录检索接口以及目录检索结果提取接口。这些接口本身并不提供资源，而是提供资源基本信息和如何去获得这些资源的元数据。资源接口：根据发现接口获得信息资源元数据，定位、查找资源具体内容的接口，包含资源内容检索接口及资源内容
8、结果提取接口。管理接口：提供元数据管理的功能，包含信息资源元数据管理接口。城市公共信息平台接口服务组成见图1.图1. 城市公共信息平台接口服务组成图4.2 接口技术要求a) 提供基于SOAP协议的web服务接口b) 支持跨语言、跨操作系统调用5 总体要求5.1 消息结构每个交易消息(包括请求和应答)有一个是名字（Message Name），交易消息以XML格式表达的，根据XML的定义，每个XML文件需要有特定的Root Tag（根标记），在本要求中，用交易名称+请求类别作为根节点，如初始化接口的请求包根节点为initRequest，而响应包的根节点为initResponse。根节点下之间放业务
9、接口数据。5.1.1 请求报文范例 5.1.2 响应报文范例 5.2 接口方式接口采用WebService方式，接口协议使用SOAP协议，提供标准的WSDL文件。5.3 接口地址公共信息目录服务（以下简称目录服务）主要有三个wsdl地址，不同的wsdl下有不同的方法，下文有说明。这是根据webservice的soap协议开放出来的wsdl地址，第三方应用可以根据实际的部署的服务器地址来使用它。1) 基础接口WSDL文件地址：http:/:/es/catalogbase?wsdl 目录服务初始化 initCatalogService 目录服务终止 stopCatalogService2) 发现接
10、口WSDL文件地址：http:/:/es/digcatalog?wsdl 目录检索 queryCatalogList 目录检索结果提取 queryCatalogResult3) 资源服务接口：http:/:/es/digresource?wsdl 资源检索 getResourceResultset 资源检索结果提取 getResourceResultDetail4) 发现接口WSDL文件地址：http:/:/es/digcatalog?wsdl 资源元数据管理 metadataManage5.4 使用说明完成资源的检索与发现需要根据以下步骤来操作完成：1) 第一步：初始化操作。调用基础接口的“
11、目录服务初始化”获得一个会 话标识符以后每次调用接口都需要次标识符。2) 第二步：查询公共信息目录操作。调用发现接口的“目录检索”组织好查询参数，发起交易，获得查询结果。注：这里的查询结果只有返回命中的查询记录数。比如：返回值是100，那么表示有100条记录符合查询条件，这个时候需要发起“公共信息目录检索结果提取”交易才能提取查询的结果。如果发回值是0，表示没有符合查询条件的记录。3) 第三步：查询公共信息目录对应的资源。这里的操作也是和上面一样，调用“资源检索”先要查询下是否有符合查询条件的资源。有资源记录的话，然后在调用“资源检索结果提取”提取符合条件的资源信息。4) 第四步：假如调用接口
12、结束后，可调用基础接口里的“目录服务终止”来释放会话标识符资源信息。6 业务接口要求6.1 基础接口要求6.1.1 目录服务初始化公共信息目录服务初始化用于建立客户端与服务端的会话，所有其他服务都必须依赖会话。会话的持续时间为30分钟，若会话持续30分钟没有活动，则会话自动终止。本次初始化作用是客户端认证同时获取会话标识符，后续发起交易时需要传递该会话标识符。1. 请求报文体序号元素名称约束类型长度描述取值说明1. protocolVersion可选String50客户端协议版本号客户端协议实现的版本号2. idAuthentication必选String50用户名/密码认证信息。包含用户身份
13、标识及其密码。格式“/”3. implementationId可选String50应用标识在公共信息平台用户体系中注册的第三方应用编号4. implementationName可选String200应用名称在公共信息平台用户管系统中注册的第三方应用名称5. otherInfo可选element其他信息备用2. 请求报文体模板 V1.0 testApp/12456 1 测试应用 3. 响应报文体序号元素名称约束类型长度描述取值说明1. referenceId必选String50会话标识当验证成功时返回，否则设置为空2. protocolVersion必选String50服务端协议版本号服务端协议
14、实现的版本号3. result必选Boolean处理结果服务器端用该参数表明是否接受建立会话的请求。true表示建立会话成功，false表示建立会话失败，此时referenceId为空。4. pubKey必选String64加解密公钥5. otherInfo可选element其他信息备用4. 响应报文体模板cde2db52-8cee-45f4-9cec-f8a68ebbad5cV1.0catalogtrue初始化服务成功6.1.2 目录服务终止公共信息目录服务终止将结束服务端与客户端的会话，与会话相关的资源将被释放。1. 请求报文体序号元素名称约束类型长度描述取值说明1. referenceI
15、d必选String50会话标识要终止的会话编号2. closeReason可选String50终止原因3. otherInfo可选element其他信息备用2. 求报文体模板 cde2db52-8cee-45f4-9cec-f8a68ebbad5c 终止使用 6.1.3 认证授权认证授权主要是公钥获取接口服务，用于根据客户端应用的请求，取出最新的加解密公钥并返回给客户端的过程。公钥获取与其他接口不同，不需要用户验证，不需要会话标识。调用客户端只有获取公钥后对用户认证信息进行加密才能完成其服务调用。整个密码加解密的处理过程如下图所示：图2. .密码加解密的处理过程图1. 请求报文体序号元素名称约
16、束类型长度描述取值说明1. otherInfo可选element其他信息备用2. 请求报文体模板3. 响应报文体序号元素名称约束类型长度描述取值说明1. pubKey必选String8公钥用于加解密密码的密钥2. opResult必选element操作结果参见表A.6 opResult属性表之说明3. otherInfo可选element其他信息备用4. 响应报文体模板catalog true codemessage6.2 发现接口要求6.2.1 资源目录检索公共信息目录检索是服务端根据客户端指定的检索条件，在服务器端从元数据库中检索并标识出匹配的元数据记录，并将元数据记录保存在结果集中的过程
17、。结果集的保存时间与会话标识一致，当会话结束后，响应的结果集将被同步删除。1. 请求报文体序号元素名称约束类型长度描述取值说明1. referenceId必选String50会话标识2. replaceIndicator必选Boolean结果集覆盖标志true表示覆盖原来的查询结果，false表示保留原来的查询结果3. resultSetID必选String200指定的查询结果集名称若存在同名的结果集，需要根据replaceIndicator判断是否需要覆盖结果集。4. databaseNames必选Element要查询的元数据库名称列表客户端指定的要查询的元数据库名称列表5. query必选
18、Element客户端定制的检索语句检索语句必须符合Type-1型，使用逆波兰表达式(RPN)作为检索语法，参见附录E QUERY-RPN范例6. preferredRecordSyntax可选String10检索结果的编码方式固定取值:”XML”7. otherInfo可选Element其他信息备用2. 请求报文体模板f4973365-a9be-4f80-b5d8-a8b9c7949185truehighResultBMDBXML根据国标的逆波兰表达式(RPN)组合的查询条件具体规则参考附录E QUERY-RPN范例3. 响应报文体序号元素名称约束类型长度描述取值说明1. referenceI
19、d必选String50会话标识2. resultCount必选NumberString20符合条件的记录数服务器端执行检索操作得到的命中记录数，检索失败设置为03. searchStatus必选String7执行检索的执行结果返回的检索状态信息，success表示检索成功，failture表示检索失败4. otherInfo可选element其他信息备用4. 响应报文体模板3720b175-7db7-408d-90cd-108e1f2ec8879success6.2.2 资源目录检索结果提取目录检索结果由服务器端从结果集中提取并返回若干数据记录给客户端。1. 请求报文体序号元素名称约束类型长度
20、描述取值说明1. referenceId必选String50会话标识2. resultSetID必选String要抽取的结果集的标识因为系统允许在抽取数据前进行多次检索，每次检索都可以指定不同的结果集名称，所以客户端必须指定要抽取的数据结果集标识3. resultSetStartPoint必选NumberString20开始抽取的位置客户端指定的从第几条记录开始抽取，序号从1开始4. numberOfRecordsResquested必选NumberString20记录数客户端指定的要抽取的记录数5. elementSetName必选element结果集属性参见表表 A.3elementSet
21、Name结果集属性6. preferredRecordSyntax可选String10提取结果的编码方式固定取值:”XML”7. otherInfo可选element其他信息备用2. 请求报文体模板 f4973365-a9be-4f80-b5d8-a8b9c7949185highResult030briefXML3. 响应报文体序号元素名称约束类型长度描述取值说明1. referenceId必选String50会话标识2. numberOfRecordsReturned必选NumberString20元数据数目服务器端返回的元数据数目3. presentStatus必选String7提取状态服
22、务器端返回的提取状态。success表示提取成功，failture表示提取失败4. records必选element结果集服务器返回的结果集,包含一个或多个singleRecord，详细描述参见表A.5 singleRecord参数表5. otherInfo可选element其他信息备用4. 响应报文体模板f4973365-a9be-4f80-b5d8-a8b9c79491859success结构化资源目录/非结构化资源目录6.3 资源服务接口要求6.3.1 资源内容检索 资源检索是公共信息平台服务端根据客户端发送的请求信息，从共享数据库中读取符合条件的记录，并将查询结果集相关返回的过程。注意，资源检索功能并不返回具体的结果集，结果集返回功能将由”资源检索结果提取”服务提供。结果集的保存时间与会话标识一致，当会话结束后，响应的结果集将被同步删除。1. 请求报文体序号元素名称约束类型长度描述取值说明1. referenceId必选String50
