HTTP-HTTPS Functions
There is also a generic function called http_request which takes the verb as a parameter for any type of HTTP/HTTPS call.
| • | Making Requests |
| • | Common Parameters for HTTP-HTTPS Functions |
| • | HTTP-HTTPS Functions Responses |
| • | http_get, http_post, http_head, http_put, http_patch, http_delete, http_options, http_trace |
| • | http_request |
When using these functions, there is some specific behavior that is of interest:
| • | If a body is given for the request and the corresponding value is not a string then the functions will encode the value in JSON. |
| • | The verb-specific functions take a single url argument that includes the scheme, host, href, and query strings. |
| • | The generic http_request function takes individual arguments (host, https, href, query_strings) to form the url. |
Common Parameters for HTTP-HTTPS Functions
The following parameters are available for all verb-specific and generic HTTP functions.
|
Name |
Possible Values |
Required |
Description |
Example |
Default |
|
Headers |
Hash of string -> string values |
No |
HTTP request headers, the keys are the classical content-type (or content_type), accepts, etc. Passing lowercase with underscore instead of dash is OK. The implementation normalizes to standard HTTP header names behind the scenes. |
{ "X-Api-Version": "1.0" } |
|
|
Body |
String (or any value if content-type is JSON) |
No |
The request body. When unspecified and the method is one of those that expect a body, will default to "" (empty string). A body can be given for methods that don't require it (GET, HEAD) and it will probably get discarded by the server. |
|
|
|
raw_response |
Boolean |
No |
The default is false. When false (default) and the response is application/json (or an extension of it), the response body will contain the parsed value (not the JSON string). In case of XML content (and unless raw_response is set to true), the XML is turned into a JSON-compatible data structure (a representation of the XML tree). |
true |
false |
|
basic_auth |
An object with keys username and password. |
No |
Specifies a pair (username, password) for the basic authentication of this request. |
{ "username": "foo", "password": "bar" } |
|
|
Cookies |
Array of cookie objects |
No |
An array of cookies to send to the server. Only name and value are allowed. |
[ { "name": "zz", "value": "yy" } ] |
|
|
Noredirect |
Boolean |
No |
The default is false. By default the http method will follow any redirection. Infinite loops are detected and raise an error. |
true |
false |
|
Insecure |
Boolean |
No |
The default is false. By default the http method will verify SSL certificates. When set to true, the check is not done. |
true |
false |
|
Signature |
An object with keys type, access_key, and secret_key. |
No |
Used for signing requests for AWS. The type should be aws. The access_key and secret_key fields specify the AWS credentials to use for signing the request. If the access_key or secret_key fields are not provided, the default AWS credentials (AWS_ACCESS_KEY_ID or AWS_SECRET_ACCESS_KEY) for the account will be used. Note:When using the default keys, the user launching the CAT must have admin role on the account in order to read credential values. |
{ "type": "aws", "access_key": "myaccesskey", "secret_key": "mysecretkey" } |
|
|
Auth |
A credentials reference |
No |
A reference to credentials in the credentials service. When called from a policy, credentials references are automatically imported as global variables such as $$auth_aws. When developing via the console, you can use the signer function to generate an equivalent reference. |
signer(aws_default) or $$auth_aws |
|
HTTP-HTTPS Functions Responses
The return value of every HTTP/S function is a hash with the following elements.
|
Name |
Type |
Description |
Example |
||||||
|
Code |
Number |
The response code |
200 |
||||||
|
Headers |
Hash |
The headers from the http response |
{ "Connection": "keep-alive", "Content-Encoding": "gzip" } |
||||||
|
Cookies |
Array of objects |
The cookies received in the response |
For a cookie received as string, zz=yy; Domain=.foo.com; path=/; secure, it will be parsed as follows: [ { "name": "zz", "value": "yy", "path": "/", "domain": ".foo.com","expires": <DateTime formatted value>, "secure": true }] |
||||||
|
Body |
|
The body of the response |
|
http_get, http_post, http_head, http_put, http_patch, http_delete, http_options, http_trace
Syntax
http_get($params), http_post($params), http_head($params), http_put($params), http_patch($params), http_delete($params), http_options($params), http_trace($params)
Description
The verb-specific functions have the following parameters, in addition to the Common Parameters for HTTP-HTTPS Functions. The return value from these functions is documented in HTTP-HTTPS Functions Responses.
|
Name |
Possible Values |
Required |
Description |
Example |
|
URL |
String |
Yes |
The URL for the request including the scheme (http/https), host, href, and query strings. |
https://www.googleapis.com/drive/v2... |
Syntax
http_request($params)
Description
The general function has the following parameters, in addition to the Common Parameters for HTTP-HTTPS Functions. The return value from these functions is documented in HTTP-HTTPS Functions Responses.
|
Name |
Possible Values |
Required |
Description |
Example |
Default |
|
Verb |
String |
Yes |
The HTTP verb (should be one of get, post, patch, put, delete, options, head) |
get |
|
|
Host |
String |
Yes |
The host of the external service |
www.googleapis.com |
|
|
HTTPS |
Boolean |
No |
Whether to https/http |
true |
false |
|
href |
String |
No |
The href of the target resource relative to the host |
/drive/v2/files/123 |
“ ” |
|
query_strings |
Hash |
No |
Query-string values (what comes after a ? in the URL). Keys must be strings. Values are turned into strings (arrays and hashes are JSON encoded). All the values are escaped. |
{ "updateViewedDate": true } |
{} |