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.
| 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. |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
create: function(query, params, response_timeout) {
if (utils.isObject(query) && (utils.isNumber(params) || !params) && !response_timeout) {
response_timeout = params;
params = query;
query = params.search;
}
params = params || {};
params.search = query;
if ((params.exec_mode || "").toLowerCase() === "oneshot") {
return Promise.reject(new Error("Please use splunkjs.Service.Jobs.oneshotSearch for exec_mode=oneshot"));
}
if (!params.search) {
return Promise.reject("Must provide a query to create a search job");
}
var that = this;
return this.post("", params, response_timeout).then((response) => {
let job = new root.Job(that.service, response.data.sid, that.namespace);
return job;
});
},Constructor for splunkjs.Service.Jobs.
| Name | Type | Description |
|---|---|---|
| service | splunkjs.Service | A |
| namespace | Object | Namespace information: |
A new splunkjs.Service.Jobs instance.
init: function (service, namespace) {
// Passing the service version and versionCompare to this.path() before instantiating splunkjs.Service.Collection.
this.version = service.version;
this.versionCompare = service.versionCompare;
this.disableV2SearchApi = service.disableV2SearchApi;
this._super(service, this.path(), namespace);
// We perform the bindings so that every function works properly
this.create = utils.bind(this, this.create);
},Creates a local instance of a job.
| Name | Type | Description |
|---|---|---|
| props | Object | The properties for this new job. For a list of available parameters, see Search job parameters on Splunk Developer Portal. |
A new splunkjs.Service.Job instance.
instantiateEntity: function(props) {
let sid = props.content.sid;
let entityNamespace = utils.namespaceFromProperties(props);
return new root.Job(this.service, sid, entityNamespace);
},Creates a oneshot search from a given search query and parameters.
| Name | Type | Description |
|---|---|---|
| query | String | The search query. |
| params | Object | A dictionary of properties for the search: |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
let jobs = service.jobs();
let results = await jobs.oneshotSearch("search ERROR", {id: "myjob_123"});
console.log("RESULT FIELDS": results.fields);
oneshotSearch: function(query, params, response_timeout) {
if (utils.isObject(query) && utils.isNumber(params) && !response_timeout) {
response_timeout = params;
params = query;
query = params.search;
}
params = params || {};
params.search = query;
params.exec_mode = "oneshot";
if (!params.search) {
return Promise.reject("Must provide a query to create a search job");
}
let outputMode = params.output_mode || "json_rows";
let path = this.qualifiedPath;
let method = "POST";
let headers = {};
let post = params;
let get = {output_mode: outputMode};
let body = null;
let req = this.service.request(
path,
method,
get,
post,
body,
headers,
response_timeout).then((response) => {
return response.data;
});
return req;
}
});Retrieves the REST endpoint path for this resource (with no namespace).
path: function () {
// Pre-9.0 uses v1 endpoint
if (this.disableV2SearchApi()) {
return Paths.jobs;
}
// Post-9.0 uses v2 endpoint
return Paths.jobsV2;
},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.
| 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. |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
let jobs = service.jobs();
let newJob = await jobs.search("search ERROR", {id: "myjob_123"});
console.log("CREATED": newJob.sid);
search: function(query, params, response_timeout) {
return this.create(query, params, response_timeout);
},Create the URL for the get and post methods This is to allow v1 fallback if the service was instantiated with v2+ and a relpath v1 was provided
| Name | Type | Description |
|---|---|---|
| qualifiedPath | String | A fully-qualified relative endpoint path (for example, "/services/search/jobs"). |
| relpath | String | A relative path to append to the endpoint path. |
// Parameters
v2 example:
qualifiedPath = "/servicesNS/admin/foo/search/v2/jobs/id5_1649796951725"
qualifiedPath = "/services/search/v2/jobs/id5_1649796951725"
relpath = "search/v2/jobs/id5_1649796951725/events"
relpath = "events"
// Step 1:
Specifically for splunkjs.Service.Job method, the service endpoint may be provided
Retrieve the service prefix and suffix
servicesNS:
- servicePrefix = "/servicesNS/admin/foo"
- serviceSuffix = "foo/v2/jobs/id5_1649796951725"
services:
- servicePrefix = "/services"
- serviceSuffix = "search/v2/jobs/id5_1649796951725"
// Step 2:
Retrieve Service API version
If version can't be detected, default to 1 (v1)
qualifiedPathVersion = 2
// Step 3:
Retrieve relpath version
If version can't be detected, default to 1 (v1)
relpath = "search/v2/jobs/id5_1649796951725/events"
=> relPathVersion = 2
Check if relpath is a one segment relative path, if so, set to -1
relpath = "events"
=> relPathVersion = -1
// Step 4:
Create the URL based on set criteria
url = "/servicesNS/admin/foo/search/v2/jobs/id5_1649796951725/events"
url = "/services/search/v2/jobs/id5_1649796951725/events"
createUrl: function (qualifiedPath, relpath) {
var url = qualifiedPath,
servicePrefix = qualifiedPath.replace(/(\/services|\/servicesNS\/[^/]+\/[^/]+)\/(.*)/, "$1"),
serviceSuffix = qualifiedPath.replace(/(\/services|\/servicesNS\/[^/]+\/[^/]+)\/(.*)/, "$2"),
qualifiedPathVersionMatch = qualifiedPath.match(/\/(?:servicesNS\/[^/]+\/[^/]+|services)\/[^/]+\/v(\d+)\//),
qualifiedPathVersionMatch = qualifiedPathVersionMatch ? qualifiedPathVersionMatch.length : 0,
qualifiedPathVersion = qualifiedPathVersionMatch || 1,
relPathVersionMatch = relpath.match(/^[^/]+\/v(\d+)\//),
relPathVersionMatch = relPathVersionMatch ? relPathVersionMatch.length : 0,
relPathVersion = relPathVersionMatch || 1;
if (relpath.indexOf('/') == -1) {
relPathVersion = -1;
}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. |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
// Will make a request to {service.prefix}/search/jobs/123456
let endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
let res = await endpoint.delete("", {});
console.log("DELETED");
del: function(relpath, params, response_timeout) {
let 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,
response_timeout
);
}
});Refreshes the resource by fetching the object from the server and loading it.
| Name | Type | Description |
|---|---|---|
| options | Object | A dictionary of collection filtering and pagination options: |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
fetch: function(options, response_timeout) {
if (utils.isNumber(options) && !response_timeout) {
response_timeout = options;
options = {};
}
options = options || {};
if (!options.count) {
options.count = 0;
}
var that = this;
let req = that.get("", options, response_timeout);
return req.then((res) => {
that._load(res.data);
return that;
}).catch((err) => {
throw err;
});
},It's an asynchronous version of fetch(options, response_timeout) function.
Refreshes the resource by fetching the object from the server and loading it.
| Name | Type | Description |
|---|---|---|
| options | Object | A dictionary of collection filtering and pagination options: |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
fetchAsync: async function(options, response_timeout) {
if (utils.isNumber(options) && !response_timeout) {
response_timeout = options;
options = {};
}
options = options || {};
if (!options.count) {
options.count = 0;
}
var that = this;
let response = await that.get("", options, response_timeout, true);
that._load(response.body);
return that;
},A static property that indicates whether to call fetch after an entity has been created. By default, the entity is not fetched because the endpoint returns (echoes) the new entity.
fetchOnEntityCreation: false,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. |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
// Will make a request to {service.prefix}/search/jobs/123456/results?offset=1
let endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
let res = await endpoint.get("results", {offset: 1});
console.log("DONE");
get: function(relpath, params, response_timeout, isAsync) {
let url = this.createUrl(this.qualifiedPath, relpath);
return this.service.get(
url,
params,
response_timeout,
isAsync
);
},Returns a specific entity from the collection.
| Name | Type | Description |
|---|---|---|
| id | String | The name of the entity to retrieve. |
| namespace | Object | Namespace information: |
let apps = service.apps();
let res = await apps.fetch();
let app = res.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.");
}
let fullPath = null;
if (this._entitiesByName.hasOwnProperty(id)) {
let 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(let i = 0; i < entities.length; i++) {
let entity = entities[i];
fullPath = this.service.fullpath(entities[i].path(), namespace);
if (entity.qualifiedPath === fullPath) {
return entity;
}
}
}
}
else {
return null;
}
},Retrieves the links information for this collection, which is the URI of the resource relative to the management port of a Splunk instance.
The links information.
links: function() {
return this._links;
},Retrieves a list of all entities in the collection.
let apps = service.apps();
let res = await apps.fetch();
let appList = res.list();
console.log(appList.length);
list: function() {
return utils.clone(this._entities);
}
});Retrieves the author information for this collection.
The author.
paging: function() {
return this._paging;
},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. |
| response_timeout | Number | A timeout period for aborting a request in milisecs (0 means no timeout). |
// Will make a request to {service.prefix}/search/jobs/123456/control
let endpoint = new splunkjs.Service.Endpoint(service, "search/jobs/12345");
let res = await endpoint.post("control", {action: "cancel"});
console.log("CANCELLED");
post: function(relpath, params, response_timeout) {
let url = this.createUrl(this.qualifiedPath, relpath);
return this.service.post(
url,
params,
response_timeout
);
},Retrieves the current properties for this resource.
The properties.
properties: function() {
return this._properties;
},Retrieves the current full state (properties and metadata) of this resource.
The current full state of this resource.
state: function() {
return this._state;
}
});Retrieves the updated time for this collection.
The updated time.
updated: function() {
return this._updated;
},