IBM Lotus Quickr Web Services 介紹

genusBIT發表於2010-05-19
IBMUIWeb

轉自http://www.ibm.com/developerworks/cn/lotus/quickr-web-services/

IBM Lotus Quickr 可以使使用者共享業務內容變得簡單。Lotus Quickr 的一個重要的設計原則是在開放的介面上建立應用，其中客戶和業務夥伴可以在需要時通過這些介面訪問內容。客戶和業務夥伴需要使用不同的客戶端和程式設計模型來處理來自不同知識庫的內容。Lotus Quickr Connectors 使用一組公開的介面與 Lotus Quickr 內容互動。

在本文中，我們將為您介紹可以使用 Lotus Quickr Web Services 執行的一些基本操作，以及您在訪問這些服務時應該使用的一些最佳實踐方法。在閱讀完本文後，您將對服務的結構和使用的請求-響應模式有足夠的瞭解，然後您就能夠開始開發您自己的與 Lotus Quickr 內容互動的應用了。

對於其他與 Lotus Quickr 內容互動的開放介面，請參考 IBM Lotus Quickr Developer's Guide。對於 Lotus Quickr REST 服務的介紹，請參考配套的 developerWorks Lotus 文章，“IBM Lotus Quickr REST 服務簡介”。

先決條件

您應該掌握基本的 Web Services 程式設計方法以便完全理解本文。其中包括對 Web Service Description Language (WSDL)、Simple Object Access Protocol (SOAP)、HTTP 和 XML 相關技術的理解。

本文所介紹的示例應用是與伺服器進行一系列 XML 請求-響應訊息互動。每一個請求-響應訊息都表示了在網路上傳輸的實際內容，從而讓讀者理解 XML 是如何格式化的。

希望使用這些服務來程式設計的開發人員通常會使用一些 SOAP 工具來產生客戶端代理，以便實現網路中傳輸的請求-響應物件的序列化。要使用這裡的示例程式碼，您應該對 C# 程式語言有一定的瞭解。示例程式碼的目的是為了說明不同程式設計環境的互操作性（例如，用一個 .NET 客戶端去呼叫一個用 J2EE 或 IBM Lotus Domino 伺服器提供的 Web Service），但是，用於建立示例程式碼的原則與方法是與任何其他提供 Web Service 技術原生支援的開發環境一致的。

概述

我們使用 Web Services 的目的是使您能儘可能快捷地建立針對 Lotus Quickr 內容的協作的文件管理解決方案。熟悉 Web Services 的客戶應該能夠很輕鬆地使用這些服務。因為這些服務是通過一個 WSDL 文件按照機器可讀格式定義的，您可以使用您喜歡的支援 Web Services 的工具環境來生成能與服務提供者互動的客戶端代理程式碼。通過這種方法，您不需要花很多的時間和精力去實現用於傳送和接受網路訊息的物件。同時，它也提供了您可以在應用中重用的一個物件模型。

關於示例

在本文中，我們建立了一個簡單且獨立的 Lotus Quickr Connector，如圖 1 所示。一個 Lotus Quickr Connector 是一個現有應用或框架的擴充套件，它允許您在需要時訪問內容。雖然這個示例是獨立的，但是它代表了一種您可以用來擴充套件現有應用以實現與 Lotus Quickr 內容互動的方法。


圖 1. 示例 Lotus Quickr Connector
示例 Lotus Quickr Connector

這個聯結器使使用者能夠向 Lotus Quickr 伺服器提交一個 URL 和認證資訊，然後操作流量伺服器上的一些庫。一個使用者可以使用聯結器對 Lotus Quickr 伺服器上的內容執行以下操作：

  • 單擊一個資料夾或文件以檢視伺服器所維護的這個資源的詳細屬性
  • 雙擊資料夾展開瀏覽樹以顯示子資料夾和文件
  • 觸發文件的預設雙擊行為，以便在一個 Web 瀏覽器上顯示內容的一個彙總檢視，或者直接下載該文件到檔案系統中
  • 通過編輯樹中的每一個資源的標籤以便重新命名資料夾和文件
  • 通過拖放操作在樹結構中移動資料夾或文件
  • 使用右鍵單擊的上下文選單操作刪除資料夾和文件

生成服務程式碼

要實現與 Lotus Quickr Web Service 的互動，您一般首先通過下面的 URL 將您的 IDE SOAP 工具代理指向 Lotus Quickr 伺服器上的 WSDL 文件：

http://:/dm/services/ContentService?wsdl.

例如：

http://localhost:10038/dm/services/ContentService?wsdl

然後使用者會被提示輸入伺服器認證資訊，從而生成一系列實現服務互動的程式碼工件。WSDL 中公開了三個服務埠型別，因此在物件導向的環境中，您通常針對 ContentService、DocumentService 和 LibraryService 與一個服務物件互動。

 

查詢伺服器資訊

Lotus Quickr Web Services 中的 ContentService 的目的是提供普通的內容操作，這些操作指的那些不是專門應用到庫、資料夾或文件的操作。對於這些服務的第一個版本，這個服務僅限於查詢伺服器的基本資訊及相關使用者。

可以預計的是，隨著 Lotus Quickr Web Services 的不斷髮展，將來可以實現包括目前所不支援的額外服務操作。客戶端需要知道可用的服務版本是什麼，這樣客戶端才不會呼叫伺服器支援的最新版本的操作。為了防止呼叫一個不支援特定操作的遠端伺服器，Web Services 包含了伺服器版本的資訊。

要確定部署在一個 Lotus Quickr 伺服器例項的 Web Services 的版本，我們的示例 Lotus Quickr Connector 傳送如清單 1 所示的請求，使用 ContentService 查詢伺服器的資訊。


清單 1. 查詢服務版本資訊的 SOAP 請求

POST /dm/services/ContentService HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; 
MSIE 6.0; MS Web Services Client Protocol 2.0.50727.832)
Content-Type: text/xml; 
charset=utf-8SOAPAction: ""Authorization: Basic am9obmRvZTpqb2huZG9l
Host: insertyourserver.com
Content-Length: 310
Expect: 100-continue
Connection: Keep-Alive

注意這個呼叫利用 HTTP Basic Auth 呼叫 Web Service。當您開發您的客戶端應用時，您應該觸發您的客戶端以便提前進行後臺認證，而不是在與服務互動時才進行認證。

然後伺服器會返回關於服務級別的一些基本資訊的響應，如清單 2 所示。其中 serverInfo 元素包含了一個定義了 Lotus Quickr 伺服器的當前服務版本資訊的版本屬性。


清單 2. 查詢服務版本資訊的 SOAP 響應

HTTP/1.1 200 OKDate: Tue, 02 Oct 2007 20:42:52 GMTServer: WebSphere Application 
Server/6.0
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
Content-Length: 2136

除此之外，其他有用的資訊是用一組 serverProperties 元素表示的。在前一個例子中，包括了伺服器的預設本地化資訊，呼叫基於 REST Atom 服務的相對 URL 模式，以及下載所有方便使用聯結器的聯結器 URL。

查詢頂級庫列表

一旦這個示例 Lotus Quickr Connector 知道了遠端伺服器上的服務級別，聯結器就會嘗試查詢伺服器上用於互動的文件庫列表（見清單 3）。要實現這一點，聯結器會與 LibraryService 元素互動，這些元素提供了查詢一個特定分類的庫。此外，它還提供了查詢一個用於管理遠端伺服器上跨庫的共享資源的庫的操作。


清單 3. 查詢文件庫列表的 SOAP 請求

POST /dm/services/LibraryService HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; MS Web Services Client 
Protocol 2.0.50727.832)
Content-Type: text/xml; charset=utf-8
SOAPAction: ""Authorization: Basic am9obmRvZTpqb2huZG9l
Host: insertyourserver.com:9090
Content-Length: 444Expect: 100-continue


  
   
   
   
   DocumentManager

這個請求會請求伺服器返回所有適合用於文件管理應用的庫元件。

清單 4 所示的響應列舉了一組伺服器互動可用的庫元件。每一個庫資源包括了諸如 ID （例如，d76a1880470797b28552b53e588f1125）和表示伺服器資源的唯一地址的路徑 （例如，/contentRoot/icm:libraries[7]/clb:libraries[2]/clb:libraries） 的後設資料。此外，其他系統後設資料將用於表示關於資源的基本屬性（例如，建立時間、最新修改時間、描述和標題等）。


清單 4. 查詢文件庫列表的 SOAP 響應

HTTP/1.1 200 OKDate: Tue, 02 Oct 2007 20:42:52 GMTServer: WebSphere Application 
Server/6.0
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
Content-Length: 1140

注意前面的響應的 getBusinessComponentsReturn 元素中包含了一個空的錯誤元素。這是 Web Services 所使用的用來表述非致命或預期錯誤條件的一個通用模式。服務的使用者應該檢查每一個響應可能發生的內嵌錯誤。SOAP 錯誤指的是用於表示嚴重的、不可恢復的系統錯誤。如果一個錯誤發生，就會有一個錯誤碼和描述，用於描述這個伺服器出現的錯誤，並允許聯結器優雅地處理這些錯誤情況。

 

查詢子資料夾、文件和後設資料

現在 Lotus Quickr Connector 能夠列出文件庫了，接下來您需要通過允許使用者展開瀏覽器中的資料夾來檢視子資料夾和文件，從而實現更深層次的瀏覽。

只要給定了上級資源的 ID 或路徑，查詢相關子資源的操作是很簡單的。由於瀏覽器可以顯示資料夾和所釋出的文件，因此您實際上發起了兩個請求。第一個請求上級資料夾內的子資料夾列表（如清單 5 所示）。


清單 5. 查詢子資料夾的 SOAP 請求

POST /dm/services/DocumentService HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; 
MS Web Services Client Protocol 2.0.50727.832)
Content-Type: text/xml; charset=utf-8
SOAPAction: ""Authorization: Basic am9obmRvZTpqb2huZG9l
Host: insertyourserver.com:9090
Content-Length: 382
Expect: 100-continue

      
         
            
               d76a1880470797b28552b53e588f1125

這個請求會查詢指定 ID 的上級資料夾的子資料夾列表，而產生的響應（如清單 6 所示）包含了資料夾物件列表。每一個資料夾物件包含了它的 ID、路徑以及它相關的後設資料，如標題、描述等。


清單 6. 查詢子資料夾的 SOAP 響應

HTTP/1.1 200 OKDate: Wed, 03 Oct 2007 17:18:06 GMT
Server: WebSphere Application Server/6.0
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
Content-Length: 6167

現在示例聯結器已經列出了層次結構中一個給定節點的子資料夾，接下來您需要查詢子文件資源列表（如清單 7 所示）。


清單 7. 查詢文件的 SOAP 請求

POST /dm/services/DocumentService HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; 
MS Web Services Client Protocol 2.0.50727.832)
Content-Type: text/xml; charset=utf-8
SOAPAction: ""Authorization: Basic am9obmRvZTpqb2huZG9l
Host: insertyourserver.com:9090
Content-Length: 423
Expect: 100-continue


 
  
   d76a1880470797b28552b53e588f1125
   
   None

這個請求查詢伺服器上指定 ID 的上級資料夾中的子文件列表，而伺服器響應（如清單 8 所示）包含了文件物件列表。每一個文件物件都包含了它的 ID、路徑以及相關原後設資料，如標題、描述等。


清單 8. 查詢文件的 SOAP 響應

HTTP/1.1 200 OKDate: Wed, 03 Oct 2007 17:18:06 GMT
Server: WebSphere Application Server/6.0
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
Content-Length: 7321

因為示例連線只建立了一個簡單的導航樹，所以聯結器不需要查詢資源的所有詳細資訊。為了提高效率，示例聯結器只查詢了它需要的最少的資訊。如果聯結器需要文件的相關資訊，它可以通過一組服務選項指定在一個呼叫中查詢相關的後設資料。

服務選項能夠使服務的客戶端指定呼叫的可選行為。對於一個特定呼叫所支援的選項，可以參考 WSDL；然而，為了方便使用，表 1 列出了所定義的每一個選項以及它們對所查詢資料的作用。


表 1. 服務選項

選項 行為
None 請求呼叫的預設行為。
IncludeDrafts 如果有草稿，那麼在所查詢的每一個文件中包含它相關的草稿。
IncludeApproveDrafts 如果服務上提供了憑證的使用者是草稿的審批者，那麼在所查詢的每一個文件中包含它相關的草稿。
IncludeSubmittedDrafts 如果服務上提供了憑證的使用者是草稿的提交者，那麼在所查詢的每一個文件中包含它相關的草稿。
IncludeReferences 在所查詢的每一個物件中包含它相關的引用型別。目前引用型別僅限於文件型別和屬性表型別。
IncludePermissions 為指定使用者查詢一項內容對應的許可權。
IncludePropertySheets 查詢與文件相關的一組任意定製屬性表。
ResolveLockOwner 生成鎖定該文件的使用者 ID。
RetrieveDownloadURL 生成用於下載文件二進位制內容的資源 URL 屬性。
RetrieveViewURL 生成檢視資源概述的資源 URL 屬性。
IncludeFolderChildren 在查詢一個資料夾物件時，在同一個請求中查詢它的子文件和資料夾。不推薦用於數量很大的子資料夾與文件。

下面，我們演示如何使用服務選項來操作在一個文件請求中查詢的後設資料（見清單 9）。


清單 9. 文件後設資料的 SOAP 請求

POST /dm/services/DocumentService HTTP/1.1
User-Agent: Mozilla/4.0 (compatible; MSIE 6.0; 
MS Web Services Client Protocol 2.0.50727.832)
Content-Type: text/xml; charset=utf-8
SOAPAction: ""Authorization: Basic cXVpa3JhZG06cXVpa3JhZG0=Host: 
insertyourserver.comContent-Length: 527
Expect: 100-continue


 
  
   a8959480470798cf8587b53e588f1125
   
   None
   IncludePropertySheets
   RetrieveDownloadURL

這個請求向伺服器傳遞兩個選項：IncludePropertySheets，用於請求伺服器返回一些定製屬性（如果文件中有定製屬性且伺服器支援）；RetrieveDownloadURL，用於請求伺服器返回可用於直接下載文件二進位制內容的 URL。

注意，這個響應（見清單 10）包含了文件中的所有定製屬性的一組動態圖。此外，文件資源的 url 屬性包含了一個下載資源二進位制內容的連結。


清單 10. 查詢文件後設資料的 SOAP 響應

HTTP/1.1 200 OKDate: Mon, 08 Oct 2007 18:10:38 GMT
Server: WebSphere Application Server/6.0
Content-Type: text/xml; charset=utf-8
Content-Language: en-US
Content-Length: 4243

示例 Lotus Quickr Connector 只能讀取文件資源後設資料。但是我們也可以使用 Lotus Quickr Web Services 來建立新文件和更新現有文件。為此作，使用者必須首先鎖定文件，建立一個資源草稿，修改草稿資源（後設資料或二進位制內容），然後將該草稿釋出為當前文件 。參考 WSDL（如前面 “生成服務程式碼” 部分所述）以瞭解所列選項的詳細文件。

 

重新命名和刪除資源

重新命名、移動和刪除操作與資源型別相關；換句話說，這些特定操作是針對資料夾和文件資源的。每一個操作都必須滿足 Lotus Quickr 伺服器的訪問控制約束的要求。

當嘗試重新命名一個資源時，呼叫者必須指定要修改的資源的 ID 或絕對路徑。新的名稱必須符合伺服器的檔案系統對映模式。

當刪除一個資源時，呼叫者必須指定要刪除的資源的 ID 或絕對路徑。資料夾和文件資源可以刪除，但是一個庫的根資料夾不能夠通過 Lotus Quickr Web Services 刪除。

 

結束語

Lotus Quickr Web Services 提供一種簡單的處理文件的方法。因為這些操作是使用 WSDL 文件描述的，您可以選擇自己喜歡的程式語言及相關的工具支援來快速地生成與遠端伺服器互動的程式碼（本文使用的是 C# 語言）。本文演示瞭如何使用這些服務來執行基本的文件操作，同時還闡述了每個請求和響應訊息的基本模式。

來自 “ ITPUB部落格 ” ，連結：http://blog.itpub.net/14751907/viewspace-663080/，如需轉載，請註明出處，否則將追究法律責任。

相關文章