splunkjs.Service.Jobs.create
Endpoint: search/jobs
Creates a search job with a given search query and optional parameters, including exec_mode
to specify the type of search:
Use exec_mode=normal
to return a search job ID immediately (default). Poll for completion to find out when you can retrieve search results.
Use exec_mode=blocking
to return the search job ID when the search has finished.
To run a oneshot search, which does not create a job but rather returns the search results, use Service.Jobs.oneshotSearch
.
Syntax
create: function(query, params, callback)
Parameters
Name |
Type |
Description |
query |
String |
The search query. |
params |
Object |
A dictionary of properties for the search job. For a list of available parameters, see Search job parameters on Splunk Developer Portal. |
callback |
Function |
A function to call with the created job: (err, createdJob) . |
create: function(query, params, callback) {
// If someone called us with the default style of (params, callback),
// lets make it work
if (utils.isObject(query) && utils.isFunction(params) && !callback) {
callback = params;
params = query;
query = params.search;
}
callback = callback || function() {};
params = params || {};
params.search = query;
if ((params.exec_mode || "").toLowerCase() === "oneshot") {
throw new Error("Please use splunkjs.Service.Jobs.oneshotSearch for exec_mode=oneshot");
}
if (!params.search) {
callback("Must provide a query to create a search job");
return;
}
var that = this;
return this.post("", params, function(err, response) {
if (err) {
callback(err);
}
else {
var job = new root.Job(that.service, response.data.sid, that.namespace);
callback(null, job);
}
});
},
splunkjs.Service.Jobs.oneshotSearch
Endpoint: search/jobs
Creates a oneshot search from a given search query and parameters.
Syntax
oneshotSearch: function(query, params, callback)
Parameters
Name |
Type |
Description |
query |
String |
The search query. |
params |
Object |
A dictionary of properties for the search: - output_mode (string): Specifies the output format of the results (XML, JSON, or CSV). - earliest_time (string): Specifies the earliest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. - latest_time (string): Specifies the latest time in the time range to search. The time string can be a UTC time (with fractional seconds), a relative time specifier (to now), or a formatted time string. - rf (string): Specifies one or more fields to add to the search. |
callback |
Function |
A function to call with the results of the search: (err, results) . |
Examples
var jobs = service.jobs();
jobs.oneshotSearch("search ERROR", {id: "myjob_123"}, function(err, results) {
console.log("RESULT FIELDS": results.fields);
});
oneshotSearch: function(query, params, callback) {
// If someone called us with the default style of (params, callback),
// lets make it work
if (utils.isObject(query) && utils.isFunction(params) && !callback) {
callback = params;
params = query;
query = params.search;
}
callback = callback || function() {};
params = params || {};
params.search = query;
params.exec_mode = "oneshot";
if (!params.search) {
callback("Must provide a query to create a search job");
}
var outputMode = params.output_mode || "json_rows";
var path = this.qualifiedPath;
var method = "POST";
var headers = {};
var post = params;
var get = {output_mode: outputMode};
var body = null;
var req = this.service.request(
path,
method,
get,
post,
body,
headers,
function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data);
}
}
);
return req;
}
});
splunkjs.Service.Jobs.search
Endpoint: search/jobs
Creates a search job with a given search query and optional parameters, including exec_mode
to specify the type of search:
Use exec_mode=normal
to return a search job ID immediately (default). Poll for completion to find out when you can retrieve search results.
Use exec_mode=blocking
to return the search job ID when the search has finished.
To run a oneshot search, which does not create a job but rather returns the search results, use Service.Jobs.oneshotSearch
.
Syntax
search: function(query, params, callback)
Parameters
Name |
Type |
Description |
query |
String |
The search query. |
params |
Object |
A dictionary of properties for the search job. For a list of available parameters, see Search job parameters on Splunk Developer Portal. Note: This method throws an error if the exec_mode=oneshot parameter is passed in with the properties dictionary. |
callback |
Function |
A function to call with the new search job: (err, createdJob) . |
Examples
var jobs = service.jobs();
jobs.search("search ERROR", {id: "myjob_123"}, function(err, newJob) {
console.log("CREATED": newJob.sid);
});
search: function(query, params, callback) {
return this.create(query, params, callback);
},
splunkjs.Service.Endpoint.del
Performs a relative DELETE request on an endpoint's path, combined with the parameters and a relative path if specified.
Syntax
del: function(relpath, params, callback)
Parameters
Name |
Type |
Description |
relpath |
String |
A relative path to append to the endpoint path. |
params |
Object |
A dictionary of entity-specific parameters to add to the query string. |
callback |
Function |
A function to call when the request is complete: (err, response) . |
Examples
// Will make a request to {service.prefix}/search/jobs/123456
var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
endpoint.delete("", {}, function() { console.log("DELETED"))});
del: function(relpath, params, callback) {
var url = this.qualifiedPath;
// If we have a relative path, we will append it with a preceding
// slash.
if (relpath) {
url = url + "/" + relpath;
}
return this.service.del(
url,
params,
callback
);
}
});
splunkjs.Service.Endpoint.get
Performs a relative GET request on an endpoint's path, combined with the parameters and a relative path if specified.
Syntax
get: function(relpath, params, callback, isAsync)
Parameters
Name |
Type |
Description |
relpath |
String |
A relative path to append to the endpoint path. |
params |
Object |
A dictionary of entity-specific parameters to add to the query string. |
callback |
Function |
A function to call when the request is complete: (err, response) . |
Examples
// Will make a request to {service.prefix}/search/jobs/123456/results?offset=1
var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
endpoint.get("results", {offset: 1}, function() { console.log("DONE"))});
get: function(relpath, params, callback, isAsync) {
var url = this.qualifiedPath;
// If we have a relative path, we will append it with a preceding
// slash.
if (relpath) {
url = url + "/" + relpath;
}
return this.service.get(
url,
params,
callback,
isAsync
);
},
splunkjs.Service.Collection.item
Returns a specific entity from the collection.
Syntax
item: function(id, namespace)
Parameters
Name |
Type |
Description |
id |
String |
The name of the entity to retrieve. |
namespace |
Object |
Namespace information: - owner (string): The Splunk username, such as "admin". A value of "nobody" means no specific user. The wildcard value "-", is not acceptable when searching for an entity. - app (string): The app context for this resource (such as "search"). The wildcard value "-" is unacceptable when searching for an entity. - sharing (string): A mode that indicates how the resource is shared. The sharing mode can be "user", "app", "global", or "system". |
Examples
var apps = service.apps();
apps.fetch(function(err, apps) {
var app = apps.item("search");
console.log("Search App Found: " + !!app);
// `app` is an Application object.
});
item: function(id, namespace) {
if (utils.isEmpty(namespace)) {
namespace = null;
}
if (!id) {
throw new Error("Must suply a non-empty name.");
}
if (namespace && (namespace.app === '-' || namespace.owner === '-')) {
throw new Error("When searching for an entity, wildcards are not allowed in the namespace. Please refine your search.");
}
var fullPath = null;
if (this._entitiesByName.hasOwnProperty(id)) {
var entities = this._entitiesByName[id];
if (entities.length === 1 && !namespace) {
// If there is only one entity with the
// specified name and the user did not
// specify a namespace, then we just
// return it
return entities[0];
}
else if (entities.length === 1 && namespace) {
// If we specified a namespace, then we
// only return the entity if it matches
// the full path
fullPath = this.service.fullpath(entities[0].path(), namespace);
if (entities[0].qualifiedPath === fullPath) {
return entities[0];
}
else {
return null;
}
}
else if (entities.length > 1 && !namespace) {
// If there is more than one entity and we didn't
// specify a namespace, then we return an error
// saying the match is ambiguous
throw new Error("Ambiguous match for name '" + id + "'");
}
else {
// There is more than one entity, and we do have
// a namespace, so we try and find it
for(var i = 0; i < entities.length; i++) {
var entity = entities[i];
fullPath = this.service.fullpath(entities[i].path(), namespace);
if (entity.qualifiedPath === fullPath) {
return entity;
}
}
}
}
else {
return null;
}
},
splunkjs.Service.Endpoint.post
Performs a relative POST request on an endpoint's path, combined with the parameters and a relative path if specified.
Syntax
post: function(relpath, params, callback)
Parameters
Name |
Type |
Description |
relpath |
String |
A relative path to append to the endpoint path. |
params |
Object |
A dictionary of entity-specific parameters to add to the body. |
callback |
Function |
A function to call when the request is complete: (err, response) . |
Examples
// Will make a request to {service.prefix}/search/jobs/123456/control
var endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
endpoint.post("control", {action: "cancel"}, function() { console.log("CANCELLED"))});
post: function(relpath, params, callback) {
var url = this.qualifiedPath;
// If we have a relative path, we will append it with a preceding
// slash.
if (relpath) {
url = url + "/" + relpath;
}
return this.service.post(
url,
params,
callback
);
},