LWP::UserAgent - Web user agent class Web 用户agent 类:

LWPUserAgent:

LWP::UserAgent - Web user agent class   Web 用户agent 类:

概述:

 require LWP::UserAgent;

 my $ua = LWP::UserAgent->new;
 $ua->timeout(10);
 $ua->env_proxy;

 my $response = $ua->get('http://search.cpan.org/');

 if ($response->is_success) {
     print $response->decoded_content;  # or whatever
 }
 else {
     die $response->status_line;
 }

 描述:

  LWP::UserAgent 是一个类 实现一个web 用户agent.

  LWP::UserAgent 对象可以用于发送web 请求:

  在通常的使用应用创建一个 LWP::UserAgent object,然后配置它使用timeouts, proxies, name 等值。

  它可以创建一个HTTP::Request 实例用于需要被执行的请求。

  这个请求然后被传递到其中的一个请求方法, 会发出请求使用相关的协议,

  返回一个 HTTP::Response object.

  这里有最常见的方法用于发送最常用的请求类型:

  get(), head(), post(), put() and delete(). 

  当使用那些方法 然后创建的请求对象是隐藏的,如在概要中所示:

  library 的基本方法是使用HTTP类型通讯对于所有的协议计划。

  这意味着你会构建HTTP::Request  对象和接收HTTP::Response objects  甚至对于non-HTTP 资源像gopher and ftp. 

  为了完成更类似的HTTP方式的通信,gopher 菜单和文件目录是转换成HTML文件

  CONSTRUCTOR METHODS 构造方法

  下面的构造方法可用:

  $ua = LWP::UserAgent->new( %options )

 这个模块构造一个新的 LWP::UserAgent  对象和返回它。

 键值对参数可能提供额外的初始化状态,下面的选项描述:

    KEY                     DEFAULT
   -----------             --------------------
   agent                   "libwww-perl/#.###"
   from                    undef
   conn_cache              undef
   cookie_jar              undef
   default_headers         HTTP::Headers->new
   local_address           undef
   ssl_opts                { verify_hostname => 1 }
   max_size                undef
   max_redirect            7
   parse_head              1
   protocols_allowed       undef
   protocols_forbidden     undef
   requests_redirectable   ['GET', 'HEAD']
   timeout                 180

  比如:
      $self->{ua} = LWP::UserAgent->new(
        cookie_jar      =>  $self->{cookie_jar},
        agent           =>  $agent,
        timeout         =>  300,
        ssl_opts        =>  {verify_hostname => 0},
    );

	下面额外的选项也被接收:如果env_proxy 选项是被传入一个TRUE 值,

  proxy 设置是从环境变量读取(查看 env_proxy() method below). 

  如果env_proxy 没有提供PERL_LWP_ENV_PROXY环境变量控制如果 env_proxy()  是被调用在初始化期间。

  如果keep_alive选项是传入的,那么 一个LWP::ConnCache  是被设置(查看 conn_cache() method below). 

  keep_alive 值被传入作为total_capacity 对于连接缓存

  ATTRIBUTES  属性:

  配置属性的设置修改LWP::UserAgent 的行为 当它发送请求时。

  那些大多数可以通过选项被初始化传递到构造方法。

  下面的属性方法被提供, 属性值是保持不变的 如果参数没有给定,

  每个方法的返回值是老的属性值

  $ua->agent
  $ua->agent( $product_id )

  获取/设置 product token 用于标识用户agent 在网络上。

  agent是是发送作为"User-Agent" header  在请求里.

  默认是_agent() method 返回的

  如果  $product_id以空格借宿 那么 _agent() string 会追加到它。

  user agent 字符串应该是一个或者多个简单的产品描述 

   $ua->agent('Checkbot/0.4 ' . $ua->_agent);
  $ua->agent('Checkbot/0.4 ');    # same as above
  $ua->agent('Mozilla/5.0');
  $ua->agent("");                 # don't identify

  $ua->_agent:

返回默认的agent identifier. 这是一个ibwww-perl/#.###"的字符串,

"#.###" 是用于libary 的版本替代  

[root@wx03 ~]# cat a18.pl
use LWP::UserAgent;
my $ua = LWP::UserAgent->new;
print $ua->_agent;
[root@wx03 ~]# perl a18.pl
libwww-perl/6.15[root@wx03 ~]# 

 $ua->from

 $ua->from( $email_address )

 Get/set e-mail address 对于用户控制请求的user agent.

 地址应该是machine-usable, 

  $ua->from('gaas@cpan.org');

  默认是不发送一个"Form" header,查看default_headers()  方法对于更多的普通的接口,允许任何header 为默认

$ua->cookie_jar
$ua->cookie_jar( $cookie_jar_obj )

Get/set cookie jar 对象来使用, 唯一的请求是cookie jar object 必须实现 extract_cookies($response) and add_cookie_header($request) methods. 

那些模块会然后被调用通过 user agent as requests 被发送和响应被接收。

通常这个会是一个HTTP::Cookies  对象或者一些子类

默认是没有cookie_jar, 不会自动增加"Cookie" headers  到请求里。

快捷: 如果一个引用到一个普通的hash 是被传递作为 $cookie_jar_object, 

然后它会被一个HTTP::Cookies实例替换, 这个是基于hash 初始化。

这种形式会自动加载 HTTP::Cookies module.  它意味着:

 $ua->cookie_jar({ file => "$ENV{HOME}/.cookies.txt" });

 cookie 信息:
  HTTP::Cookies=HASH(0x2c4776c)$VAR1 = bless( {
                 'ignore_discard' => 1,
                 'autosave' => 1,
                 'COOKIES' => {
                                '121.52.220.246' => {
                                                      '/' => {
                                                               'ASP.NET_SessionId' => [
                                                                                        '0',
                                                                                        'yh5lhl45l3scy0jblotcy545',
                                                                                        undef,
                                                                                        1,
                                                                                        '',
                                                                                        undef,
                                                                                        1,
                                                                                        {
                                                                                          'HttpOnly' => undef
                                                                                        }
                                                                                      ]
                                                             }
                                                    },
                                'wenjinbao.winfae.com' => {
                                                            '/' => {
                                                                     'ZJZCJSESSIONID' => [
                                                                                           '0',
                                                                                           '4441b56a-55f0-4c9d-ac0e-4767558dfa3b',
                                                                                           undef,
                                                                                           1,
                                                                                           1,
                                                                                           undef,
                                                                                           1,
                                                                                           {
                                                                                             'HttpOnly' => undef
                                                                                           }
                                                                                         ]
                                                                   }
                                                          }
                              },
                 'file' => 'lwp_cookies.txt'
               }, 'HTTP::Cookies' );

  #LWP-Cookies-1.0
Set-Cookie3: ASP.NET_SessionId=yh5lhl45l3scy0jblotcy545; path="/"; domain=121.52.220.246; path_spec; discard; HttpOnly; version=0
Set-Cookie3: ZJZCJSESSIONID=4441b56a-55f0-4c9d-ac0e-4767558dfa3b; path="/"; domain=wenjinbao.winfae.com; path_spec; secure; discard; HttpOnly; version=0

$ua->default_headers
$ua->default_headers( $headers_obj )

获取/设置 headers 对象会提供默认的header 值对于任何请求的发送 ,默认是一个空的 HTTP::Headers object.  

  [root@wx03 ~]# cat a18.pl
use LWP::UserAgent;
 use Data::Dumper;
my $ua = LWP::UserAgent->new;
print $ua->_agent;
print "\n";
print $ua->from;
print "\n";
print Dumper($ua->default_headers);
print "\n";
[root@wx03 ~]# perl a18.pl
libwww-perl/6.15

$VAR1 = bless( {
                 'user-agent' => 'libwww-perl/6.15'
               }, 'HTTP::Headers' );

[root@wx03 ~]# 

$ua->default_header( $field )
$ua->default_header( $field => $value )
This is just a short-cut for $ua->default_headers->header( $field => $value ). Example:

这个只是一个short-cut  对于 $ua->default_headers->header( $field => $value ). Example:

[root@wx03 ~]# cat a18.pl
use LWP::UserAgent;
 use Data::Dumper;
my $ua = LWP::UserAgent->new;
print $ua->_agent;
print "\n";
print $ua->from;
print "\n";
print Dumper($ua->default_headers);
print "\n";
  $ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
  $ua->default_header('Accept-Language' => "no, en");
print Dumper($ua->default_headers);
print "\n";
[root@wx03 ~]# perl a18.pl
libwww-perl/6.15

$VAR1 = bless( {
                 'user-agent' => 'libwww-perl/6.15'
               }, 'HTTP::Headers' );

$VAR1 = bless( {
                 'accept-language' => 'no, en',
                 'user-agent' => 'libwww-perl/6.15',
                 'accept-encoding' => 'gzip, x-gzip, deflate, x-bzip2'
               }, 'HTTP::Headers' );

$ua->conn_cache
$ua->conn_cache( $cache_obj )

 Get/set LWP::ConnCache  对象来使用  查看LWP::ConnCache 更多的细节:

 Handlers 处理程序:

 handlers 是编码注入到请求的各个阶段在请求处理期间,下面的方式是提供管理活动的handlers：

 $ua->add_handler( $phase => \&cb, %matchspec )

  Add handler 被调用在给定的处理阶段,如何制定%matchspec 查看 "Matching" in HTTP::Config.

 可能的值$phase 和响应的回调签名是:

 request_preprepare => sub { my($request, $ua, $h) = @_; ... }

  handler 是被调用在request_prepare 前和其他请求的标准初始化。

  这个可以用于设置headers 和request_prepare handler 依赖的属性。

  Proxy 初始化应该立即发生,但是通常不会在这个阶段注册handlers.

  REQUEST METHODS  请求方法:

  方法描述在这个章节是用于发送请求通过user agent 下面请求方法提供:

  $ua->get( $url )
$ua->get( $url , $field_name => $value, ... )

  这种方法会发出一个GET请求在给定的$url,进一步的参数可以给定来初始化请求的headers.

  有单独的给定的 name/value pairs.

  返回的值 是一个响应对象,查看HTTP::Response  对于一个接口的描述

  仍旧会有响应对象返回当LWP不能连接到server 通过指定的URL或者其他失败在协议handlers 发生。

  那些内部的响应使用标准的HTTP 状态代码, 因此响应不能单独的通过测试响应状态码来区分。

  错误的响应 LWP 内部产生会有"Client-Warning"  header 设置值  "Internal response". 

  如果你需要区分那些内部响应来自远端服务器实际产生的响应,你需要测试这个请求头值:

  字段名字以.开始是特定的,那些没有初始化的请求headers

但是会决定如何处理响应内容 下面得到字段是被识别的:

  :content_file   => $filename
    :content_cb     => \&callback
    :read_size_hint => $bytes