內容： API概述 Catalog Service Member Service Feedback Service Order Service 描述與注冊: 發布Web服務 參考資料 作者簡介 相關內容： 實戰Web服務 基于Web服務的應用、解決方案和開發平臺 什么是Web服務? 為什么需要Web服務?

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

（本文最初由 IBM developerWorks 中國網站發表，其網址是
http://www.ibm.com/developerWorks/cn/）

本文是架構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等。本文的最后給出了這些資源的鏈接，有興趣的讀者可以通過這些資源鏈接找到所需的內容。

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

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

3. 兼容性，其實兼容性與可擴展性是互通的，API的兼容性指的就是向后兼容性，高版本的API應該具備對低版本API的兼容性，也就是說使用高版本API的Web服務，應當能支持使用低版本API的調用。

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

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

<category categoryKey="..." parentCategoryKey="...">
  <name>...</name>
  <description>...</description>
</category>

Product的具體描述格式：

<product productKey="..." parentCategoryKey="...">
  <name>...</name>
  <description>...</description>
  <compliantSpecBag />
  <featureBag />
  <parameterBag />
</category>

<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消息中，支持四種搜索條件：

1. category，該元素描述了待搜索category子樹的根。表明待執行的搜索的空間是由該元素中的categoryKey所標識的category的所有子元素組成。
2. name，這個name元素中描述的字符串是作為名串的最左子串存在的，在搜索中實施的也是最左匹配，比如在這個name元素中描述了"中國"那么"中國汽車"，"中國計算機"就會被匹配到，而"優質中國汽車"就不會被匹配到。
3. compliantSpecBag，該元素中描述了一個業界規范的聚集，依靠這個搜索時指定的聚集，我們就可以將所有不符合這些規范的計算機產品排除在搜索結果集之外。例如該元素中包含了兩個規范USB1.1和IEEE1394，那么只有同時支持這兩個規范的產品才會被搜索到。
4. 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，一來這三個消息相對簡單，傳入鍵值返回實體信息，二來經過前面的演示，相信大家應該有了一個具體的認識，因此在這里就不花篇幅定義具體消息了。

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

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

參考資料

• 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
• 架構Web services系列
• • 架構Web Service(一): 為什么需要Web服務
  • 架構Web Service(二): 什么是Web服務
  • 架構Web Service(三):基于Web服務的應用、解決方案和開發平臺
  • 架構Web Service(四): 實戰Web服務
  • 架構Web Service(六):描述與注冊，發布Web服務