标准规范下载简介
Q／GDW 12105-2021 电力物联网数据中台服务接口规范.pdfICS 35. 240
国家电网有限公司企业标
Q/GDW121052021
碧海红树园主体施工组织设计方案家电网有限公司 发布
Q/GDW12105—2021目次前言1范围2规范性引用文件3术语和定义，4缩略语.5总体要求..5. 1概述5. 2数据服务接口流程..5. 3数据服务接口需求..5. 4数据服务接口设计5.5数据服务接口注册发布..5. 6数据服务接口运行维护.5. 7数据服务接口安全要求数据服务接口技术要求6. 1数据服务接口形式.6. 2数据服务接口命名..6. 3数据服务接口创建..6. 4数据服务接口发布..6.5数据服务接口授权6. 6数据服务接口查看，6. 7数据服务接口认证..6. 8数据服务接口调用。附录A（资料性附录）数据服务请求及返回应答示例编制说明12
为规范国家电网有限公司数据中台服务接口规范，指导数据中台数据服务接口开发，支撑数据应 用构建和快速迭代，制定本标准。 本标准由国家电网有限公司互联网部提出并解释， 本标准由国家电网有限公司科技部归口。 本标准起草单位：国网信息通信产业集团有限公司、国网冀北电力有限公司、国网山东省电力公 同、国网浙江省电力有限公司、国网四川省电力公司、国网辽宁省电力有限公司、国网内蒙古东部电 力有限公司、国网甘肃省电力公司、南瑞集团有限公司、国家电网有限公司大数据中心。 本标准主要起草人：李金湖、赖征田、许元斌、张毅琦、黄文思、章剑涛、许梓明、陈智鹏、王 川江、刘燕秋、郝悍勇、马汉斌、林境祥、翁文娟、蒋演、郭晶、吴佳，王艺霏、夏洪涛、王加易、 曾愚、唐震宇、王丽霞、王诗清、范秉旭，梁旭、赵博、肖海龙、李国强、王冲、王华、王威、曹健、 未文婷、丁阳。 本标准首次发布。 本标准在执行过程中的意见或建议反馈至国家电网有限公司科技部。
Q/GDW12105202
力物联网数据中台服务接口规
本标准规定了数据中台服务接口规范，包括数据服务总体要求、技术要求两部分。 本标准适用于国家电网有限公司数据服务接口设计、开发、运行、维护等环节。
下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅注日期的版本适用于本文 件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。 Q/GDW12098电力物联网术语
Q/GDW12098界定的以及下列术语和定义适用于本文件。 3.1 接口interface 对协定进行定义的引用类型，接口指定必须由类提供的成员或实现它的其他接口。 3.2 服务接口serviceinterface 特定功能的形式化描述，定义了实现功能所需的参数和返回结果。 3.3 公有服务publicservice 可供所有用户订阅/调用的数据服务。 3.4 私有服务privateservice 仅供属主用户订阅/调用的数据服务。 3.5 服务调用者serviceconsumer 根据服务接口描述访问服务的程序。 3.6 服务提供者servicenravider
服务提供者serviceprovider
实行服务接口定义的功能并提供服务的程序
下列缩略语适用于本文件。 API：应用程序编程接口（ApplicationProgrammingInterface） HTTP：超文本传输协议（HyperTextTransferProtocol) HTTPS：超文本传输安全协议（HyperTextTransferProtocolOverSecureSocketLayer） JSON：JavaScript对象标记（JavaScriptObjectNotation） REsT：表述性状态转移（representationalstatetransfer） RESTFUL：一种网络应用程序的设计风格和开发方式（RepresentationalStateTransfer） SOAP：简单对象访问协议（SimpleObjectAccessProtocol） TCP：传输控制协议（TransmissionControlProtocol） URI：统一资源标识符（UniformResourceIdentifier） UUID：通用唯一标识符（UniversallyUniqueIdentifier） WSDL：Web服务描述语言（WebServicesDescriptionLanguage） XML：可扩展标记语言（ExtensibleMarkupLanguage）
数据服务接口是通过数据中台的数据服务组件，实现安全、友好、可控的对内对外数据服务统一 方问。其中数据服务组件应支持数据中台组件接口和第三方接口的数据服务接口统一注册、管理和调 度等全生命周期的管理，支持免认证、token、Basic等认证形式，主要提供WebService和RestService 两种接口形式。数据服务接口总体集成架构如图1所示。
5.2数据服务接口流程
图1数据服务接口总体集成架构图
数据服务接口流程请求/响应模式如图2所示，由使用者发起请求，数据中台相关组件处理请求， 具体交互过程如下： a 服务提供者基于数据服务组件（数据中台）注册相关数据服务接口定义信息，支持数据中台 各组件API接口及第三方接口的注册：
Q/GDW 121052021
b）服务调用者通过数据服务组件（数据中台）查询数据服务接口定义信息： 服务调用者获取数据服务接口定义信息： 服务调用者向数据服务组件（数据中台）发起数据服务接口请求，数据服务组件（数据中台） 请求进行鉴权、路由等处理，并将请求转发到数据中台相关组件或第三方接口； 服务提供者接收数据服务接口请求； 服务提供者对请求进行处理，并返回数据服务接口应答信息至数据服务组件，由数据服务组 件对响应进行路由、转换等处理，并转发到服务调用者： 服务调用者接收数据服务接口应答结果
5.3数据服务接口需求
图2数据服务接口流程
数据服务接口需求由数据服务调用者或数据服务提供者提出，具体如下： a 数据服务调用者评估使用需求，对暂无相应数据服务接口的数据集提出服务接口生成需求； b） 数据服务提供者进行需求调研，对有使用需求或有较高使用价值的数据集提出服务接口生成 需求：
5.4数据服务接口设计
数据服务接口设计应遵循以下要求： a 以业务应用需求为驱动，按需进行服务的生成，遵循企业级服务沉淀共享原则，避免重复生 成同一类型、同一性质的服务接口； b 按照数据中台数据存储分层架构设计，基于共享层、分析层数据进行数据服务接口生成，原 则上不基于贴源层生成服务接口； 严格按照数据分级权限进行数据服务接口访问控制，根据数据业务特点及应用特点设置服务 接口的有效期约束，确保服务接口授权范围符合安全管理要求。
Q/GDW121052021
5.5数据服务接口注册发布
5.6数据服务接口运行维护
5.6数据服务接口运行维护
5.6.1监控及异常处理
为确保服务接口的有效运行，需常态开展服务接口运行的巡查监控，及时处理服务接口异常，主 要的服务接口监控及异常处理规则如下： a 基于数据中台数据服务接口监控管理功能，按照服务接口对应的业务应用调用频度分别设置 监控规则，并进行服务接口的常态监控： b 根据服务接口监测发现的异常，按以下处理规则进行服务接口异常的处理： 1 针对服务接口状态失效的异常情况，按照服务接口标准操作流程，进行服务状态的重启， 并监测服务接口重启后的状态； 2 针对服务接口访问延迟、响应时间过长，结合监测日志分析结果，进行服务接口的访问 流量的优化配置或其他井发参数配置； 3 针对服务接口异常重启或参数配置优化无法解决的异常，转入服务接口故障分析处理流 程，进行详细分析处理。
版本更新分为新版本上线和旧版本下线两个阶段，数据服务接口版本更新如图3所示，具体要求如 a) 数据服务提供者在数据中台数据服务组件注册新版本数据服务接口； b 数据中台数据服务组件发布新版本数据服务并自动替换老版本数据服务，同时下线老版本数 据服务； C）数据服务调用者调用新版本数据服务
图3数据服务接口版本更新
5. 6. 4下线退出
Q/GDW12105202
服务接口应月 服务，服务接口下线退出按以下规则开展： a）自动退出：按照服务接口创建时设置的有效期时间条件及版本升级等其他触发约束条件，在 服务接口达到运行时长并满足退出条件时，由数据中台数据服务组件自动设置服务接口为下 线状态，实现服务接口的自动退出； b） 手动退出：是指根据对服务接口的监测以及服务接口版本的迭代更新要求，进行服务接口手 动下线退出
5.7数据服务接口安全要求
数据服务接口安全应满足以下要求： a）数据服务封装的数据必须满足数据安全要求，对于涉密数据，需进行脱敏处理或者特殊加密； b）数据服务接口安全日志至少保存6个月以上； C）数据服务访问权限按照公司数据分级分类权限等级管理要求进行授权管理。
表1WebService协议栈
表2RESTService协
Q/GDW121052021
6.2数据服务接口命名
应采用基于XML的数据格式，RESTService应采
一个资源应具有一个或多个标识，采用URI作为资源标识。为保证URI的可寻址性和可读性，采用 路径变量来表达资源层次结构，URL全部采用小写字母及数字，至少两层，根据场景支持多级分类。URL 定义规则如下： (通信协议)//(数据服务网关地址)/(服务所属应用域)/《版本号)/(子目录)//(子目录
6.3数据服务接口创建
数据服务接口创建应基于数据中台数据服务组件完成，包括操作请求和返回应答两部分。数 接口创建请求参数包括但不限于表4内容，数据服务接口创建返回参数包括但不限于表5内容。
Q/GDW 121052021
表4数据服务接口创建请求参数
表5数据服务接口创建返回参数
6.4数据服务接口发布
数据服务接口发布应基于数据中台数据服务组件完成，包括操作请求和返回应答两部分。数 接口发布请求参数包括但不限于表6内容，数据服务接口发布返回参数包括但不限于表7内容。
表6数据服务接口发布请求参数
表7数据服务接口发布返回参数
6.5数据服务接口授权
数据服务提供者根据数据服务调用者申请的数据服务权限，进行审核及授权，确保数据访问的独 立性和安全性，示例见附录A。数据服务接口授权应基于数据中台数据服务组件完成，包括操作请求和 返回应答两部分。数据服务接口授权请求参数包括但不限于表8内容，数据服务接口授权返回参数包括 但不限于表9内容。
Q/GDW121052021
表8数据服务接口授权请求参数
表9数据服务接口授权返回参数
6.6数据服务接口查看
数据服务接口查看应基于数据中台数据服务组件完成， 包括操作请求和返回应答两部分。数 接口查看请求参数包括但不限于表10内容， 数据服务接口查看返回参数包括但不限于表11内容
表10数据服务接口查看请求参数
表11数据服务接口查看返回参数
6.7数据服务接口认证
调用数据服务API接口应选择一种或多种认证方式进行认证，具体如下： a APPKey认证，通过AppKey和AppSecret进行签名认证； b) Basic认证，采用HTTP的BASIC认证方式，后端服务通过用户名和密码进行认证； C PublicKey认证，采用AuthAdv的TokenNE认证，后端服务通过公钥验证Token进行认证； d）无认证，可直接调用API，无需认证。
江西省萍乡市东方巴黎工程D2-2栋土方工程专项施工方案6.8数据服务接口调用
服务请求方法包括新增、删除等，见表12。
Q/GDW12105202
6.8.2HTTP状态码
HTTP响应状态码定义应遵从RFC7231协议，见表13所示，资源应尽量保证不返回除200以外的 态码。
某工程卫生间、屋面、地下室防水施工方案表13HTTP状态码
当资源返回的HTTP状态码为200时，资源返回数据应为JSON或XML格式的数据。数据中应包含资源 调用是否成功、异常代码、异常原因、业务数据等信息，示例如下： success：true,//返回正确或错误 errcode：//当success为false时，组件自定义的错误代码
Q/GDW 121052021