-
Notifications
You must be signed in to change notification settings - Fork 1
client
The object via which the API for the Turbonomic instance can be accessed. The connection with the instance is defined according to the credentials specified on the TBScript command line, or the @default credentials from .tbutilrc if none are specified explicitly.
Example..
var groups = client.getGroups();The list of methods that can be called using this object includes...
- The methods listed for the relevant turbonomic version selected from https://github.com/turbonomic/tbutil/wiki/API
- The methods declared in the "jsmodules/client_addins.js" script.
- The methods listed below.
Note: client is implemented internally as an alias to a function call, so trying to set it's value results in a syntax error.
Closes the client connection, meaning that it cannot be used for any further API calls,
This is an updated version of findInstance for XL Turbonomic instances.
Searches for an instance with the specified type and/or display name. Returns the instance or null if none (or more than one) is found. This leverages the "search" endpoint with the "types" and "q" fields set.
Note: this function should not be used with an XL Turbonomic instance.
Searches for instances with the specified type and/or display name. Returns the instance list - which may be empty. This call leverages the "search" endpoint with the "types" and "q" fields set.
Finds entities of the given type with any of the specified names. The result is an array of entity records which may be of any length.
The search is performed in a case-sensitive manner.
Gets the value of the named cookie used in the communication with Turbonomic. Note that this should be called AFTER access to a REST API method to ensure that the cookie is up to date.
If the credentials for the Turbonomic instance were specified on the command line or in the TURBO_CREDENTIALS environment variable using the "@...." syntax (and hence: lifted from the .tbutilrc file), this function returns the credential key used.
If credentials were specified on the command line or in the TURBO_CREDENTIALS environment variable using the "user:password@host" syntax, then this function returns an empty string.
Returns the specified persistent fact string for the client connection. Facts are typically used internally by the API code to differentiate between different Turbonomic instance types.
Note: facts are stored during the API login phase. If no REST API calls have yet been made on the client connection, then the fact will come back empty.
This function gets the group who's name or uuid is supplied and returns the DTO of the group thus found.
It throws an error if the group is not found.
Returns the name of the host (or IP) for the Turbonomic instance to which "client" refers.
Collects and returns the information for all instances of the specified types. This uses the "getSearchResults" API endpoint.
If the first argument is a function then pagination is used and the function is called for each object found. The return value in this case is the number of objects found.
Returns the list of available license records, excluding Reporting licenses.
Collects the SWAGGER definiiton of the API from the Turbonomic instance, and returns it as a JavaScript object.
Returns the URL used to access the Turbonomic instance. This does NOT include the username or password.
Returns true if the Turbonomic instance manages any service, business application or business transaction entities.
Returns true if the Turbonomic instance manages any cloud region entities.
Returns true if the client credentials include the details needed to allow access the instance's MySQL DB.
Returns true if the Turbonomic instance manages on-prem host entities.
Returns true if the client credentials include the details needed to access the instance using SSH.
Returns true if the Turbonomic instance has a valid license (valid means: not expired or exhausted).
Allows direct access to any Turbonomic API call that uses the "DELETE" web method.
The "path" parameter omits the protocol, username, password, host, port, base path and query parameters but includes the API-specific subpath. If "path" starts with "~" then the configured base URL path is ignored.
The options argument is a JS object that contains the key:value pairs for any URL query options that need to be passed. You can use null if there are none.
The body is a JS object that will be used as the method body. If none is needed, using the null value.
The retun is the API response body (which must in JSON format), parsed into a JS object.
For example - deleting a group who's UUID is known ...
var rtn = client.http.delete("/groups/"+group_uuid, null, null);Allows access to any Turbonomic API call that uses the "GET" web method, but it writes the raw returned body to a temporary file instead of returning it to the caller. This is useful for running APIs that return large data sets. The return value is an object with the following fields..
| Name | Description |
|---|---|
| fileName | The name of the created temporary file |
| size | The file size in bytes. |
| status | The HTTP return status code. |
| headers | The HTTP headers from the response (lower-case keys) |
Allows access to any Turbonomic API call that uses the "GET" web method.
The "path" parameter omits the protocol, username, password, host, port, base path and query parameters but includes the API-specific subpath. If "path" starts with "~" then the configured base URL path is ignored.
The options argument is a JS object that contains the key:value pairs for any URL query options that need to be passed. You can use null if there are none.
The retun is the API response body (which must in JSON format), parsed into a JS object.
Example - getting the details of a group ...
var group = client.http.get("/groups/"+uuid, { include_aspects: true });Like {client}.http.get but returns the unparsed response body as a string. You can use this (for example) to read endpoints that return non-JSON responses.
Allows access to any Turbonomic API call that uses the anonymous "GET" web method (ie: "GET" calls that do not required a login token).
The "path" parameter omits the protocol, username, password, host, port, base path and query parameters but includes the API-specific subpath. If "path" starts with "~" then the configured base URL path is ignored.
The options argument is a JS object that contains the key:value pairs for any URL query options that need to be passed. You can use null if there are none.
The retun is the API response body (which must in JSON format), parsed into a JS object.
Example - getting the details of a group ...
var version = client.http.get_anon("/admin/versions");Like {client}.http.get_anon but returns the unparsed response body as a string. You can use this (for example) to read endpoints that return non-JSON responses.
Allows access to any Turbonomic API call that uses the "POST" web method.
The "path" parameter omits the protocol, username, password, host, port, base path and query parameters but includes the API-specific subpath. If "path" starts with "~" then the configured base URL path is ignored.
The options argument is a JS object that contains the key:value pairs for any URL query options that need to be passed. You can use null if there are none.
The body is a JS object that will be used as the method body. If none is needed, using the null value.
The retun is the API response body (which must in JSON format), parsed into a JS object.
Allows access to Turbonomic API "POST" calls that require an XML formatted body.
Allows access to any Turbonomic API call that uses the "PUT" web method.
The "path" parameter omits the protocol, username, password, host, port, base path and query parameters but includes the API-specific subpath. If "path" starts with "~" then the configured base URL path is ignored.
The options argument is a JS object that contains the key:value pairs for any URL query options that need to be passed. You can use null if there are none.
The body is a JS object that will be used as the method body. If none is needed, using the null value.
Returns true if the client connection refers to a CWOM instace. Otherwise it returns false.
NB: this only works on XL instances. It fails with "Not found" on V6.
Returns true if the client connection refers to an IWO instance, otherwise it returns false.
Returns true if the client connection refers to the local host or any of it's local IP addresses, otherwise it returns false.
Returns true if the client connection refers to a Turbonomic V7 (also known as "XL") instance, otherwise it returns false.
Note: IWO is also an "XL" style platform. Is isXL returns true for IWO instances as well.
This call returns details of the last exception reported by the API when accessed via the client object. The actual exception has to be caught using try/catch in order to avoid the automatic script termination. For that reason, this call is normally used in the "catch" clause.
The function returns the REST error body as a JS object. This normally has the following properties...
| Property | Description |
|---|---|
| type | integer: the HTTP protocol status code. Eg: 404 for "not found". |
| status | The string representation of the HTTP status code. |
| exception | The JAVA exception as a string. |
| message | The message field of the java exception (not always present). |
| isNotFound | bool: true if the error denotes a not-found response (type 404). |
Example: delete a policy but do not complain if it didnt exist...
try {
client.deleteSettingsPolicyByUuid(uuid);
} catch(err) {
if (client.lastException().type !== 404) {
throw err;
}
}Returns the time value contained in the response to the last API call made. This allows the script to learn the time as known by the instance server.
The value returned is the integer count of the number of seconds since the UNIX Epoch.
Exposes the "next-cursor" header used on API functions that implement paging. These APIs are those that include a "cursor" and "limit" field in their options object (see REFERENCE.md).
Example of use that processes all the VMs in the market in pages of 250 (see the comments for details of how the cursor value and nextCursor() function should be used)...
var cursor = "0"; // always use "0" to seed the pagination loop (must be string, not integer)
while (cursor !== "") { // an empty cursor string marks the end of the results.
var opts = {
scopes: [ "Market" ],
types: [ "VirtualMachine" ]
cursor: cursor, // copy the cursor value into the opts object
limit: 250 // number of objects to return per page
};
var found = client.getSearchResults(opts);
cursor = client.nextCursor(); // update the cursor after each call to the API function
// now do something with the contents of "found"
}See also {client}.totalRecordCount(), {client}.paginate()
This function can be used to handle the pagination of results from many Turbonomic API functions.
funcName is the name of the API function to use. For example "getSearchResults".
args are the arguments that the function takes. You should use as many args values as the function expects (not an array of arguments).
opts is the options object for the function. If you wish, you can set the limit field here to override the default value of 500. If no options are to be password you should pass an empty object.
body is required if the function takes a body, but should be omitted otherwise.
callback is the function to called for each item returned by the function.
The paginate method can be used for all API functions that return an array of objects whether or not pagination is supported. This allows code to avoid the need to be aware of changes in pagination support between API versions.
Example ..
var opts = {
scopes: [ "Market" ],
types: [ "VirtualMachine" ]
};
client.paginate("getSearchResults", opts, item => {
// handle the found VM here.
});Sets the client up for cached exchanges. This allows for repeated calls to be made without actually exchanging data. It should ONLY be used when the possibly negative impact is understood. The feature is designed primarily to assist unit testing of the tbutil tool itself.
If no arguments are specified, the values of the env vars TURBO_CACHE_TIME and TURBO_CACHE_DIR are used (note: the function is implicitly called this way for the default initial client connection used by JS code).
The duration indicates how long the cached packets are valid for. It may be specified as an integer number in seconds, or a GO language duration string.
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
The directory_or_null argument indicates the name of the directory where the cache files are to be stored. If null, then the default directory "turbo-cache.d" will be used.
This function sets the timeout applied to all the following REST API transactions for the client. The duration_string must be given in the format supported by the GOLang time.ParseDuration function.
A value of "0" turns the timeout feature off, meaning that the timeout drops back to the OS's default times for the socket system calls.
A duration string is a possibly signed sequence of decimal numbers, each with optional fraction and a unit suffix, such as "300ms", "-1.5h" or "2h45m". Valid time units are "ns", "us" (or "µs"), "ms", "s", "m", "h".
This function overrides any values specified using the TURBO_HTTP_TIMEOUT environment variable.
Note: the newClient function call performs some API queries so to specifiy a timeout early enough to impact those, you should use the timeout argument in the newClient function itself.
This is an object that allows the "loadXXX()" commands to be used to access files on a remote Turbonomic instance using SSH (provided the relevant credentials are defined). This mechanism is more useful for managing a "classic" instance than an "XL" one though - and may be deprecated in future.
For example ..
var data = client.ssh.loadCsv("/tmp/data-file.csv");This mechanism supports the following methods..
- download
- executeShellCommand
- loadCsv
- loadJson
- loadGrep
- loadText
- loadDiscoveryData
- loadXml
The file name in each "load...()" case must the name of a file on the remote file system OR a shell command line, ending with a pipe character ("|""). In this latter case, the shell command is executed and its standard output is treated as if it was the content of the file. For example:
var files = client.ssh.loadText("ls -l /srv/tomcat/data |");Note: You must define the SSH credentials for the client connection using "tbutil [@key] save ssh credentials", and the mechanism only works for connections estalished using a credential key set up in this way (specified either on the tbscript command line or as the parameter to the newClient function).
This command can be used to execute any of the tbutil built-in commands, and optionally capture the output.
The sub_command parameter is a string specifying the action to take. An example would be "create static group".
The capture_stdout parameter is a boolean. If true, then the text written to the standard output by the subcommand is collected into the "out" field of the return object instead of being written to the stdout device or file. This allows the calling script to inspect the returned information.
The arguments_list parameter is an array of strings, containing the arguments to be passed to the command.
The function returns an object with the following fields:
-
status: the integer value the sub command returned (0=okay, 1=warning, 2=error) -
out: if capture_stdout is true, then this field contains the text that the sub command wrote to the standard output.
For example..
var rtn = client.tbutil("create static group", true, _.flatten(["New Group", "VirtualMachine", "-u", vmUuids]) );
if (rtn.status === 0) {
var uuid = rtn.out.trim();
printf("Created group with uuid %s\n", uuid);
}See the call and collect functions for an alternative approach.
The value of the "totalRecordCount" REST API header will be placed here for calls that make use of pagination. This operation returns the most recently seen value of the header.
See also {client}.nextCursor()
NB: This WIKI is a work in progress and is known to be incomplete and inaccurate in places as it stands.
Starting points
Popular pages