pub struct Request { /* private fields */ }
Expand description
Request instances are builders that creates a request.
let mut request = ureq::get("https://www.google.com/");
let response = request
.query("foo", "bar baz") // add ?foo=bar%20baz
.call(); // run the request
Implementations
sourceimpl Request
impl Request
sourcepub fn build(&self) -> Request
pub fn build(&self) -> Request
“Builds” this request which is effectively the same as cloning. This is needed when we use a chain of request builders, but don’t want to send the request at the end of the chain.
let r = ureq::get("/my_page")
.set("X-Foo-Bar", "Baz")
.build();
sourcepub fn call(&mut self) -> Response
pub fn call(&mut self) -> Response
Executes the request and blocks the caller until done.
Use .timeout_connect()
and .timeout_read()
to avoid blocking forever.
let r = ureq::get("/my_page")
.timeout_connect(10_000) // max 10 seconds
.call();
println!("{:?}", r);
sourcepub fn send_string(&mut self, data: &str) -> Response
pub fn send_string(&mut self, data: &str) -> Response
Send data as a string.
The Content-Length
header is implicitly set to the length of the serialized value.
Defaults to utf-8
Charset support
Requires feature ureq = { version = "*", features = ["charset"] }
If a Content-Type
header is present and it contains a charset specification, we
attempt to encode the string using that character set. If it fails, we fall back
on utf-8.
// this example requires features = ["charset"]
let r = ureq::post("/my_page")
.set("Content-Type", "text/plain; charset=iso-8859-1")
.send_string("Hällo Wörld!");
println!("{:?}", r);
sourcepub fn send(&mut self, reader: impl Read + 'static) -> Response
pub fn send(&mut self, reader: impl Read + 'static) -> Response
Send data from a reader.
The Content-Length
header is not set because we can’t know the length of the reader.
use std::io::Cursor;
let text = "Hello there!\n";
let read = Cursor::new(text.to_string().into_bytes());
let resp = ureq::post("/somewhere")
.set("Content-Type", "text/plain")
.send(read);
sourcepub fn set(&mut self, header: &str, value: &str) -> &mut Request
pub fn set(&mut self, header: &str, value: &str) -> &mut Request
Set a header field.
let r = ureq::get("/my_page")
.set("X-API-Key", "foobar")
.set("Accept", "text/plain")
.call();
if r.ok() {
println!("yay got {}", r.into_string().unwrap());
} else {
println!("Oh no error!");
}
sourcepub fn header<'a>(&self, name: &'a str) -> Option<&str>
pub fn header<'a>(&self, name: &'a str) -> Option<&str>
Returns the value for a set header.
let req = ureq::get("/my_page")
.set("X-API-Key", "foobar")
.build();
assert_eq!("foobar", req.header("x-api-Key").unwrap());
sourcepub fn has<'a>(&self, name: &'a str) -> bool
pub fn has<'a>(&self, name: &'a str) -> bool
Tells if the header has been set.
let req = ureq::get("/my_page")
.set("X-API-Key", "foobar")
.build();
assert_eq!(true, req.has("x-api-Key"));
sourcepub fn all<'a>(&self, name: &'a str) -> Vec<&str>
pub fn all<'a>(&self, name: &'a str) -> Vec<&str>
All headers corresponding values for the give name, or empty vector.
let req = ureq::get("/my_page")
.set("X-Forwarded-For", "1.2.3.4")
.set("X-Forwarded-For", "2.3.4.5")
.build();
assert_eq!(req.all("x-forwarded-for"), vec![
"1.2.3.4",
"2.3.4.5",
]);
sourcepub fn query(&mut self, param: &str, value: &str) -> &mut Request
pub fn query(&mut self, param: &str, value: &str) -> &mut Request
Set a query parameter.
For example, to set ?format=json&dest=/login
let r = ureq::get("/my_page")
.query("format", "json")
.query("dest", "/login")
.call();
println!("{:?}", r);
sourcepub fn query_str(&mut self, query: &str) -> &mut Request
pub fn query_str(&mut self, query: &str) -> &mut Request
Set query parameters as a string.
For example, to set ?format=json&dest=/login
let r = ureq::get("/my_page")
.query_str("?format=json&dest=/login")
.call();
println!("{:?}", r);
sourcepub fn timeout_connect(&mut self, millis: u64) -> &mut Request
pub fn timeout_connect(&mut self, millis: u64) -> &mut Request
Timeout for the socket connection to be successful.
The default is 0
, which means a request can block forever.
let r = ureq::get("/my_page")
.timeout_connect(1_000) // wait max 1 second to connect
.call();
println!("{:?}", r);
sourcepub fn timeout_read(&mut self, millis: u64) -> &mut Request
pub fn timeout_read(&mut self, millis: u64) -> &mut Request
Timeout for the individual reads of the socket.
The default is 0
, which means it can block forever.
let r = ureq::get("/my_page")
.timeout_read(1_000) // wait max 1 second for the read
.call();
println!("{:?}", r);
sourcepub fn timeout_write(&mut self, millis: u64) -> &mut Request
pub fn timeout_write(&mut self, millis: u64) -> &mut Request
Timeout for the individual writes to the socket.
The default is 0
, which means it can block forever.
let r = ureq::get("/my_page")
.timeout_write(1_000) // wait max 1 second for sending.
.call();
println!("{:?}", r);
sourcepub fn auth(&mut self, user: &str, pass: &str) -> &mut Request
pub fn auth(&mut self, user: &str, pass: &str) -> &mut Request
Basic auth.
These are the same
let r1 = ureq::get("http://localhost/my_page")
.auth("martin", "rubbermashgum")
.call();
println!("{:?}", r1);
let r2 = ureq::get("http://martin:rubbermashgum@localhost/my_page").call();
println!("{:?}", r2);
sourcepub fn auth_kind(&mut self, kind: &str, pass: &str) -> &mut Request
pub fn auth_kind(&mut self, kind: &str, pass: &str) -> &mut Request
Auth of other kinds such as Digest
, Token
etc.
let r = ureq::get("http://localhost/my_page")
.auth_kind("token", "secret")
.call();
println!("{:?}", r);
sourcepub fn redirects(&mut self, n: u32) -> &mut Request
pub fn redirects(&mut self, n: u32) -> &mut Request
How many redirects to follow.
Defaults to 5
.
let r = ureq::get("/my_page")
.redirects(10)
.call();
println!("{:?}", r);
sourcepub fn get_method(&self) -> &str
pub fn get_method(&self) -> &str
Get the method this request is using.
Example:
let req = ureq::post("/somewhere")
.build();
assert_eq!(req.get_method(), "POST");
sourcepub fn get_url(&self) -> &str
pub fn get_url(&self) -> &str
Get the url this request was created with.
This value is not normalized, it is exactly as set. It does not contain any added query parameters.
Example:
let req = ureq::post("https://cool.server/innit")
.build();
assert_eq!(req.get_url(), "https://cool.server/innit");
sourcepub fn get_host(&self) -> Result<String, Error>
pub fn get_host(&self) -> Result<String, Error>
Normalizes and returns the host that will be used for this request.
Example:
let req1 = ureq::post("https://cool.server/innit")
.build();
assert_eq!(req1.get_host().unwrap(), "cool.server");
let req2 = ureq::post("/some/path")
.build();
assert_eq!(req2.get_host().unwrap(), "localhost");
sourcepub fn get_scheme(&self) -> Result<String, Error>
pub fn get_scheme(&self) -> Result<String, Error>
Returns the scheme for this request.
Example:
let req = ureq::post("https://cool.server/innit")
.build();
assert_eq!(req.get_scheme().unwrap(), "https");