Contents

Method

Post

ModuleHttp
LibraryCore
Action

Send the supplied Body text via a HTTP request to the specified Uri endpoint to consume and return the response if completed. This Method is primarily for use with Splunk Event Collectors, but it might support other similar Web APIs.

Parameters

Url (string): The absolute URL of the end point to make the request to.

Authorization (string, optional): The value for an Authorization request header.

Body (string, optional): Always a JSON encoded string to send. It is sent verbatim if ContentType is "application/json" (which is highly likely for a lot of APIs) otherwise it is unescaped from JSON to a stream of octets and sent like that.

ContentType (string, optional, default "application/json"): The media type of the body supplied. A comprehensive list can be found at https://www.iana.org/assignments/media-types/media-types.xhtml.

Headers (table, optional, default empty): A table of two columns [Header x Value] with multiple rows, one for each header line in the request. Header is the Key to the table, the last value in the table will prevail if there are duplicate key Headers.

Stagger (boolean, optional, default true): if true then the method will stagger using a random time period within the DefaultStaggerRangeSeconds setting before sending the post request, if false then the method will execute the post immediately.

Return values

Completed (boolean): Whether the request and response both completed. If false, the ErrorMessage column should be consulted.

ErrorMessage (string): if Completed is false then an error that will help to diagnose the problem.

If Completed is true then the following columns will also be in the output:

  • StatusCode (integer): The HTTP Status Code returned in response to posting the body to the Uri specified.

If Completed is true then the following columns might also be in the output if the server supplied them:

  • Date (string): The time on the server when the response was sent.

If Complete is true and a Body was sent in the response then the following columns will also be output if the server supplied them:

  • Body (string}: JSON-encoded text that represents the response from the server. If the Content-Type is "application/json" then the value is exactly as returned by the server, otherwise it is JSON-encoded (and the Content-Length will not match the length of this string).
  • Content-Length (integer): The length (in octets) of the contents of the body that was sent by the server. It is not necessarily the length of the Body that is returned by this method.
  • Content-Type (string): The content type of what is in the Body, e.g. "text/html".
  • WWW-Authenticate (string): The authentication method used to gain access to the resource.
  • X-Powered-By (string): E.g. "ASP.NET".

Regardless of the success or otherwise, two ever-present columns indicating the success or otherwise of the operation are returned, 'Completed' and 'ErrorMessage'. If the request is successful then a plethora of unique response headers and values will be transformed into additional output columns, e.g. "Connection", "Server", "WWW-Authenticate" etc.

The standard HTTP headers have '-' (U+002D hyphen-minus) in them, and are supported. If the header names that the server returns have more unusual characters in them then it may cause issues with the SCALE language, however this is extremely unlikely to occur.

TIMS can complain about the hyphens in some of the column names.

Example
Splunk Event Collector Post all-in-one
@response = Http.Post(Url : "https://input-prd-p-ftgwgk5k7h7p.cloud.splunk.com:8088/services/collector/event",
                     Authorization : "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     Body : "{\"sourcetype\" : \"my_test_data\", \"event\": \"Simple event: HEC token in Authorization header\"}");
Splunk Event Collector Post using a table parameter for Headers
@headers = SELECT 'Authorization' AS [Header], 'Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' AS [Value];

@response = Http.Post(  Url : "https://input-prd-p-ftgwgk5k7h7p.cloud.splunk.com:8088/services/collector/event",
                        Headers: @headers, 
                        Body : "{\"sourcetype\" : \"my_test_data\", \"event\": \"Simple event: HEC token in Authorization header\"}");

A more complex example shows constructing a json object to post by using a table:

Using a table to build a Json body (assuming the server will accept this format)
@eventTable = SELECT "my_test_data" as sourcetype, "Simple event: HEC token in Authorization header" as event;

@eventJson = Utilities.JsonFromTable(Table:@eventTable);

// @eventJson.Json is '[{"event":"Simple event: HEC token in Authorization header","sourcetype":"my_test_data"}]'
// that is an array but maybe the server doesn't accept arrays

@eventJson = SELECT SUBSTR(@eventJson.Json, 2, LENGTH(@eventJson.Json)-2) AS Json FROM @eventJson;

// @eventJson.Json is '{"event":"Simple event: HEC token in Authorization header","sourcetype":"my_test_data"}'
// now it's just a single object. 
// Do not REPLACE(REPLACE(@eventJson.Json, '[', ''), ']', '') because that could change the content rather than the markup

@response = Http.Post(Url : "https://input-prd-p-ftgwgk5k7h7p.cloud.splunk.com:8088/services/collector/event",
                     Authorization : "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     Body : @eventJson.Json);

And how to examine the contents of the response object returned from Splunk. Utilities.TableFromJson requires a Json Array [..] of Objects {..} as input.

Manually building Json objects
@response = Http.Post(Url : "https://input-prd-p-ftgwgk5k7h7p.cloud.splunk.com:8088/services/collector/event",
                     Authorization : "Splunk xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
                     Body : "{\"sourcetype\" : \"my_test_data\", \"event\": \"Simple event: HEC token in Authorization header\"}");

// @response.Body is '{"text":"Success","code":0}' this is a single object, a table is an array of homogeneous objects.

@bodyJson = SELECT "[" || Body || "]" AS Json FROM @response;

// wrap array notation around the object to make a json representation of a SCALE table

@bodyTable = Utilities.TableFromJson(Json:@bodyJson.Json);

// @bodyTable is :
//
// code	| text
// -----+--------------
// 0	| Success

Extra care has to be taken handling Json and binary data. The output Body column is ALWAYS JSON. If the server returned Json then it is exactly what the server returned. If the server returned something else, including binary data, then Body will contain the JSON encoded version, so that it can be processed in SCALE. But this creates difficulties in handling the data.

Handling binary data in the Body parameter / column
@binaryBody = SELECT CHAR(1) || CHAR(2) AS BinaryInUtf8;
// @binaryBody.BinaryInUtf8 is '1️⃣2️⃣'

@jsonBody = Utilities.JsonFromTable(Table:@binaryBody);
// @jsonBody.Json is '[{"BinaryInUtf8":"\u0001\u0002"}]'

@jsonBinary = SELECT SUBSTR(@jsonBody.Json, 18, LENGTH(@jsonBody.Json) - 19) AS BinaryInJson FROM @jsonBody;
// @jsonBinary.BinaryInJson is '"\u0001\u0002"'

@jsonManual = SELECT "[{\"Binary\":\"\\u0001\\u0002\"}]" AS Json;
// @jsonManual.Json is '[{"Binary":"\u0001\u0002"}]'

@table = Utilities.TableFromJson(Json:@jsonManual);
// @table.Binary is '1️⃣2️⃣'
Platforms
  • Windows
  • Linux
  • MacOS
  • Solaris Intel
  • Solaris Sparc
  • Android
Notes

This Method is primarily for use with Splunk Event Collectors, but it might support other similar Web APIs. Web APIs vary wildly, so it crucial to understand exactly what the API call requires and how that can be constructed using the Body field.

Available from v5.0.