DB43-T 3019-2024 智慧文旅信息系統(tǒng)數(shù)據(jù)接口規(guī)范

ICS35.240.01CCSL67DB43湖南省地方標準智慧文旅信息系統(tǒng)數(shù)據(jù)接口規(guī)范specificationfordatainterfaceofsmartculturaltourisminformationsystem2024-07-12發(fā)布2024-09-12實施湖南省市場監(jiān)督管理局發(fā)布DB43/T30192024前言 III1范圍 13術(shù)語和定義 14接口技術(shù)要求 15接口安全要求 26政務(wù)外網(wǎng)數(shù)據(jù)接口 37公網(wǎng)數(shù)據(jù)接口 6附錄A(資料性)政務(wù)外網(wǎng)Digest認證示例 9附錄B(資料性)公網(wǎng)認證示例 DB43/T30192024本文件按照GB/T1.12020《標準化工作導則第1部分:標準化文件的結(jié)構(gòu)和起草規(guī)則》的規(guī)定起草。請注意本文件的某些內(nèi)容可能涉及專利。本文件的發(fā)布機構(gòu)不承擔識別專利的責任。本文件由湖南省文化和旅游廳提出。本文件由湖南省旅游和標準化技術(shù)委員會歸口。本文件起草單位:湖南省文化和旅游廳、中移系統(tǒng)集成有限公司、中國移動通信集團湖南有限公司、湖南省質(zhì)量和標準化研究院、長沙市天心閣大數(shù)據(jù)研究院、湖南金智標準科技發(fā)展有限公司。本文件主要起草人:徐凱、張?；邸②w小龍、周樹韜、胡迪欣、鄧玉昆、李彭健、陳堅、盛立新、高翔、殷歡、彭添、姜海彬。 DB43/T30192024智慧文旅信息系統(tǒng)數(shù)據(jù)接口規(guī)范本文件規(guī)定了智慧文旅信息系統(tǒng)的數(shù)據(jù)接口技術(shù)要求、接口安全要求、政務(wù)外網(wǎng)數(shù)據(jù)接口、公網(wǎng)數(shù)據(jù)接口等要求。本文件適用于智慧文旅信息系統(tǒng)與全省文旅系統(tǒng)、政務(wù)機構(gòu)相關(guān)部門、外部第三方組織機構(gòu)不同權(quán)限接口的應(yīng)用和管理。下列文件中的內(nèi)容通過文中的規(guī)范性引用而構(gòu)成本文件必不可少的條款。其中,注日期的引用文件,僅該日期對應(yīng)的版本適用于本文件;不注日期的引用文件,其最新版本(包括所有的修改單)適用于本文件。GB/T25069信息安全技術(shù)術(shù)語DB43/T17542020政務(wù)大數(shù)據(jù)中心數(shù)據(jù)交換規(guī)范RFC2616超文本傳輸協(xié)議1.1(HypertexttransferprotocolHTTP/1.1)RFC4627JSON格式定義(Theapplication/JSONmediatypeforjavascriptobjectnotation)3術(shù)語和定義GB/T25069、YD/T4248界定的術(shù)語和定義適用于本文件。4接口技術(shù)要求數(shù)據(jù)接口模型用于信息交換傳輸時封裝交換信息。數(shù)據(jù)接口模型的數(shù)據(jù)文檔結(jié)構(gòu)名稱是數(shù)據(jù)接口模型用于信息交換傳輸時封裝交換信息。數(shù)據(jù)接口模型的數(shù)據(jù)文檔結(jié)構(gòu)名稱是由接口數(shù)據(jù)頭(Header)信息、數(shù)據(jù)體(Body)組成。接口Header是必選元素,用來描述數(shù)據(jù)申請方的身份信息(Authiorization)和內(nèi)容類型信息(contentType)。Body是必選元素,用來封裝交換的數(shù)據(jù)圖1接口模型DB43/T301920244.2接口流程本文件采用web服務(wù)接口方式進行數(shù)據(jù)交換,數(shù)據(jù)接口應(yīng)使用基于HT'TP/HTTPS協(xié)議的JSON格式進行傳輸。流程使用了"請求Request"、"指示Indication"、"響應(yīng)Response"、"確認confirm"四條服確認confirm4.3接口調(diào)用>><圖2接口服務(wù)流程接口調(diào)用方式包括: 請求:請求接口應(yīng)按照RFC2616中規(guī)定的要求,使用Get、post、put、Delete等方法調(diào)用平臺數(shù)據(jù)服務(wù)接口,請求接口將請求參數(shù)按照JSON格式封裝后,在HTTP的Request消息中發(fā)送給平臺方; 響應(yīng):請求接口調(diào)用成功或失敗,平臺應(yīng)將處理結(jié)果按照JSON格式封裝后,放置在HTTP的Response消息中,返回給調(diào)用者。HTTP的Response消息應(yīng)符合RFC2616中的要求。4.4接口基本要求接口應(yīng)滿足以下條件: 采用UTF-8字符編碼; 支持數(shù)據(jù)傳輸過程中的機密性與完整性保護; 接口數(shù)據(jù)應(yīng)符合RFC4627中JSON格式要求。4.5接口基本分類按照數(shù)據(jù)共享交換的網(wǎng)絡(luò)不同進行分類區(qū)分,可以將接口分為政務(wù)外網(wǎng)數(shù)據(jù)接口、公網(wǎng)數(shù)據(jù)接口2類 政務(wù)外網(wǎng)數(shù)據(jù)接口:部署在政務(wù)外網(wǎng)上,用于政府機構(gòu)和相關(guān)部門進行數(shù)據(jù)資源共享,以及按 公網(wǎng)數(shù)據(jù)接口:部署在公網(wǎng)上,用于與智慧文旅系統(tǒng)進行數(shù)據(jù)交互的企業(yè)、第三方組織和公眾的數(shù)據(jù)資源接口。5接口安全要求接口安全應(yīng)符合YD/T4248的相關(guān)規(guī)定。2 DB43/T301920246.1接口描述通過電子政務(wù)外網(wǎng)提供給政府機構(gòu)和相關(guān)部門的數(shù)據(jù)接口,通過數(shù)據(jù)的一致性、可訪問性和互操作性,以實現(xiàn)政府部門之間數(shù)據(jù)交換和共享,支持公共服務(wù)決策分析、信息查詢以及協(xié)同工作等應(yīng)用場景。6.2接口方法接口應(yīng)遵循HTTPREST風格6.3認證和授權(quán)6.3.1驗證規(guī)則如下: 由省交換平臺提供唯一的應(yīng)用碼; 由省交換平臺提供唯一的授權(quán)碼用于簽名: 加密算法采用SM4; 6.3.2Basic認證用戶訪問接口時,需要在HTTP請求頭中攜帶"Authorization","Authorization"的值對應(yīng)格式為BasicxXXXXXXX,其中XXXXXXXX是使用BASE64對用戶名和密碼加密后的信息。示例:用戶名為user,密碼為password時,Authorization請求頭計算方法:return"Basic"+hashreturn"Basic"+hash}6.3.3Digest認證訪問接口時,需要在HTTP請求頭中攜帶"Authorization","Authorization"的值對應(yīng)格式(見表1)為:Algorithm?Algorithm,Timestamp=Timestamp,AccesskeyId=AccesskeyId,signature-signature3DB43/T30192024表1Digest認證格式名稱描述Algorithm用于計算簽名的算法Timestamp時間戳,為API調(diào)用時刻對應(yīng)的urc時間(北京時間-8小時),時間格式如下"2015-01-01注:Timestamp不能與服務(wù)端時間相差超過5分鐘。AccesskeyId授權(quán)后為用戶分配的AccesskeyID,服務(wù)端使用該字段來校驗簽名合法性。signature簽名過程如下:1.URL參數(shù)規(guī)范化2).把分隔后得到的字符串按參數(shù)名稱的字典順序依次使用&符號連接。3).使用UTF-8字符集進行URL編碼。stringTosign=HT'TPMethod+"&"+percentEncode("/")+"&"+percentEncode("Timestamp")+"&"+其中percentEncode指使用UTF-8字符集進行編碼。3.計算簽名使用Algorithm對stringTosign進行簽名,簽名密鑰為AccesskeyId對應(yīng)的6.4接口約束接口約束主要如下: 響應(yīng)時間<=30秒; 單個文件傳輸大小<=10M。6.5消息狀態(tài)碼狀態(tài)碼信息說明400.1請求參數(shù)錯誤400.2請求地址與路由配置地址不匹配400.3獲取token信息錯誤400.4url解析錯誤400.5請求參數(shù)錯誤,模板渲染失敗4 DB43/T30192024狀態(tài)碼信息說明400.6禁止重放攻擊400.7消息格式錯誤400.8請求參數(shù)錯誤,添加認證信息失敗401.1認證失敗,認證簽名己過期401.2認證失敗401.3認證失敗,未進行授權(quán)401.4用戶尚未注冊402.1認證失敗,當前網(wǎng)關(guān)未進行授權(quán)402.2級聯(lián)失敗,當前請求網(wǎng)關(guān)未配置級聯(lián)模式402.3認證失敗,用戶名或密碼錯誤402.4認證失敗,當前接口未對網(wǎng)關(guān)進行授權(quán)402.5認證失敗,當前接口拒絕遠端級聯(lián)請求403.1計算簽名時發(fā)生錯誤403.2插件運行時發(fā)生錯誤403.3403.4無效的authorization格式403.5無效的認證機制403.6認證驗證失敗403.7認證簽名已過期403.8AccesskeyId授權(quán)無效簽名授權(quán)無效403.9調(diào)用頻率過高403.15訪問次數(shù)過多404.1請求路徑不正確405.1請求方法不支持406.1路由信息錯誤406.2當前路由己被禁用406.3接口組信息不存在406.4當前接口組已被禁用5DB43/T30192024狀態(tài)碼信息說明406.5本地網(wǎng)關(guān)配置不存在,請編輯配置級聯(lián)網(wǎng)關(guān)配置不存在,請編輯配置407.1contentType不支持408.1真實接口請求超時408.2查詢數(shù)據(jù)庫超時500.1無法獲取用戶信息500.2真實接口返回異常500.3解析結(jié)果異常500.4數(shù)據(jù)庫服務(wù)異常500.5請重新請求接口500.6數(shù)據(jù)系列化錯誤500.7參數(shù)錯誤500.8notsupportsqlgrammar從Redis數(shù)據(jù)庫獲取數(shù)據(jù)錯誤500.9系統(tǒng)錯誤500.10數(shù)據(jù)截斷500.11postgresQLWarning500.12rmi請求錯誤:查詢內(nèi)容沒有在服務(wù)器端的注冊表里500.13發(fā)生URL解析異常500.14創(chuàng)建遠程對象發(fā)生異常502.1網(wǎng)關(guān)錯誤(與真實接口的連接相關(guān)錯誤)7公網(wǎng)數(shù)據(jù)接口7.1接口描述通過公網(wǎng)(internet)提供給企業(yè)及第三方組織和公眾使用的數(shù)據(jù)接口,支持數(shù)據(jù)的實時查詢、獲取、分享和分析,以滿足商業(yè)應(yīng)用、研究分析和社會創(chuàng)新的需求。7.2接口方法接口方法為POST7.3接口請求參數(shù)6DB43/T30192024表序號報文名稱英文名稱可空數(shù)據(jù)類型賬號IDappId否string(32)2報文實體bizcontent否string3接口名稱否string4請求IdrequestId否5時間戳timestamp否string版本號version否string7簽名sign否string注:非空值待簽名參數(shù)按照首字母以ASCII方式升序排列(ASCIIASC),對于相同字母則使用下個字母做二次排7.4認證和授權(quán)7.4.1采用Token認證方式,訪問接口時需通過3步完成 客戶端用戶注冊,獲得智慧文旅平臺提供的用戶名及密碼; 客戶端通過用戶ID(client_id)和密鑰(client_secret)登錄平臺,獲得Token; 客戶端使用Token依權(quán)限訪問服務(wù)器資源。7.4.2驗證規(guī)則如下 由智慧文旅平臺提供唯一賬號和私鑰; 簽名算法為MD5; Token有效期為2個小時,Token丟失后應(yīng)重新獲取Token7.4.3公網(wǎng)簽名認證訪問接口時,將排序后的接口請求參數(shù)按照參數(shù)名(key)參數(shù)值(value)的次序進行字符串拼接,拼接處不包含任何字符,并在該長串的頭部及尾部分別拼接密鑰(secret),完成簽名字符串的組裝,并在MD5加密后做大寫轉(zhuǎn)換。如:sign-MD5(appkeytkeytvalue+appkey).touppercase()。示例參見附錄B。7.5接口約束接口約束主要如下: 響應(yīng)時間<=20秒,7.6消息狀態(tài)碼7DB43/T30192024狀態(tài)碼信息說明10000成功20000系統(tǒng)錯誤20001服務(wù)繁忙20002超時異常21000缺少requestId參數(shù)21001缺少簽名參數(shù)2100221003缺少時間戳參數(shù)21004缺少接口名參數(shù)21005缺少業(yè)務(wù)參數(shù)21006contentType請求頭參數(shù)必須為application/xWwwy-formurlencoded21007不支持Header的Expect請求頭參數(shù)22000接口路由不存在22001接口服務(wù)不可用23000簽名無效23001無效的appId參數(shù)或未綁定接口權(quán)限40000業(yè)務(wù)處理失敗24000沒有當前接口權(quán)限24001缺少parkcode旅游區(qū)編碼參數(shù)24002請求業(yè)務(wù)404,請檢查接口路徑是否正常24009限流異常26000無效參數(shù)26001業(yè)務(wù)接口異常26002未知錯誤26003bizcontent請求報文必須是json格式且不能為空26006參數(shù)檢查不符合預(yù)期26007業(yè)務(wù)校驗失敗26008HTTP請求錯誤26009接口限流了,請稍后重試26010服務(wù)降級了,請稍后重試26012觸發(fā)系統(tǒng)保護規(guī)則26013授權(quán)規(guī)則不通過8DB43/T30192024附錄A(資料性)政務(wù)外網(wǎng)Digest認證示例A.1認證代理信息接口服務(wù)中的代理信息如表A.1所示:表A.1接口服務(wù)代理信息名稱值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請求參數(shù),通常為?號之后的內(nèi)容*?paramtimestamp時間戳,格式y(tǒng)yyy-MMddHH:mm:ss,注意時區(qū)為UTC時區(qū),如何獲取utc時間,參看getuTCTime方法**@return計算結(jié)果,該字段為string類型,上層需要把該字段放到httpheader中,其中key為Authorization,value為返回結(jié)果*/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)