T_PSC 8-2022 海洋科学数据共享服务规范 接口服务.pdf

T/PSC 8-2022 海洋科学数据共享服务规范 接口服务 Specification for marine scientific data sharing serviceInterface service 2022-05-30 发布 2022-05-30 实施 中国太平洋学会 发 布 ICS 35.240.01；07.060 CCS L 70 团体标准 全国团体标准信息平台全国团体标准信息平台T/PSC 8-2022 I 目次 前言.II 1 范围.1 2 规范性引用文件.1 3 术语和定义.1 4 缩略语.1 5 基本要求.1 接口要求.1 5.1 安全要求.2 5.2 管理要求.2 5.3 6 接口分类.2 7 接口描述方法.3 接口名称.3 7.1 接口说明.3 7.2 接口 HTTP 请求地址.3 7.3 接口 HTTP 请求方法.3 7.4 接口 HTTP 请求参数.3 7.5 接口响应内容.4 7.6 附录 A（资料性）海洋科学数据共享服务接口示例.5 附录 B（规范性）常用请求参数类型及代码.11 参考文献.12 全国团体标准信息平台T/PSC 8-2022 II 前言 本文件按照GB/T 1.12020标准化工作导则 第1部分：标准化文件的结构和起草规则的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由国家海洋信息中心提出。本文件由中国太平洋学会归口。本文件起草单位：国家海洋信息中心、国家海洋局北海信息中心、国家海洋局南海信息中心、广西科学院、大连海洋大学。本文件主要起草人：吕憧憬、姜晓轶、童心、王漪、孟繁超、田天、唐灵、王子珂、宋恩辉、孙苗、严小敏、郭俊如、富砚昭。全国团体标准信息平台T/PSC 8-2022 1 海洋科学数据共享服务规范 接口服务 1 范围 本文件规定了海洋科学数据共享服务接口的基本要求、接口分类和接口描述方法。本文件适用于海洋科学数据共享服务接口的设计研发和共享调用。各类海洋科学数据共享服务平台（以下简称“平台”）的开发可参考使用。2 规范性引用文件 下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中，注日期的引用文件，仅该日期对应的版本适用于本文件；不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。T/PSC 6-2022 海洋科学数据共享服务规范 数据标识 3 术语和定义 下列术语和定义适用于本文件。3.1 海洋科学数据 marine scientific data 通过观测监测、考察调查、检验检测、试验开发、模式计算、统计核算等方式获取的可用于海洋科学研究和管理应用等活动的原始数据及其衍生产品。3.2 海洋科学数据共享服务平台 marine scientific data sharing service platform 提供海洋科学数据及产品查询检索、可视化展示、共享下载、在线计算等功能的数据资源共享交换平台。3.3 服务接口 service interface 通过网络调用来传输信息的一组程序级的网络通信规则。4 缩略语 下列缩略语适用于本文件。FTP：文件传输协议（File Transfer Protocol）HTTP：超文本传输协议（Hyper Text Transfer Protocol）IP：网际协议（Internet Protocol）JSON：JS对象表示法（Javascript Object Notation）UDDI：统一描述、发现和集成协议（Universal Description Discovery and Integration）URL：统一资源定位符（Uniform Resource Locator）5 基本要求 接口要求 5.1 海洋科学数据共享服务接口应满足以下基本要求：a)接口的描述、注册和发布符合 UDDI 标准；全国团体标准信息平台T/PSC 8-2022 2 b)支持向下兼容升级，降低调用方对服务接口实现的依赖；c)支持动态弹性扩展，满足服务接口功能的更新迭代需求；d)符合通用设计要求，能跨操作系统、跨开发语言、跨浏览器调用。安全要求 5.2 海洋科学数据共享服务接口环境安全条件应满足以下基本要求：a)采用但不限于虚拟网、防火墙、病毒防护等安全技术，防止服务接口被攻击；b)采用但不限于服务代理、IP地址验证和动态密钥等加密技术，保障点对点数据传输安全；c)针对安全性要求较高的接口，采用Https或分发密钥的方式提供服务。管理要求 5.3 海洋科学数据共享服务接口管理应满足以下基本要求：a)在平台中完成注册发布；b)发布时应提供详细的说明信息，包括但不限于名称、所属类别、访问地址、开放权限、参数说明和调用示例等；c)注册、发布、调用、变更及撤销等操作，提前向平台管理员发出请求，平台管理员审核通过后才能执行操作；d)变更和撤销前，由平台管理员在平台首页发布公告，并通知服务资源使用方。6 接口分类 服务接口按照功能类型，应包括但不限于数据集管理、数据资源管理、目录清单查询、元数据信息查询、数据资源获取、服务接口管理、用户管理、权限管理、运行监控和其他等10类，支持按需扩展，接口分类见表1，部分接口编码及调用示例见附录A。表1 接口分类 序号 接口类型 接口名称 1 数据集管理类 新增数据集接口 删除数据集接口 修改数据集接口 2 数据资源管理类 新增数据资源接口 删除数据资源接口 修改数据资源接口 3 目录清单查询类 数据集目录清单查询接口 数据目录清单查询接口 4 元数据信息查询类 数据集元数据查询接口 数据元数据查询接口 5 数据资源获取类 文件在线下载接口 库表资源调用接口 服务地址调用接口 6 服务接口管理类 注册接口 发布接口 变更接口 撤销接口 审核接口 全国团体标准信息平台T/PSC 8-2022 3 表1 接口分类（续）序号 接口类型 接口名称 7 用户管理类 新增用户接口 删除用户接口 修改用户接口 查询用户接口 8 权限管理类 数据集权限管理接口 用户权限管理接口 9 运行监控类 服务运行监控接口 数据资源获取监控接口 用户访问监控接口 10 其他 7 接口描述方法 接口名称 7.1 接口名称应满足唯一性、可读性要求，其编码应遵循统一的命名规则。接口名称应采用帕斯卡命名法1)编码。示例：“数据目录清单查询接口”的接口名称为“GetDataList”（见 A.4.1）。接口说明 7.2 可采用中文、英文、数字和标点符号进行描述，宜简明扼要。接口 HTTP 请求地址 7.3 应采用“http或https:/服务器地址:端口号/接口名称”。注：端口号可选。接口 HTTP 请求方法 7.4 宜采用GET或POST服务接口调用方式。接口 HTTP 请求参数 7.5 7.5.1 参数名称 参数名称应满足唯一性、可读性要求，其编码应遵循统一的命名规则。参数名称应采用驼峰式命名法2)编码。示例：“数据集标识符”的参数名称为“datasetIdentifier”（见 A.5.5）。7.5.2 参数要求 接口请求参数应满足以下基本要求：a)海洋科学数据服务应按照 T/PSC 6-2022 和附录 B 的规定进行分类和编码；b)当用到数据标识、更新时效、服务方式和开放级别作为请求参数时，采用 T/PSC 6-2022 中的数据标识和附录 B 中表 B.1表 B.3 对应的“代码”；示例：“更新时效类型”作为请求参数时（见附录 B 表 B.1），应采用代码“01”、“02”、“03”。c)当请求为 POST 方式时，应采用 JSON 格式进行传递；d)当请求为 GET 方式时，应采用字符串格式通过 URL 进行传递。1)当名称由多个单词构成时，所有单词的首字母都应大写。2)当名称由多个单词构成时，第一个单词首字母小写，其余单词首字母都应大写。全国团体标准信息平台T/PSC 8-2022 4 接口响应内容 7.6 接口响应内容应包括库表调用类、服务地址类和文件下载类。库表调用类和服务地址类接口响应内容应采用JSON格式返回，JSON响应键值对中的键命名应采用驼峰式命名法；接口响应状态码应作为JSON中的第一个键值对，响应状态码见表2。文件下载类接口响应内容应采用HTTP、FTP等方式返回。表2 接口响应状态码 状态码 说明 1 请求成功 2 用户未授权 3 资源已删除 4 调用超时 5 服务器错误 全国团体标准信息平台T/PSC 8-2022 5 A A 附录A （资料性）海洋科学数据共享服务接口示例 A.1 概述 A.2A.6给出了数据集管理类、数据资源管理类、目录清单查询类、元数据信息查询类和数据资源获取类的接口示例。A.2 新增数据集接口 A.2.1 接口名称 InsertDataset A.2.2 接口说明 新增一个数据集。A.2.3 接口HTTP请求地址 http:/或https:/+“服务器地址”+/InsertDataset A.2.4 接口HTTP请求方法 HTTP POST A.2.5 接口HTTP请求参数 接口HTTP请求参数采用JSON格式进行传递，其请求参数、类型等说明见表A.1。表A.1 请求参数说明 序号 请求参数 类型 可为空 备注 1 citationModeCh String 可 致谢声明 2 dataNumber String 否 文件个数 3 dataTime String 可 数据时间 4 dataVolume String 否 数据量 5 datasetDescription String 可 数据集介绍 6 datasetKeyword String 可 数据集关键字 7 datasetName String 否 数据集中文名称 8 datasetNameEn String 可 数据集英文名 9 updateFrequency String 可 更新频率 10 owner String 可 拥有者 11 sharingMode String 否 共享级别 12 subjectClass String 否 学科分类 13 themeCategory String 否 主题分类 14 timeliness String 否 时效性 示例：citationModeCh:感谢国家海洋科学数据中心(http:/ 8-2022 6 datasetNameEn:Integrated ocean current dataset surface contour,updateFrequency:年度,owner:国家海洋信息中心,sharingMode:完全共享,subjectClass:海洋水文,themeCategory:实测数据,timeliness:延迟 A.2.6 接口响应内容 接口响应内容采用JSON格式进行传递，其响应参数、类型等说明见表A.2。表A.2 接口响应参数说明 序号 响应参数 类型 备注 1 statusCode String 状态码 2 insertState String 创建状态 3 datasetId String 数据集id 4 datasetIdentifier String 数据集标识符 示例：statusCode:1,result:insertState:Insert Dataset Success，datasetName：海流综合数据集大面分集,datasetId:1,datasetIdentifier:CSTR:13452.11.10110007 A.3 修改数据资源接口 A.3.1 接口名称 UpdateData A.3.2 接口说明 修改数据资源的内容。A.3.3 接口HTTP请求地址 http:/或https:/+“服务器地址”+/UpdateData A.3.4 接口HTTP请求方法 HTTP POST A.3.5 接口HTTP请求参数 接口HTTP请求参数采用JSON格式进行传递，其请求参数、类型等说明见表A.3。表A.3 请求参数说明 序号 请求参数 类型 可为空 备注 1