2024智慧社區(qū)跨界服務(wù)需求建模與設(shè)計(jì)規(guī)范

前 引 范 基于RESTAPI的跨界服務(wù)接口設(shè)計(jì)規(guī) 附錄A智慧社區(qū)跨界服務(wù)案 附錄B智慧社區(qū)跨界服務(wù)API設(shè)計(jì)案 引本文件規(guī)定了智慧社區(qū)跨界服務(wù)的需求建模與基于RESTAPI的跨界服務(wù)接口設(shè)計(jì)。CrossoverMeta活動(dòng)角色目標(biāo)功能性目標(biāo)FunctionalNon-functional約束分解資源表現(xiàn)層Presentation請(qǐng)求響應(yīng)Status 統(tǒng)一建模語(yǔ)言（Unifiedmodeling 應(yīng)用程序接口（ApplicationProgrammingInterface） 表現(xiàn)層狀態(tài)轉(zhuǎn)移（RepresentationalStateTransfer） 超文本傳輸協(xié)議（HyperTextTransferProtocol） 統(tǒng)一資源標(biāo)志符（UniformResourceIdentifier） 開放接口說明文檔（OpenAPISpecification）擁有產(chǎn)生使用實(shí)現(xiàn)11名稱組織名稱類型名稱執(zhí)行者名稱類型價(jià)值接口提供者消費(fèi)者名稱1..*扮 1..*擁 產(chǎn) 22概況上下文環(huán)境名稱組織名稱類型名稱執(zhí)行者名稱類型價(jià)值接口提供者消費(fèi)者領(lǐng)域名稱上層目標(biāo)和下層目標(biāo)之間存在兩種分解關(guān)系：“與”和“或”?！芭c”關(guān)系意味著如果上層目標(biāo)被選Q/BFW248-

0..*擁有

3概況上下文環(huán)境名稱組織名稱類型類型類型是否可操作目標(biāo)操作操作對(duì)象實(shí)現(xiàn)方式類型達(dá) 名 組合類 44名稱類型名稱執(zhí)行者名稱組合類型名稱領(lǐng)域質(zhì)量提供者名稱名稱名稱基于RESTAPI在跨界服務(wù)流程模型分析的基礎(chǔ)上進(jìn)行跨界服務(wù)開發(fā)與實(shí)現(xiàn)時(shí)，推薦基于RESTAPI進(jìn)行服務(wù)接口設(shè)計(jì)?；赗ESTAPI的跨界服務(wù)接口設(shè)計(jì)過程中，從API資源設(shè)計(jì)、API交互設(shè)計(jì)、API性能和非功能API資源（Resource）是一種網(wǎng)絡(luò)實(shí)體，是RESTAPI（Rpeenaona）URUnomReoucedene）ETUI只代表資源實(shí)體（位置），不代表其表現(xiàn)形式。使用不同的TP方法與R組合來實(shí)現(xiàn)對(duì)資源的不同ET資源命名（URI設(shè)計(jì)）是在創(chuàng)建易于理解和易于調(diào)用的WebAPI時(shí)最重要的概念。選擇資源的出發(fā)資源具有層次結(jié)構(gòu)以及內(nèi)部聯(lián)系。例如，在銀行領(lǐng)域中可以使用“/customers/{customerId}/accounts”來標(biāo)識(shí)特定“客戶”的子集合資源“帳戶”。本節(jié)從層級(jí)嵌套和資源建模粒度兩方面來規(guī)范RESTAPIa

nespapersed/

比如URI：/orgs/{org_id}/apps/{app_id}/dynos/{dyno_id}，在上述例子中，dyno屬于app，app屬于org可設(shè)計(jì)RESTAPI時(shí)，選擇正確的資源并以正確的粒度對(duì)資源進(jìn)行建模非常重要，關(guān)系到使用者是否表 RESTAPI屬性類型中以JSONID都能訪問，例如:/apps/{appid-or-name}。URI結(jié)構(gòu)Web服務(wù)中，用于限制兩個(gè)或多個(gè)輸入?yún)?shù)的依賴關(guān)系從而獲取對(duì)服務(wù)的有API說明文件中，方便用6是常見屬性依賴模式。表 p1->p1p2p12Or(p1;p2;...;APIp1,...,pnOnlyOne(p1;p2;...;APIp1,...,pnAllOrNone(p1;p2;...;APIp1,...,pnAPI調(diào)用中，聲明屬性p1,...,pnRESTAPI支持服務(wù)器返回多種不同類型的資源，支持MIMEType，其網(wǎng)絡(luò)資源的具體表現(xiàn)形式，RESTAPIAcceptRESTAPI通過HTTP協(xié)議實(shí)現(xiàn)客戶端與服務(wù)器的通信，因此RESTAPI的設(shè)計(jì)規(guī)范需依賴對(duì)HTTP協(xié)議的規(guī)范使用。下面從請(qǐng)求和響應(yīng)兩方面定義RESTAPI交互設(shè)計(jì)規(guī)范。RESTAPI要求使用HTTP協(xié)議定義的標(biāo)準(zhǔn)方法來對(duì)資源進(jìn)行操作，具體描述見表7。對(duì)資源的常見表 類似于GET體中。POST請(qǐng)求可能會(huì)導(dǎo)致新的資源的建立和/HTTP/1.1是對(duì)PUT在某些情況下，客戶端庫(kù)或工具可能不支持HTTP協(xié)議PUTDELETE方法，此時(shí)建議的兼容方POSTPUT和DELETEAPIURL的查詢字符串中添加_method一項(xiàng)，指明POST替代的是PUT還是DELETE。RESTAPI的響應(yīng)要符合HTTP1.1響應(yīng)標(biāo)準(zhǔn)結(jié)構(gòu)。針對(duì)資源的各種操作（HTTP請(qǐng)求方法）的不同9為常用HTTP狀態(tài)碼。表 HTTP狀態(tài)碼類別表 常用HTTP狀態(tài)碼成功創(chuàng)建（通過POST或PUT）LocationNO例如NOTGETDateContent-Location和EtagGETBADNOT401403INTERNAL "message":"AccountreacheditsAPIratelimit.", 建議使用Out2協(xié)議來進(jìn)行用戶身份認(rèn)證。Ouh2協(xié)議為用戶資源的授權(quán)提供了一個(gè)安全開放的（oke）用來代替密碼，供第三方應(yīng)用使用。獲得令牌的四種授權(quán)方式為：授（auhozaone（pci（paso（centcednaatoded和EtTaEnttyaNoneMchGTTagfNoneMcTPETgfNoneMch與服務(wù)器重新計(jì)算的所請(qǐng)求的資源的ETg值不一致時(shí)，服務(wù)器才響應(yīng)新資源。如果服務(wù)器端計(jì)算Tg值與請(qǐng)求頭中fNoneMch一致，說明客戶端再次發(fā)起相同請(qǐng)求，且所請(qǐng)求的網(wǎng)絡(luò)資源304Notoded從客戶端瀏覽器緩存中讀取。在協(xié)商緩存機(jī)制aModed（最后修改時(shí)間）中，請(qǐng)求時(shí)包含fModfeSnce頭信息，可以使服務(wù)器根據(jù)atModed來判斷是否再次返回資源。使用標(biāo)準(zhǔn)時(shí)間戳aodfRSTPPPNPI3.ETP（nah（eesutag（exenaDoc（coponenPeadaaPI標(biāo)題、簡(jiǎn)介、類別以及提供服務(wù)的服務(wù)商等。路徑部分為P描述文檔的主要功能部分，描述該P(yáng)的TP附錄A.1A.1表A.1智慧社區(qū)跨界服務(wù)價(jià)值網(wǎng)絡(luò)模型元素屬性定義圖A.2為智慧社區(qū)平臺(tái)的目標(biāo)分解模型。智慧社區(qū)跨界服務(wù)系統(tǒng)主要目的是賦能社區(qū)構(gòu)建智慧社A.2A.2APPAPPAPPAPPAPPAIAIA.3給出了智慧社區(qū)平臺(tái)原子過程“保安巡查”、原子過程“現(xiàn)場(chǎng)處理”、原子過程“審查報(bào)告”、原子過程“物業(yè)審核”。A.3A.3附錄智慧社區(qū)跨界服務(wù)APIuriAPIuri，每個(gè)API都有唯一的uriAPI的接口定義。舉例：ip:port為平臺(tái)webOpenAPI包含多種應(yīng)用資源集：包括視頻應(yīng)用資源集，人員管控資源集，車輛管控資源5.1.1節(jié)描述的命名規(guī)范。圖B.1 "receptionistId":"123v453673dsfgef12312","visitorPermissionSet":{"defaultPrivilegeGroupFlag":"1","privilegeGroupIds":["visitStartTime":"2018-07-26T15:00:00+08:00","visitEndTime":"2018-07-26T19:00:00+08:00","visitPurpose"visitorInfoList":["visitorName":"gender":1,"phoneNo":"plateNo":"浙A12345","certificateType"certificateNo":,"certAddr":"江蘇南京","certIssuer"nation":1,"birthplace"visitorPhoto":cMc8yMjIfE87ujdq0nvyPcKodJ3XPpvt//2Q==","visitorWorkUnit":"海康威視","visitorAddress":"code":"msg":"success","data":{"appointRecordId":"123456789","appointmentInfoList":["visitorName":"張三","receptionistId":"3124126241412","receptionistName":"王五","verificationCode":"1234","QRCode":"v1256v5755","orderId":"170xd8g157t7cu8w8yvhiwr","svrIndexCode":"120d8qbvuhr8qy81bhq85fubhqvhu0438"該案例中，使用了POST從其他返回圖片Uri圖片Uri（headerLocation可以獲取到。HTTP/1.1Cache-Control:no-cachePragma:no-cacheexpires:Wed,31Dec196923:59:59GMTContent-Length:Date:Fri,28Sep201801:55:00"code":"data":"msg":"Therequiredparameterp