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 "
";
print $ua->from;
print "
";
print Dumper($ua->default_headers);
print "
";
[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 "
";
print $ua->from;
print "
";
print Dumper($ua->default_headers);
print "
";
$ua->default_header('Accept-Encoding' => scalar HTTP::Message::decodable());
$ua->default_header('Accept-Language' => "no, en");
print Dumper($ua->default_headers);
print "
";
[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