DB37T 2930-2017 气象服务信息数据接口规范

ICS07.060A 47DB37山东省地方标准DB37/T 29302017气象服务信息数据接口规范Specification for weather service information data interface2017-02-21发布2017-03-21实施山东省质量技术监督局发布DB37/T 29302017目次前言II1范围12规范性引用文件13术语和定义14访问方法25授权机制46效能要求47接口说明4附录A（资料性附录）JSON格式和XML格式示例5附录B（资料性附录）返回码清单6附录C（资料性附录）天气预报编码8附录D（资料性附录）接口说明示例10参考文献11前言本标准按照GB/T 1.12009给出的规则起草。本标准由山东省气象标准化技术委员会（鲁TC 16）提出并归口。本标准起草单位：山东省气象服务中心。本标准主要起草人：周雪松、李玉华、褚希、徐彩艳、任广治、张鹏、姚蔚、石春玲。10气象服务信息数据接口规范1 范围本标准规定了气象服务信息的访问方法、授权机制、效能要求和接口说明。本标准适用于气象行业和相关气象服务信息应用单位或个人进行气象服务信息系统的设计、研发和维护。2 规范性引用文件下列文件对于本文件的应用是必不可少的。凡是注日期的引用文件，仅所注日期的版本适用于本文件。凡是不注日期的引用文件，其最新版本（包括所有的修改单）适用于本文件。GB/T 2260中华人民共和国行政区划代码RFC 2616超文本传输协议（Hypertext Transfer Protocol）3 术语和定义下列术语和定义适用于本文件。3.1域名系统DNSdomain name system因特网上作为域名和IP地址相互映射的一个分布式数据库，能够使用户更方便的访问互联网，而不用去记住能够被机器直接读取的IP数串。3.2可扩展标记语言XMLextensible markup language一种用于标记电子文件使其具有结构性的标记语言。注： 可从以下网址获得：（/TR/REC-xml/）。3.3JavaScript对象表示法JSONjavascript object notation一种基于Javascript的轻量级数据交换格式。3.4统一资源定位符URLuniform resoure locator对可以从互联网上得到的资源的位置和访问方法的一种简洁的表示。3.5表述性状态转移RESTrepresentational state transfer一组架构约束条件和原则，通常基于使用HTTP、URI、XML以及HTML这些现有的广泛流行的协议和标准，根据这些原则设计以系统资源为中心的Web服务。注： 包括使用不同语言编写的客户端如何通过HTTP处理和传输资源状态。3.6气象服务信息weather service information在决策、公众和专业气象服务中向政府、社会和生产部门提供的信息。注： 气象服务信息数据格式类别包括文本、数字、图片、视频等。4 访问方法4.1 访问方式对气象服务信息的访问对应唯一的资源标识符（URL网址），应采用RFC 2616中的HTTP协议的GET方式进行。服务请求字符串及返回结果编码宜采用RFC 3629/STD 63（2003）定义的UTF-8字符集。如使用其他字符集，应在返回结果中标明。4.2 访问步骤4.2.1 需授权气象服务信息数据资源访问步骤对于需要授权的气象服务信息数据接口（即需要用户认证的服务），访问步骤如下：a) 身份认证并获取授权：通过平台注册用户申请相关服务资源，经审核后获取合法授权（用户名密码、IP认证或Key值）；b) 获取服务资源地址：通过平台获取气象服务信息数据接口资源访问地址；c) 构建加密服务资源的访问地址：在气象服务信息数据访问接口资源地址上加入用户名和密码或Key值参数，形式为“&username=&password=”或“&key=”，生成新的服务网址（经过IP认证的用户可以直接访问）；d) 服务资源访问：通过加密的气象信息服务资源访问地址访问气象服务信息，获取返回结果。4.2.2 不需授权气象服务信息数据资源访问步骤对于不需要授权的气象服务信息数据接口（即不需要用户认证的服务），访问步骤如下：a) 获取服务资源地址：通过平台获取气象服务信息数据接口资源访问地址；b) 服务资源访问：通过气象信息服务资源访问地址访问气象信息服务，获取返回结果。4.3 服务请求4.3.1 请求字符串的组成服务请求字符串应包含数据接口地址，可包含应用识别码、请求参数、授权码等部分。4.3.2 数据接口地址数据接口地址按照RFC 1738中URL的有关规定编写。其中，主机地址宜采用域名，不宜采用IP地址。23页。4.3.3 应用识别码每个数据接口服务应由数据接口地址标识，如数据接口地址相同则需另加应用识别码组成唯一标识。应用识别码应保持唯一性，并标明服务请求的具体气象服务信息。4.3.4 服务请求参数 参数可包含位置、时间、气象信息服务数据种类等信息。 位置参数可采用下列四种编码之一：a) 中华人民共和国行政区划代码，区划代码符合GB/T 2260有关规定；b) 气象站标识；c) 经纬度信息；d) 其他约定的位置编码。 时间编码可采用下列两种编码之一：a) 字符型时间，格式为yyyymmddHHiiss，如20140926160150，其中yyyy表示4位年，mm表示两位月，dd表示两位日，HH表示两位时，ii表示两位分，ss表示两位秒；b) unix时间戳，为1970年1月1日00：00：00至当前时间的总秒数。例如当前时间为：2014-09-26 16:01:50，对应的时间戳：1411718510。 服务请求参数字符串按照下列规则拼装：a) 当请求参数为一个要素时，应直接给出要素编码；b) 当请求参数为两个以上要素时，要素间采用分隔符进行分割，宜使用日常符号，如“|”、“,”等，不应使用URL标准已经规定有特殊用途的符号，如“+”、“&”等；c) 当请求参数为时间段时，时间段使用数学区间表示的方法，且应使用下列四种表示方法： 前开后开：(yyyymmddHHiiss, yyyymmddHHiiss)； 前开后闭：(yyyymmddHHiiss, yyyymmddHHiiss； 前闭后开：yyyymmddHHiiss, yyyymmddHHiiss)； 前闭后闭：yyyymmddHHiiss, yyyymmddHHiiss。注： 开区间不包含端点值，闭区间包含端点值。4.4 服务响应4.4.1 结果返回格式请求响应返回信息格式宜使用JSON格式，也可使用XML格式，格式示例参见附录A。4.4.2 返回结果内容服务请求返回结果应包括请求结果状态信息和内容信息，且满足下列要求：a) 返回结果字段使用英文字母、数字、下划线或以上三种类型的组合命名；b) 返回结果字段命名具有明确的含义，便于阅读。4.4.3 状态信息要求状态信息应满足下列要求：a) 结果状态信息至少包含状态码和状态说明信息；b) 状态码使用数字编码，且需编制统一的状态信息编码表；c) 状态说明信息使用英文表述。状态信息参见附录B返回码清单。4.4.4 内容信息要求内容信息应满足下列要求：a) 返回结果内容信息中包含时间、空间、产品要素名称和要素单位等信息，可增加其他相关字段信息；b) 返回结果内容为图片、视频和其他固定文件形式的，使用URL给出其访问地址；c) 返回结果为代码的，给出结果相应代码表，其中天气预报参见附录C天气预报编码。5 授权机制5.1 用户授权基本要求气象服务信息数据接口应提供用户授权机制，且用户授权应使用逐次请求授权方式进行,可使用下列用户授权方式：a) 用户唯一标识码授权，为每一接口用户提供唯一授权访问标识，且用户唯一授权码宜采用通用唯一识别码（UUID，Universally Unique Identifier）；b) 用户名密码授权，应为每一用户提供用户和密码；c) 用户签名授权，在为每一用户提供唯一授权标识的基础上，通过加密算法加密服务请求字符串；d) 用户IP授权，通过识别客户端IP地址是否在允许范围内鉴别用户权限。5.2 用户签名授权算法对请求字符串中的client_id(用户方公钥)、client_key(用户方私钥)和timestamp（时间戳），按照对应的顺序按key=value方式拼接起来，并对拼接的字符串加密。服务器端采用同样方法对客户端请求进行鉴别授权。6 效能要求6.1 并行性气象服务信息数据接口应提供多用户并行访问支持。6.2 响应时间气象服务信息数据接口响应时间应小于500 ms。7 接口说明气象服务信息数据接口应提供相应接口说明书，并应与气象服务信息数据接口一起提交用户使用。接口说明书应包括气象服务信息数据接口描述、调用请求方式、各参数说明、常用参数代码表等内容，说明书宜给出数据接口调用示例代码，接口说明示例参见附录D。AA附录A （资料性附录）JSON格式和XML格式示例JSON格式：returnCode:返回代码,returnMessage:返回的错误信息,rowCount:返回数据行数,colCount:返回数据列数,requestParams:调用参数,requestTime:接收请求时间,responseTime:返回请求结果时间,takeTime:耗时（单位秒）,DS:字段名1:”字段值1”, 字段名2:”字段值2”, 字段名3:”字段值3”, ,字段名1:”字段值1”, 字段名2:”字段值2”, 字段名3:”字段值3”, , /其他行数据，此处省略XML格式： BB附录B （资料性附录）返回码清单表B.1规定了标准中数据接口返回结果的状态信息中返回码及其含义。表B.1 返回码清单返回码返回码含义返回信息的中文描述0Query Succeed查询成功-1No data is retrieved查询成功,没有获取到数据（数据库中无数据）-1001Missing UserID用户名缺失-1002Invalid User无效用户-1003Missing Password密码缺失-1004Password Error密码错误-2001Incorrect Parameter of InterfaceID.接口名参数不正确-2002Incorrect Parameter of dataCode.资料代码（单个）参数不正确-3001Incorrect Parameter参数不正确-3002Missing Parameter 参数缺失-3003Disable Parameters禁用的参数-4001No access to the data.没有访问该数据的权限-4002No access to the datas history data.没有访问该资料历史数据的权限-4003Access time is beyond the available time points.访问的时间超出了该用户能访问的最早时间点-5001Time Span is out of Range.时间参数跨度超过范围-5002Time parameter number exceeds the limit.时间参数个数超过限制-6001Failed to Connect Server.服务器连接失败-7001SQL ErrorSQL错误-8001No data is retrieved.没有检索到数据-8002File does not Exist.文件不存在-8003The Grid Writing Data type is not correct.格点写入数据类型不正确-8004Grid Part-Writing data array length is not the same as index Size.N-8005Grid dataFormat implement class failed to initialize.N-8006File is Locked.文件加锁-8007File can not be read.文件不可读-8008File can not be writen.文件不可写-8009Fail to Read grid file.格点文件读取失败-8010Fail to Write grid file.格点文件写入失败-8011Fail to Write NC file.多个文件符合条件，不能确定写哪个-9001Grid NWP_Client.xml load failed.N表B.1返回码清单（续）返回码返回码含义返回信息的中文描述-9002Grid Msg Command Parsing failed.N-9003Grid Socket Reading data failed.N-9004Grid Socket Writing data failed.N-9005Numerical error of Grid Data.格点数据数值错误-9006GeneralAPI failed to initialize.通用接口初始化失败-9007KVElement failed to initialize.服务端参数处理逻辑失败-10001Other Exception其他异常CC附录C （资料性附录）天气预报编码表C.1规定了标准中天气预报编码及其含义。表C.1 天气预报编码（业务规范）编号中文名称00晴01多云02阴03阵雨04雷阵雨05雷阵雨伴有冰雹06雨夹雪07小雨08中雨09大雨10暴雨11大暴雨12特大暴雨13阵雪14小雪15中雪16大雪17暴雪18雾19冻雨20沙尘暴21小到中雨22中到大雨23大到暴雨24暴雨到大暴雨25大暴雨到特大暴雨26小到中雪27中到大雪28大到暴雪29浮尘30扬沙表C.1天气预报编码（业务规范）（续）编号中文名称31强沙尘暴32浓雾49强浓雾53霾54中度霾55重度霾56严重霾57大雾58特强浓雾99无301雨302雪DD附录D （资料性附录）接口说明示例接口名称：实时温度实况接口接口描述：返回固定时间和地点温度实况信息。调用请求方式：http get。请求字符串：http:/domain/api?userId=user&pwd=password&interfaceId=getSurfEleByTimeAndStaID&dataCode=SURF_CHN_MUL_HOR&elements=Station_Name,Datetime,Station_Id_C,TEM×=20160806000000&staIds=54823&dataFormat=json注： userId，pwd：用户授权的用户名密码；interfaceId，dataCode：数据接口识别相关参数；elements：调用的要素内容；times：调用的数据时间；staIds：调用的站点标识；dataFormat：返回格式类型。返回结果： returnCode: 0, returnMessage: