Oh!Coder

Coding Life

RestClient Gem简介

| Comments

今天简单了解了一个名叫REST Client的gem,一个访问HTTP和REST resource的DSL。

简介

这是一个用Ruby封装的访问HTTP和REST client的gem,其中HTTP访问动词(get, put, post, delete)的形式,受到Sinatra的架构风格影响。

当前gem的版本支持Ruby 1.9.3或者更新版本,对于早期的Ruby 1.8.7和1.9.2版本不再提供支持。rest-client自身依赖于其他三个gem:

基本使用

原生URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
require 'rest_client'

RestClient.get 'http://example.com/resource'

RestClient.get 'http://example.com/resource', {:params => {:id => 50, 'foo' => 'bar' }}

RestClient.get 'https://user:[email protected]/private/resource', {:accept => :json}

RestClient.post 'http://example.com/resource', :param1 => 'one', :nested => {:param2 => 'two'}

RestClient.post 'http://example.com/resource', { 'x' => 1 }.to_json, :content_type => :json, :accept => :json

RestClient.delete 'http://example.com/resource'

response = RestClient.get 'http://example.com/resource'
response.code
-> 200
response.cookies
-> {"Foo"=>"BAR", "QUUX"=>"QUUUUX"}
response.headers
-> {:content_type=>"text/html; charset=utf-8", :cache_control=>"private"...
response.to_str
-> \n<!DOCTYPE html PUBLIC \"-//W3C//DTD HTML 4.01//EN\"\n \"http://www.w3.org/TR/html4/strict.dtd\">\n\n<html ...

RestClient.post( url,
    {
        :transfer => {
            :path => '/foo/bar',
            :owner => 'that_guy',
            :group => 'those_guys'
        },
        :upload => {
            :file => File.new(path, 'rb')
        }
    }
)

多部件(Multipart)

使用RestClient可以完成多部件的发送。

1
RestClient.post '/data', :myfile => File.new("/path/to/image.jpg", 'rb')

上面这句代码做了两件事情:

  • 自动检测作为多部件发送的File类型对象的值
  • 自动检测文件的MIME,并在payload中将其设置到每个实体的HEAD中

如果发送的参数里不包括File对象,那么在payload中需要设置multipart:

1
RestClient.post '/data', {:foo => 'bar', :multipart => true}

ActiveResource-Style

1
2
3
4
5
resource = RestClient::Resource.new 'http://example.com/resource'
resource.get

private_resource = RestClient::Resource.new 'https://example.com/private/resource', 'user', 'pass'
private_resource.put File.read('pic.jpg'), :content_type => 'image/jpg'

关于这部分,更详细的内容可以参见相关文档。

异常(更多参见w3.org)

  • 状态码在200和207之间,RestClient::Response将会返回
  • 状态码是301,302或307的,如果请求类型是GET或HEAD,随后进行重定向
  • 状态码是303的,请求类型将会变成GET,随后进行重定向
  • 对于其他情况,RestClient::Exception将会被抛出异常;针对已知的错误代码,一个特定的异常将会被抛出
1
2
3
4
5
6
7
8
9
RestClient.get 'http://example.com/resource'
-> RestClient::ResourceNotFound: RestClient::ResourceNotFound

begin
  RestClient.get 'http://example.com/resource'
rescue => e
  e.response
end
-> 404 Resource Not Found | text/html 282 bytes

处理Result

一个block会传给RestClient方法。这个代码块随后会被Response调用。Response.return!会执行默认的response行为。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Don't raise exceptions but return the response
RestClient.get('http://example.com/resource'){|response, request, result| response}
-> 404 Resource Not Found | text/html 282 bytes

# Manage a specific error code
RestClient.get('http://my-rest-service.com/resource'){|response, request, result, &block|
  case response.code
  when 200
    p "It worked !"
    response
  when 423
    raise SomeCustomExceptionIfYouWant
  else
    response.return!(request, result, &block)
  end
}
# Follow redirections for all request types and not only for get and head
# RFC : "If the 301, 302 or 307 status code is received in response to a request other than GET or HEAD,
# the user agent MUST NOT automatically redirect the request unless it can be confirmed by the user,
# since this might change the conditions under which the request was issued."
RestClient.get('http://my-rest-service.com/resource'){|response, request, result, &block|
  if [301, 302, 307].include? response.code
    response.follow_redirection(request, result, &block)
  else
    response.return!(request, result, &block)
  end
}

非标准URI(Non-normalized URIs)

如果需要标准化URI,诸如此类。需要让国际化的资源标示(International Resource Identifiers, IRIs)正常工作,可以在代码中使用addressable gem

1
2
require 'addressable/uri'
RestClient.get(Addressable::URI.parse("http://www.詹姆斯.com/").normalize.to_str)

更低层次访问(Lower-level access)

对于一些事例,通用的API并没有覆盖到,你可以使用提供了更低层次(lower-level)API的RestClient::Request类型进行访问。

  • 使用ssl的特定参数
  • 覆盖cookies
  • 手动处理response

更多详细信息可以参照RestClient::Request的文档。

Shell

restclient shell命令提供了一个已经加载过RestClient的IRB session:

1
2
$ restclient
>> RestClient.get 'http://example.com'

为resource的访问动词 get/post/put/delete 的URL提供参数

1
2
$ restclient http://example.com
>> put '/resource', 'data'

为认证resource添加认证用户和密码:

1
2
$ restclient https://example.com user pass
>> delete '/private/resource'

为已经命名的session创建~/.restclient:

1
2
3
4
5
6
7
8
sinatra:
  url: http://localhost:4567
rack:
  url: http://localhost:9292
private_site:
  url: http://example.com
  username: user
  password: pass

然后调用:

1
restclient private_site

临时使用策略,curl书写风格(curl-style):

1
2
restclient get http://example.com/resource > ourput_body
restclient put http://example.com/resource < input_body

日志

开启日志:

  • 使用Ruby Logger设置RestClient.log,或者
  • 为了避免修改代码可以设置一个环境变量(本例中可以使用一个名为”stdout”或”stderr”的文件名):
1
$ RESTCLIENT_LOG=stdout path/to/my/program

生产环境的log如下:

1
2
3
4
RestClient.get "http://some/resource"
# => 200 OK | text/html 250 bytes
RestClient.put "http://some/resource", "payload"
# => 401 Unauthorized | application/xml 340 bytes

代理(Proxy)

对于所有调用RestClient,包括Resource的,可以使用RestClient.proxy进行设定:

1
2
3
RestClient.proxy = "http://proxy.example.com/"
RestClient.get "http://some/resource"
# => response from some/resource as proxied through proxy.example.com

通常情况下,代理的URL通过环境变量进行设置,所以可以通过下面这种方式进行设置:

1
RestClient.proxy = ENV['http_proxy']

查询参数

请求对象知道进行参数查询并自动把它们添加到GET,HEAD和DELETE的URL请求上,根据需要丢掉key和value:

1
2
RestClient.get 'http://example.com/resource', :params => {:foo => 'bar', :baz => 'qux'}
# will GET http://example.com/resource?foo=bar&baz=qux

Cookies

请求和响应对象知道HTTP的cookie,并根据需要设置或取出header:

1
2
3
4
5
6
7
8
9
10
response = RestClient.get 'http://example.com/action_which_sets_session_id'
response.cookies
# => {"_application_session_id" => "1234"}

response2 = RestClient.post(
  'http://localhost:3000/',
  {:param1 => "foo"},
  {:cookies => {:session_id => "1234"}}
)
# ...response body

SSL客户端认证

1
2
3
4
5
6
7
RestClient::Resource.new
  'https://example.com',
  :ssl_client_cert => OpenSSL::X509::Certificate.new(File.read("cert.pem")),
  :ssl_client_key  => OpenSSL::PKey::RSA.new(File.read("key.pem"), "passphrase, if any"),
  :ssl_ca_file     => "ca_certificate.pem"
  :verify_ssl      => OpenSSL::SSL::VERIFY_PEER
).get

钩子(Hook)

RestClient.add_before_execution_proc在每次调用之前会添加一个Proc。如果需要直接访问HTTP请求会很好用。

1
2
3
4
5
6
7
8
9
# Add oauth support using the oauth gem
require 'oauth'
access_token = ...

RestClient.add_before_execution_proc do |req, params|
  access_token.sign! req
end

RestClient.get 'http://example.com'

更多

需要缓存,更高级的log功能或者希望能够通过Rack middleware提供功能?可以参见rest-client-component

Comments