互動介面,Web服務定義的核心

來源:互聯網
上載者:User
web|web服務|互動  
架構Web Service: 互動介面,Web服務定義的核心  
  


   
內容:

API概述
Catalog Service
Member Service
Feedback Service
Order Service
描述與註冊: 發布Web服務
參考資料
作者簡介


相關內容:

實戰Web服務
基於Web服務的應用、解決方案和開發平台
什麼是Web服務?
為什麼需要Web服務?




柴曉路 (fennivel@uddi-china.org)
Chief System Architect
2001年9月17日

本文是架構Web服務的系列文章的第五篇,以在前文中描述的應用執行個體為基礎,詳細定義了Catalog服務的API訊息,全部API是使用SOAP完成調用和返回的,本文通過API的具體定義,詳細介紹和示範了互動的資料結構和API訊息結構的定義方法和相應模式,為讀者在定義自己的Web服務介面時提供了執行個體的協助和教程。
在本系列的前一篇文章中,對於給出的Case做了系統分析,並對系統作了模組劃分,初步界定有如下線上服務組件:

Catalog Service - 類別(Category)管理,產品(Product)管理,資料交換,資料備份等;
Order Service - 接受訂單,向其他接受訂單的服務發送訂單等;
Feedback Service - 反饋資訊(Feedback)管理,資料交換等。
由於這些服務顯然必須有一個使用者系統來支援,無論是因為安全性的考慮(有許可權的才能做某些操作,還是因為事務的使用者相關性(顯然Order這樣的服務不大可能脫離使用者而實施)。因此我們需要增加一個線上服務Member Service,Membership的申請基本上可以依靠Web服務之外的流程完成,比如Web Application,因此Member Service的Web Service介面相對可以非常簡化。所有這些線上元件服務需要提供的對外介面,我們的詳細定義從下圖開始:

Figure 1.   API訊息


本文所引用的資源主要包括兩類,一類是Web服務的技術資源網站,包含了大量Web服務的技術資訊,另一類是Web服務“stack"系列技術規範,他們是一個整體的技術體系,包括UDDI、SOAP、WSDL、XML等。本文的最後給出了這些資源的連結,有興趣的讀者可以通過這些資源連結找到所需的內容。

API概述

對於整個系統的API設計,其遵循的原則有這樣幾條:

簡單性,由於這是一個對於公用開放的Web服務,它的API的設計首先應當是簡單的,要被大量使用者接受,要獲得比較好的應用,那麼API必須簡單,沒有哪個複雜難用的API會得到大家的廣泛接受的,除非是普及率太廣的系統,而目前我們要設計的Web服務是新系統,所以針對目前的應用實況,API必須簡單。

可擴充性,作為更新頻率較高,開放性較強的Web服務,其API應當具有很好的向後擴充性,當應內部需求的改變或外部需求的改變的需要時,API將根據新的商業邏輯發生變化,此時不應當將API從根本上推翻重建,而應當具備增量式的可擴充的能力。

相容性,其實相容性與可擴充性是互連的,API的相容性指的就是向後相容性,高版本的API應該具備對低版本API的相容性,也就是說使用高版本API的Web服務,應當能支援使用低版本API的調用。

高效性,API應該在堅持簡單性的前提下,兼顧高效性,當某些組合操作應用地非常頻繁的時候,我們應當為這樣的組合操作調用設計一個只需一次互動的單一入口調用,這樣能夠提升外部應用的效率,同時減輕Web服務的負載。

完備性,所謂完備性就是說整個API要覆蓋所有需要對外公開的功能,這相對而言是最好實現的目標,只要設計階段考慮得完備,就能達到完備性的要求。而且萬一發現不完備的情況,修正起來也是相對容易的。

Catalog Service

save_category: 儲存category,在這個API調用中,包含了更新和建立的操作,同時category的遷移也可以通過這個API來完成。
delete_category: 刪除category,將指定category及其全部子項目從Catalog中刪除。
find_category: 在catalog中定位尋找category,可以通過多種方式,比如名稱,比如關鍵字等。
save_product: 儲存product,在這個API調用中,同樣可以包含更新、建立和遷移的操作。
delete_product: 刪除product,將指定product的資訊從Catalog中刪除。
find_product: 在catalog中定位尋找product,可以通過多種方式,比如名稱,比如所在的category,比如關鍵字等。
get_categoryDetail: 擷取category的完整資訊,包括包含的所有category的簡要資訊和product的詳細資料。
get_productDetail: 擷取product的完整資訊。
get_categoryInfo: 擷取category及其所有子孫category和product的所有資訊。
在定義這些訊息之前,我們首先需要確定的是category和product這兩個實體的XML描述格式。參照前文中的實體關聯模型,我們可以將它們定義如下:

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描述的是一種電腦產品遵循了哪些相關的業界標準。在這個聚集裡面,specification這個元素可以出現多次,每一個條目分別表示其遵循了一種工業標準,比如一台娛樂型的攜帶型電腦可能就會遵循諸如USB1.0、IEEE1394等等的工業規範。


<featureBag>
  <feature>……</feature> *
</featureBag>




featureBag描述的是一種電腦產品的重要特性。在這個聚集裡面,feature這個元素可以出現多次,每一個條目使用字串文本來描述某一種產品特性。比如一台娛樂型的攜帶型電腦可能的特性會包括"重量僅有2磅,厚度僅有1.9cm,超級便攜"這樣的特性描述。


<parameterBag>
  <parameter> *
    <keyName>……</keyName>
    <keyValue>……</keyValue>
  </parameter>
</parameterBag>




parameterBag描述的是一種電腦產品的相關技術參數。在這個聚集裡面,parameter這個元素可以出現多次,每一個條目使用keyName和keyValue名值對來描述某一個技術參數。比如一台攜帶型電腦可能的技術參數會是TFT_Size10.1"。

在定義了核心的資料模型之後,我們就可以來分別定義具體的API訊息了。

save_category

用於儲存category的最新資訊,使用這個API調用,可以完成對category的更新、建立和遷移的操作。


<save_category>
  <authInfo>……</authInfo>
  <category categoryKey="…" parentCategoryKey="…"> *
    <name>……</name>
    <description>……</description>
    <category /> *
    <product /> *
  </category>
</save_category>




在上述的文法描述中,大家應該可以發現,save_category能夠用於儲存一棵或多棵完整的category樹,而不光光是僅僅儲存一個或多個category結點,這樣的設計是為了高效性的設計目標而做的調整。

當整個訊息中的任意一個category或product所屬的標識自身實體的索引值categoryKey或productKey為空白,即表示這是一個新增的category或product,需要被插入到資料庫中,在返回訊息中,將回送這些元素的索引值。

當訊息中任意一個category或product的parentCategoryKey沒有發生更改時,表明是要更新該元素的資訊。而若parentCategoryKey發生更改的時候,表明該元素將從之前的由原有parentCategoryKey所標識的category結點下被遷移到由新的parentCategoryKey所標識的category結點下。當然如果包含了資料更新操作,同樣會實施該資料更新操作。

細心的讀者一定已經發現了在這個訊息中,有一個authInfo元素,這是一個用於許可權檢驗的授權令牌。在後面我將指明這個元素是如何擷取並使用的。

save_category訊息調用的返回是一個或多個完整的被接受的category資訊,與提交的資訊的差別就是僅有概要資訊,沒有相信資訊,同時原先空著的索引值都被填上Web服務所指派的索引值。下面是一個返回訊息的例子:


<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調用,能夠將一個或多個category及其全部子項目從Catalog中刪除。


<delete_category>
  <authInfo>……</authInfo>
  <category categoryKey="…" /> *
</delete_category>




在上述的文法描述中,大家應該可以發現,save_category能夠用於刪除一個或多個使用categoryKey標識的category。當一個category被刪除時,其所有子項目(包括category子項目和product子項目)都將被刪除。

delete_category訊息調用的返回是一個或多個被實施刪除的category資訊的索引值列表。

find_product

用於在某個catalog中搜尋滿足指定條件的product,在這個API訊息中,支援多種查詢方式,比如名稱,比如按照所遵循的行業規範等。


<find_product>
  <authInfo>……</authInfo>
  <category categoryKey="…" />
  <name />
  <compliantSpecBag />
  <parameterBag>
</find_product>




在find_product訊息中,支援四種搜尋條件:

category,該元素描述了待搜尋category子樹的根。表明待執行的搜尋的空間是由該元素中的categoryKey所標識的category的所有子項目組成。
name,這個name元素中描述的字串是作為名串的最左子串存在的,在搜尋中實施的也是最左匹配,比如在這個name元素中描述了"中國"那麼"中國汽車","中國電腦"就會被匹配到,而"優質中國汽車"就不會被匹配到。
compliantSpecBag,該元素中描述了一個業界規範的聚集,依靠這個搜尋時指定的聚集,我們就可以將所有不符合這些規範的電腦產品排除在搜尋結果集之外。例如該元素中包含了兩個規範USB1.1和IEEE1394,那麼只有同時支援這兩個規範的產品才會被搜尋到。
parameterBag,該元素中描述了一個技術參數的聚集,其使用方式與compliantSpecBag類似,所有不符合所描述的技術參數指定的電腦產品將被排除在搜尋結果集之外。
對於compliantSpecBag和parameterBag預設的搜尋中的處理行為是邏輯與的方式,我們可以通過參數指定來定義邏輯或的方式。例如:


<compliantSpecBag>
  <logicBehavior value="OR" />
  <specification specificationKey="Key[USB1.1]" />
  <specification specificationKey="Key[IEEE1394]" />
</compliantSpecBag>




這個例子表示需要搜尋的電腦產品要麼相容USB1.1,要麼相容IEEE1394介面,那麼不支援這兩種規範中任一規範的電腦產品將被排除在搜尋結果集之外。

find_product訊息調用的返回是一個或多個被匹配到的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和前面三個訊息基本類似,且形式更為簡化,因此就不在詳細說明,浪費篇幅了。

而對於其餘三個訊息:get_categoryDetail,get_productDetail和get_categoryInfo,一來這三個訊息相對簡單,傳入索引值返回實體資訊,二來經過前面的示範,相信大家應該有了一個具體的認識,因此在這裡就不花篇幅定義具體訊息了。

Member Service

對於Member Service而言,提供兩個API訊息:

get_authToken

用於向Member Service請求一個認證令牌。在調用其他所有API 時都需要使用認證令牌。此函數在功能上等價於那些完成登入請求的程式。


<get_authToken generic="2.0" xmlns="urn:uddi-org:api_v2"
  userID="someLoginName"
  password="somePassword" />




userID參數必須出現,表示線上服務所授權的個體使用者。Member Service提供對使用者所提供的使用者ID和密碼進行有效性檢查的方法。password參數必須出現,它表示了使用者ID所對應的密碼。

discard_authToken

用於通知Member Service,先前提供的認證令牌不再有效。當其他Web服務在Member Service接受到本訊息之後,仍然收到這一認證令牌的使用,那麼其他Web服務應當判斷其為非法。


<discard_authToken generic="2.0" xmlns="urn:uddi-org:api_v2" >
  <authInfo/>
</discard_authToken>




authInfo這個參數是必需的,它是一個包含了認證令牌的元素。認證令牌可以使用 get_authToken API調用來獲得。

Feedback Service

save_feedback: 儲存feedback,在這個API調用中,包含了更新和建立的操作,同時category的遷移也可以通過這個API來完成。另外,使用這個API還能完成刪除的操作(之所以這樣設計是因為考慮到刪除是萬不得已才會發生的操作),刪除操作通過僅傳入feedbackKey和authInfo來完成操作。
find_feedback: 在catalog中定位尋找feedback,比如名稱,比如categoryKey等。
get_feedbackDetail: 擷取一個category下同層所有feedback的詳細資料。
get_feedbackInfo: 擷取一個category下整個子樹中所有feedback的詳細資料。
Order Service

request_order: 發出訂單請求,在這個API中包含了申請新訂單和取消訂單的兩個操作。當傳入的orderKey為空白並包含其他細節內容時,即為申請新訂單操作。如果傳入的orderKey為已有的order的索引值,同時不包含order的其他細節內容,那麼即認為其是取消訂單的操作。該訊息的返回分別可以指明對於訂單請求的接受或拒絕指示。
get_orderDetail: 擷取訂單的詳細情況,用於在事後參閱。
find_order: 搜尋按照輸入參數指明的條件的相關訂單。
描述與註冊: 發布Web服務

在本文中,詳細描述和介紹了Web服務的API是如何設計和定義的,其中介紹了一些基本的設計和應用的模式。在本系列之後的文章中,我將以使用WSDL描述Web服務,以及使用UDDI註冊Web服務來結束這個系列。

參考資料

Web Service 技術/評論網站
UDDI-China.ORG, 以UDDI為主的Web服務技術網站。
WebServices.ORG, Web服務的綜合類技術網站。
IBM developerWorks/Web Service Zone, IBM的Web服務技術資源中心
MSDN Online Web Services Developer Resources, Microsoft的Web服務的開發人員資源網站
ITPapers/Web Service, ITPapers的Web服務評論文章
解決B2B電子商務應用互動和整合的InterOP Stack系列技術標準規範
UDDI執行白皮書, UDDI-China.org, UDDI.org
UDDI技術白皮書, UDDI-China.org, UDDI.org
UDDI程式員API規範, UDDI-China.org, UDDI.org
UDDI資料結構參考, 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
作者簡介

柴曉路: 上海得易電子商務技術有限公司(DealEasy)首席系統架構師、XML技術顧問。UDDI-China.org藍色火焰工作室(Blue Blaze Studio)成員。UDDI Advisor Group成員,WSUI Working Group成員。2000年獲複旦大學電腦科學碩士學位,曾在國際電腦科學學術會議(ICSC)、亞太地區區XML技術研討會(XML Asia/Pacific'99)、中國XML技術研討會(北京)、電腦科學期刊等各類國際、國內重要會議與期刊上發表論文多篇。專長於基於XML的系統整合和資料交換的技術研究,同時對資料庫、物件導向技術及CSCW等技術比較擅長。



相關文章

E-Commerce Solutions

Leverage the same tools powering the Alibaba Ecosystem

Learn more >

Apsara Conference 2019

The Rise of Data Intelligence, September 25th - 27th, Hangzhou, China

Learn more >

Alibaba Cloud Free Trial

Learn and experience the power of Alibaba Cloud with a free trial worth $300-1200 USD

Learn more >

聯繫我們

該頁面正文內容均來源於網絡整理,並不代表阿里雲官方的觀點,該頁面所提到的產品和服務也與阿里云無關,如果該頁面內容對您造成了困擾,歡迎寫郵件給我們,收到郵件我們將在5個工作日內處理。

如果您發現本社區中有涉嫌抄襲的內容,歡迎發送郵件至: info-contact@alibabacloud.com 進行舉報並提供相關證據,工作人員會在 5 個工作天內聯絡您,一經查實,本站將立刻刪除涉嫌侵權內容。