交互界面，Web服務(wù)定義的核心
2024-07-21 02:21:50
供稿：網(wǎng)友
國內(nèi)最大的酷站演示中心!
架構(gòu)web service: 交互界面，web服務(wù)定義的核心
內(nèi)容：
api概述
catalog service
member service
feedback service
order service
描述與注冊: 發(fā)布web服務(wù)
參考資料
作者簡介
相關(guān)內(nèi)容：
實(shí)戰(zhàn)web服務(wù)
基于web服務(wù)的應(yīng)用、解決方案和開發(fā)平臺
什么是web服務(wù)?
為什么需要web服務(wù)?
柴曉路 ([email protected])
chief system architect
2001年9月17日
本文是架構(gòu)web服務(wù)的系列文章的第五篇，以在前文中描述的應(yīng)用實(shí)例為基礎(chǔ)，詳細(xì)定義了catalog服務(wù)的api消息，全部api是使用soap完成調(diào)用和返回的，本文通過api的具體定義，詳細(xì)介紹和演示了交互的數(shù)據(jù)結(jié)構(gòu)和api消息結(jié)構(gòu)的定義方法和相應(yīng)模式，為讀者在定義自己的web服務(wù)接口時(shí)提供了實(shí)例的幫助和教程。
在本系列的前一篇文章中，對于給出的case做了系統(tǒng)分析，并對系統(tǒng)作了模塊劃分，初步界定有如下在線服務(wù)組件：
catalog service - 類別(category)管理，產(chǎn)品(product)管理，數(shù)據(jù)交換，數(shù)據(jù)備份等；
order service - 接受訂單，向其他接受訂單的服務(wù)發(fā)送訂單等；
feedback service - 反饋信息(feedback)管理，數(shù)據(jù)交換等。
由于這些服務(wù)顯然必須有一個用戶系統(tǒng)來支持，無論是因?yàn)榘踩缘目紤](有權(quán)限的才能做某些操作，還是因?yàn)槭聞?wù)的用戶相關(guān)性(顯然order這樣的服務(wù)不大可能脫離用戶而實(shí)施)。因此我們需要增加一個在線服務(wù)member service，membership的申請基本上可以依靠web服務(wù)之外的流程完成，比如web application，因此member service的web service界面相對可以非常簡化。所有這些在線組件服務(wù)需要提供的對外接口，我們的詳細(xì)定義從下圖開始：
figure 1. api消息
本文所引用的資源主要包括兩類，一類是web服務(wù)的技術(shù)資源網(wǎng)站，包含了大量web服務(wù)的技術(shù)信息，另一類是web服務(wù)“stack"系列技術(shù)規(guī)范，他們是一個整體的技術(shù)體系，包括uddi、soap、wsdl、xml等。本文的最后給出了這些資源的鏈接，有興趣的讀者可以通過這些資源鏈接找到所需的內(nèi)容。
api概述
對于整個系統(tǒng)的api設(shè)計(jì)，其遵循的原則有這樣幾條：
簡單性，由于這是一個對于公共開放的web服務(wù)，它的api的設(shè)計(jì)首先應(yīng)當(dāng)是簡單的，要被大量用戶接受，要獲得比較好的應(yīng)用，那么api必須簡單，沒有哪個復(fù)雜難用的api會得到大家的廣泛接受的，除非是普及率太廣的系統(tǒng)，而目前我們要設(shè)計(jì)的web服務(wù)是新系統(tǒng)，所以針對目前的應(yīng)用實(shí)況，api必須簡單。
可擴(kuò)展性，作為更新頻率較高，開放性較強(qiáng)的web服務(wù)，其api應(yīng)當(dāng)具有很好的向后擴(kuò)展性，當(dāng)應(yīng)內(nèi)部需求的改變或外部需求的改變的需要時(shí)，api將根據(jù)新的商業(yè)邏輯發(fā)生變化，此時(shí)不應(yīng)當(dāng)將api從根本上推翻重建，而應(yīng)當(dāng)具備增量式的可擴(kuò)展的能力。
兼容性，其實(shí)兼容性與可擴(kuò)展性是互通的，api的兼容性指的就是向后兼容性，高版本的api應(yīng)該具備對低版本api的兼容性，也就是說使用高版本api的web服務(wù)，應(yīng)當(dāng)能支持使用低版本api的調(diào)用。
高效性，api應(yīng)該在堅(jiān)持簡單性的前提下，兼顧高效性，當(dāng)某些組合操作應(yīng)用地非常頻繁的時(shí)候，我們應(yīng)當(dāng)為這樣的組合操作調(diào)用設(shè)計(jì)一個只需一次交互的單一入口調(diào)用，這樣能夠提升外部應(yīng)用的效率，同時(shí)減輕web服務(wù)的負(fù)載。
完備性，所謂完備性就是說整個api要覆蓋所有需要對外公開的功能，這相對而言是最好實(shí)現(xiàn)的目標(biāo)，只要設(shè)計(jì)階段考慮得完備，就能達(dá)到完備性的要求。而且萬一發(fā)現(xiàn)不完備的情況，修正起來也是相對容易的。
catalog service
save_category: 保存category，在這個api調(diào)用中，包含了更新和新建的操作，同時(shí)category的遷移也可以通過這個api來完成。
delete_category: 刪除category，將指定category及其全部子元素從catalog中刪除。
find_category: 在catalog中定位尋找category，可以通過多種方式，比如名稱，比如關(guān)鍵字等。
save_product: 保存product，在這個api調(diào)用中，同樣可以包含更新、新建和遷移的操作。
delete_product: 刪除product，將指定product的信息從catalog中刪除。
find_product: 在catalog中定位尋找product，可以通過多種方式，比如名稱，比如所在的category，比如關(guān)鍵字等。
get_categorydetail: 獲取category的完整信息，包括包含的所有category的簡要信息和product的詳細(xì)信息。
get_productdetail: 獲取product的完整信息。
get_categoryinfo: 獲取category及其所有子孫category和product的所有信息。
在定義這些消息之前，我們首先需要確定的是category和product這兩個實(shí)體的xml描述格式。參照前文中的實(shí)體關(guān)系模型，我們可以將它們定義如下：
category的具體描述格式：
<category categorykey="…" parentcategorykey="…">
<name>……</name>
<description>……</description>
</category>
product的具體描述格式：
<product productkey="…" parentcategorykey="…">
<name>……</name>
<description>……</description>
<compliantspecbag />
<featurebag />
<parameterbag />
</category>
其中，compliantspecbag、featurebag和parameterbag的具體格式分別如下：
<compliantspecbag>
<specification specificationkey="……" /> *
</compliantspecbag>
compliantspecbag描述的是一種計(jì)算機(jī)產(chǎn)品遵循了哪些相關(guān)的業(yè)界標(biāo)準(zhǔn)。在這個聚集里面，specification這個元素可以出現(xiàn)多次，每一個條目分別表示其遵循了一種工業(yè)標(biāo)準(zhǔn)，比如一臺娛樂型的便攜式計(jì)算機(jī)可能就會遵循諸如usb1.0、ieee1394等等的工業(yè)規(guī)范。
<featurebag>
<feature>……</feature> *
</featurebag>
featurebag描述的是一種計(jì)算機(jī)產(chǎn)品的重要特性。在這個聚集里面，feature這個元素可以出現(xiàn)多次，每一個條目使用字符串文本來描述某一種產(chǎn)品特性。比如一臺娛樂型的便攜式計(jì)算機(jī)可能的特性會包括"重量僅有2磅，厚度僅有1.9cm，超級便攜"這樣的特性描述。
<parameterbag>
<parameter> *
<keyname>……</keyname>
<keyvalue>……</keyvalue>
</parameter>
</parameterbag>
parameterbag描述的是一種計(jì)算機(jī)產(chǎn)品的相關(guān)技術(shù)參數(shù)。在這個聚集里面，parameter這個元素可以出現(xiàn)多次，每一個條目使用keyname和keyvalue名值對來描述某一個技術(shù)參數(shù)。比如一臺便攜式計(jì)算機(jī)可能的技術(shù)參數(shù)會是tft_size10.1"。
在定義了核心的數(shù)據(jù)模型之后，我們就可以來分別定義具體的api消息了。
save_category
用于保存category的最新信息，使用這個api調(diào)用，可以完成對category的更新、新建和遷移的操作。
<save_category>
<authinfo>……</authinfo>
<category categorykey="…" parentcategorykey="…"> *
<name>……</name>
<description>……</description>
<category /> *
<product /> *
</category>
</save_category>
在上述的語法描述中，大家應(yīng)該可以發(fā)現(xiàn)，save_category能夠用于保存一棵或多棵完整的category樹，而不光光是僅僅保存一個或多個category結(jié)點(diǎn)，這樣的設(shè)計(jì)是為了高效性的設(shè)計(jì)目標(biāo)而做的調(diào)整。
當(dāng)整個消息中的任意一個category或product所屬的標(biāo)識自身實(shí)體的鍵值categorykey或productkey為空，即表示這是一個新增的category或product，需要被插入到數(shù)據(jù)庫中，在返回消息中，將回送這些元素的鍵值。
當(dāng)消息中任意一個category或product的parentcategorykey沒有發(fā)生更改時(shí)，表明是要更新該元素的信息。而若parentcategorykey發(fā)生更改的時(shí)候，表明該元素將從之前的由原有parentcategorykey所標(biāo)識的category結(jié)點(diǎn)下被遷移到由新的parentcategorykey所標(biāo)識的category結(jié)點(diǎn)下。當(dāng)然如果包含了數(shù)據(jù)更新操作，同樣會實(shí)施該數(shù)據(jù)更新操作。
細(xì)心的讀者一定已經(jīng)發(fā)現(xiàn)了在這個消息中，有一個authinfo元素，這是一個用于權(quán)限檢驗(yàn)的授權(quán)令牌。在后面我將指明這個元素是如何獲取并使用的。
save_category消息調(diào)用的返回是一個或多個完整的被接受的category信息，與提交的信息的差別就是僅有概要信息，沒有相信信息，同時(shí)原先空著的鍵值都被填上web服務(wù)所指派的鍵值。下面是一個返回消息的例子：
<result>
<category categorykey="a01" parentcategorykey="……">
<category categorykey="a02" parentcategorykey="a01" />
<category categorykey="a03" parentcategorykey="a01" />
<category categorykey="a04" parentcategorykey="a01" />
<product productkey="p01" parentcategorykey="a01" />
<product productkey="p02" parentcategorykey="a01" />
</category>
<category categorykey="b01" parentcategorykey="……">
<category categorykey="b07" parentcategorykey="b01" />
<category categorykey="b08" parentcategorykey="b01" />
<product productkey="p09" parentcategorykey="b01" />
</category>
</result>
delete_category
用于刪除category的api調(diào)用，能夠?qū)⒁粋€或多個category及其全部子元素從catalog中刪除。
<delete_category>
<authinfo>……</authinfo>
<category categorykey="…" /> *
</delete_category>
在上述的語法描述中，大家應(yīng)該可以發(fā)現(xiàn)，save_category能夠用于刪除一個或多個使用categorykey標(biāo)識的category。當(dāng)一個category被刪除時(shí)，其所有子元素(包括category子元素和product子元素)都將被刪除。
delete_category消息調(diào)用的返回是一個或多個被實(shí)施刪除的category信息的鍵值列表。
find_product
用于在某個catalog中搜尋滿足指定條件的product，在這個api消息中，支持多種查詢方式，比如名稱，比如按照所遵循的行業(yè)規(guī)范等。
<find_product>
<authinfo>……</authinfo>
<category categorykey="…" />
<name />
<compliantspecbag />
<parameterbag>
</find_product>
在find_product消息中，支持四種搜索條件：
category，該元素描述了待搜索category子樹的根。表明待執(zhí)行的搜索的空間是由該元素中的categorykey所標(biāo)識的category的所有子元素組成。
name，這個name元素中描述的字符串是作為名串的最左子串存在的，在搜索中實(shí)施的也是最左匹配，比如在這個name元素中描述了"中國"那么"中國汽車"，"中國計(jì)算機(jī)"就會被匹配到，而"優(yōu)質(zhì)中國汽車"就不會被匹配到。
compliantspecbag，該元素中描述了一個業(yè)界規(guī)范的聚集，依靠這個搜索時(shí)指定的聚集，我們就可以將所有不符合這些規(guī)范的計(jì)算機(jī)產(chǎn)品排除在搜索結(jié)果集之外。例如該元素中包含了兩個規(guī)范usb1.1和ieee1394，那么只有同時(shí)支持這兩個規(guī)范的產(chǎn)品才會被搜索到。
parameterbag，該元素中描述了一個技術(shù)參數(shù)的聚集，其使用方式與compliantspecbag類似，所有不符合所描述的技術(shù)參數(shù)指定的計(jì)算機(jī)產(chǎn)品將被排除在搜索結(jié)果集之外。
對于compliantspecbag和parameterbag默認(rèn)的搜索中的處理行為是邏輯與的方式，我們可以通過參數(shù)指定來定義邏輯或的方式。例如：
<compliantspecbag>
<logicbehavior value="or" />
<specification specificationkey="key[usb1.1]" />
<specification specificationkey="key[ieee1394]" />
</compliantspecbag>
這個例子表示需要搜索的計(jì)算機(jī)產(chǎn)品要么兼容usb1.1，要么兼容ieee1394接口，那么不支持這兩種規(guī)范中任一規(guī)范的計(jì)算機(jī)產(chǎn)品將被排除在搜索結(jié)果集之外。
find_product消息調(diào)用的返回是一個或多個被匹配到的product信息，但改信息列表是一個概要信息的列表。下面是一個返回消息的例子：
<result>
<product productkey="p01" parentcategorykey="a01" />
<name>……</name>
<description>……</description>
</product>
<product productkey="p02" parentcategorykey="a01" />
<name>……</name>
<description>……</description>
</product>
</result>
在分析了上述三個api消息之后，我們不難理解save_product、delete_product和find_category和前面三個消息基本類似，且形式更為簡化，因此就不在詳細(xì)說明，浪費(fèi)篇幅了。
而對于其余三個消息：get_categorydetail，get_productdetail和get_categoryinfo，一來這三個消息相對簡單，傳入鍵值返回實(shí)體信息，二來經(jīng)過前面的演示，相信大家應(yīng)該有了一個具體的認(rèn)識，因此在這里就不花篇幅定義具體消息了。
member service
對于member service而言，提供兩個api消息：
get_authtoken
用于向member service請求一個認(rèn)證令牌。在調(diào)用其他所有api 時(shí)都需要使用認(rèn)證令牌。此函數(shù)在功能上等價(jià)于那些完成登錄請求的程序。
<get_authtoken generic="2.0" xmlns="urn:uddi-org:api_v2"
userid="someloginname"
password="somepassword" />
userid參數(shù)必須出現(xiàn)，表示在線服務(wù)所授權(quán)的個體用戶。member service提供對用戶所提供的用戶id和密碼進(jìn)行有效性檢查的方法。password參數(shù)必須出現(xiàn)，它表示了用戶id所對應(yīng)的密碼。
discard_authtoken
用于通知member service，先前提供的認(rèn)證令牌不再有效。當(dāng)其他web服務(wù)在member service接受到本消息之后，仍然收到這一認(rèn)證令牌的使用，那么其他web服務(wù)應(yīng)當(dāng)判斷其為非法。
<discard_authtoken generic="2.0" xmlns="urn:uddi-org:api_v2" >
<authinfo/>
</discard_authtoken>
authinfo這個參數(shù)是必需的，它是一個包含了認(rèn)證令牌的元素。認(rèn)證令牌可以使用 get_authtoken api調(diào)用來獲得。
feedback service
save_feedback: 保存feedback，在這個api調(diào)用中，包含了更新和新建的操作，同時(shí)category的遷移也可以通過這個api來完成。另外，使用這個api還能完成刪除的操作(之所以這樣設(shè)計(jì)是因?yàn)榭紤]到刪除是萬不得已才會發(fā)生的操作)，刪除操作通過僅傳入feedbackkey和authinfo來完成操作。
find_feedback: 在catalog中定位尋找feedback，比如名稱，比如categorykey等。
get_feedbackdetail: 獲取一個category下同層所有feedback的詳細(xì)信息。
get_feedbackinfo: 獲取一個category下整個子樹中所有feedback的詳細(xì)信息。
order service
request_order: 發(fā)出訂單請求，在這個api中包含了申請新訂單和取消訂單的兩個操作。當(dāng)傳入的orderkey為空并包含其他細(xì)節(jié)內(nèi)容時(shí)，即為申請新訂單操作。如果傳入的orderkey為已有的order的鍵值，同時(shí)不包含order的其他細(xì)節(jié)內(nèi)容，那么即認(rèn)為其是取消訂單的操作。該消息的返回分別可以指明對于訂單請求的接受或拒絕指示。
get_orderdetail: 獲取訂單的詳細(xì)情況，用于在事后參閱。
find_order: 搜索按照輸入?yún)?shù)指明的條件的相關(guān)訂單。
描述與注冊: 發(fā)布web服務(wù)
在本文中，詳細(xì)描述和介紹了web服務(wù)的api是如何設(shè)計(jì)和定義的，其中介紹了一些基本的設(shè)計(jì)和應(yīng)用的模式。在本系列之后的文章中，我將以使用wsdl描述web服務(wù)，以及使用uddi注冊web服務(wù)來結(jié)束這個系列。
參考資料
web service 技術(shù)/評論網(wǎng)站
uddi-china.org, 以uddi為主的web服務(wù)技術(shù)網(wǎng)站。
webservices.org, web服務(wù)的綜合類技術(shù)網(wǎng)站。
ibm developerworks/web service zone, ibm的web服務(wù)技術(shù)資源中心
msdn online web services developer resources, microsoft的web服務(wù)的開發(fā)者資源網(wǎng)站
itpapers/web service, itpapers的web服務(wù)評論文章
解決b2b電子商務(wù)應(yīng)用交互和集成的interop stack系列技術(shù)標(biāo)準(zhǔn)規(guī)范
uddi執(zhí)行白皮書, uddi-china.org, uddi.org
uddi技術(shù)白皮書, uddi-china.org, uddi.org
uddi程序員api規(guī)范, uddi-china.org, uddi.org
uddi數(shù)據(jù)結(jié)構(gòu)參考, uddi-china.org, uddi.org
web service description language (wsdl) 1.0, ibm, 25 sep 2000
soap: simple object access protocol specification 1.1, ibm, microsoft, developmentor, 2000
extensible markup language (xml) 1.0 (second edition), w3c, 6 oct 2000
作者簡介
柴曉路: 上海得易電子商務(wù)技術(shù)有限公司(dealeasy)首席系統(tǒng)架構(gòu)師、xml技術(shù)顧問。uddi-china.org藍(lán)色火焰工作室(blue blaze studio)成員。uddi advisor group成員，wsui working group成員。2000年獲復(fù)旦大學(xué)計(jì)算機(jī)科學(xué)碩士學(xué)位，曾在國際計(jì)算機(jī)科學(xué)學(xué)術(shù)會議(icsc)、亞太區(qū)xml技術(shù)研討會(xml asia/pacific'99)、中國xml技術(shù)研討會(北京)、計(jì)算機(jī)科學(xué)期刊等各類國際、國內(nèi)重要會議與期刊上發(fā)表論文多篇。專長于基于xml的系統(tǒng)集成和數(shù)據(jù)交換的技術(shù)研究，同時(shí)對數(shù)據(jù)庫、面向?qū)ο蠹夹g(shù)及cscw等技術(shù)比較擅長。
