337 lines
8.6 KiB
HTML
337 lines
8.6 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of HTTP::Request</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>HTTP::Request</H1>
|
|
Section: User Contributed Perl Documentation (3pm)<BR>Updated: 2020-02-29<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
HTTP::Request - HTTP style request message
|
|
<A NAME="lbAC"> </A>
|
|
<H2>VERSION</H2>
|
|
|
|
|
|
|
|
version 6.22
|
|
<A NAME="lbAD"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
|
|
|
|
|
|
|
|
<PRE>
|
|
require HTTP::Request;
|
|
$request = HTTP::Request->new(GET => '<A HREF="http://www.example.com/');">http://www.example.com/');</A>
|
|
|
|
</PRE>
|
|
|
|
|
|
<P>
|
|
|
|
and usually used like this:
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
$ua = LWP::UserAgent->new;
|
|
$response = $ua->request($request);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
|
|
|
|
<TT>"HTTP::Request"</TT> is a class encapsulating <FONT SIZE="-1">HTTP</FONT> style requests,
|
|
consisting of a request line, some headers, and a content body. Note
|
|
that the <FONT SIZE="-1">LWP</FONT> library uses <FONT SIZE="-1">HTTP</FONT> style requests even for non-HTTP
|
|
protocols. Instances of this class are usually passed to the
|
|
<B>request()</B> method of an <TT>"LWP::UserAgent"</TT> object.
|
|
<P>
|
|
|
|
<TT>"HTTP::Request"</TT> is a subclass of <TT>"HTTP::Message"</TT> and therefore
|
|
inherits its methods. The following additional methods are available:
|
|
<DL COMPACT>
|
|
<DT id="1">$r = HTTP::Request->new( $method, $uri )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="2">$r = HTTP::Request->new( $method, $uri, $header )<DD>
|
|
|
|
|
|
|
|
|
|
<DT id="3">$r = HTTP::Request->new( $method, $uri, $header, $content )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Constructs a new <TT>"HTTP::Request"</TT> object describing a request on the
|
|
object <TT>$uri</TT> using method <TT>$method</TT>. The <TT>$method</TT> argument must be a
|
|
string. The <TT>$uri</TT> argument can be either a string, or a reference to a
|
|
<TT>"URI"</TT> object. The optional <TT>$header</TT> argument should be a reference to
|
|
an <TT>"HTTP::Headers"</TT> object or a plain array reference of key/value
|
|
pairs. The optional <TT>$content</TT> argument should be a string of bytes.
|
|
<DT id="4">$r = HTTP::Request->parse( $str )<DD>
|
|
|
|
|
|
|
|
|
|
This constructs a new request object by parsing the given string.
|
|
<DT id="5">$r->method<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="6">$r->method( $val )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the method attribute. The method should be a
|
|
short string like ``<FONT SIZE="-1">GET'', ``HEAD'', ``PUT'', ``PATCH''</FONT> or ``<FONT SIZE="-1">POST''.</FONT>
|
|
<DT id="7">$r->uri<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="8">$r->uri( $val )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the uri attribute. The <TT>$val</TT> can be a
|
|
reference to a <FONT SIZE="-1">URI</FONT> object or a plain string. If a string is given,
|
|
then it should be parsable as an absolute <FONT SIZE="-1">URI.</FONT>
|
|
<DT id="9">$r->header( $field )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="10">$r->header( $field => $value )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set header values and it is inherited from
|
|
<TT>"HTTP::Headers"</TT> via <TT>"HTTP::Message"</TT>. See HTTP::Headers for
|
|
details and other similar methods that can be used to access the
|
|
headers.
|
|
<DT id="11">$r->accept_decodable<DD>
|
|
|
|
|
|
|
|
|
|
This will set the <TT>"Accept-Encoding"</TT> header to the list of encodings
|
|
that <B>decoded_content()</B> can decode.
|
|
<DT id="12">$r->content<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="13">$r->content( $bytes )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
This is used to get/set the content and it is inherited from the
|
|
<TT>"HTTP::Message"</TT> base class. See HTTP::Message for details and
|
|
other methods that can be used to access the content.
|
|
|
|
|
|
<P>
|
|
|
|
|
|
Note that the content should be a string of bytes. Strings in perl
|
|
can contain characters outside the range of a byte. The <TT>"Encode"</TT>
|
|
module can be used to turn such strings into a string of bytes.
|
|
<DT id="14">$r->as_string<DD>
|
|
|
|
|
|
|
|
|
|
|
|
<DT id="15">$r->as_string( $eol )<DD>
|
|
|
|
|
|
|
|
|
|
|
|
Method returning a textual representation of the request.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
|
|
|
|
Creating requests to be sent with LWP::UserAgent or others can be easy. Here
|
|
are a few examples.
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Simple <FONT SIZE="-1">POST</FONT></H3>
|
|
|
|
|
|
|
|
Here, we'll create a simple <FONT SIZE="-1">POST</FONT> request that could be used to send <FONT SIZE="-1">JSON</FONT> data
|
|
to an endpoint.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#!/usr/bin/env perl
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
use HTTP::Request ();
|
|
use JSON::MaybeXS qw(encode_json);
|
|
|
|
my $url = '<A HREF="https://www.example.com/api/user/123';">https://www.example.com/api/user/123';</A>
|
|
my $header = ['Content-Type' => 'application/json; charset=UTF-8'];
|
|
my $data = {foo => 'bar', baz => 'quux'};
|
|
my $encoded_data = encode_json($data);
|
|
|
|
my $r = HTTP::Request->new('POST', $url, $header, $encoded_data);
|
|
# at this point, we could send it via LWP::UserAgent
|
|
# my $ua = LWP::UserAgent->new();
|
|
# my $res = $ua->request($r);
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H3>Batch <FONT SIZE="-1">POST</FONT> Request</H3>
|
|
|
|
|
|
|
|
Some services, like Google, allow multiple requests to be sent in one batch.
|
|
<<A HREF="https://developers.google.com/drive/v3/web/batch">https://developers.google.com/drive/v3/web/batch</A>> for example. Using the
|
|
<TT>"add_part"</TT> method from HTTP::Message makes this simple.
|
|
<P>
|
|
|
|
|
|
|
|
<PRE>
|
|
#!/usr/bin/env perl
|
|
|
|
use strict;
|
|
use warnings;
|
|
|
|
use HTTP::Request ();
|
|
use JSON::MaybeXS qw(encode_json);
|
|
|
|
my $auth_token = 'auth_token';
|
|
my $batch_url = '<A HREF="https://www.googleapis.com/batch';">https://www.googleapis.com/batch';</A>
|
|
my $url = '<A HREF="https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id';">https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id';</A>
|
|
my $url_no_email = '<A HREF="https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id">https://www.googleapis.com/drive/v3/files/fileId/permissions?fields=id</A>&sendNotificationEmail=false';
|
|
|
|
# generate a JSON post request for one of the batch entries
|
|
my $req1 = build_json_request($url, {
|
|
emailAddress => '<A HREF="mailto:example@appsrocks.com">example@appsrocks.com</A>',
|
|
role => "writer",
|
|
type => "user",
|
|
});
|
|
|
|
# generate a JSON post request for one of the batch entries
|
|
my $req2 = build_json_request($url_no_email, {
|
|
domain => "appsrocks.com",
|
|
role => "reader",
|
|
type => "domain",
|
|
});
|
|
|
|
# generate a multipart request to send all of the other requests
|
|
my $r = HTTP::Request->new('POST', $batch_url, [
|
|
'Accept-Encoding' => 'gzip',
|
|
# if we don't provide a boundary here, HTTP::Message will generate
|
|
# one for us. We could use UUID::uuid() here if we wanted.
|
|
'Content-Type' => 'multipart/mixed; boundary=END_OF_PART'
|
|
]);
|
|
|
|
# add the two POST requests to the main request
|
|
$r->add_part($req1, $req2);
|
|
# at this point, we could send it via LWP::UserAgent
|
|
# my $ua = LWP::UserAgent->new();
|
|
# my $res = $ua->request($r);
|
|
exit();
|
|
|
|
sub build_json_request {
|
|
my ($url, $href) = @_;
|
|
my $header = ['Authorization' => "Bearer $auth_token", 'Content-Type' => 'application/json; charset=UTF-8'];
|
|
return HTTP::Request->new('POST', $url, $header, encode_json($href));
|
|
}
|
|
|
|
</PRE>
|
|
|
|
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
|
|
|
|
HTTP::Headers, HTTP::Message, HTTP::Request::Common,
|
|
HTTP::Response
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>AUTHOR</H2>
|
|
|
|
|
|
|
|
Gisle Aas <<A HREF="mailto:gisle@activestate.com">gisle@activestate.com</A>>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>COPYRIGHT AND LICENSE</H2>
|
|
|
|
|
|
|
|
This software is copyright (c) 1994-2017 by Gisle Aas.
|
|
<P>
|
|
|
|
This is free software; you can redistribute it and/or modify it under
|
|
the same terms as the Perl 5 programming language system itself.
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="16"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="17"><A HREF="#lbAC">VERSION</A><DD>
|
|
<DT id="18"><A HREF="#lbAD">SYNOPSIS</A><DD>
|
|
<DT id="19"><A HREF="#lbAE">DESCRIPTION</A><DD>
|
|
<DT id="20"><A HREF="#lbAF">EXAMPLES</A><DD>
|
|
<DL>
|
|
<DT id="21"><A HREF="#lbAG">Simple <FONT SIZE="-1">POST</FONT></A><DD>
|
|
<DT id="22"><A HREF="#lbAH">Batch <FONT SIZE="-1">POST</FONT> Request</A><DD>
|
|
</DL>
|
|
<DT id="23"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
<DT id="24"><A HREF="#lbAJ">AUTHOR</A><DD>
|
|
<DT id="25"><A HREF="#lbAK">COPYRIGHT AND LICENSE</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:46 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|