Cancels a search job.
Cancels a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call when the search is done: |
var job = service.jobs().item("mysid");
job.cancel(function(err) {
console.log("CANCELLED");
});
cancel: function(callback) {
var req = this.post("control", {action: "cancel"}, callback);
return req;
},Disables preview generation for a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with this search job: |
var job = service.jobs().item("mysid");
job.disablePreview(function(err, job) {
console.log("PREVIEW DISABLED");
});
disablePreview: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "disablepreview"}, function(err) {
callback(err, that);
});
return req;
},Enables preview generation for a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with this search job: |
var job = service.jobs().item("mysid");
job.disablePreview(function(err, job) {
console.log("PREVIEW ENABLED");
});
enablePreview: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "enablepreview"}, function(err) {
callback(err, that);
});
return req;
},Returns the events of a search job with given parameters.
| Name | Type | Description |
|---|---|---|
| params | Object | The parameters for retrieving events. For a list of available parameters, see the GET search/jobs/{search_id}/events endpoint in the REST API documentation. |
| callback | Function | A function to call when the events are retrieved: |
var job = service.jobs().item("mysid");
job.events({count: 10}, function(err, events, job) {
console.log("Fields: ", events.fields);
});
events: function(params, callback) {
callback = callback || function() {};
params = params || {};
params.output_mode = params.output_mode || "json_rows";
var that = this;
return this.get("events", params, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Finalizes a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with the job: |
var job = service.jobs().item("mysid");
job.finalize(function(err, job) {
console.log("JOB FINALIZED");
});
finalize: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "finalize"}, function(err) {
callback(err, that);
});
return req;
},Constructor for splunkjs.Service.Job.
| Name | Type | Description |
|---|---|---|
| service | splunkjs.Service | A |
| sid | String | The search ID for this search job. |
| namespace | Object | Namespace information: |
A new splunkjs.Service.Job instance.
init: function(service, sid, namespace) {
this.name = sid;
this._super(service, this.path(), namespace);
this.sid = sid;
// We perform the bindings so that every function works
// properly when it is passed as a callback.
this.cancel = utils.bind(this, this.cancel);
this.disablePreview = utils.bind(this, this.disablePreview);
this.enablePreview = utils.bind(this, this.enablePreview);
this.events = utils.bind(this, this.events);
this.finalize = utils.bind(this, this.finalize);
this.pause = utils.bind(this, this.pause);
this.preview = utils.bind(this, this.preview);
this.results = utils.bind(this, this.results);
this.searchlog = utils.bind(this, this.searchlog);
this.setPriority = utils.bind(this, this.setPriority);
this.setTTL = utils.bind(this, this.setTTL);
this.summary = utils.bind(this, this.summary);
this.timeline = utils.bind(this, this.timeline);
this.touch = utils.bind(this, this.touch);
this.unpause = utils.bind(this, this.unpause);
},Returns an iterator over this search job's events or results.
| Name | Type | Description |
|---|---|---|
| type | String | One of {"events", "preview", "results"}. |
| params | Object | A dictionary of optional parameters: |
An iterator object with a next(callback) method, where callback is of the form (err, results, hasMoreResults).
iterator: function(type, params) {
return new root.PaginatedEndpointIterator(this[type], params);
},Retrieves the REST endpoint path for this resource (with no namespace).
path: function() {
return Paths.jobs + "/" + encodeURIComponent(this.name);
},Pauses a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with the job: |
var job = service.jobs().item("mysid");
job.pause(function(err, job) {
console.log("JOB PAUSED");
});
pause: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "pause"}, function(err) {
callback(err, that);
});
return req;
},Gets the preview results for a search job with given parameters.
| Name | Type | Description |
|---|---|---|
| params | Object | The parameters for retrieving preview results. For a list of available parameters, see the GET search/jobs/{search_id}/results_preview endpoint in the REST API documentation. |
| callback | Function | A function to call when the preview results are retrieved : |
var job = service.jobs().item("mysid");
job.preview({count: 10}, function(err, results, job) {
console.log("Fields: ", results.fields);
});
preview: function(params, callback) {
callback = callback || function() {};
params = params || {};
params.output_mode = params.output_mode || "json_rows";
var that = this;
return this.get("results_preview", params, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Gets the results for a search job with given parameters.
The callback can get undefined for its results parameter if the job is not yet done. To avoid this, use the Job.track() method to wait until the job is complete prior to fetching the results with this method.
| Name | Type | Description |
|---|---|---|
| params | Object | The parameters for retrieving search results. For a list of available parameters, see the GET search/jobs/{search_id}/results endpoint in the REST API documentation. |
| callback | Function | A function to call when the results are retrieved: |
var job = service.jobs().item("mysid");
job.results({count: 10}, function(err, results, job) {
console.log("Fields: ", results.results);
});
results: function(params, callback) {
callback = callback || function() {};
params = params || {};
params.output_mode = params.output_mode || "json_rows";
var that = this;
return this.get("results", params, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Gets the search log for this search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with the search log and job: |
var job = service.jobs().item("mysid");
job.searchlog(function(err, searchlog, job) {
console.log(searchlog);
});
searchlog: function(callback) {
callback = callback || function() {};
var that = this;
return this.get("search.log", {}, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Sets the priority for this search job.
| Name | Type | Description |
|---|---|---|
| value | Number | The priority (an integer between 1-10). A higher value means a higher priority. |
| callback | Function | A function to call with the search job: |
var job = service.jobs().item("mysid");
job.setPriority(6, function(err, job) {
console.log("JOB PRIORITY SET");
});
setPriority: function(value, callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "setpriority", priority: value}, function(err) {
callback(err, that);
});
return req;
},Sets the time to live (TTL) for the search job, which is the time before the search job expires after it has been completed and is still available.
| Name | Type | Description |
|---|---|---|
| value | Number | The time to live, in seconds. |
| callback | Function | A function to call with the search job: |
var job = service.jobs().item("mysid");
job.setTTL(1000, function(err, job) {
console.log("JOB TTL SET");
});
setTTL: function(value, callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "setttl", ttl: value}, function(err) {
callback(err, that);
});
return req;
},Gets the summary for this search job with the given parameters.
| Name | Type | Description |
|---|---|---|
| params | Object | The parameters for retrieving the summary. For a list of available parameters, see the GET search/jobs/{search_id}/summary endpoint in the REST API documentation. |
| callback | Function | A function to call with the summary and search job: |
var job = service.jobs().item("mysid");
job.summary({top_count: 5}, function(err, summary, job) {
console.log("Summary: ", summary);
});
summary: function(params, callback) {
callback = callback || function() {};
var that = this;
return this.get("summary", params, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Gets the timeline for this search job.
| Name | Type | Description |
|---|---|---|
| params | Object | The parameters for retrieving the timeline. For a list of available parameters, see the GET search/jobs/{search_id}/timeline endpoint in the REST API documentation. |
| callback | Function | A function to call with the timeline and search job: |
var job = service.jobs().item("mysid");
job.timeline({time_format: "%c"}, function(err, job, timeline) {
console.log("Timeline: ", timeline);
});
timeline: function(params, callback) {
callback = callback || function() {};
var that = this;
return this.get("timeline", params, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, response.data, that);
}
});
},Touches a search job, which means extending the expiration time of the search to now plus the time to live (TTL).
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with the search job: |
var job = service.jobs().item("mysid");
job.touch(function(err) {
console.log("JOB TOUCHED");
});
touch: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "touch"}, function(err) {
callback(err, that);
});
return req;
},Starts polling the status of this search job, and fires callbacks upon each status change.
| Name | Type | Description |
|---|---|---|
| options | Object | A dictionary of optional parameters: |
| callbacks | Object,Function | A dictionary of optional callbacks: |
track: function(options, callbacks) {
var period = options.period || 500; // ms
if (utils.isFunction(callbacks)) {
callbacks = {
done: callbacks
};
}
var noCallbacksAfterReady = (
!callbacks.progress &&
!callbacks.done &&
!callbacks.failed &&
!callbacks.error
);
callbacks.ready = callbacks.ready || function() {};
callbacks.progress = callbacks.progress || function() {};
callbacks.done = callbacks.done || function() {};
callbacks.failed = callbacks.failed || function() {};
callbacks.error = callbacks.error || function() {};
// For use by tests only
callbacks._preready = callbacks._preready || function() {};
callbacks._stoppedAfterReady = callbacks._stoppedAfterReady || function() {};
var that = this;
var emittedReady = false;
var doneLooping = false;
Async.whilst(
function() { return !doneLooping; },
function(nextIteration) {
that.fetch(function(err, job) {
if (err) {
nextIteration(err);
return;
}
var dispatchState = job.properties().dispatchState;
var notReady = dispatchState === "QUEUED" || dispatchState === "PARSING";
if (notReady) {
callbacks._preready(job);
}
else {
if (!emittedReady) {
callbacks.ready(job);
emittedReady = true;
// Optimization: Don't keep polling the job if the
// caller only cares about the `ready` event.
if (noCallbacksAfterReady) {
callbacks._stoppedAfterReady(job);
doneLooping = true;
nextIteration();
return;
}
}
callbacks.progress(job);
var props = job.properties();
if (dispatchState === "DONE" && props.isDone) {
callbacks.done(job);
doneLooping = true;
nextIteration();
return;
}
else if (dispatchState === "FAILED" && props.isFailed) {
callbacks.failed(job);
doneLooping = true;
nextIteration();
return;
}
}
Async.sleep(period, nextIteration);
});
},
function(err) {
if (err) {
callbacks.error(err);
}
}
);
},Resumes a search job.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call with the search job: |
var job = service.jobs().item("mysid");
job.unpause(function(err) {
console.log("JOB UNPAUSED");
});
unpause: function(callback) {
callback = callback || function() {};
var that = this;
var req = this.post("control", {action: "unpause"}, function(err) {
callback(err, that);
});
return req;
}
});Loads the entity and stores the properties.
| Name | Type | Description |
|---|---|---|
| properties | Object | The properties for this entity. |
_load: function(properties) {
properties = utils.isArray(properties) ? properties[0] : properties;
// Initialize the properties to
// empty values
properties = properties || {
content: {},
fields: {},
acl: {},
links: {}
};
this._super(properties);
// Take out the entity-specific content
this._properties = properties.content || {};
this._fields = properties.fields || this._fields || {};
this._acl = properties.acl || {};
this._links = properties.links || {};
this._author = properties.author || null;
this._updated = properties.updated || null;
this._published = properties.published || null;
},Retrieves the access control list (ACL) information for this entity, which contains the permissions for accessing the entity.
The ACL.
acl: function() {
return this._acl;
},Retrieves the author information for this entity.
The author.
author: function() {
return this._author;
},Performs a relative DELETE request on an endpoint's path, combined with the parameters and a relative path if specified.
| 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: |
// 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
);
}
});Disables the entity on the server.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call when the object is disabled: |
disable: function(callback) {
callback = callback || function() {};
var that = this;
this.post("disable", {}, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, that);
}
});
},Enables the entity on the server.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call when the object is enabled: |
enable: function(callback) {
callback = callback || function() {};
var that = this;
this.post("enable", {}, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, that);
}
});
},Refreshes the entity by fetching the object from the server and loading it.
| Name | Type | Description |
|---|---|---|
| options | Object | An optional dictionary of collection filtering and pagination options: |
| callback | Function | A function to call when the object is retrieved: |
fetch: function(options, callback) {
if (!callback && utils.isFunction(options)) {
callback = options;
options = {};
}
callback = callback || function() {};
options = options || {};
var that = this;
return this.get("", options, function(err, response) {
if (err) {
callback(err);
}
else {
that._load(response.data ? response.data.entry : null);
callback(null, that);
}
});
},A static property that indicates whether to call fetch after an update to get the updated entity. By default, the entity is not fetched because the endpoint returns (echoes) the updated entity.
fetchOnUpdate: false,Retrieves the fields information for this entity, indicating which fields are wildcards, required, and optional.
The fields information.
fields: function() {
return this._fields;
},Performs a relative GET request on an endpoint's path, combined with the parameters and a relative path if specified.
| 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: |
// 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
);
},Retrieves the links information for this entity, which is the URI of the entity relative to the management port of a Splunk instance.
The links information.
links: function() {
return this._links;
},Performs a relative POST request on an endpoint's path, combined with the parameters and a relative path if specified.
| 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: |
// 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
);
},Retrieves the current properties for this resource.
The properties.
properties: function() {
return this._properties;
},Retrieves the published time for this entity.
The published time.
published: function() {
return this._published;
},Reloads the entity on the server.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call when the object is reloaded: |
reload: function(callback) {
callback = callback || function() {};
var that = this;
this.post("_reload", {}, function(err, response) {
if (err) {
callback(err);
}
else {
callback(null, that);
}
});
}
});Deletes the entity from the server.
| Name | Type | Description |
|---|---|---|
| callback | Function | A function to call when the object is deleted: |
remove: function(callback) {
callback = callback || function() {};
var that = this;
return this.del("", {}, function(err) {
callback(err);
});
},Retrieves the current full state (properties and metadata) of this resource.
The current full state of this resource.
state: function() {
return this._state;
}
});Updates the entity on the server.
| Name | Type | Description |
|---|---|---|
| props | Object | The properties to update the object with. |
| callback | Function | A function to call when the object is updated: |
update: function(props, callback) {
callback = callback || function() {};
if (props.hasOwnProperty("name")) {
throw new Error("Cannot set 'name' field in 'update'");
}
var that = this;
var req = this.post("", props, function(err, response) {
if (!err && !that.fetchOnUpdate) {
that._load(response.data.entry);
callback(err, that);
}
else if (!err && that.fetchOnUpdate) {
that.fetch(function() {
if (req.wasAborted) {
return; // aborted, so ignore
}
else {
callback.apply(null, arguments);
}
});
}
else {
callback(err, that);
}
});
return req;
},Retrieves the updated time for this entity.
The updated time.
updated: function() {
return this._updated;
},