Q-CR 821-2021 铁路数据服务平台接口规范

ics03.220.30

Q/CR

中国国家铁路集团有限公司企业标准

Q/CR821—2021

铁路数据服务平台接口规范

Interfacespecificationofrailwaydataserviceplatform

2021-04-11发布2021-07-11实施

“，国国家铁路集团有限公司发布

Q/CR821-2021

目次

而言.....................................................................................1U

I范围..................................................................................I

2规范性引用文件........................................................................1

3术语和定义............................................................................I

4缩略语................................................................................2

5总体要求..............................................................................2

6文件交换方式..........................................................................3

6.I通用要求..........................................................................3

6.2接口a（文件接收）.................................................................3

6.3接口b（文件共享）.................................................................3

7WBI）服务方式..........................................................................4

7.1通用要求..........................................................................4

7.2接口c（服务发布）.................................................................4

7.3接口d（服务调用）.................................................................7

8消息队列方式..........................................................................7

81通用要求..........................................................................7

8.2接Ue（消息生产）.................................................................7

8.3接口f（消息消费）.................................................................8

附录A（规范性）错谟信息...............................................................9

附录B（规柩性）数据格式...............................................................10

参考文献................................................................................11

Q/CR821-2021

**.i

刖R

本文件按照＜；B/TI.1—2020《标潴化工作导则第1部分：标准化文件的结构和起卓规则》的规

定起草

请注意本文件的某些内容可能涉及专利本文件的发布机构不承担识别专利的责任

本文件由中国铁道科学研究院集团有限公司电子计算技术研究所归口

本文件起草单位：中国铁道科学研究院集团有限公司电广计算技术研究所、中国铁路北京均集团

有限公司、中国铁路广州局集团有限公司

本文件主要起草人：马志强、马小宁、吴艳华、刘彦军、武威、孙远运、朱建生、李平、周亮理、徐贵红、

刘忠东、张艳祥、周发明、刘飞、王洪业.刘庆猛、刘敏、赵正阳、杨森、刘艺飞、邹丹、张晓栋.徐温雅、

余振国.钱琳、李奇鹏、王佳琦

本文件版权心中国国家铁路集团彳限公司所有,任何单位和个人未经许可不得复制及转让。

III

No.Q/CR821-2021

铁路数据服务平台接口规范

1范圉

本文件规定了铁路数据服务平台数据接口的总体要求和各接口方式的相关要求

本文件适用于铁路数据服务平行数据接口的开发、测试和应用等：

2规范性引用文件

下列文件中的内容通过文中的规他性引用而构成本文件必不可少的条款其中，注日期的引用文

件，仅该H期对应的版本适用于本文件不注H期的引用文件.其最新版本（包括所有的修改单）适用

于本文件。

GB/T28168-2011信息技术中间件消息中间件技术规范

GB/T35295-2017信息技术大数据术语

Q/CR743-2020铁路数据服务平台技术要求

Q/CR775-2020铁路信息系统信息共享与交换技术规范

3术语和定义

GB/T28168—2011.GB/T35295—2017、Q/CR743—2020界定的以及下列术附和定义适用于本

文件。

3.1

铁路数据服务平台railwaydataserviceplatform

为铁路数据提供基础数据管理、数据集成、数据共享、大数据存储与分析等各项服务的软硬件

[来源：Q/CR743—2020,3.1]，

3.2

结构化数据structureddata

一种数据表示形式,按此种形式，由数据元素汇集而成的每个记录的结构都是一致的，并且可以使

用关系模型予以有效描述.

[来源：GB/T35295—2017,2.2.13]I

3.3

非结构化数据unstructureddata

不具有定义模型或未以预定义方式组织的数据

[来源：GB/T35295—2017,2.1.25]

3.4

消息message

不同应用程序（进程或线程）宜接传递或交换的信息

[来源：GB/T28168—20]

Q/CR821-2021No.

3.5

消息的发送者messagesender

产生消息的应用程序。

[来源：GB/T28168—2011,3.1.3]

3.6

消息的接收者messagereceiver

接收消息的应用程序

[来源:GB/T28168—2011,3.1.4]

4缩略语

下列缩略语适用F本文件

HTTP：超文本传输协议(HyperTextTransferProtocol)

JS()^：JavaScriptX'j■象标记(JavaScriptObjectNotation)

REST：我述性状态传递(RepresentationalStateTransfer)

SFTP:安全文件传送协议(SSHFileTransferPKMKOI)

5总体要求

5.1铁路数据服务平台和集成服务平台是铁路•体化信息集成平台的重要组成部分。铁路数据服务

平台为铁路信息系统提供基础数据、共享数据等服务，集成服务平台提供应用集成和流程集成等服

务，铁路数据服务平台数据接n实现铁路数据服务平台与铁路信息系统、集成服务平台之间的数据

交换。

5.2本文件涉及的数据接「1方式包括文件交换方式、web服务方式、消息队列方式三类,其中文件交

换方式包括文件接收和文件共享，web服务方式包括服务发布和服务调用，消息队列))式包括消息生产

和消息消费铁路数据服务平台数据交换方式应符合图।的规定,数据接口实现方式应符合

Q/CK775—2020的规定.

快路值息系统

集成取务平台

企业M务总线

外部协作平台

图1铁路数据服务平台数据交换方式

5.3接口H、h是铁路数据服务平台与铁路信息系统之间的文件交换方式接口；铁路信息系统从铁路

数据服务平价获取认证信息(authorization八传输数据时宜通过加密算法进行数据加密传输

2

No.Q/CR821-2021

5.4接Uc、d是铁路数据服务平台与集成服务平价之间的web服务方式接口；铁路数据服务平台提

供“性服务方式的接口应通过集成服务平台进行注册和调用，

5.5接ne、f是铁路数据服务平台与集成服务平台之间的消息队列方式接口；铁路数据服芬平台通过

消息队列方式的接口与集成服务平台进行消息生产和消息消粮

5.6铁路数据服务平台数据接口格式如下：

a）接口名：接口的名称；

b）描述：对接口内容的谕单描述；

c）参数：请求谢用的参数；

<1）返回信息：调用成功或失败时返回的信息

6文件交换方式

6.1通用要求J

文件交换接口宜采用SFTP协议进行传输,返回结果的错误信息应符合附录A的规定

6.2接口a（文件接收），

采用SFTP协议进行文件交换时,获取SFTP配置信息的接口名称为-rftplnfo”，请求方式为

“POST.输入参数应符合表I的规定.调用成功返回信息应符合表2的规定，调］用失败返回信息应符合

表3的规定

表1输入参数表

输人参数字段描述叁数类型数据类型是否必须

autliorizAlion身份验证hea<lerSiring是

系统名称Siring是

表2调用成功返回信息表

返回字段字段描述数据类型是否必须

5taleCode状态XIni是

mr^Magr返何任务执行情况信息Siring是

tiftplnfuSKTP配置项信息JSON是

表3调用失败返回信息表

返回字段字段描述，数据类型是否必须

MlalrCiNJr状态码ini是

mpiiftage错误描述String是

errorType错误名称Siring是

6.3接口b（文件共享）

采用SFTP协议进行文件交换时，获取SFTP配置信息的接口名称为“sflplnfJ,请求方式为

“POST”.输入参数应符合去1的规定，期用成功返信息应符合去2的规定，谢用失败返何信息应符合

表3的规定。

3

Q/CR821-2021No.

7web服务方式

7.1通用要求

web服务方式接"分为接【I"服务发布和接【Id服务谢用，服务发布接口分为结构化数据导入和

共享接口、非结构化数据导入和共享接口,服务调用接口分为结构化数据和非结构化数据的导入接口

web服务方式接口宜采用Rest协议进行传输

返回结果的错误信息应符合附录A的规定。

7.2接口c（服务发布）

7.2.1结构化数据导入

采用Rest协议进行数据传输时.数据导人接口名称为“dalajson”,请求方式为“POST”.输入参数应

符合表4的规定,谢用成功返回信息应符合表5的规定,调用失败返回信息应符合表6的规定传输的

数据应符合附墟B的规定

表4输入畚数表

帏人参数字段描述参数类型数据类型是否必很

aulhorizalion身份验证headerSiring是

lablrNamr表名queryString是

传输的数据iMxiyJSON是

表5调用成功返回信息表

返回字段字段描述数据类型是否必痢

slatrCodr状态码Ini是

mpAMge返回任务执行情况信息-shmg是

表6调用失败返回信息表

返网字段字段描述数据类型是否必劭

HtatrCoflr状蠢码Ini是

meMxage错误描述1String是

rrrorTypr错误名称String是

7.2.2结构化数据共享

采用Rest协议进行数据传输时,数据共享的接口名称为“queryDuta”，请求方式为“POST”.输人参

数应符合表7的规定，调用成功返回信息应符合表8的规定，调用失败返回信息应符合表9的规定“传

输的数据应符合附录B的规定

表7输入参数表

幡人挈数字段描述参数类型数据类型是否必须

authorixalion身份验证headerString是

querySQL杳询SQLbodySiring是

4

No.Q/CR821-2021

表8洞用成功返回信息表

返回字段字段描述数据类型是否必劭

slalHJndr状态码Int是

mcftAage返阿任务执行情况信息String是

data返回数据JSON是

表9调用失败返回信息表

返阿宇段字段描述数据类型是否必须

statrCodr状态码lilt是

mesucage错误描述Siring是

errorTypc错误名称String&

7.2.3非结构化数据导入

采用Rest协议进行数据传输时.数据导人的接口名称^*ilportFile",请求方式为“POST”，输入参

数应符合表10的规定，调用成功返何信息应符合表II的规定，谢用失败返1"1信息应符合去12的规定“

表10输入参数表

输入参数字段描述参数类型数据类型是否必须

aulliorizalion身份验证headerSiring是

Gd目录1DqueryString是

AleM<15文件的M05值||IHl\Siring是

file文件一单个bodyFile是

表11调用成功返回信息表

返回字段字段描述数据类型是否必别

MtatrCiMir状态码Ini是

mrAftagr返阿任务执行情况信息Siring是

data返回文件的标识码彳Siring是

表12调用失败返回信息表

返回字段字段描述数据类型是否必须

MtatrCodr状态码Ini是

mrnMagr错误描述Siring是

errorType错误名称String是

7.2.4非结构化数据共享

7.2.4.1获取文件的目录信息

采用Rea协议进行数据传输时,获取文件目录下所有文件夹及文件的元数据信息的接口名称为

“fileCatal咽nfe”，请求方式为“POST”，输入参数应符合表13的规定,调用成功返回信息应符合表14的

规定,调用失败返回信息应符合表15的规定传输的数据应符合附录B的规定

Q/CR821-2021No.

表13输入参数表

临人参数字段描述畲数类型数据类型是否必缎

authorizalion身份验证headerString是

Gd目录IDqueryString是

表14调用成功返回信息表

返向字段字段描述数据类暨是否必须

"lateCodr状态码Int是

返阿任务执行境况西息String是

data文件目录数据（文件夹信息、文件信息等）JSON是

*15调用失败返回信息表

返网字段字我描述数据类里是齐必劭

HtateCmle状态码ini是

mrftjmgr错误描述String是

errorType错误名称Siring是

7.2.4.2获取文件

采用Best协议进行效据传输时,获取文件的接口名称为“fetchFile-，请求方式为“GET”.摘人文件

应符合表16的规定,谢用成功返I可信息应符合衣17的规定，谢用失败返何信息应符合表18的规定

表16输入参数表

输人参数字段描述多数类型数据类型是否必须

authorization身份脸证hra<lrrString是

rid文件IDquerySiring是

表17调用成功返回信息表

返网字段字段描述数据类型是否必劭

siatrCmir状态码Int是

menage返何任务执行情况信息String是

'件

GleF.lr是

表18调用失败返回信息表

返何字段字段描述数据类激是否必然

HtatrCmlr状态科Int是

mejiimge错误描述String是

rrrorTyiM,错误名称Siring是

7.2.4.3获取校验文件

采用Rest协议进行数据传输时，获取文件对应的MD5信息的接口名称为“fetchFileMd5”,请求方

6

No.Q/CR821-2021

式为“CET”.输入参数应符合表19的规定，调用成功返回信息应符合表20的规定,调用失败返回信息

应符合表21的规定，

«19输入参数表

输入叁数字段描述参数类型数据类型是否必须

aulhorizalion身份验证headerSiring是

rid文件IDquerySiring是

表20调用成功返回信息表

返网字段字段描述数据类型是否必衡

sitatrCode状毒码Int是

message返回任务执行情况信息Siring是

md5返回文件的MD5信息是

*21调用失败返回信息表

返网字段字段描述数据类型是否必御

MlatrCixir状态码Ini是

me^Aage错误描述Siring是

rrrorType错误名称,String是

7.3接口d（服务调用）

7.3.1结构化数据导入

采用Rest协议进行数据传输时,数据导人接口名称为“MnwtDatHimport”，其他要求应符合7.2.1的

规定。

7.3.2非结构化数据导入

采用Rest协议进行数据传输时，数据导人接F1名称为“5闺0131）1^加卜＞旧”，其他要求应符合7.2.3

的规定.

8消息队列方式

8.1通用要求

消息队列方式接口宜采用kafka.MQ等中间件进行传输，返回结果的错误信息应符合附录A的

规定。

8.2接口e（消息生产）

菸于kulla的消息队列方式的接U进彳j数据传输时，获取消息队列生产者配置信息的接口名称为

-kafkaPrcKlucerlnfo",请求方式为-POST'.输入参数应符合衣22的规定，调用成功返回信息应符合

表23的规定,调用失败返网信息应符合表24的规定

7

Q/CR821-2021No.

表22输入参数表

输入参数字照描述叁数类型数据类整是否必须

authorizalion身份验证hratlrrString是

咿MmName系统名称quer>>String是

lableName表名queryString，1

表23调用成功返回信息表

返回字段字段描述数据类型是否必沏

HlalrCodc状态码ini是

返回任务执行情况信息ftring是

kafkalnfo返同参数配膏信息Maprkey,valur是

表24调用失败返回信息表

返何字段字段描述数据类型是否必须

staleCode状忠叫Im是

mr»sagr借误描述SUMIg是

errorType错提名称Siring是

8.3接口r（消息消费）

堪于kafka的消息队列方式的接口进行数据传输时.获取消费者配置信息的接口名称为

"kaftaConsumerlnfo",请求方式为“POST”,愉人参数应符合表25的规定,调用成功返回信息应符合

表26的规定.商用失败返回信息应符合表27的规定

表25渝入参数表

辎人叁数字段描述数据类型是否必须

aulhorizalion身份脸证hradrrString是

systemID系统II）queryString是

tabielD表IDqueiyString是

表26调用成功返回信息表

返回字段字殴描述放据类型是否必须

MtaleCmle状强码In!是

meM^age返回任务执行情况信息Siring是

kufkalnfo返mi叁数配者信息Mapkey.value：是

袅27调用失败返回信息表

返回字段字段描述数据类型是否必湎

HlaleCode状态码Ini是

mrMMugr错误描述String是

errorTypr错误名称Siring是

8

No.Q/CR821-2021

附录A

（规范性）

错误信息

错误信息应符合表A.I的规定

表A.1错误信息列表

MUteCode(状态码)“rrurType（错误名称）.menage（错误描述）

400