DB43-T 3019-2024 智慧文旅信息系统数据接口规范

ICS35.240.01CCSL67DB43湖南省地方标准智慧文旅信息系统数据接口规范specificationfordatainterfaceofsmartculturaltourisminformationsystem2024-07-12发布2024-09-12实施湖南省市场监督管理局发布DB43/T30192024前言 III1范围 13术语和定义 14接口技术要求 15接口安全要求 26政务外网数据接口 37公网数据接口 6附录A(资料性)政务外网Digest认证示例 9附录B(资料性)公网认证示例 DB43/T30192024本文件按照GB/T1.12020《标准化工作导则第1部分:标准化文件的结构和起草规则》的规定起草。请注意本文件的某些内容可能涉及专利。本文件的发布机构不承担识别专利的责任。本文件由湖南省文化和旅游厅提出。本文件由湖南省旅游和标准化技术委员会归口。本文件起草单位:湖南省文化和旅游厅、中移系统集成有限公司、中国移动通信集团湖南有限公司、湖南省质量和标准化研究院、长沙市天心阁大数据研究院、湖南金智标准科技发展有限公司。本文件主要起草人:徐凯、张希慧、赵小龙、周树韬、胡迪欣、邓玉昆、李彭健、陈坚、盛立新、高翔、殷欢、彭添、姜海彬。 DB43/T30192024智慧文旅信息系统数据接口规范本文件规定了智慧文旅信息系统的数据接口技术要求、接口安全要求、政务外网数据接口、公网数据接口等要求。本文件适用于智慧文旅信息系统与全省文旅系统、政务机构相关部门、外部第三方组织机构不同权限接口的应用和管理。下列文件中的内容通过文中的规范性引用而构成本文件必不可少的条款。其中,注日期的引用文件,仅该日期对应的版本适用于本文件;不注日期的引用文件,其最新版本(包括所有的修改单)适用于本文件。GB/T25069信息安全技术术语DB43/T17542020政务大数据中心数据交换规范RFC2616超文本传输协议1.1(HypertexttransferprotocolHTTP/1.1)RFC4627JSON格式定义(Theapplication/JSONmediatypeforjavascriptobjectnotation)3术语和定义GB/T25069、YD/T4248界定的术语和定义适用于本文件。4接口技术要求数据接口模型用于信息交换传输时封装交换信息。数据接口模型的数据文档结构名称是数据接口模型用于信息交换传输时封装交换信息。数据接口模型的数据文档结构名称是由接口数据头(Header)信息、数据体(Body)组成。接口Header是必选元素,用来描述数据申请方的身份信息(Authiorization)和内容类型信息(contentType)。Body是必选元素,用来封装交换的数据图1接口模型DB43/T301920244.2接口流程本文件采用web服务接口方式进行数据交换,数据接口应使用基于HT'TP/HTTPS协议的JSON格式进行传输。流程使用了"请求Request"、"指示Indication"、"响应Response"、"确认confirm"四条服确认confirm4.3接口调用>><图2接口服务流程接口调用方式包括: 请求:请求接口应按照RFC2616中规定的要求,使用Get、post、put、Delete等方法调用平台数据服务接口,请求接口将请求参数按照JSON格式封装后,在HTTP的Request消息中发送给平台方; 响应:请求接口调用成功或失败,平台应将处理结果按照JSON格式封装后,放置在HTTP的Response消息中,返回给调用者。HTTP的Response消息应符合RFC2616中的要求。4.4接口基本要求接口应满足以下条件: 采用UTF-8字符编码; 支持数据传输过程中的机密性与完整性保护; 接口数据应符合RFC4627中JSON格式要求。4.5接口基本分类按照数据共享交换的网络不同进行分类区分,可以将接口分为政务外网数据接口、公网数据接口2类 政务外网数据接口:部署在政务外网上,用于政府机构和相关部门进行数据资源共享,以及按 公网数据接口:部署在公网上,用于与智慧文旅系统进行数据交互的企业、第三方组织和公众的数据资源接口。5接口安全要求接口安全应符合YD/T4248的相关规定。2 DB43/T301920246.1接口描述通过电子政务外网提供给政府机构和相关部门的数据接口,通过数据的一致性、可访问性和互操作性,以实现政府部门之间数据交换和共享,支持公共服务决策分析、信息查询以及协同工作等应用场景。6.2接口方法接口应遵循HTTPREST风格6.3认证和授权6.3.1验证规则如下: 由省交换平台提供唯一的应用码; 由省交换平台提供唯一的授权码用于签名: 加密算法采用SM4; 6.3.2Basic认证用户访问接口时,需要在HTTP请求头中携带"Authorization","Authorization"的值对应格式为BasicxXXXXXXX,其中XXXXXXXX是使用BASE64对用户名和密码加密后的信息。示例:用户名为user,密码为password时,Authorization请求头计算方法:return"Basic"+hashreturn"Basic"+hash}6.3.3Digest认证访问接口时,需要在HTTP请求头中携带"Authorization","Authorization"的值对应格式(见表1)为:Algorithm⃞Algorithm,Timestamp=Timestamp,AccesskeyId=AccesskeyId,signature-signature3DB43/T30192024表1Digest认证格式名称描述Algorithm用于计算签名的算法Timestamp时间戳,为API调用时刻对应的urc时间(北京时间-8小时),时间格式如下"2015-01-01注:Timestamp不能与服务端时间相差超过5分钟。AccesskeyId授权后为用户分配的AccesskeyID,服务端使用该字段来校验签名合法性。signature签名过程如下:1.URL参数规范化2).把分隔后得到的字符串按参数名称的字典顺序依次使用&符号连接。3).使用UTF-8字符集进行URL编码。stringTosign=HT'TPMethod+"&"+percentEncode("/")+"&"+percentEncode("Timestamp")+"&"+其中percentEncode指使用UTF-8字符集进行编码。3.计算签名使用Algorithm对stringTosign进行签名,签名密钥为AccesskeyId对应的6.4接口约束接口约束主要如下: 响应时间<=30秒; 单个文件传输大小<=10M。6.5消息状态码状态码信息说明400.1请求参数错误400.2请求地址与路由配置地址不匹配400.3获取token信息错误400.4url解析错误400.5请求参数错误,模板渲染失败4 DB43/T30192024状态码信息说明400.6禁止重放攻击400.7消息格式错误400.8请求参数错误,添加认证信息失败401.1认证失败,认证签名己过期401.2认证失败401.3认证失败,未进行授权401.4用户尚未注册402.1认证失败,当前网关未进行授权402.2级联失败,当前请求网关未配置级联模式402.3认证失败,用户名或密码错误402.4认证失败,当前接口未对网关进行授权402.5认证失败,当前接口拒绝远端级联请求403.1计算签名时发生错误403.2插件运行时发生错误403.3403.4无效的authorization格式403.5无效的认证机制403.6认证验证失败403.7认证签名已过期403.8AccesskeyId授权无效签名授权无效403.9调用频率过高403.15访问次数过多404.1请求路径不正确405.1请求方法不支持406.1路由信息错误406.2当前路由己被禁用406.3接口组信息不存在406.4当前接口组已被禁用5DB43/T30192024状态码信息说明406.5本地网关配置不存在,请编辑配置级联网关配置不存在,请编辑配置407.1contentType不支持408.1真实接口请求超时408.2查询数据库超时500.1无法获取用户信息500.2真实接口返回异常500.3解析结果异常500.4数据库服务异常500.5请重新请求接口500.6数据系列化错误500.7参数错误500.8notsupportsqlgrammar从Redis数据库获取数据错误500.9系统错误500.10数据截断500.11postgresQLWarning500.12rmi请求错误:查询内容没有在服务器端的注册表里500.13发生URL解析异常500.14创建远程对象发生异常502.1网关错误(与真实接口的连接相关错误)7公网数据接口7.1接口描述通过公网(internet)提供给企业及第三方组织和公众使用的数据接口,支持数据的实时查询、获取、分享和分析,以满足商业应用、研究分析和社会创新的需求。7.2接口方法接口方法为POST7.3接口请求参数6DB43/T30192024表序号报文名称英文名称可空数据类型账号IDappId否string(32)2报文实体bizcontent否string3接口名称否string4请求IdrequestId否5时间戳timestamp否string版本号version否string7签名sign否string注:非空值待签名参数按照首字母以ASCII方式升序排列(ASCIIASC),对于相同字母则使用下个字母做二次排7.4认证和授权7.4.1采用Token认证方式,访问接口时需通过3步完成 客户端用户注册,获得智慧文旅平台提供的用户名及密码; 客户端通过用户ID(client_id)和密钥(client_secret)登录平台,获得Token; 客户端使用Token依权限访问服务器资源。7.4.2验证规则如下 由智慧文旅平台提供唯一账号和私钥; 签名算法为MD5; Token有效期为2个小时,Token丢失后应重新获取Token7.4.3公网签名认证访问接口时,将排序后的接口请求参数按照参数名(key)参数值(value)的次序进行字符串拼接,拼接处不包含任何字符,并在该长串的头部及尾部分别拼接密钥(secret),完成签名字符串的组装,并在MD5加密后做大写转换。如:sign-MD5(appkeytkeytvalue+appkey).touppercase()。示例参见附录B。7.5接口约束接口约束主要如下: 响应时间<=20秒,7.6消息状态码7DB43/T30192024状态码信息说明10000成功20000系统错误20001服务繁忙20002超时异常21000缺少requestId参数21001缺少签名参数2100221003缺少时间戳参数21004缺少接口名参数21005缺少业务参数21006contentType请求头参数必须为application/xWwwy-formurlencoded21007不支持Header的Expect请求头参数22000接口路由不存在22001接口服务不可用23000签名无效23001无效的appId参数或未绑定接口权限40000业务处理失败24000没有当前接口权限24001缺少parkcode旅游区编码参数24002请求业务404,请检查接口路径是否正常24009限流异常26000无效参数26001业务接口异常26002未知错误26003bizcontent请求报文必须是json格式且不能为空26006参数检查不符合预期26007业务校验失败26008HTTP请求错误26009接口限流了,请稍后重试26010服务降级了,请稍后重试26012触发系统保护规则26013授权规则不通过8DB43/T30192024附录A(资料性)政务外网Digest认证示例A.1认证代理信息接口服务中的代理信息如表A.1所示:表A.1接口服务代理信息名称值URLhttp://ww.data/api/v1.0/catlog?id=1&flag=true&type=jsonHT'TPMethodGETTimestamp2016-010101:01:01AlgorithmHMACSHA256AccesskeyIdbf796cld7081462a49042coa71edgb143Accesskeysecret8bf76cld7081462a9042coa71edgb142A.2Authorition请求头算法请求算法如下:importjava.util.Arrays;/***DataMall签名计算工具类*createdbyw0592on2017/11/14.*/publicclasssignatureutils(DB43/T30192024publicstaticfinalstringUTF_8="UTF-8";/**、取得本地时间:/l2、取得时间偏移量:/l3、取得夏令时差:cal.add(calendar.MILLISECOND,-(zoneoffset+dstoffset));simpleDateFormatsdf=newsimpleDateFormat("yyyy-MM-ddHH:mm:ss");/***签名计算方法*密钥id*cparamaccesskeysecret密钥secret*@paramhttpMethodhttp请求方法类型,目前支持POST,PUT,DELETE,GET四种*⃞paramquerystringhttp请求参数,通常为?号之后的内容*⃞paramtimestamp时间戳,格式yyyy-MMddHH:mm:ss,注意时区为UTC时区,如何获取utc时间,参看getuTCTime方法**@return计算结果,该字段为string类型,上层需要把该字段放到httpheader中,其中key为Authorization,value为返回结果*/if} DB43/T30192024.append("").append(signature);,stringifquerystring=URLDecoder.decode(querystring,UTF_8);}strTosign=buildcanonicalstring(querystring,httpMethod}catch(unsupportedEncodingExceptione){}{builder.append(httpMethod).append("&");try(builder.append(URLEncoder.encode("/",UTF_8)).append("&");if(null!=timestamp)