方法信息（对数据采取什么操作的信息）

方法信息

Method Information

HTTP是Programmable Web上的所有服务所共有的。而Web服务之间差别的形成，是因为它们在两个问题上的做法有所不同。只要了解一个Web服务是如何处理这两个问题的，就可以清楚地知道该服务是否跟Web的理念保持一致。

第一个问题是：客户端如何把自己的意图传达给服务器。服务器怎么知道该请求是要获取数据、删除数据，还是改写数据呢？服务器为什么要做这个操作，而不是做那个操作呢？

这种关于对数据采取什么操作的信息，称之为方法信息（method information）。要在Web服务里传达方法信息，一种方式是把它放在HTTP方法（HTTP method）里——这是REST式Web服务（RESTful Web Services）的做法，后面还会详细讲述。现在，请记住五种最常见的HTTP方法是GET、HEAD、PUT、DELETE和POST。通过它们足以分辨“获取数据”（GET）、“删除数据”（DELETE）及“改写数据”（PUT）。

HTTP方法具有标准化的名称，这是一个很好的优点。当然，跟编程语言的方法名称相比，HTTP方法的名称要少得多。有些Web服务喜欢在HTTP请求里的其他地方（比如URI路径或请求文档里，而不在HTTP方法里）寻找针对特定应用的方法名称。

示例1-7就是一个把方法信息放在URI路径（path）里的Web服务客户端的例子。该客户端调用的是用于在线照片分享的Flickr Web服务，它将搜索Flickr上的照片。要运行本程序，你得先申请一个Flickr账户，并申请API key（http://www.flickr.com/services/api/keys/ apply/）。

示例1-7：搜索Flickr上的照片

#!/usr/bin/ruby -w
# flickr-photo-search.rb
require 'open-uri'
require 'rexml/document'

# 返回指向一个小尺寸的Flickr照片的URI
def small_photo_uri(photo)
server = photo.attribute('server')
id = photo.attribute('id')
secret = photo.attribute('secret')
return "http://static.flickr.com/#{server}/#{id}_#{secret}_m.jpg"
end

# 在Flickr上搜索与给定tag相匹配的所有照片，并打印出照片的URI。
# 对于每一个搜索结果
def print_each_photo(api_key, tag)
# 构造URI
uri = "http://www.flickr.com/services/rest?method=flickr.photos.search" +

"&api_key=#{api_key}&tags=#{tag}"

# 发出HTTP请求，获取实体主体 
response = open(uri).read

# 把实体主体作为XML文档来解析 
doc = REXML::Document.new(response)

# 对于每个找到的照片… 
REXML::XPath.each(doc, '//photo') do |photo|
# …生成URI，并打印出来
puts small_photo_uri(photo) if photo
end
end

# 主程序
if ARGV.size < 2
puts "Usage: #{$0} [Flickr API key] [search term]"
exit
end

api_key, tag = ARGV
print_each_photo(api_key, tag)

XPath介绍

XPath是一个特定领域的语言。利用它，不用写许多代码就能对XML文档进行切分。它有许多令人望而却步的特性，不过你只要掌握少许知识就明白怎么用了。关键一点是：把XPath表达式看成一种从XML文档里提取标签（tags）或元素（elements）的规则。本书中出现XPath表达式不会很多，我会在每次使用时加以解释。

要知道一个XPath表达式是什么意思，只要从右往左读就行了。比如，表达式//photo的意思是：

寻找所有photo标签       photo

无论它在文档里出现在何处      //
用REXML::XPath.each(doc, '//photo') 这行简单的Ruby代码可以实现遍历每一个photo标签（tag），而不必遍历整个XML树。

该程序向http://www.flickr.com/services/rest?method=flickr.photos.search&api_key=xxx&tag= penguin这个（或类似）URI发出HTTP请求。那么服务器是怎么知道客户端想要做什么的呢？嗯，URI表明方法名称是flickr.photos.search；不过为什么HTTP方法（HTTP method）是GET呢？嗯，我确实是要获取（get）信息，所以，没准HTTP方法里的才是真正的方法信息。

不过这一假设不是总能成立。因为Flickr API除了“获取（GET）”型方法（比如flickr. photos.search和flickr.people.findByEmail）以外，还支持很多其他方法（比如flickr.photos.addTags和flickr.photos.comments.deleteComment等），而所有这些方法，无论它们是否真的“获取（GET）”数据，都是通过GET请求来调用的。可见，Flickr把真正的方法信息放在查询变量（query variable）method里，并希望客户端忽略HTTP方法（HTTP method）。

相比之下，SOAP服务一般是把方法信息放在实体主体（entity-body）和HTTP报头（HTTP header）里的。示例1-8是一段Ruby脚本，它用Google SOAP API来搜索Web。

示例1-8：用Google的搜索服务来搜索Web

#!/usr/bin/ruby -w
# google-search.rb
require 'soap/wsdlDriver'

# 做一次Google搜索，并把各个搜索结果打印出来
def print_page_titles(license_key, query)
wsdl_uri = 'http://api.google.com/GoogleSearch.wsdl'
driver = SOAP::WSDLDriverFactory.new(wsdl_uri).create_rpc_driver 
result_set = driver.doGoogleSearch(license_key, query, 0, 10, true, ' ',
false, ' ', ' ', ' ')
result_set.resultElements.each { |result| puts result.title }
end

# 主程序 
if ARGV.size < 2
puts "Usage: #{$0} [Google license key] [query]"
exit
end

license_key, query = ARGV
print_page_titles(license_key, query)

提示：正当我在写这本书时，Google宣布弃用SOAP搜索服务，转而建议采用一种REST式、面向资源的服务（不过，它在使用上要受到条款限制，而SOAP版服务没有这一限制）。因为Google的SOAP服务是我所知道的最好的例子，而且我也相信你不会实际去运行这个程序，所以就没修改这个例子了。你只要看一下这段代码及相关的SOAP和WSDL文档就好了。

嗯，也许从这段代码中看不出什么，因为WSDL库（WSDL library）已经隐蔽了大部分细节。实际的细节是这样的：当调用doGoogleSearch方法时，WSDL库会向位于http://api. google.com/search/beta2的Google SOAP服务“端点（endpoint）”发出一个POST请求。所有对Google SOAP API的调用都采用这个URI，而且HTTP方法（HTTP method）总是POST。 所有这些细节（比如doGoogleSearch的定义）都是在WSDL文档（参见http://api.google.

com/GoogleSearch.wsdl）里定义的，示例1-9给出了定义doGoogleSearch的片断。

示例1-9：Google搜索服务的WSDL文档片断

由于每次调用都采用同一个URI和相同的HTTP方法（HTTP method），所以方法信息（比如这里的“doGoogleSearch”）无法放在URI或者HTTP方法里，而只能放在POST请求的实体主体（entity-body）里。示例1-10显示了一个用于搜索“REST”的HTTP请求。

示例1-10：一个作SOAP RPC调用的HTTP请求

POST search/beta2 HTTP/1.1
Host: api.google.com
Content-Type: application/soap+xml
SOAPAction: urn:GoogleSearchAction

http://schemas.xmlsoap.org/soap/envelope/">


REST
...

这里的方法信息是“doGoogleSearch”。我们注意到，上述SOAP信封（Envelope）里有一个XML标签（tag）的名称是 doGoogleSearch，它跟示例1-9所示WSDL文档里的那个操作（operation）名称相同，跟示例1-8所示Ruby脚本里的一个方法名称也相同，而且跟HTTP请求报头里的SOAPAction值也相同（有些SOAP实现，会在HTTP请求报头，而不是实体主体里寻找方法信息）。

看过Google SOAP API的例子之后，让我们言归正传，现在来看一下Google搜索引擎本身。要用浏览器在Google上搜索“REST”，你要向http://www.google.com/search?q=REST发送GET请求，然后你会得到一个HTML响应。这里，方法信息是放在HTTP方法里的：你在获取（GET）搜索结果列表。