Python 研究(Dive Into Python)

lastwinner

第 12 章 SOAP Web 服务
12.1. 概览
12.2. 安装 SOAP 库
12.2.1. 安装 PyXML
12.2.2. 安装 fpconst
12.2.3. 安装 SOAPpy
12.3. 步入 SOAP
12.4. SOAP 网络服务查错
12.5. WSDL 介绍
12.6. 以 WSDL 进行 SOAP 内省
12.7. 搜索 Google
12.8. SOAP 网络服务故障排除
12.9. 小结
第 11 章 关注 HTTP 上面向文档的web 服务。 “输入参数” 是 URL, “返回值” 是需要你来解析的一个实际的 XML 文档。

本章将关注更加结构化地 SOAP web 服务。 SOAP 不需要你直接与 HTTP 请求和 XML 文档打交道，而是允许你模拟返回原始数据类型的函数调用。 正像你将要看到的，这个描述恰如其份；你可以使用标准 Python 调用语法通过 SOAP 库去调用一个函数，这个函数也自然会返回 Python 对象和值。 但解开这层面纱， SOAP 库实际上扮演了一个多 XML 文档和远程服务器参与的复杂处理过程。

SOAP 的贴切定义很复杂，不要误认为 SOAP 就是用于调用远程函数。有些人觉得应该补充上： SOAP 还允许单向异步的信息通过，并且是面向文档的 Web 服务。 有这样想法的人是正确的，SOAP 的确是这样，但却不止于此。但这一章的重点在于所谓的 “RPC-style” SOAP —— 调用远程函数获得返回结果。

lastwinner

12.1. 概览
你用 Google, 对吧? 它是一个很流行的搜索引擎。 你是否曾经希望能以程序化的方式访问 Google 的搜索结果呢? 现在你能做到了。 下面是一个用 Python 搜索 Google 的程序。

例 12.1. search.py
from SOAPpy import WSDL

# you'll need to configure these two values;
# see http://www.google.com/apis/
WSDLFILE = '/path/to/copy/of/GoogleSearch.wsdl'
APIKEY = 'YOUR_GOOGLE_API_KEY'

_server = WSDL.Proxy(WSDLFILE)
def search(q):
    """Search Google and return list of {title, link, description}"""
    results = _server.doGoogleSearch(
        APIKEY, q, 0, 10, False, "", False, "", "utf-8", "utf-8"
    return [{"title": r.title.encode("utf-8",
             "link": r.URL.encode("utf-8",
             "description": r.snippet.encode("utf-8"}
            for r in results.resultElements]

if __name__ == '__main__':
    import sys
    for r in search(sys.argv[1])[:5]:
        print r['title']
        print r['link']
        print r['description']
        print你可以在较大的程序中以模块导入并使用它, 也可以在命令行上运行这个脚本。在命令行上, 需要把查询字符串作为命令行参数使用, 之后就会打印出最前面的五个 Google 查询结果，包括： URL, 标题和描述信息。

下面是以 “python” 作为命令行参数的查询结果。

例 12.2. search.py 的使用样例
C:\diveintopython\common\py> python search.py "python"
<b>Python</b> Programming Language
http://www.python.org/
Home page for <b>Python</b>, an interpreted, interactive, object-oriented,
extensible<br> programming language. <b>...</b> <b>Python</b>
is OSI Certified Open Source: OSI Certified.

<b>Python</b> Documentation Index
http://www.python.org/doc/
<b>...</b> New-style classes (aka descrintro). Regular expressions. Database
API. Email Us.<br> docs@<b>python</b>.org. (c) 2004. <b>Python</b>
Software Foundation. <b>Python</b> Documentation. <b>...</b>

Download <b>Python</b> Software
http://www.python.org/download/
Download Standard <b>Python</b> Software. <b>Python</b> 2.3.3 is the
current production<br> version of <b>Python</b>. <b>...</b>
<b>Python</b> is OSI Certified Open Source:

Pythonline
http://www.pythonline.com/


Dive Into <b>Python</b>
http://diveintopython.org/
Dive Into <b>Python</b>. <b>Python</b> from novice to pro. Find:
<b>...</b> It is also available in multiple<br> languages. Read
Dive Into <b>Python</b>. This book is still being written. <b>...</b>

lastwinner

进一步阅读

• http://www.xmethods.net/ 是一个访问 SOAP web 服务的公共知识库。
• SOAP 说明书 对于 SOAP 相关的问题讨论非常易读。

lastwinner

12.2. 安装 SOAP 库
12.2.1. 安装 PyXML
12.2.2. 安装 fpconst
12.2.3. 安装 SOAPpy
与本书中的其他代码不同, 本章依赖的库不是 Python 预安装的。

在深入学习 SOAP web 服务之前, 你需要安装三个库: PyXML, fpconst 和 SOAPpy。

12.2.1. 安装 PyXML
你所要用到的第一个库是 PyXML，是 XML库的一个高级组件，这个库提供了比我们在 第 9 章 学习的 XML 内建库提供更多的功能。

过程 12.1.
下面是安装 PyXML 的步骤：

访问 http://pyxml.sourceforge.net/， 点击 Downloads， 下载适合你所使用操作系统的最新版本。

如果你所使用的是 Windows，那么你有多个选择。一定要确保你所下载的 PyXML 和你所使用的 Python 版本匹配。

双击安装程序。如果你下载的是为 Windows 提供的 PyXML 0.8.3 ，并且你所使用的是 Python 2.3，这个安装程序应该是 PyXML-0.8.3.win32-py2.3.exe.

深入安装过程

安装完成后，关闭安装程序，没有任何安装成功的昭示（并没有在开始菜单、快捷栏或桌面出现图标）。因为 PyXML 仅仅是被其他程序调用的 XML 的库集合。

希望检验 PyXML 安装的是否正确，可以运行 Python IDE ，下面的指令可以看到 XML 库的安装版本。

例 12.3. 检验 PyXML 安装
>>> import xml
>>> xml.__version__
'0.8.3'
这个安装版本号应该和你所下载并安装的 PyXML 安装程序版本号一致。

lastwinner

12.2.2. 安装 fpconst
你所需要安装的第二个库是 fpconst，使一系列支持 IEEE754 double-precision 特殊值得常量和函数。提供了对 Not-a-Number (NaN), Positive Infinity (Inf) 和 Negative Infinity (-Inf) 等特殊值得支持，这是 SOAP 数据类型规范的组成部分。

过程 12.2.
下面是 fpconst 的安装过程

从 http://www.analytics.washington. ... ects/rzope/fpconst/ 下载 fpconst 的最新版本。

提供了两种格式的下载： .tar.gz 和 .zip。如果你使用的是 Windows 操作系统，下载 .zip 文件；其他情况下应该下载 .tar.gz 文件。

对这个文件进行解压缩。在 Windows XP 上你可以鼠标右键单击这个文件并选择“解压文件”；在较早的 Windows 版本上则需要 WinZip 之类的第三方解压程序。在 Mac OS X 上，可以右键单击压缩文件进行解压。

打开命令提示符窗口并定位到解压目录。

键入 python setup.py install 运行安装程序。

希望检验 fpconst 安装的是否正确， 运行 Python IDE 并查看版本号。

例 12.4. 检验 fpconst 安装
>>> import fpconst
>>> fpconst.__version__
'0.6.0'
这个安装版本号应该和你所下载并用于安装的 fpconst 压缩包版本号一致。

lastwinner

12.2.3. 安装 SOAPpy
第三个，也是最后一个需要安装的库是 SOAP 库本身： SOAPpy。

过程 12.3.
下面是安装 SOAPpy的过程

访问 http://pywebsvcs.sourceforge.net/ 并选择 SOAPpy 部分中最新的官方发布。

提供了两种格式的下载。如果你使用的是 Windows，那么下载 .zip 文件；其他情况则下载 .tar.gz 文件。

和安装 fpconst 时一样先解压下载的文件．

打开名利提示符窗口并定位到解压 SOAPpy 文件的目录。

键入 python setup.py install 运行安装程序。

希望检验 SOAPpy 安装的是否正确， 运行 Python IDE 并查看版本号。

例 12.5. 检验 SOAPpy 安装
>>> import SOAPpy
>>> SOAPpy.__version__
'0.11.4'
这个安装版本号应该和你所下载并用于安装的 SOAPpy 压缩包版本号一致。

lastwinner

12.3. 步入 SOAP
调用远程函数是 SOAP 的核心功能。有很多提供公开 SOAP 访问的服务器提供用于展示的简单功能。

最受欢迎的 SOAP 公开访问服务器是 http://www.xmethods.net/。这个例子使用了一个展示函数，可以根据美国邮政编码返回当地气温。

例 12.6. 获得现在的气温
>>> from SOAPpy import SOAPProxy            
>>> url = 'http://services.xmethods.net:80/soap/servlet/rpcrouter'
>>> namespace = 'urn:xmethods-Temperature'  
>>> server = SOAPProxy(url, namespace)      
>>> server.getTemp('27502')                 
80.0
  你通过 SOAPProxy 这个 proxy 类访问远程 SOAP 服务器。这个 proxy 处理了所有的 SOAP 内部事务，其中包括：根据函数名和参数列表创建 XML 请求文档并将这个请求文档通过 HTTP 发送到远程 SOAP 服务器，解析 XML 返回文档并创建 Python 原始返回值。在下一节中你将看到这个 XML 文档。
  每个 SOAP 服务都有一个 URL 用以处理所有请求。 相同的 URL 可以用于所有的函数请求。每个特定服务则只有一个函数。但稍后你将看到的 Google API 却有多个函数。这个服务的 URL 提供给所有函数分享。每个 SOAP 服务都有一个命名空间（namespace），这个命名空间是由服务器任意命名的。这不过是为了调用 SOAP 方法而设置的。它使得服务器为多个不相关的服务提供服务 URL 和路径请求共享成为可能。这与 Python 中模块到 packages 的关系类似。
  这里你创建了包含服务 URL 和服务命名空间的 SOAPProxy。这与 SOAP 服务器无关，仅仅是建立了一个本地 Python 对象。
  到此为止，如果你的设置完全正确，应该可以向调用本地函数一样调用远程 SOAP 方法。像给普通函数传递参数并接收返回一样，但在这背后却隐藏着很多的工作。

让我们看一看这些背后的工作。

lastwinner

12.4.  SOAP 网络服务查错
SOAP 提供了一个很方便的方法用以查看背后的情形。

SOAPProxy 的两个小设置就可以打开查错模式。

例 12.7.  SOAP 网络服务查错
>>> from SOAPpy import SOAPProxy
>>> url = 'http://services.xmethods.net:80/soap/servlet/rpcrouter'
>>> n = 'urn:xmethods-Temperature'
>>> server = SOAPProxy(url, namespace=n)     
>>> server.config.dumpSOAPOut = 1            
>>> server.config.dumpSOAPIn = 1
>>> temperature = server.getTemp('27502')   
*** Outgoing SOAP ******************************************************
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
  xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance"
  xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsd="http://www.w3.org/1999/XMLSchema">
<SOAP-ENV:Body>
<ns1:getTemp xmlns:ns1="urn:xmethods-Temperature" SOAP-ENC:root="1">
<v1 xsi:type="xsd:string">27502</v1>
</ns1:getTemp>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
************************************************************************
*** Incoming SOAP ******************************************************
<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<SOAP-ENV:Body>
<ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature"
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<return xsi:type="xsd:float">80.0</return>
</ns1:getTempResponse>

</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
************************************************************************

>>> temperature
80.0
  首先，正常建立带有服务 URL 和命名空间的 SOAPProxy。
  然后，通过设置 server.config.dumpSOAPIn 和 server.config.dumpSOAPOut 打开查错模式。
  最后，正常调用远程 SOAP 方法。SOAP 库将会输出送出的 XML 请求文档和收到的 XML 返回文档。这是 SOAPProxy 为你做的所有工作。 有点恐怖，不是吗？让我们来分析一下。

大部分 XML 请求文档都基于模板文件。 忽略所有命名空间声明这些对于所有 SOAP 调用都一成不变的东西。这个 “函数调用” 的核心是<Body> 当中的部分：

<ns1:getTemp                                 
  xmlns:ns1="urn:xmethods-Temperature"      
  SOAP-ENC:root="1">
<v1 xsi:type="xsd:string">27502</v1>         
</ns1:getTemp>
  这个元素名 getTemp 就是函数名。SOAPProxy 把 getattr 当作一个发报机。有别使用方法名分别调用本地方法，这里使用方法名构造了一个 XML 请求文档。
  函数的 XML 元素被存储于一个特别的命名空间，这个命名空间就是你在建立 SOAPProxy 对象时所指定的那个命名空间。也不必为 SOAP-ENC:root 而苦恼，因为它也是基于模板文件的。
  函数的参数也被记入 XML 文档。 SOAPProxy 查看并确定每个参数的数据类型（这里是 string 字符串类型）。参数的数据类型记入 xsi:type 属性，并在其后记入实际的字符串值。

返回的 XML 文档同样容易理解，重点在于知道应该忽略掉哪些内容。把注意力集中在 <Body> 部分：

<ns1:getTempResponse                             
  xmlns:ns1="urn:xmethods-Temperature"           
  SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<return xsi:type="xsd:float">80.0</return>      
</ns1:getTempResponse>
  服务器传回的值记录在 <getTempResponse> 部分的几行中。 通常包括函数名和回应 （Response）。当然其他的内容也可能出现在这里，但 SOAPProxy 所重视的不是这里的元素名，而是命名空间。
  服务器返回时所使用的命名空间就是在请求时所用的命名空间，也就是在创建 SOAPProxy 对象时所指定的命名空间。本章稍后的部分中，我们将看到在创建 SOAPProxy 对象时忘记指定功能名空间会怎样。
  这是返回值和它的数据类型（浮点类型 float）。 SOAPProxy 使用显性数据类型创建一个原始数据类型的 Python 对象并返回之。

lastwinner

12.5. WSDL 介绍
SOAPProxy 类本地方法调用并透明地转向到远程 SOAP 方法。 正如你所看到的，这是很多的工作，SOAPProxy 快速和透明地完成他们。它没有做到的是提供任何方法自省的手段。
试想一下：前面两部分所展现的调用只有一个参数和返回的简单远程 SOAP 方法。服务 URL 和一系列参数及它们的数据类型需要被知道并跟踪。任何的缺失或错误都会导致整体的失败。
这并没有什么可惊讶的。如果我要调用一个本地函数，我需要知道函数所在的包和模块名（与之对应的则是服务 URL 和命名空间）。我还需要知道正确的函数名以及其函数个数。 Python 精妙地在不需要明示类型，但我还是需要知道有多少个参数需要传递，多少个值将被返回。
最大的区别就在于内省。 就像你在 第 4 章 看到的那样， Python 擅长于让你实时地去探索模块和函数的情况。你可以对一个模块中的所有函数进行列表，并不费吹灰之力地明了函数的声明和参数情况。
WSDL 允许你对 SOAP 网络服务做相同的事情。 WSDL 是 “网络服务描述语言（Web Services Description Language）”的缩写。 尽管是为自如地表述多种类型的网络服务而设定，却也经常用于描述 SOAP 网络服务。
一个 WSDL 文件不过就是一个文件。 更具体地讲，是一个 XML 文件。通常存储于你所访问的 SOAP 网络服务这个被描述对象所在的服务器上，并没有什么特殊之处。 在本章稍后的位置，我们将下载 Google API 的 WSDL 文件并在本地使用它。 这并不意味着本地调用 Google， 这个 WSDL 文件所描述的仍旧是 Google 服务器上的远程函数。
在 WSDL 文件中描述了调用相应的 SOAP 网络服务的一切：

• 服务 URL 和命名空间
• 网络服务的类型（可能还包括 SOAP 的函数调用，正像我所说过的，WSDL 足够自如地去描述网络服务的广泛内容）
• 有效函数列表
• 每个函数的参数
• 每个参数的类型
• 每个函数的返回值及其数据类型

换言之，一个 WSDL 文件告诉你调用 SOAP 所需要知道的一切。

lastwinner

12.6. 以 WSDL 进行 SOAP 内省
就像网络服务舞台上的所有事物， WSDL 也经历了一个充满明争暗斗而且漫长多变的历史。 我不打算讲述这段令我伤心的历史。 还有一些其他的标准提供相同的支持，但 WSDL 还是胜出，所以我们还是来学习一下如何使用它。

WSDL 最基本的功能便是让你揭示 SOAP 服务器所提供的有效方法。

例 12.8. 揭示有效方法
>>> from SOAPpy import WSDL         
>>> wsdlFile = 'http://www.xmethods.net/sd/2001/TemperatureService.wsdl')
>>> server = WSDL.Proxy(wsdlFile)   
>>> server.methods.keys()            
[u'getTemp']
  SOAPpy 包含一个 WSDL 解析器。 在本书写作之时，它被标示为开发的初级阶段，但我从来没有在解析任何 WSDL 文件时遇到问题。
  使用一个 WSDL 文件，你还是要用到一个 proxy 类：WSDL.Proxy，它只需一个参数： WSDL 文件。 我所说的是把存储在远程服务器上的 WSDL 的 URL， 但是这个 proxy 类对于本地的 WSDL 副本工作同样出色。创建 WSDL proxy 将会下载 WSDL 文件并解析它， 所以如果 WSDL 文件有任何问题（或者由于网络问题不能获得）你会立刻知道。
  WSDL proxy 类以 Python 字典 server.methods 的方式揭示有效函数。所以列表有效方法就像调用字典方法 keys() 一样简单。

好的，你知道这个 SOAP 服务器提供一个方法： getTemp。但是如何去调用它呢？ WSDL 也在这方面提供信息。

例 12.9. 揭示一个方法的参数
>>> callInfo = server.methods['getTemp']  
>>> callInfo.inparams                     
[<SOAPpy.wstools.WSDLTools.ParameterInfo instance at 0x00CF3AD0>]
>>> callInfo.inparams[0].name            
u'zipcode'
>>> callInfo.inparams[0].type            
(u'http://www.w3.org/2001/XMLSchema', u'string')
  server.methods 字典中记录一个 SOAPpy 的特别结构，被称为 CallInfo。 CallInfo 对象中包含着特定函数和函数参数的信息。
  函数参数信息存储在 callInfo.inparams 中，这是一个记录每一个参数信息的 ParameterInfo 对象的 Python 列表。
  每个 ParameterInfo 对象包含一个 name 属性，这便是参数名。再通过 SOAP 调用函数时，你不需要知道参数名，但 SOAP 却支持在调用函数时使用参数名的情形（类似于 Python ）。如果使用参数名， WSDL.Proxy 将会正确地把这些参数关联到远程函数。
  每个参数都是都是显性类型的，在 XML Schema 中以数据类型定义。你可以在上一节中发现这一点：XML Schema 命名空间是我让你忽略的模版的一部分。就目前而言，你还是可以继续忽略它。 zipcode 参数是一个字符串，如果你向 WSDL.Proxy 对象传递一个 Python 字符串，它会被正确地关联和传递到服务器。

WSDL 还允许你自省函数的返回值。