T-CESA《基于区块链的生态环境数据共享交换 第4部分：接口要求》

ICS35.240.01

CCSL70

团体标准

T/CESAXXX.4—202X

基于区块链的生态环境数据共享交换

第4部分：接口要求

Blockchain-basedecologicalenvironmentdatasharingandexchange-

Part4：Interfacerequirements

征求意见稿

在提交反馈意见时，请将您知道的相关专利连同支持性文件一并附上。

已授权的专利证明材料为专利证书复印件或扉页，已公开但尚未授权的专利申请

证明材料为专利公开通知书复印件或扉页，未公开的专利申请的证明材料为专利申请

号和申请日期。

202X-XX-XX发布202X-XX-XX实施

中国电子工业标准化技术协会发布

T/CESAXXX.4—202X

目次

前言3

引言4

1范围5

2规范性引用文件5

3术语和定义5

4缩略语6

5接口规则6

5.1身份认证6

5.2API接口6

6接口描述7

6.1生态环境数据目录7

6.2内部管理7

6.3数据共享13

附录A（规范性）对象描述16

附录B（规范性）返回状态码21

20

T/CESAXXX.4—202X

基于区块链的生态环境数据共享交换第4部分：接口要求

1范围

本文件规定了用于区块链的多源生态环境数据共享交换的数据存储，数据目录上链，前置机部署成

为节点后数据库与节点的通信形式，节点间的数据通信，数据目录查询，数据申请等智能合约运行的通

信，数据审批的流转，数据传输，数据共享记录的存证等过程中的数据通信接口的功能实现和使用方法，

对各类数据和操作情况的处理方式等内容。

本文件适用于设计、研发、实施、应用、评估生态环境数据共享交换的机构的环境信息数据共享交

换活动。

2规范性引用文件

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

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

文件。

GB/T18391.3—2009信息技术元数据注册系统(MDR)第3部分：注册系统公共设施元模型

GB/T42752-2023区块链和分布式记账技术参考架构

3术语和定义

GB/T18391.3—2009、GB/T42752-2023界定的以及下列术语和定义适用于本文件。

3.1

数据共享交换datasharingexchange

公共建立数据汇集的通道使不同地方使用不同计算机、不同软件的用户能够读取他人数据并进行各

种操作运算和分析。实现数据从一个系统跨授权边界访问或传递到另一个系统时所需要的协议平台，为

访问或交换数据进行许可授权、形式转换、数据传输、使用记录和保证数据安全进行系统性设计。

3.2

数据接口datainterface

进行数据传输时向数据连接线输出数据的通道。由两个功能单元的功能特性、物理互联特性、信号

交换特性及其它特性定义。

3.3

数据目录datacatalog

以核心元数据为主要描述方式，按照资源分类体系对公共数据进行有序排列的一组信息，用以描述

公共数据的特征,以便对公共数据进行检索、定位与获取。

[来源：GB／T18391.3—2009,定义3.2.18]

3.4

5

T/CESAXXX.4—202X

前置机front-endprocessor

一种位于数据处理链路前端的数据处理设备，在机构后台核心处理系统和外部数据业务之间提供各

种接口服务，通过专线或硬件隔离技术将运行这个软件的计算机连接到外部企业的外网系统上，用于对

数据进行加工、转换、清洗、聚合等操作，以便于后续的数据处理和分析，运行这个软件的计算机，从

功能上称呼为前置机。

3.5

智能合约Smartcontracts

一种基于区块链技术的自动化合约，可以在不需要第三方干预的情况下自动执行合同条款。智能合

约通常使用编程语言编写，存储在分布式账本中并通过区块链网络进行验证和执行。

[来源：GB/T42752—2023，3.13，有修改]

4缩略语

下列缩略语适用于本文件

ETL：提取，转换和加载（Extract,Transform,andLoad）

FTP：文件传输协议（FileTransferProtocol）

HTTP：超文本传输协议（HyperTextTransferProtocol）

HTTPS：超文本传输协议安全版（HyperTransferProtocoloverSecureSocketLayer）

PKI：公钥基础设施（publickeyinfrastructure）

SFTP：完全文件传送协议（SecretFileTransferProtocol）

SMTP：简单邮件传输协议（SimpleMailTransferProtocol）

XML：可扩展标记语言（ExtensibleMarkupLanguage）

5接口规则

5.1身份认证

数据需求方应通过身份认证申请后，按照数据共享平台或数据提供方定义的数据接口获取数据。相

关要求应包括但不限于：

a)数据需求方通过用户名/密码向数据共享平台请求身份认证；

b)通过认证后，数据需求方按照数据共享平台或数据提供方提供的接口方式、接口说明等要求来

获取数据，具体接口要求见5.2。

5.2API接口

API接口是数据提供方通过数据共享平台提供的数据获取方式，数据需求方通过调用数据提供方定

义的API接口获取数据。

API接口说明应包括但不限于：

a)接口名称：名称突出数据内容指向的对象以及对象具有的显著特征；

b)接口描述：接口给功能性描述；

c)接口地址：接口的调用地址；

d)请求方式：对数据进行操作采用的类型，可采用GET或POST等方式；

e)请求参数：访问接口时必要的或可选的参数，说明参数名称、类型、是否必填和描述等；

60

T/CESAXXX.4—202X

f)返回结果：请求数据后，系统返回的请求结果。包括但不限于返回状态码、返回消息说明和数

据信息等内容；

g)返回字段说明：返回结果中数据信息的字段说明，包括但不限于字段的名称、类型和描述等信

息；

h)返回状态码：请求数据后，系统返回的状态码及其说明。

6接口描述

6.1生态环境数据目录

6.1.1生态环境数据接口

数据类型定义

1）数据类型DataCatalogVO为复合类型，描述一条生态环境数据信息，见表1.

表1

名称类型是否必填描述

NameString是数据目录名称

dataItemString是数据项

dataAbstractString是数据更新周期

CodeString是数据目录编码

shareTypeString是共享类型

生态环境数据接口

接口名称：ResponseData<Page<DataCatalogVO>>getList(pageNo,pageSize)

接口地址：43:10353/server/datacatalog/list

接口描述：分页获取所有生态环境数据

请求方式：GET

请求参数：分页参数

返回结果：生态环境分页数据

6.2内部管理

6.2.1内设机构

数据类型定义

1)数据类型SysOrgVO为复合类型，描述一条内设机构，见表2.

表2

名称类型是否必填描述

orgTypeInteger是机构类型

nameString是数据目录名称

codeString是机构编码

statusInteger是状态

7

T/CESAXXX.4—202X

seqInteger是排序

2)数据类型SysOrgTreeVO为复合类型，描述一条内设机构的树结构，见表3.

表3

名称类型是否必填描述

orgLevelInteger是机构所属级别

nameString是数据目录名称

codeString是机构编码

lookupPathString是路径

nodeLevelInteger是节点级别

subOrgCountsInteger是是否是叶子节点

内设机构接口

方法1：

接口名称：ResponseData<SysOrgVO>save(SysOrgVOsysOrgVo)

接口描述：保存一条内设机构。

接口地址：43:10353/server/org/save

请求方式：POST

请求参数：sysOrgVo为内设机构信息。

返回参数：内设机构信息

方法2：

接口名称：ResponseData<SysOrgVO>submitExamine(SysOrgVOsysOrgVo)

接口描述：提交一条内设机构

接口地址：43:10353/server/org/submitExamine

请求方式：POST

请求参数：sysOrgVo为内设机构信息。

返回参数：内设机构信息

方法3：

接口名称：ResponseData<Boolean>delOrg(DelRequestBodyVOdelRequestBodyVO)

接口描述：删除一条内设机构

接口地址：43:10353/server/org/del/one

请求方式：POST

请求参数：删除参数

返回参数：是否成功的布尔值

方法4：

接口名称：ResponseData<Page<SysOrgVO>>getAllList(pageNo,pageSize)

接口描述：分页查询内设机构列表

接口地址：43:10353/server/org/get/pageList

请求方式：GET

请求参数：分页参数

80

T/CESAXXX.4—202X

返回参数：内设机构分页列表

方法5：

接口名称：ResponseData<List<SysOrgTreeVO>>getUserTree()

接口描述：查询机构属性列表

接口地址：43:10353/server/org/get/userTree

请求方式：GET

请求参数：无

返回参数：机构树形结构

6.2.2业务目录

数据类型定义

1)数据类型DutyCatalogVO为复合类型，描述一条业务目录数据结构，见表4.

表4

名称类型是否必填描述

orgIdString是机构id

orgCodeString是机构编码

orgNameString是机构名称

resourceNameString是数据源名称

codeColumnString是核心数据项

statusInteger是状态

2)数据类型DutyCatalogUpdateVO为符合类型，描述一条提交或更新的业务目录数据结构，见表

5.

表5

名称类型是否必填描述

orgIdString是机构id

codeString是业务目录编码

deptNameString是机构名称

resourceNameString是数据源名称

codeColumnString是核心数据项

statusInteger是状态

dutyTypeString是业务类型

业务目录接口

方法1：

接口名称：ResponseData<DutyCatalogVO>save(DutyCatalogVOdutyCatalogVO)

接口描述：保存一条业务目录

接口地址：43:10353/server/dutycatalog/save

请求方式：GET

请求参数：业务目录属性

9

T/CESAXXX.4—202X

返回参数：业务目录

方法2：

接口名称：ResponseData<DutyCatalogUpdateVO>submitAudit(DutyCatalogUpdateVO

dutyCatalogUpdateVO)

接口描述：提交或更新一条业务目录

接口地址：43:10353/server/dutycatalog/commit

请求方式：POST

请求参数：业务目录更新属性

返回参数：业务目录

方法3：

接口名称：ResponseData<Boolean>delete(DelRequestBodyVOdelRequestBodyVO)

接口描述：删除一条业务目录

接口地址：43:10353/server/dutycatalog/del/one

请求方式：POST

请求参数：删除参数

返回参数：删除成功的布尔值

方法4：

接口名称：ResponseData<Page<DutyCatalogVO>>getAllList(pageNo,pageSize)

接口描述：分页获取业务目录列表

接口地址：43:10353/server/dutycatalog/get/list

请求方式：GET

请求参数：分页参数

返回参数：业务目录的分页数据

方法5：

接口名称：ResponseData<Map<String,Object>>importData(MultipartFilefile,

HttpServletResponseresponse,LongorgId)

接口描述：业务目录数据导入

接口地址：43:10353/server/dutycatalog/importData

请求方式：POST

请求参数：导入文件

返回参数：导入结果

6.2.3数据目录

数据类型定义

1)数据类型DataCatalogVO是符合类型，描述一条数据目录的结构，见表6。

表6

名称类型是否必填描述

dutyIdString是业务目录ID

codeString是数据目录编码

deptIdString是所属机构ID

deptCodeString是机构code

100

T/CESAXXX.4—202X

orgIdString是所属内设机构ID

itemVOListString是数据项列表

NameString是数据目录名称

timeUnitString是数据更新周期

dataVersionString是数据版本号

sysNameString是信息系统ID

2)数据类型DataCatalogDelVO是复合类型，描述删除数据目录的参数结构，见表7。

表7

名称类型是否必填描述

idString是数据目录ID

versionString是版本号

deleteReasonString是删除原因

数据目录接口

方法1：

接口名称：ResponseData<Boolean>save(DataCatalogVOvo)

接口描述：保存一条数据目录

接口地址：43:10353/server/datacatalog/save

请求方式：POST

请求参数：数据目录属性

返回参数：是否保存成功

方法2：

接口名称：ResponseData<Boolean>submit(DataCatalogVOvo)

接口描述：提交一条数据目录

接口地址：43:10353/server/datacatalog/submit

请求方式：POST

请求参数：数据目录属性

返回参数：是否提交成功

方法3：

接口名称：ResponseData<Page<DataCatalogVO>>getAllList(pageNo,pageSize)

接口描述：分页获取数据目录列表

接口地址：43:10353/server/datacatalog/list

请求方式：GET

请求参数：分页参数

返回参数：数据目录分页列表

方法4：

接口名称：ResponseData<DataCatalogVO>details(Longid)

接口描述：获取数据目录详情

接口地址：43:10353/server/datacatalog/details

请求方式：GET

11

T/CESAXXX.4—202X

请求参数：数据目录ID

返回参数：数据目录详情

方法5：

接口名称：ResponseData<Boolean>delete(DataCatalogDelVOdelVO)

接口描述：删除数据目录

接口地址：43:10353/server/datacatalog/del/one

请求方式：POST

请求参数：删除属性

返回参数：是否删除成功

6.2.4信息系统

数据类型定义

1)数据类型InfoSysVO是复合类型，描述一条信息系统的结构，见表8。

表8

名称类型是否必填描述

netenvString是网络环境

ContactsString是联系人

contactTypeString是联系方式

dutyCatalogStrListString是对应的业务目录

nameString是信息系统名称

2)数据类型InfoSysDelVO是复合类型，描述删除参数的结构，见表9。

表9

名称类型是否必填描述

idString是信息系统ID

versionString是版本号

reasonString是删除理由

信息系统接口

方法1：

接口名称：ResponseData<InfoSysVO>save(InfoSysVOvo)

接口描述：保存信息系统

接口地址：43:10353/server/sys/save

请求方式：POST

请求参数：信息系统属性

返回参数：信息系统

方法2：

接口名称：ResponseData<InfoSysVO>commit(InfoSysVOvo)

接口描述：提交信息系统

接口地址：43:10353/server/sys/commit

120

T/CESAXXX.4—202X

请求方式：POST

请求参数：信息系统属性

返回参数：信息系统

方法3：

接口名称：ResponseData<Boolean>delete(InfoSysDelVOdelVO)

接口描述：删除信息系统

接口地址：43:10353/server/sys/del/one

请求方式：POST

请求参数：删除信息系统参数

返回参数：删除是否成功的布尔值

方法4：

接口名称：ResponseData<InfoSysVO>details(Longid)

接口描述：获取信息系统详情

接口地址：43:10353/server/sys/details

请求方式：GET

请求参数：信息系统ID

返回参数：信息系统详情

方法5：

接口名称：ResponseData<Page<InfoSysVO>>getAllList(pageNo,pageSize)

接口描述：分页获取信息系统列表

接口地址：43:10353/server/sys/get/list

请求方式：GET

请求参数：分页参数

返回参数：分页信息系统列表

6.3数据共享

6.3.1数据共享申请

数据类型定义

1)数据类型ShareApplyConfirmPageVO是复合类型，标识一条已申请的数据信息，见表10。

表10

名称类型是否必填描述

rIdString是数据资源ID

orgIdString是提供机构ID

orgNameString是提供机构名称

applyOrgIdString是申请机构ID

applyOrgNameString是申请机构名称

resourceNameString是数据资源名称

dataItemString是数据项

modeString是交换方式

13

T/CESAXXX.4—202X

2)数据类型ShareApplyPageVO是复合类型，标识一条申请的数据信息，见表11。

表11

名称类型是否必填描述

orgIdString是机构ID

orgNameString是机构名称

resourceNameString是数据资源名称

dataItemString是数据项

modeString是交换方式

sysIdString是信息系统ID

resourceTypeInteger是资源类型

codeString是编码

数据共享申请接口

方法1：

接口名称：ResponseData<Page<ShareApplyConfirmPageVO>>

findAlreadyShareApplyPage(pageNo,pageSize)

接口描述：分页获取数据共享申请-已申请列表

接口地址：43:10353/server/shareApply/get/page

请求方式：GET

请求参数：分页信息

返回参数：已申请的数据分页列表

方法2：

接口名称：ResponseData<Page<ShareApplyPageVO>>findShareApplyPage(pageNo,pageSize)

接口描述：分页获取数据共享申请列表

接口地址：43:10353/server/shareApply/get/alreadyPage

请求方式：GET

请求参数：分页信息

返回参数：申请数据分页列表

6.3.2数据共享审批

数据类型定义

1)数据类型ShareApplyPageVO是复合类型，描述了一条数据共享审批的信息结构，见表12。

表12

名称类型是否必填描述

orgIdString是机构ID

orgNameString是机构名称

resourceNameString是数据资源名称

dataItemString是数据项

modeString是交换方式

140

T/CESAXXX.4—202X

sysIdString是信息系统ID

resourceTypeInteger是资源类型

codeString是编码

statusString是申请状态

数据共享审批接口

方法1：

接口名称：ResponseData<Page<ShareApplyPageVO>>findShareApplyPageByApproval(pageNo,

pageSize)

接口描述：分页获取数据共享审批列表

接口地址：43:10353/server/shareApply/findShareApplyPageByApproval

请求方式：GET

请求参数：分页信息

返回参数：数据共享审批列表

6.3.3共享情况

数据类型定义

1)数据类型ShareApplyPageVO是复合类型，描述一条共享情况的数据结构，见表13。

表13

名称类型是否必填描述

orgNameString是机构名称

resourceNameString是数据资源名称

dataItemString是数据项

resourceTypeDescString是资源类型

codeString是编码

共享情况接口

方法1：

接口名称：ResponseData<Page<ShareApplyPageVO>>findShareApplyCitySharePage(pageNo,

pageSize)

接口描述：分页获取共享情况列表

接口地址：43:10353/server/shareApply/get/cityShare

请求方式：GET

请求参数：分页信息

返回参数：共享情况列表

15

T/CESAXXX.4—202X

附录A

（规范性）

对象描述

A.1机构名称对象描述

{

"custom":{

"officename":["

机构名称1",

"机构名称2",

"机构名称3"

]

},

"start":{

"code":1,

"text":"查询成功"

}

}

机构名称对象参数说明见表A.1：

表A.1机构名称对象参数说明

序号名称字段名备注

1返回的结果集custom

2机构名称officename

3状态start

4成功1；失败0code

5接口调用说明text

A.2职责目录对象描述

{

"custom":{

"dutylist":[

{

"officeduty":"业务机构职责",

"officename":"业务机构名称",

"corecolumn":"核心数据项名称",

"dutycode":"职责目录编码",

"resourcename":"数据资源名"

}

]

160

T/CESAXXX.4—202X

},

"start":{

"code":1,

"text":"查询成功"

}

}

职责目录对象参数说明见表A.2：

表A.2职责目录对象参数说明

序号名称字段名备注

1返回的结果集custom

2结果list集合dutylist

3业务机构职责officeduty

4业务机构名称officename

5核心数据项名称corecolumn

6职责目录编码dutycode

7数据资源名称resourcename

A.3数据目录对象描述

{

"custom":{

"orgcatalog":[

{"summary":"数据资源摘要","updatecycle":"更新周期","systemguid":"是否源自新

建信息系统","total":"数据量",

"format":"数据格式（数据项，见Format说明）","resourcename":"

数据资源名称",

"dutyname":"所属职责目录",

"startdate":"数据起始时间","fieldlist":

[

{"fieldname":"字段名称","valuerange":"取值范围","isnull":"是否为空",

"iskey":"是否主键",

"description":"字段描述",

"fieldlength":"字段长度",

"sharetype":"共享类型",

"fieldtype":"字段类型",

"structguid":"对应字段",

"opentype":"开放属性",

"example":"数据样例"

}

17

T/CESAXXX.4—202X

],

"version":"版本"8

}

]

},

"start":{

"code":1,

"text":"查询成功"

}

}

数据目录对象参数说明见表A.3：

表A.3数据目录对象参数说明

序号名称字段名备注

1返回的结果集custom

2数据目录集合orgacatalog

3数据资源摘要summary

4更新周期updatecycle

5是否源自新建信息系统systemguid

6数据量total

7数据格式format

8数据资源名称resourcename

9所属职责目录dutyname

10数据起始时间startdate

11版本version

12数据项集合fieldlist

13字段名称fieldname

14取值范围valuerange

15是否为空isnull1：是，0：否

16是否主键iskey1：是，0：否

17字段描述description

18字段长度fieldlength

0：无条件共享，1：有

19共享类型sharetype

条件共享，2：不予共享

20字段类型fieldtype

21对应字段structguid

22开放属性opentype

23数据样例example

24查询状态start

180

T/CESAXXX.4—202X

25成功1；失败0code

26接口调用说明text

A.4信息系统对象描述

{

"status":"0",

"count":"0",

"data":[

{

"id":"信息系统id",

"appname":"信息系统名称",

"oucode":"单位编码",

"ouname":"单位名称",

"list":"是否完成目录编制",

"listemark":"未编制备注说明",

"listexplain":"未编制具体情况说明",

"contacter":"联系人姓名",

"phone":"联系人电话"

}

]

}

信息系统对象参数说明见表A.4：

表A.4信息系统对象参数说明

序号名称字段名备注

1执行结果代码status

2执行结果数量count

3数据data

4信息系统idid

5信息系统名称appname

6单位编码oucode

7单位名称ouname

8是否编制目录List0：未编制，1：已编制，2：计划编制

9未入云备注说明listremark

10未入云具体情况说明listexplain

11联系人姓名contacter

12联系人电话phone

表A.5数据目录上传示例

数据目数据数据格数据日数据资数数长字取样共享共开

19

T/CESAXXX.4—202X

录名称更新式期量源据据度段值例类型享放

周期摘项类描范条属

要名型述围件性

称

数据目1月ORACLE2023/3/100G案数字100无条开

录XX9B例据符件共放

项1型享

数据目1月ORACLE2023/3/101G案数整100无条开

录XX9B例据型件共放

项2享

数据目1月ORACLE2023/3/102G案数时100无条开

录XX9B例据间件共放

项3型享

200

T/CESAXXX.4—202X

附录B

（规范性）

返回状态码

返回状态码说明

200成功

1001无效token

1003没有访问权限

1599登录失败

1707Sql错误

4000调用智能合约失败

5002数据项名称重复

5004业务目录不存在

5011数据目录不存在

5013数据