1E 23.11 (SaaS)

Http

Core

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.

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.

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:

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

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:

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.TableFromJsonrequires 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️⃣'

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.