转自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 服务器提交一个 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 查询服务器的信息。

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 服务器的当前服务版本信息的版本属性。

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 元素交互，这些元素提供了查询一个特定分类的库。此外，它还提供了查询一个用于管理远程服务器上跨库的共享资源的库的操作。

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） 的元数据。此外，其他系统元数据将用于表示关于资源的基本属性（例如，创建时间、最新修改时间、描述和标题等）。

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 所示）。

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、路径以及它相关的元数据，如标题、描述等。

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 所示）。

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、路径以及相关原元数据，如标题、描述等。

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. 服务选项

下面，我们演示如何使用服务选项来操作在一个文档请求中查询的元数据（见清单 9）。

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 属性包含了一个下载资源二进制内容的链接。

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# 语言）。本文演示了如何使用这些服务来执行基本的文档操作，同时还阐述了每个请求和响应消息的基本模式。