...
qs— a map that will be used to create the URI encoded query parametersheaders— a map with additional http headers- body — a raw string for the http body
- auth — a optional map with keys
"username"and"password"which is used to add a basic authentication header to the request - json — data to encode the http body as json, also setting the `application/json` header (this parameter is ignored if body is provided)
- form — a map to encode as `application/x-www-form-urlencoded`, also setting that header (this parameter is ignored if body or json is provided)
- parseJSON — set this to true if you want to try to parse the `content` as json
- autoraise — a string that will be the label applied to the event that this action automatically raises.
- autosend — a map like the map specifying an event to be sent in
event:send(see documentation of the event library). It specifies the Event Channel Identifier (ECI), and the domain and type of an event to be added to a pico's queue when the HTTP response becomes available. Note that this will happen in a separate transaction. The pico to receive the response event must be hosted on the same pico engine.
The action supports an optional setting clause that gives the name of the variable in which the response to the HTTP request should be stored for later use. This variable is available to any expression executed after the action takes place: expressions in the parameters of later actions or in the postlude of the rule.
The resulting map of name-value pairs has the following structure:
content— the content of the responsecontent_type— the MIME type of the contentcontent_length— the number of bytes in the contentheaders— a map with all the response headersstatus_code— the three digit HTTP status codestatus_line— the complete status string including the three digit HTTP status codelabel— the autoraise label, if autoraise is set (see above)
The following example shows using an http:post() action inside a rule:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r1 {
select when web pageview url #re#/archives/#
http:post("http://www.example.com/go", form = {"answer": "x"})
} |
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r2 {
select when web pageview url re#/archives/#
http:post("https://example.com/printenv.pl",
body =
<< <?xml encoding='UTF-8'?>
<feed version='0.3'>
</feed> >>,
headers = {"content-type": "application/xml"});
}
|
Get
The http:get() action works in the same manner as http:post(), except that an HTTP GET is used instead of a POST.
...
| Code Block | ||||
|---|---|---|---|---|
| ||||
url_content = http:get(my_url){"content"}; |
If you're retrieving JSON, you'll need to turn the string in the content field into a data structure using decode():
| Code Block | ||||
|---|---|---|---|---|
| ||||
json_from_url = http:get(my_url){"content"}.decode(); |
Processing the Response
With autosend
If autosend is set, the rule will complete evaluation, and at a later time, when the server at the URL returns its response, the event specified will be generated and added to the queue of the pico which provides the channel matching the ECI included in the autosend map.
With autoraise
If autoraise is set, the rule will automatically raise an event with the event domain http and the event type equal to the HTTP method used (i.e. post, put, get, delete). The event will contain attributes with the same name-value structure that HTTP actions and function return.
...
The following simple example shows a rule that has an http:post() action with an event autoraise:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r1 {
select when web pageview url re#archives/(\d+)# setting(year)
http:post("http://www.example.com/go"),
form = {"answer": "x"},
autoraise = "example");
} |
This is roughly equivalent to the following rule:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r1 {
select when web pageview url re#archives/(\d+)# setting(year)
http:post("http://www.example.com/go", form = {"answer": "x"}) setting (resp)
always {
raise explicit event "post" attributes resp
}
} |
The biggest difference is that the autoraise would create an event with the event domain http while the raise statement would create an event with the event type explicit.
Assuming we raised the http:post event in the first rule shown above, we could chain additional rules for subsequent processing of the response. The following two rules check the status code of the response and present a notification of the result:
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r2 {
select when http post
label re#example#
status_code re#(2\d\d)# setting (status)
send_directive("Status", {"status":"Success! The status is " + status});
}
rule r3 {
select when http post
label re#example#
status_code re#([45]\d\d)# setting (status)
fired {
log error <<#{status}: #{event:attr("status_line")}>>;
last;
}
} |
The second rule fires when the status code in the response indicates an error, logs the error, and uses the last control statement in the postlude to stop subsequent processing of rules in the ruleset.
This example rule shows the content of the response if its content type is “text.”
| Code Block | ||||
|---|---|---|---|---|
| ||||
rule r4 {
select when http post label re#example#
if(event:attr("content_type") like "^text/") then
send_directive("Page says...", {"content":event:attr("content")});
} |
Rule chaining from an autoraise on an http:post() action provides a convenient and simple way of easily dealing with the results of an action.
...