基于區(qū)塊鏈的港航集裝箱信息交換平臺(tái)及接口技術(shù)要求

PAGEPAGE11PAGEPAGE10基于區(qū)塊鏈的港航集裝箱信息交換平臺(tái)及接口技術(shù)要求范圍本文件規(guī)定了基于區(qū)塊鏈的港航集裝箱信息交換平臺(tái)要求和接口要求。本文件適用于基于區(qū)塊鏈的港航集裝箱信息交換平臺(tái)及接口的設(shè)計(jì)和應(yīng)用。（GB/T34990信息安全技術(shù)信息系統(tǒng)安全管理平臺(tái)技術(shù)要求和測(cè)評(píng)評(píng)價(jià)方法JT/T1417交通運(yùn)輸行業(yè)網(wǎng)絡(luò)安全等級(jí)保護(hù)基本要求YD/T3747區(qū)塊鏈技術(shù)架構(gòu)安全要求RFC2616超文本傳輸協(xié)議HTTP1.1（HypertextTransferProtocol--HTTP/1.1）下列術(shù)語(yǔ)和定義適用于本文件。分布賬本 distributedledgerGM/T0111—2021，3.4]智能約 smartcontract一套以數(shù)字形式定義的約定。[來源：GM/T0111—2021，3.3]節(jié)點(diǎn) node構(gòu)建數(shù)據(jù)結(jié)構(gòu)的基本組件。交易 transactionGM/T0111—2021，3.6]哈希值 hashvalue將任意長(zhǎng)度的二進(jìn)制串映射為固定長(zhǎng)度的二進(jìn)制串的函數(shù)輸出的比特串。時(shí)間戳 timestamp以公共時(shí)間為參考的時(shí)間點(diǎn)?？s略語(yǔ)下列縮略語(yǔ)適用于本文件。gRPCs：Google發(fā)起的開源遠(yuǎn)程過程調(diào)用安全協(xié)議(googleRemoteProcedureCallsecurityprotocol）HTTP：超文本傳輸協(xié)議（HyperTextTransferProtocol）JSON：腳本語(yǔ)言對(duì)象符號(hào)，一種輕量級(jí)的數(shù)據(jù)交換格式（JavaScriptObjectNotation）REST：表征狀態(tài)轉(zhuǎn)移（RepresentationalStateTransfer）SCAC：標(biāo)準(zhǔn)承運(yùn)人數(shù)字代碼（StandardCarrierAlphaCode）URI：通用資源標(biāo)識(shí)符（UniformResourceIdentifier））YD/T3747求。GB/T34990JT/T1417其他業(yè)務(wù)系統(tǒng)平臺(tái)框架見圖1。其他業(yè)務(wù)系統(tǒng)集基業(yè)務(wù)應(yīng)用層信息創(chuàng)建 信息更新 信息推送 信息查詢信息驗(yàn)證平臺(tái)服務(wù)層平臺(tái)基礎(chǔ)層身份管理 分布式賬本 智能合約密碼算法 隱私保護(hù) 共識(shí)機(jī)節(jié)點(diǎn)交易管理 節(jié)點(diǎn)節(jié)點(diǎn) 節(jié)點(diǎn)裝于箱信塊息鏈交換平臺(tái)航圖1 平臺(tái)架信息創(chuàng)建方創(chuàng)建需要上鏈的集裝箱信息并發(fā)送到平臺(tái)，平臺(tái)應(yīng)返回上鏈?zhǔn)聞?wù)信息數(shù)據(jù)。消息上鏈成功之后，平臺(tái)應(yīng)將消息推送給該消息角色清單中的參與方。信息查詢方請(qǐng)求查詢鏈上集裝箱信息，平臺(tái)應(yīng)向信息查詢方返回所查詢信息的明細(xì)。gRPCs平臺(tái)基礎(chǔ)層——審計(jì)內(nèi)容包括隱私保護(hù)策略和隱私保護(hù)技術(shù)手段；——審查形式包括但不限于日常監(jiān)控、定期審計(jì)、不定期審計(jì)；——審查對(duì)象包括但不限于操作記錄等支持性文檔；——確認(rèn)執(zhí)行過程中遵循并實(shí)現(xiàn)既定的策略和技術(shù)手段。RESTRESTRFC2616HTTPHTTP——無(wú)狀態(tài)的設(shè)計(jì)，不保留請(qǐng)求的狀態(tài)，同時(shí)連接應(yīng)為短連接；——公開目錄結(jié)構(gòu)式的URI；——傳輸JSON格式的請(qǐng)求體。接口響應(yīng)狀態(tài)碼應(yīng)使用RFC2616規(guī)范定義的HTTP狀態(tài)碼，常用的接口響應(yīng)狀態(tài)碼及其說明應(yīng)符合表1表1 接口應(yīng)用態(tài)及說明常用狀態(tài)碼說明200服務(wù)調(diào)用成功400請(qǐng)求格式錯(cuò)誤401未授權(quán)訪問403服務(wù)器拒絕訪問404指定的資源未找到429請(qǐng)求數(shù)超出限額500服務(wù)器內(nèi)部錯(cuò)誤504響應(yīng)超時(shí)注：業(yè)務(wù)產(chǎn)生的錯(cuò)誤或異常，其錯(cuò)誤描述和錯(cuò)誤號(hào)在HTTP響應(yīng)體中返回。HTTPHTTPHTTP平臺(tái)服務(wù)宜采用JSON作為數(shù)據(jù)交換的格式。HTTP（POST）（PUT）（GET）6.1.6IP平臺(tái)接口類型和交互方式應(yīng)符合表2的要求。表2 類型交方式接口類型交互方式URI發(fā)送方接收方信息創(chuàng)建POST/api/[assetType]信息創(chuàng)建方港航集裝箱信息交換平臺(tái)信息更新PUT/api/[assetType]信息更新方港航集裝箱信息交換平臺(tái)信息推送POST/api/push港航集裝箱信息交換平臺(tái)信息接收方信息查詢GET/api/[assetType]/[assetId]/version/[assetVersion]信息查詢方港航集裝箱信息交換平臺(tái)信息驗(yàn)證POST/api/verify信息驗(yàn)證方港航集裝箱信息交換平臺(tái)數(shù)據(jù)屬性包括：層次、中文名稱、英文名稱、類型、是否必填、說明，其中：——說明及要求：字段的內(nèi)容和表達(dá)的含義；（string）（object）——是否必填：該數(shù)據(jù)元是否必填，必填為M、非必填為C；——說明：字段的內(nèi)容和表達(dá)的含義。創(chuàng)建需要上鏈的信息。信息創(chuàng)建接口的請(qǐng)求參數(shù)數(shù)據(jù)格式和要求應(yīng)符合表3的規(guī)定。表3 信息建求信數(shù)格式求序號(hào)中文名稱英文名稱類型是否必填說明1區(qū)塊鏈組織代碼orgIDstringM織代碼2角色rolestringM信息創(chuàng)建方3區(qū)塊鏈業(yè)務(wù)應(yīng)用場(chǎng)景編號(hào)applicationIDstringM區(qū)塊鏈針對(duì)業(yè)務(wù)應(yīng)用場(chǎng)景分配的編號(hào)上鏈內(nèi)容的數(shù)據(jù)格式和要求應(yīng)符合表4的規(guī)定。表4 信息建鏈容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10角色清單roleListobjectM信息創(chuàng)建方指定允許查詢的參與方清單1.11角色清單定位鍵roleListLocatorKeyobjectM息識(shí)別碼1.1.12承運(yùn)人代碼carrierScacstringM承運(yùn)人scac代碼1.1.22提單號(hào)blNumberstringC提單號(hào)1.1.32提貨單號(hào)doNumberstringC提貨單號(hào)1.1.42集裝箱號(hào)cntrNumberstringC集裝箱號(hào)1.1.52角色清單類型roleListTypestringM角色清單類型1.21角色清單類型roleListTypestringM角色清單類型1.31角色清單內(nèi)容roleListContentobjectM參與方清單內(nèi)容1.3.12承運(yùn)人組織代碼carrierOrgIDstringC承運(yùn)人在區(qū)塊鏈的組織代碼1.3.22最終卸港碼頭組織代碼lastPodTerminalOperatorOrgIDstringC最終卸港碼頭在區(qū)塊鏈的組織代碼1.3.32托運(yùn)人組織代碼shipperOrgIDstringC托運(yùn)人在區(qū)塊鏈的組織代碼1.3.42貨運(yùn)代理組織代碼forwardeOrgIDstringC貨運(yùn)代理在區(qū)塊鏈的組織代碼1.3.52收貨人組織代碼consigneeOrgIDstringC收貨人在區(qū)塊鏈的組織代碼1.3.62船公司代理組織代碼shipAgentOrgIDstringC船公司代理在區(qū)塊鏈的組織代碼20信息明細(xì)assetContentobjectM所需創(chuàng)建的信息明細(xì)返回內(nèi)容的數(shù)據(jù)格式和要求應(yīng)符合表5的規(guī)定。表5 信息建回容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10代碼codestringM由區(qū)塊鏈返回的回執(zhí)代碼20錯(cuò)誤簡(jiǎn)要描述errorstringC1000000：表示成功；30回執(zhí)明細(xì)dataobjectM其余代碼：表示出錯(cuò)3.11事務(wù)識(shí)別號(hào)txnIDstringC回錯(cuò)誤簡(jiǎn)要描述3.21信息識(shí)別碼assetIDstringC錯(cuò)，則會(huì)返回錯(cuò)誤明細(xì)3.31錯(cuò)誤列表detailsarrayC識(shí)別號(hào)3.3.12錯(cuò)誤明細(xì)messagestringC信息識(shí)別碼3.3.22錯(cuò)誤類型typestringCassestcontent信息更新接口的請(qǐng)求頭信息數(shù)據(jù)格式和要求應(yīng)符合表6的規(guī)定。表6 信息新求信數(shù)格式求序號(hào)中文名稱英文名稱類型是否必填說明1區(qū)塊鏈組織代碼orgIDstringM織代碼2角色rolestringM信息更新方3區(qū)塊鏈業(yè)務(wù)應(yīng)用場(chǎng)景編號(hào)applicationIDstringM區(qū)塊鏈針對(duì)業(yè)務(wù)應(yīng)用場(chǎng)景分配的編號(hào)4信息識(shí)別碼assetIDstringM唯一信息識(shí)別碼5信息版本assetVersionstringM當(dāng)前區(qū)塊鏈上該信息的版本信息更新上鏈內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表7的規(guī)定。表7 信息新鏈容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10角色清單roleListobjectM信息更新方指定允許查詢的參與方清單1.11角色清單定位鍵roleListLocatorKeyobjectM息識(shí)別碼1.1.12承運(yùn)人代碼carrierScacstringM承運(yùn)人scac代碼1.1.22提單號(hào)blNumberstringC提單號(hào)1.1.32提貨單號(hào)doNumberstringC提貨單號(hào)1.1.42集裝箱號(hào)cntrNumberstringC集裝箱號(hào)1.1.52角色清單類型roleListTypestringM角色清單類型。如：SEAWAY_BILL1.21角色清單類型roleListTypestringM角色清單類型。如：SEAWAY_BILL1.31角色清單內(nèi)容roleListContentobjectM參與方清單內(nèi)容1.3.12承運(yùn)人組織代碼carrierOrgIDstringC承運(yùn)人在區(qū)塊鏈的組織代碼1.3.22最終卸港碼頭組織代碼lastPodTerminalOperatorOrgIDstringC最終卸港碼頭在區(qū)塊鏈的組織代碼1.3.32托運(yùn)人組織代碼shipperOrgIDstringC托運(yùn)人在區(qū)塊鏈的組織代碼1.3.42貨運(yùn)代理組織代碼forwardeOrgIDstringC貨運(yùn)代理在區(qū)塊鏈的組織代碼1.3.52收貨人組織代碼consigneeOrgIDstringC收貨人在區(qū)塊鏈的組織代碼1.3.62船公司代理組織代碼shipAgentOrgIDstringC船公司代理在區(qū)塊鏈的組織代碼1.41信息明細(xì)assetContentobjectM所需更新的信息明細(xì)返回內(nèi)容應(yīng)符合6.2.4的規(guī)定。消息上鏈成功之后，平臺(tái)將消息推送給該消息角色清單中的參與方。信息推送請(qǐng)求頭信息數(shù)據(jù)格式要求應(yīng)符合表8的規(guī)定。表8 信息送求信數(shù)格式求序號(hào)中文名稱英文名稱類型是否必填說明1授權(quán)碼authorizationstringM鏈，用來接收信息推送接口的授權(quán)碼，是數(shù)據(jù)交互安全的手段之一信息推送上鏈內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表9的規(guī)定。表9 信息送鏈容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10信息識(shí)別碼assetIDstringM信息推送所對(duì)應(yīng)的唯一信息識(shí)別碼20信息版本assetVersionstringM由區(qū)塊鏈返回的當(dāng)前信息版本30信息類型assetTypestringM返回由區(qū)塊鏈預(yù)先定義的信息類型，每種信息均有定義的專屬信息類型。40數(shù)字指紋locatorKeystringM相關(guān)參與方50上鏈?zhǔn)聞?wù)onchainTxnsarrayM由區(qū)塊鏈返回的上鏈?zhǔn)聞?wù)識(shí)別號(hào)和時(shí)間戳5.11區(qū)塊鏈通道channelstringM個(gè)通道對(duì)應(yīng)一本區(qū)塊鏈分布式賬本5.21事務(wù)識(shí)別號(hào)txnIDstringM由區(qū)塊鏈返回的唯一事務(wù)識(shí)別號(hào)5.31參與方participantsarrayM由區(qū)塊鏈返回的參與方清單5.41時(shí)間戳timestampstringM用格林威治時(shí)間60創(chuàng)建的時(shí)間戳createAtstringM威治時(shí)間70更新的時(shí)間戳updateAtstringM威治時(shí)間80加密策略encryptStrategystringM由區(qū)塊鏈返回的加密策略90信息提供方的事務(wù)數(shù)字簽名payloadSignstringM由區(qū)塊鏈返回的信息提供方的數(shù)字簽名100鏈上信息的哈希值assetHashstringM由區(qū)塊鏈返回的鏈上信息哈希值110信息明細(xì)assetContentobjectM由區(qū)塊鏈返回的信息明細(xì)信息推送接口的狀態(tài)應(yīng)由HTTP狀態(tài)碼進(jìn)行識(shí)別，HTTP狀態(tài)碼200為成功，其它狀態(tài)碼為失敗。參與方可通過該接口查詢鏈上信息。信息查詢請(qǐng)求內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表10的規(guī)定。表10 信息詢求容據(jù)式要求序號(hào)中文名稱英文名稱類型是否必填說明1區(qū)塊鏈組織代碼orgIDstringM織代碼2角色rolestringM信息查詢方3區(qū)塊鏈業(yè)務(wù)應(yīng)用場(chǎng)景編號(hào)applicationIDstringM區(qū)塊鏈針對(duì)業(yè)務(wù)應(yīng)用場(chǎng)景分配的編號(hào)4信息識(shí)別碼assetIDstringM需要查詢信息所對(duì)應(yīng)的唯一信息識(shí)別碼5信息版本assetVersionstringC當(dāng)前區(qū)塊鏈上該信息的版本信息查詢返回內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表11的規(guī)定。表11 信息詢回容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10代碼codestringM由區(qū)塊鏈返回的回執(zhí)代碼20數(shù)據(jù)dataarrayM由區(qū)塊鏈返回的回執(zhí)明細(xì)2.11信息識(shí)別碼assetIDstringM需要查詢信息所對(duì)應(yīng)的唯一信息識(shí)別碼2.21信息版本assetVersionstringM由區(qū)塊鏈返回的鏈上信息的當(dāng)前版本2.31信息類型assetTypestringM返回由區(qū)塊鏈預(yù)先定義的信息類型，每種信息均有定義的專屬信息類型。區(qū)塊鏈用此信息類型定義，控制信息中具體數(shù)據(jù)項(xiàng)的訪問權(quán)限2.41數(shù)字指紋locatorKeystringM相關(guān)參與方2.51數(shù)據(jù)報(bào)文散列值assetHashstringM由區(qū)塊鏈返回的資產(chǎn)散列值2.61提供方的事務(wù)數(shù)字簽名payloadSignstringM由區(qū)塊鏈返回的提供方的交易數(shù)字簽名2.71加密策略encryptStrategystringM由區(qū)塊鏈返回的加密策略2.81創(chuàng)建的時(shí)間戳createAtstringM威治時(shí)間2.91更新的時(shí)間戳updateAtstringM威治時(shí)間2.101上鏈?zhǔn)聞?wù)onchainTxnsarrayM由區(qū)塊鏈返回的上鏈?zhǔn)聞?wù)識(shí)別號(hào)和時(shí)間戳2.10.12事務(wù)識(shí)別號(hào)txnIDstringM由區(qū)塊鏈返回的唯一事務(wù)識(shí)別號(hào)2.10.22區(qū)塊鏈通道channelstringM個(gè)通道對(duì)應(yīng)一本區(qū)塊鏈分布式賬本2.10.32參與方participantsarrayM由區(qū)塊鏈返回的參與方清單2.10.42時(shí)間戳timestampstringM由區(qū)塊鏈返回的上鏈時(shí)的時(shí)間戳，采用格林威治時(shí)間2.111信息明細(xì)assetContentobjectM由區(qū)塊鏈返回的所查詢信息的明細(xì)各參與方通過鏈上信息與鏈下信息的對(duì)比，來驗(yàn)證鏈下信息是否有篡改。信息驗(yàn)證請(qǐng)求內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表12的規(guī)定。表12 信息證求容據(jù)式要求序號(hào)中文名稱英文名稱類型是否必填說明1信息類型assetTypestringM中具體數(shù)據(jù)項(xiàng)的訪問權(quán)限2驗(yàn)證方區(qū)塊鏈組織代碼orgIDstringM一的組織代碼3角色rolestringM（建方、信息更新方或信息查詢方）4區(qū)塊鏈業(yè)務(wù)應(yīng)用場(chǎng)景編號(hào)applicationIDstringM針對(duì)業(yè)務(wù)應(yīng)用場(chǎng)景分配的編號(hào)5信息識(shí)別碼assetIDstringM需要查詢信息所對(duì)應(yīng)的唯一信息識(shí)別碼6信息版本assetVersionstringM當(dāng)前區(qū)塊鏈上該信息的版本信息驗(yàn)證校驗(yàn)內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表13的規(guī)定。表13 信息證驗(yàn)容據(jù)式要求序號(hào)中文名稱英文名稱類型是否必填說明1驗(yàn)證方組織代碼originatorOrgIDstringM一的組織代碼2需驗(yàn)證的內(nèi)容assetContentobjectM信息驗(yàn)證方需驗(yàn)證的信息內(nèi)容3需驗(yàn)證的文件filestringC信息驗(yàn)證方需驗(yàn)證的文件信息校驗(yàn)返回內(nèi)容數(shù)據(jù)格式要求應(yīng)符合表14的規(guī)定。表14 信息證回容據(jù)式要求序號(hào)層次中文名稱英文名稱類型是否必填說明10代碼codestringM由區(qū)塊鏈返回的回執(zhí)代碼20數(shù)據(jù)dataobjectM由區(qū)塊鏈返回的回執(zhí)明細(xì)2.11驗(yàn)證結(jié)果verificationResultstringM失敗2.21原因reasonstringC由區(qū)塊鏈返回的失敗原因［請(qǐng)求參數(shù)以HTTPHeader的方式提供：POST/api/seawayBill

附錄A（資料性）信息交互示例orgID:6aba7011-a947-4d61-ae59-700791870c99role:CarrierapplicationID:b6422a60-caeb-41f7-81be-847af760c635［［請(qǐng)求示例］請(qǐng)求參數(shù)以HTTPURL參數(shù)和HTTPHeader的方式提供，assetID及assetVersion以URL參數(shù)的方式提供，其它參數(shù)以HTTPHeader的方式提供：PUT/api/seawayBill/1888512039056320807/version/1orgID:6aba7011-a947-4d61-ae59-700791870c99role:Carr