| Info | ||
|---|---|---|
| ||
This library has not yet been ported to the New Pico Engine |
The HTTP Library
The HTTP library provides for more general, flexible access to cloud-based data than dataset and datasource declarations. The HTTP library supports the primary HTTP methods--get, post, put, delete, head, and patch as both functions and actions.
...
In addition, the response map will contain any keys given in the fourth optional parameter to the request and their value in the resulting response header.
The following example shows using http:get() to call a URL on example.com:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
pre {
r = http:get("http://example.com/widgets/printenv.pl",
{"a": "5",
"version": "dev"
}
);
} |
...
Suppose we made the same function application, but also included the third and fourth optional arguments:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
pre {
r = http:get("http://example.com/widgets/printenv.pl",
{"a": "5",
"version": "dev"},
{"X-proto": "flipper"},
["flopper"]);
} |
...
Because the content (what you're likely after) is in a map, you will almost always need to pull it out. For example:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
url_content = http:get(my_url).pick("$.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).pick("$.content").decode(); |
...
For example, you could specify credentials for the HTTP Basic authentication as follows:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
x1 = http:get(carvoyent_url(my_vehicle_id),
{"credentials": {"username": API_key,
"password": carvoyent_secret,
"realm": "Carvoyant API",
"netloc": "dash.carvoyant.com:443"
},
"params":{}
}); |
| Info |
|---|
You must correctly specify the realm and net location (including the port as shown) for this to work. The easiest way to get this information by attempting to go to the URL in a browser and gathering it from the challenge window that the browser shows. |
Other Functions
In addition tohttp:get(), you can also use http:post(), http:delete(), http:put(), and http:patch() as functions using this same syntax. This is useful when you want to create functions (e.g. in a module) that interact with an API.
HTTP Actions
Post
Interacting with cloud-based services usually involves sending data. To send data we use the http:post() action. The http:post() action takes a single argument, the URL of the resource accepting the POST request.
...
The following example shows using an http:post() action inside a rule:
| Code Block | |||||
|---|---|---|---|---|---|
| |||||
| |||||
rule r1 {
select when pageview url #/archives/#
http:post("http://www.example.com/go")
with params = {"answer": "x"}
} |
...
Here's another example showing the use of the http:post() action to POST raw content—XML in this case:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
rule r2 {
select when pageview url #/archives/#
http:post("http://example.com/printenv.pl")
with body = << <?xml encoding='UTF-8'?>
<feed version='0.3'>
</feed> >> and
headers = {"content-type": "application/xml"};
}
|
...
The http:put() action works in the same manner as http:post(), except that an HTTP PUT is used instead of a POST. For example, here is a user defined action, update, that uses http:put():
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
update = defaction(id, value) {
http:put(base_url+feed_id) with
body = {"version": vers,
"datastreams":[
{"id":id, "current_value":value}
]
} and
headers= {"X-ApiKey": api_key,
"content-type": "application/json"
}
} |
...
The autoraise parameter is given with a string as its value. When the explicit event is automatically raised, one of the event parameters will be label and it will have the value of the autoraise string.
Each action defines its own event domain and type. For the http:post() action the event that is raised will have event domain http and event type of post. Similarly, each action will include relevant data from the action. The response values given above are sent as event parameters and can thus be checked as part of the event selection. The http:post() action includes response information from the POST.
The following simple example shows a rule that has an http:post() action with an event autoraise:
| Code Block | ||||||
|---|---|---|---|---|---|---|
| ||||||
rule r1 is active {
select when pageview "/archives/(\d+)/" setting(year)
http:post("http://www.example.com/go")
with params = {"answer": "x"}
and autoraise = "example";
} |
This is roughly equivalent to the following rule:
| Code Block |
|---|
| |||||
| |||||
rule r1 is active {
select when pageview "/archives/(\d+)/" setting(year)
http:post("http://www.example.com/go") setting (resp)
with params = {"answer": "x};
always {
raise explicit event post with 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 is active {
select when http post
label #example#
status_code #(2\d\d)# setting (status)
notify("Status", "Success! The status is " + status);
}
rule r3 is active {
select when http post
label #example#
status_code #([45]\d\d)# setting (status)
fired {
log <<Error: #{status}: #{event:param("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 is active {
select when http post label #example#
if(event:param("content_type") like "^text/") then
notify("Page says...", event:param("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.