JT∕T 1415.3-2022 交通运输数据资源交换与共享 第3部分：数据格式与接口.pdf

ICS 35.240.60CCS R 07中华人民共和国交通运输行业标准JT / T 1415. 32022交通运输数据资源交换与共享第 3 部分:数据格式与接口Transportation data exchanging and sharingPart 3:Data format and interface2022-01-13 发布2022-04-13 实施中华人民共和国交通运输部发 布目次前言引言1 范围12 规范性引用文件13 术语和定义、缩略语14 资源共享要求15 资源交换要求5附录 A(资料性) 结构化数据文件内容示例7附录 B(规范性) 控制文件和应答文件格式8参考文献11JT/ T 1415.32022前言本文件按照 GB/ T 1. 12020标准化工作导则 第1 部分:标准化文件的结构和起草规则的规定起草。本文件是 JT/ T 1415交通运输数据资源交换与共享的第 3 部分。 JT/ T 1415 已经发布了以下部分: 第 1 部分:总体架构; 第 2 部分:通用技术要求; 第 3 部分:数据格式与接口。请注意本文件的某些内容可能涉及专利。 本文件的发布机构不承担识别专利的责任。本文件由交通运输信息通信及导航标准化技术委员会提出并归口。本文件起草单位:交通运输部科学研究院、长城计算机软件与系统有限公司、贵州省交通运输厅、贵州银智科技发展有限公司。本文件主要起草人:郭明多、李洪囤、杨艳芳、黄莉莉、曹剑东、陈博、段成民、刘娜、田璐、郭亚茹、张莉、周雷、尚华、田仁薪、杨波、王君、张冰冰、李政达、康厚荣。JT/ T 1415.32022引言在交通运输数据资源共享交换的总体架构、通用技术和数据格式与接口等方面提出统一要求,有利于进一步实现行业数据资源高效共享与开发利用,对完善交通运输行业数据资源共享交换体系具有重要意义。 JT/ T 1415 由三个部分构成: 第 1 部分:总体架构。 目的是规范交通运输数据资源共享交换平台的体系架构、功能架构、业务架构等总体架构。 第 2 部分:通用技术要求。 目的是提出交通运输数据资源共享交换的共享、交换、日志、部署环境和数据安全等通用技术要求。 第 3 部分:数据格式与接口。 目的是规范交通运输数据资源共享交换平台资源共享和交换的数据格式与接口要求。JT/ T 1415.32022交通运输数据资源交换与共享第 3 部分:数据格式与接口1 范围本文件规定了交通运输数据资源共享交换平台的资源共享要求和资源交换要求。本文件适用于交通运输数据资源共享交换平台的数据格式与接口的规划、设计、建设和运维。2 规范性引用文件下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。 其中,注日期的引用文件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。GM/ T 00042012 SM3 密码杂凑算法JT/ T 1415. 22022 交通运输数据资源交换与共享 第 2 部分:通用技术要求IETF RFC 1945 超文本传输协议 1. 0(Hypertext Transfer Protocol 1. 0)IETF RFC 2616 超文本传输协议 1. 1(Hypertext Transfer Protocol 1. 1)W3C 简单对象访问协议 1. 1(Simple Object Access Protocol 1. 1)W3C 简单对象访问协议 1. 2(Simple Object Access Protocol 1. 2)3 术语和定义、缩略语3.1 术语和定义JT/ T 1415. 2 界定的术语和定义适用于本文件。3.2 缩略语下列缩略语适用于本文件。ANSI:美国国家标准学会(American National Standards Institute)GBK:汉字内码扩展规范(Guo Biao Kuozhan)SFTP:安全文件传输协议(Secure File Transfer Protocol)UTF-8:Unicode 的可变长度字符编码(8-bit Unicode Transformation Format)4 资源共享要求4.1 数据库要求以数据库方式提供资源时,数据更新方式分为全量更新和增量更新。 全量更新的数据字段中应包含主键。 增量更新的数据字段应包含主键、时间戳和操作标识,其中操作标识中“C”代表增量新增,“D”代表增量删除。 若存在主键缺失的情况,应设置联合主键。1JT/ T 1415.320224.2 数据文件要求4.2.1 基本要求以数据文件方式提供资源时,应包括结构化数据文件和附件文件夹,结构化数据文件是特定字符分隔文本文件,当无附件时,附件文件夹为空。4.2.2 文件格式结构化数据文件应为 csv 格式,附件文件可包括图像、文档、音视频等格式类型。数据文件压缩应满足以下要求:a) 同一批次仅有一个结构化数据文件时无需压缩。b) 同一批次包含多个结构化数据文件且有执行顺序要求时,应将多个文件压缩为一个 ZIP 文件,并提供索引信息,索引信息具体要求符合 4. 2. 5。c) 有附件时应将同一批次的结构化数据文件和附件文件夹压缩为一个 ZIP 文件。4.2.3 文件命名4.2.3.1 结构化数据文件命名结构化数据文件应以“业务编码-资源编码-时间戳. 后缀名”格式命名,其中:a) 业务编码:唯一标识其所属业务,由 10 位 ASCII 字符组成:前 6 位为大写字母,采用信息系统简称的拼音首字母;后 4 位为数字字符,用于区分同一信息系统的不同传输业务。b) 资源编码:唯一标识对应的数据资源,具体编码在注册资源时由部级共享平台或省级交通共享平台生成。c) 时间戳:标识生成时间,格式为 24 小时制时间格式“YYYYMMDDhhmmss”。d) 后缀名:标识数据格式,如. csv。示例:SJHJYW0000-014GL04OATGCA0001-20180726153000. csv4.2.3.2 附件命名附件名包括显示名和文件名,其中文件名应以附件内容的哈希值命名。4.2.4 文件内容结构化数据文件内容应符合以下要求:a) 第一行为字段名称,使用西文半角符号“, ”进行分隔。b) 每条记录存为一行,每行数据应以回车换行( rn)分隔。c) 数据项之间以西文半角符号“,”进行分隔。d) 数据内容以西文半角双引号()限定,数据内容包含双引号时,用转义字符( )表示。提供资源含附件时,结构化数据文件内容还应包含该附件显示名和文件名字段。 结构化数据文件内容示例见附录 A。4.2.5 索引信息索引信息位于控制文件(见 5. 2. 2)的业务附加信息中,用于标识同一批次内结构化数据文件的执行顺序,根据该顺序实现资源提供与服务使用。 控制文件的业务附加信息应符合附录 B 的规定。索引信息中每段信息格式为:结构化数据文件名称 + “:” + 操作标识 + 换行符。 其中,操作标识用于标识该数据文件中数据的操作类型,U 代表全量更新, C 代表增量新增,D 代表增量删除。示例 1:SJHJYW0000-014GL04OATGCA0001-20200726153000. csv:C2JT/ T 1415.32022示例 2:SJHJYW0000-014GL04OATGCA0001-20200727153000. csv:D4.3 接口要求4.3.1 接口分类接口分为认证接口和业务接口两类。 认证接口用于验证调用者身份的合法性,业务接口用于提供数据资源服务。4.3.2 接口接入接口应支持 RESTful 或 WebService 接口形式。 RESTful 服务消息封装协议应采用IETF RFC 1945超文本传输协议 1. 0或IETF RFC 2616 超文本传输协议 1. 1,WebService 服务消息封装协议应采用W3C 简单对象访问协议 1. 1或W3C 简单对象访问协议 1. 2。接口接入信息应包含:a) 接口访问地址。b) 接口参数:包括参数中文名、参数英文名、参数类型。c) 接口编码:UTF-8 或者 GBK。d) 接口描述。4.3.3 认证接口4.3.3.1 接口信息认证接口信息应包含:a) 服务地址:https:/ / IP 地址:端口。b) 接口路径:/ oauth/ token。c) 接口类型:RESTful 或 WebService。d) 接口请求方式:POST。e) 接口编码:UTF-8。f) 内容类型:application/ x-www-form-urlencoded。4.3.3.2 输入参数认证接口输入参数应符合表 1 的规定。表 1 认证接口输入参数序号参 数 名 称参 数 代 码参 数 类 型非 空备 注1用户名usernameString是 登录账户2密码passwordString是 登录密码3身份标识client_idString是 用户接口调用唯一身份标识4加密信息client_secretString是 身份标识加密信息5认证方式grant_typeString是 接口调用认证方式 client_cre-dentials 或 password 或 CA 证书,默 认 client _ credentials。 使 用password 模式需要传入用户名及密码,client_credentials 时无需传入用户名密码6权限范围scopeString是 read 或 write,默认值 read3JT/ T 1415.320224.3.3.3 返回参数认证接口返回参数应符合表 2 的规定。表 2 认证接口返回参数序号参 数 名 称参 数 代 码参 数 类 型非 空备 注1身份令牌access_tokenString是2令牌类型token_typeString是 默认值 Bearer3过期时间expires_inString是 从调用认证接口获得身份令牌开始计时,在该时段内响应的身份令牌有效,单位为秒4.3.4 业务接口4.3.4.1 接口信息业务接口信息应包含:a) 服务地址:https:/ / IP 地址:端口。b) 接口路径:/ manage/ service。c) 接口类型:RESTful 或 WebService。d) 接口请求方式:POST。e) 接口编码方式:UTF-8。f) 内容编码类型(Content-Type):application/ json。4.3.4.2 输入参数业务接口输入参数应符合表 3 的规定。表 3 业务接口输入参数序号参 数 名 称参 数 代 码参 数 类 型非 空备 注1资源服务标识sidString是 资源服务接口唯一标识2业务参数编码dataCodeString是 资源服务接口调用时的业务参数3业务参数数值dataValueString是 业务参数的输入值4逻辑符号operationString是 描述业务参数与数据之间的关系,如等于、大于、小于等4.3.4.3 返回参数业务接口返回参数应符合表 4 的规定。表 4 业务接口返回参数序号参 数 名 称参 数 代 码参 数 类 型非 空备 注1调用状态标识stateCodeString是 资源服务接口调用状态标识2错误描述信息errorDescriptionString 错误信息,调用成功则为空3业务参数数值dataJSON 业务数据返回值4JT/ T 1415.320224.3.4.4 状态码调用业务接口时,通过状态码判定接口调用情况,业务接口状态码应符合表 5 的规定。表 5 业务接口状态码状 态 码说 明0000成功0001找不到服务配置信息0002服务停用0003没有数据或数据准备中0004没有权限或令牌过期0101当前资源不存在0102当前资源未发布0103合并资源不存在0104合并结果集出错0201文件下载失败0202请调用文件下载接口0203数据准备中0204当前不是异步任务0301调用 RESTful 客户端发送错误,地址为空0302调用 RESTful 接口发生错误0401调用 WebService 接口发生错误0501数据节点配置为空,但返回的不是数组对象0502调用 csv 接口发生错误0601请求字段错误,字段不存在0602条件字段错误,字段不存在0701数据库查询错误0901权限认证未过0902权限认证调用失败9999转发类服务接口调用失败或无数据返回5 资源交换要求5.1 文件夹结构要求5.1.1 在前置机中创建文件传输文件夹,其文件夹结构分为主文件夹和业务文件夹:a) 主文件夹:在前置机初始化时自动生成且对 SFTP 登录用户不可见。b) 业务文件夹:对 SFTP 登录用户可见。5.1.2 主文件夹和业务文件夹共同组成文件传输任务的实际物理路径。 其中,业务文件夹包含三个层级:5JT/ T 1415.32022a) 第一级为业务代码文件夹,由业务名称前 6 位小写首字母拼接 4 位数字组成,业务名称不足 6位的以 x 补足。b) 第二级为任务代码文件夹,由任务名称首字母大写拼接 8 位不重复序列号组成。c) 第三级为业务功能文件夹,按照功能划分为四个文件夹: / send:发送文件夹,用于传输待发送文件的路径; / receive:接收文件夹,用于存放接收文件的路径; / succeed:发送成功文件夹,用于存放发送成功文件的路径; / failed:发送失败文件夹,用于存放发送失败文件的路径。示例 1:业务代码文件夹 / gsglsj0000 或/ csxxxx0000示例 2:任务代码文件夹 / GSGLHB10030609示例 3:业务功能文件夹 / data/ nfs/ data/ special/ gsglsj0000/ GSGLHB10030609/ send5.2 交换文件要求5.2.1 数据文件交换的数据文件包含所需要传输的数据或信息,不应传输可执行文件和脚本文件。 传输数据文件数量较多时,应对数据文件打包。 部级共享平台或省级交通共享平台应明确数据文件大小的限制要求,对较大数据文件应进行压缩。5.2.2 控制文件控制文件用于数据文件传输控制和校验,应包含文件信息、加密信息、投放信息和业务附加信息等。控制文件应符合以下要求:a) 控制文件命名与数据文件命名一致,与所控制的数据文件一一对应。b) 控制文件中每段信息格式为:信息段名称 + “:” + 信息段内容 + “ n”,信息段名称不能重复。c) “#”开始的段落为说明性文字,不作处理。d) 控制文件保存为 ANSI 编码纯文本格式,其标志性字符为西文半角符号,如:#,及要求为字母数字处,格式要求符合附录 B 的规定。5.2.3 应答文件应答文件用于数据文件处理结果的反馈信息,应包含文件信息、处理结果和投放信息等。 应答文件应符合以下要求:a) 应答文件命名与所应答控制文件命名一致,与所应答控制文件一一对应。b) 应答文件中每段信息格式为:信息段名称 + “:” + 信息段内容 + “ n”。c) “#”开始的段落为说明性文字,不作处理。d) 应答文件保存为 ANSI 编码纯文本格式,其标志性字符为西文半角符号,如:#,及要求为字母数字处,格式要求符合附录 B 的规定。6JT/ T 1415.32022附 录 A(资料性)结构化数据文件内容示例A.1 不包含附件的数据文件内容示例数据文件内容示例如下: RegistrationNumber, ShipIdentificationNumer, ChineseNameOfVessel, EnglishNameOfVessel,ChineseNameUsedBefore, InitialRegistrationNumber, IMONumber, MMSINumber, ValueOfShip,ClassNumber, CallSign, ShipbuildingDate, ShipyardName, EnglishNameOfShipyard, Shipbuilding-Place, LengthOverall, MouledBreadth, MouledDepth, GrossTonnage, NetTonnage, DeadWeight-Tonnage船舶登记号 1,船舶识别号 1,中文船名 1,英文船名 1,曾用中文船名 1,初次登记号1,IMO 编号 1, MMSI 编号 1, 船舶价值 1, 船检登记号 1, 船舶呼号 1, 船舶建造日期1,造船厂名称 1, 造船厂英文名称 1, 造船地点 1, 船舶总长(标准)1, 船舶型宽(标准)1,船舶型深 1,总吨 1,净吨 1,参考载重吨 1船舶登记号 2,船舶识别号 2,中文船名 2,英文船名 2,曾用中文船名 2,初次登记号2,IMO 编号 2, MMSI 编号 2, 船舶价值 2, 船检登记号 2, 船舶呼号 2, 船舶建造日期2,造船厂名称 2, 造船厂英文名称 2, 造船地点 2, 船舶总长(标准)2, 船舶型宽(标准)2,船舶型深 2,总吨 2,净吨 2,参考载重吨 2A.2 包含附件的数据文件内容示例数据文件内容示例如下: NameOfSeafer, SpellingOfName, RegistrationNumberOfGrew, TypeOfRegistration, Codes-ForSexualDistinction, DateOfBirth, NumberOfIDCertificate, Nationality, ContactNumberOfSeafer,InformationOfPhoto,DisplayNameOfAppendix,FileNameOfAppendi船员姓名1,姓名拼音1,船员注册号1,注册类别1,性别代码1,出生日期1,身份证号码 1,国籍 1,船员联系电话 1,照片信息 1,附件显示名 1,附件文件名 1船员姓名2,姓名拼音2,船员注册号2,注册类别2,性别代码2,出生日期2,身份证号码 2,国籍 2,船员联系电话 2,照片信息 2,附件显示名 2,附件文件名 27JT/ T 1415.32022附 录 B(规范性)控制文件和应答文件格式B.1 控制文件B.1.1 文件格式控制文件格式如下,斜体加粗部分为部级共享平台或省级交通共享平台用户填写部分,以“ n”结尾:文件信息数据文件名:数据文件名控制文件名:控制文件名大小:大小哈希校验码:哈希校验码加密信息密钥密文:密文投放信息源节点名:源节点名目的节点名:目的节点名接收目录名:接收目录名业务授权码:业务授权码业务附加信息业务附加信息控制文件填写应符合表 B. 1 的规定。表 B.1 控制文件填写规则字 段 名 称填 写 规 则文件名 控制文件命名与数据文件命名完全一致大小 以字节为单位的数据文件实际大小,不是占用磁盘空间大小哈希校验码 数据文件的哈希值,采用符合 GM/ T 0004 要求的加密算法密钥密文 如需加密,则发送节点对数据文件自动执行对称加密,并将加密密钥通过非对称加密算法加密后的密钥写入控制文件源节点名 发送端交换节点名,由各级共享交换平台配置并提供目的节点名 接收端交换节点名,如果目的节点是多节点,采用“,”分隔,由各级共享交换平台配置并提供接收目录名 由各级共享交换平台配置并提供业务授权码 由各级共享交换平台配置并提供业务附加信息 业务附加信息为可选项,最大不超过 4096 个全角字符(即不超过 4096 个汉字)8JT/ T 1415.32022B.1.2 文件样式控制文件的标志性字符应为西文半角符号,如:#,及要求为字母数字处,“#”开始的段落为说明性文字,系统不处理。 控制文件格式样例如下:#控制文件格式样例文件信息数据文件名:SJHJYW0000-014GL04OATGCA0001-20180726153000. csv控制文件名:SJHJYW0000-014GL04OATGCA0001-20180726153000. ctl大小:10032哈希校验码:11dae069f467b524dcfa28ae11fe6d41加密信息密钥密文:3e3dc0b9b61097d5673b06ea7fc321c42b718a39954c80c0e64dfac861f06027efb5e5c6af847324fd904f5eb2ef05101d2a5a8a50939c5fa9ae93ffbde4a6253e3dc0b9b61097d5673b06ea7fc321c42b718a39954c80c0e64dfac861f06027efb5e5c6af847324fd904f5eb2ef05101d2a5a8a50939c5fa9ae93ffbde4a625:投放信息源节点名:BL0100目的节点名:BC0100接收目录名:/ home/ gtpuser/ data/ special/ gsglsj0000/ GSGLHB10030609/ receive业务授权码:101d2a5a8a50939c5fa9ae93ffb。B.2 应答文件B.2.1 文件格式应答文件格式如下,斜体加粗部分为部级共享平台或省级交通共享平台用户填写部分,以 / n结尾:文件信息数据文件名:数据文件名控制文件名:控制文件名应答文件名:应答文件名大小:大小哈希校验码:哈希校验码处理结果校验结果:校验结果处理结果描述:处理结果描述投放信息源节点名:源节点名目的节点名:目的节点名接收目录名:接收目录名业务附加信息业务附加信息应答文件填写应符合表 B. 2 的规定。9JT/ T 1415.32022表 B.2 应答文件填写规则字 段 名 称填 写 规 则文件名 应答文件命名与数据文件命名必须完全一致大小 以字节为单位的数据文件实际大小,而不是占用磁盘空间大小哈希校验码 数据文件的哈希值,采用符合 GM/ T 0004 要求的加密算法校验结果 接收方或传输平台依据控制文件的信息对数据文件进行校验的结果,内容为:“通过”“异常”处理结果描述 由接收方或传输平台根据处理结果给出的具体描述,如业务数据加载错误、控制文件中哈希码校验错误等源节点名 发送端交换节点名,由各级共享交换平台配置并提供目的节点名 接收端交换节点名,由各级共享交换平台配置并提供接收目录名 由各级共享交换平台配置并提供业务附加信息 业务附加信息为可选项,最大不超过 4096 个全角字符(即不超过 4096 个汉字)B.2.2 文件样式应答文件的标志性字符应为西文半角符号,如:#,及要求为字母数字处,“#”开始的段落为说明性文字,系统不处理。 应答文件格式样例如下:#应答文件格式样例文件信息版本号:V1. 0数据文件名:WFCXAJ0000-超限信息表-20171026-0001. csv控制文件名:WFCXAJ0000-超限信息表-20171026-0001. ctl应答文件名:WFCXAJ0000-超限信息表-20171026-0001. resp大小:10032哈希校验码:11dae069f467b524dcfa28ae11fe6d41处理结果记录数:100校验结果:通过。处理结果描述:数据文件“用户名”字段长度超过限制,数据未能正常加载。投放信息源节点名:BL0100目的节点名:BC0100接收目录名:/ home/ gtpuser/ data/ special/ gsglsj0000/ GSGLHB10030609/ receive01JT/ T 1415.32022参 考 文 献1 C 0126. 22019 国家政务服务平台数据交换与共享接口 第 2 部分:共享接口要求11JT/ T 1415.32022