HTTP-HTTPS Functions

This set of functions provides the ability to call HTTP/HTTPS endpoints from within Cloud Workflow. There is one function for each of the well-known HTTP verbs (get, post, head, put, patch, delete, options, and trace). The functions take all request attributes as parameters and return the response in a hash value with the keys code, headers, cookies, and body (each containing their respective response attributes).

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

Making Requests

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. 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	string if raw_response was set to true (or it was set to false but could not be parsed as an object) object if raw_response was set to false (which is by default) and the content type was xml or json	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\.\.\.

http_request

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 }	{}